XCAP Application Server - Usage and Architecture Documentation

Executive Summary
XCAP in 3GPP Networks
System Architecture
HSS Integration
BSF Authentication
XCAP Document Types
Call Flow Diagrams
Example XCAP Documents
Configuration Guide
API Reference

Executive Summary

This XCAP (XML Configuration Access Protocol) Application Server provides IMS (IP Multimedia Subsystem) Supplementary Services management for telecommunications networks. It enables subscribers to manage call forwarding, call barring, and caller ID presentation settings through standardized XML documents.

Key Features:

3GPP Compliant: Implements ETSI TS 183 063 for IMS Supplementary Services
HSS Integration: REST API-based communication with Home Subscriber Server
BSF Ready: Framework for Generic Bootstrapping Architecture (GBA) authentication
Multi-Service: Call Forwarding, Call Barring (incoming/outgoing), Caller ID control
High Availability: Load balancing across multiple HSS peers
Web UI: Self-care portal for subscriber management

XCAP in 3GPP Networks

What is XCAP?

XCAP (XML Configuration Access Protocol) is a standardized HTTP-based protocol defined by the IETF (RFC 4825) and adopted by 3GPP for managing user configuration data in IMS networks. It allows mobile devices and applications to create, read, update, and delete XML documents stored on network servers.

Role in 3GPP IMS Architecture

XCAP Service Categories

The XCAP server manages three primary categories of IMS Supplementary Services:

Communication Diversion (Call Forwarding)
- Unconditional (CFU)
- Busy (CFB)
- No Answer (CFNA)
- Not Reachable (CFNRc)
- Not Registered (CFNReg)
Communication Barring (Call Blocking)
- Incoming: All calls, International, International except Home Country, While Roaming
- Outgoing: All calls, International, International except Home Country, While Roaming
Identity Presentation Services
- Originating Identity Presentation (OIP) - Show caller ID
- Originating Identity Presentation Restriction (OIR) - Hide caller ID

3GPP Standards Compliance

Standard	Title	Relevance
ETSI TS 183 063	IMS-based PSTN/ISDN simulation services	Primary specification for simservs XML schema
3GPP TS 24.623	Extensible Markup Language (XML) Configuration Access Protocol (XCAP) over Ut	XCAP interface specifications
3GPP TS 24.238	Session Initiation Protocol (SIP) based user configuration	User configuration management
3GPP TS 33.220	Generic Authentication Architecture (GAA)	BSF/GBA authentication framework
RFC 4825	The Extensible Markup Language (XML) Configuration Access Protocol (XCAP)	Base XCAP protocol definition
RFC 4745	Common Policy: A Document Format for Expressing Privacy Preferences	XML namespace for rule conditions

System Architecture

High-Level Component View

Data Flow Architecture

Component Responsibilities

Component	Purpose	Port/Protocol
XCAP Server	Main application server, REST API endpoints	5000/HTTP
XML Handler	XML document conversion and manipulation	N/A
HSS Client	Retrieves/updates subscriber data via REST API	8080/HTTP
Template Engine	Generates XCAP XML from subscriber data	N/A
BSF Auth	Optional GBA digest authentication	N/A
Web UI	Self-care portal for subscribers	5000/HTTP

HSS Integration

HSS Communication Pattern

The XCAP server acts as a stateless proxy between XCAP clients and the HSS. It does not maintain local storage of subscriber data but instead queries the HSS for each request.

HSS REST API Endpoints

1. Retrieve Subscriber by MSISDN

GET /ims_subscriber/ims_subscriber_msisdn/{msisdn}
Host: 10.4.2.140:8080

Response:

{
  "ims_subscriber_id": 12345,
  "imsi": "505570000012345",
  "msisdn": "15551234567",
  "xcap_profile": "<ss:communication-diversion>...</ss:communication-diversion>",
  "scscf": "sip:scscf1.ims.example.com:6060",
  "scscf_peer": "scscf1.ims.example.com",
  "scscf_realm": "ims.example.com"
}

2. Update Subscriber Profile

PATCH /ims_subscriber/{ims_subscriber_id}
Host: 10.4.2.140:8080
Content-Type: application/json

{
  "xcap_profile": "<ss:communication-diversion xmlns:ss=\"http://uri.etsi.org/ngn/params/xml/simservs/xcap\" active=\"true\">...</ss:communication-diversion>"
}

Response:

{
  "Status": "success",
  "ims_subscriber_id": 12345
}

3. PCRF Subscriber Lookup (IP-based)

GET /pcrf/subscriber_routing/{ip_address}
Host: 10.4.2.140:8080

Purpose: Resolves subscriber identity from UE IP address for web UI access.

Response:

{
  "subscriber_id": 67890,
  "ip_address": "100.64.4.16",
  "apn": "ims"
}

4. Get Base Subscriber Info

GET /subscriber/{subscriber_id}
Host: 10.4.2.140:8080

Response:

{
  "subscriber_id": 67890,
  "imsi": "505570000012345",
  "msisdn": "15551234567"
}

5. Get IMS Subscriber by IMSI

GET /ims_subscriber/ims_subscriber_imsi/{imsi}
Host: 10.4.2.140:8080

Response: Same structure as endpoint #1

HSS Load Balancing

Characteristics:

Stateless: Each request can go to any HSS peer
Random Distribution: Load balanced across available peers
Database Synchronization: HSS peers share a common backend database
No Sticky Sessions: No client affinity or session persistence

Why REST Instead of Diameter?

Traditional 3GPP networks use Diameter Sh interface for XCAP↔HSS communication. This implementation uses REST API for simplicity:

Aspect	Diameter Sh (Traditional)	REST API (This Implementation)
Protocol	Diameter (RFC 6733)	HTTP/JSON
Complexity	High - requires Diameter stack	Low - standard HTTP library
Message Format	AVP (Attribute-Value-Pair) binary	JSON (human-readable)
Port	3868 (SCTP/TCP)	8080 (HTTP)
Use Case	Carrier-grade telecom networks	Cloud-native, API-first deployments
Integration	Requires FreeDiameter, OpenDiameter	Standard REST client (requests)
Authentication	TLS/Diameter security	API tokens, OAuth (future)

Advantages of REST Approach:

Easier integration with modern DevOps tools
Simpler debugging (curl, Postman)
Cloud-native architecture compatibility
Reduced infrastructure complexity
Developer-friendly

BSF Authentication

Generic Bootstrapping Architecture (GBA)

GBA is a 3GPP authentication framework (TS 33.220) that enables mutual authentication between UE and network services using shared keys derived from the UMTS/LTE authentication infrastructure.

BSF Implementation Status

The server provides flexible authentication options with full BSF/GBA support available when required.

Configuration:

# config.yaml
bsf_support: False

Authentication Challenge:

When BSF authentication is enabled, the server issues HTTP 401 Unauthorized with:

WWW-Authenticate: Digest realm="3GPP-bootstrapping@xcap.ims.example.com",
                  qop="auth-int",
                  nonce="<random-32-chars>",
                  opaque="<random-32-chars>",
                  algorithm="MD5",
                  domain="/"

Digest Authentication Parameters

When BSF authentication is enabled, the server challenges clients with these parameters:

Parameter	Value	Purpose
realm	`3GPP-bootstrapping@xcap.ims.example.com`	Authentication domain
qop	`auth-int`	Quality of Protection: authentication with integrity protection
algorithm	`MD5`	Hash algorithm for digest computation
nonce	32-char random string	Server challenge to prevent replay attacks
opaque	32-char random string	Server-specific data returned by client unchanged
domain	`/`	URI space for which credentials are valid

Authentication Architecture

The XCAP server provides multiple authentication mechanisms to suit different deployment scenarios:

1. UE IP-based Authentication via PCRF (Recommended)

The XCAP server can authenticate subscribers by validating their UE IP address against active sessions in the HSS/PCRF. This provides secure, session-aware authentication without requiring GBA infrastructure.

How it Works:

Advantages:

Session-Aware: Only authenticated UEs with active data sessions can access XCAP
No Shared Secrets: Doesn't require pre-shared keys or passwords
Automatic Logout: When UE detaches from network, IP session terminates
Roaming Support: Works across home and visited networks (if PCRF accessible)
NAT-Safe: Direct UE IP validated, not client-side headers

Security Properties:

Source IP Verification: TCP connection source IP cannot be spoofed in established connection
PCRF Authorization: Only UEs with active, authorized PDP/PDN contexts have IP addresses
Real-time Validation: Each request queries current PCRF state
Subscriber Binding: IP-to-subscriber mapping validated on every request

Configuration:

# config.yaml
ue_subnets:
  - '100.64.0.0/22'      # UE CGNAT range 1
  - '100.64.4.0/22'      # UE CGNAT range 2
  - '100.64.24.0/24'     # UE test range

# PCRF lookup via HSS API
hss_peers:
  - '10.4.2.140:8080'    # HSS with PCRF endpoint
  - '10.4.2.141:8080'

PCRF API Endpoint:

GET /pcrf/subscriber_routing/{ue_ip_address}
Host: hss-server:8080

Response:
{
  "subscriber_id": 12345,
  "ip_address": "100.64.4.16",
  "apn": "ims",
  "session_start": "2026-01-07T10:30:00Z",
  "rat_type": "EUTRAN"
}

Validation Flow:

Extract source IP from HTTP request TCP connection
Verify IP is in configured ue_subnets range
Query PCRF: GET /pcrf/subscriber_routing/{source_ip}
PCRF returns subscriber_id if active session exists
Retrieve subscriber details: GET /subscriber/{subscriber_id}
Get IMSI, then query: GET /ims_subscriber/ims_subscriber_imsi/{imsi}
Compare MSISDN in XCAP URL with PCRF-resolved MSISDN
If match: authenticated ✓

Use Cases:

Web Self-Care: UE connects via mobile data, automatic authentication by IP
Mobile Apps: Native XCAP clients on smartphones
Enterprise: CPE devices with fixed UE IP allocations

2. IP Subnet Whitelisting (Trusted Networks)

For trusted application servers and test environments:

# config.yaml
as_allowed_ips:
  - '10.4.3.60'          # SIP Application Server
  - '10.4.3.61'          # Test server

Use Cases:

SIP Application Servers retrieving subscriber profiles during call processing
Internal network management tools
Development/test environments

3. SIP URI to MSISDN Resolution

The server extracts subscriber identity from the XCAP URL itself:

/simservs.ngn.etsi.org/users/sip:+15551234567@ims.example.com/simservs.xml
                              └─────────┬─────────┘
                                    MSISDN: 15551234567

The server parses the SIP URI to extract the E.164 telephone number (MSISDN).

4. X-3GPP-Intended-Identity Header

The server supports the standard 3GPP header for identity assertion:

GET /simservs.xml HTTP/1.1
Host: xcap.ims.example.com
X-3GPP-Intended-Identity: sip:+15551234567@ims.example.com

This header allows clients to explicitly specify the target subscriber identity for the request.

Enabling BSF Authentication

To enable GBA authentication in production:

Deploy BSF Server: Implement 3GPP TS 33.220 bootstrapping server
Configure Diameter Zh: Connect BSF to HSS via Diameter

Update config.yaml:

bsf_support: True
bsf_url: "http://bsf-server:8090"

Implement NAF-Key Retrieval: Add BSF API call to fetch Ks_NAF for validation
Add Digest Validation Logic: Verify client response using shared key

XCAP Document Types

Simservs Root Document Structure

All XCAP documents are wrapped in the simservs root element:

<?xml version="1.0" encoding="UTF-8"?>
<simservs xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
          xmlns:cp="urn:ietf:params:xml:ns:common-policy">

    <!-- Identity Presentation Services -->
    <originating-identity-presentation active="true"/>
    <originating-identity-presentation-restriction active="true">
        <default-behaviour>presentation-not-restricted</default-behaviour>
    </originating-identity-presentation-restriction>

    <!-- Call Forwarding (Communication Diversion) -->
    <communication-diversion active="true">
        <NoReplyTimer>20</NoReplyTimer>
        <cp:ruleset>
            <!-- Call forwarding rules -->
        </cp:ruleset>
    </communication-diversion>

    <!-- Call Barring -->
    <incoming-communication-barring active="false">
        <cp:ruleset>
            <!-- Incoming barring rules -->
        </cp:ruleset>
    </incoming-communication-barring>

    <outgoing-communication-barring active="false">
        <cp:ruleset>
            <!-- Outgoing barring rules -->
        </cp:ruleset>
    </outgoing-communication-barring>

</simservs>

Document Type Details

1. Communication Diversion (Call Forwarding)

Purpose: Redirect incoming calls to alternative destinations based on conditions

XCAP URL Pattern:

/simservs.ngn.etsi.org/users/{sip_uri}/simservs.xml/~~/simservs/communication-diversion

Rule Types:

Rule ID	Condition	Description
cfa	(none)	Call Forwarding Unconditional - forward all calls immediately
cfb	busy	Call Forwarding on Busy - forward when line is busy
cfna	no-answer	Call Forwarding on No Answer - forward after NoReplyTimer expires
cfnrc	not-reachable	Call Forwarding on Not Reachable - forward when device is offline
cfnreg	not-registered	Call Forwarding on Not Registered - forward when not registered to IMS

XML Structure:

<ss:communication-diversion xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
                            active="true">
    <ss:NoReplyTimer>20</ss:NoReplyTimer>
    <cp:ruleset xmlns:cp="urn:ietf:params:xml:ns:common-policy">

        <!-- Unconditional Forwarding -->
        <cp:rule id="cfa">
            <cp:conditions></cp:conditions>
            <cp:actions>
                <ss:forward-to>
                    <ss:target>tel:+15559999999</ss:target>
                    <ss:notify-caller>false</ss:notify-caller>
                </ss:forward-to>
            </cp:actions>
        </cp:rule>

        <!-- Forward on Busy -->
        <cp:rule id="cfb">
            <cp:conditions>
                <ss:busy/>
            </cp:conditions>
            <cp:actions>
                <ss:forward-to>
                    <ss:target>tel:+15558888888</ss:target>
                    <ss:notify-caller>false</ss:notify-caller>
                </ss:forward-to>
            </cp:actions>
        </cp:rule>

    </cp:ruleset>
</ss:communication-diversion>

2. Incoming Communication Barring

Purpose: Block incoming calls from specific categories

XCAP URL Pattern:

/simservs.ngn.etsi.org/users/{sip_uri}/simservs.xml/~~/simservs/incoming-communication-barring

Rule Types:

Rule ID	Condition	Description
all	(none)	Block all incoming calls
international	international	Block calls from international numbers
international-exHC	international-exHC	Block international calls except home country
roaming	roaming	Block incoming calls while roaming

XML Structure:

<ss:incoming-communication-barring xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
                                   active="true">
    <cp:ruleset xmlns:cp="urn:ietf:params:xml:ns:common-policy">

        <cp:rule id="international">
            <cp:conditions>
                <ss:international/>
            </cp:conditions>
            <cp:actions>
                <ss:allow>false</ss:allow>
            </cp:actions>
        </cp:rule>

        <cp:rule id="roaming">
            <cp:conditions>
                <ss:roaming/>
            </cp:conditions>
            <cp:actions>
                <ss:allow>false</ss:allow>
            </cp:actions>
        </cp:rule>

    </cp:ruleset>
</ss:incoming-communication-barring>

3. Outgoing Communication Barring

Purpose: Restrict outgoing calls to specific destinations

XCAP URL Pattern:

/simservs.ngn.etsi.org/users/{sip_uri}/simservs.xml/~~/simservs/outgoing-communication-barring

Rule Types: Same as incoming barring

XML Structure:

<ss:outgoing-communication-barring xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
                                   active="false">
    <cp:ruleset xmlns:cp="urn:ietf:params:xml:ns:common-policy">

        <cp:rule id="international">
            <cp:conditions>
                <ss:international/>
            </cp:conditions>
            <cp:actions>
                <ss:allow>false</ss:allow>
            </cp:actions>
        </cp:rule>

    </cp:ruleset>
</ss:outgoing-communication-barring>

4. Originating Identity Presentation Restriction (Caller ID)

Purpose: Control whether caller ID is shown to called parties

XCAP URL Pattern:

/simservs.ngn.etsi.org/users/{sip_uri}/simservs.xml/~~/simservs/originating-identity-presentation-restriction

XML Structure:

<ss:originating-identity-presentation-restriction active="true">
    <ss:default-behaviour>presentation-restricted</ss:default-behaviour>
</ss:originating-identity-presentation-restriction>

Options:

presentation-restricted - Hide caller ID (Anonymous)
presentation-not-restricted - Show caller ID (Normal)

Call Flow Diagrams

Call Forwarding Configuration Flow

Web UI Self-Care Flow

Call Barring Enforcement Flow

BSF GBA Authentication Flow (When Enabled)

Example XCAP Documents

Complete Simservs Document (De-identified)

<?xml version="1.0" encoding="UTF-8"?>
<simservs xmlns="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
          xmlns:cp="urn:ietf:params:xml:ns:common-policy"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!-- Caller ID Services -->
    <originating-identity-presentation active="true"/>

    <originating-identity-presentation-restriction active="true">
        <default-behaviour>presentation-not-restricted</default-behaviour>
    </originating-identity-presentation-restriction>

    <!-- Call Forwarding Configuration -->
    <communication-diversion active="true">
        <NoReplyTimer>20</NoReplyTimer>
        <cp:ruleset>

            <!-- Unconditional Forwarding (Disabled) -->
            <cp:rule id="cfa">
                <cp:conditions></cp:conditions>
                <cp:actions>
                    <forward-to>
                        <target>tel:+15556666666</target>
                        <notify-caller>false</notify-caller>
                    </forward-to>
                </cp:actions>
            </cp:rule>

            <!-- Forward on Busy (Enabled) -->
            <cp:rule id="cfb">
                <cp:conditions>
                    <busy/>
                </cp:conditions>
                <cp:actions>
                    <forward-to>
                        <target>tel:+15557777777</target>
                        <notify-caller>false</notify-caller>
                    </forward-to>
                </cp:actions>
            </cp:rule>

            <!-- Forward on No Answer (Enabled) -->
            <cp:rule id="cfna">
                <cp:conditions>
                    <no-answer/>
                </cp:conditions>
                <cp:actions>
                    <forward-to>
                        <target>tel:+15558888888</target>
                        <notify-caller>false</notify-caller>
                    </forward-to>
                </cp:actions>
            </cp:rule>

            <!-- Forward on Not Reachable (Enabled) -->
            <cp:rule id="cfnrc">
                <cp:conditions>
                    <not-reachable/>
                </cp:conditions>
                <cp:actions>
                    <forward-to>
                        <target>tel:+15559999999</target>
                        <notify-caller>false</notify-caller>
                    </forward-to>
                </cp:actions>
            </cp:rule>

            <!-- Forward on Not Registered (Enabled) -->
            <cp:rule id="cfnreg">
                <cp:conditions>
                    <not-registered/>
                </cp:conditions>
                <cp:actions>
                    <forward-to>
                        <target>tel:+15559999999</target>
                        <notify-caller>false</notify-caller>
                    </forward-to>
                </cp:actions>
            </cp:rule>

        </cp:ruleset>
    </communication-diversion>

    <!-- Incoming Call Barring -->
    <incoming-communication-barring active="false">
        <cp:ruleset>

            <!-- Block All Incoming (Disabled) -->
            <cp:rule id="all">
                <cp:conditions></cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Block International Incoming (Disabled) -->
            <cp:rule id="international">
                <cp:conditions>
                    <international/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Block International Except Home Country (Disabled) -->
            <cp:rule id="international-exHC">
                <cp:conditions>
                    <international-exHC/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Block While Roaming (Disabled) -->
            <cp:rule id="roaming">
                <cp:conditions>
                    <roaming/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

        </cp:ruleset>
    </incoming-communication-barring>

    <!-- Outgoing Call Barring -->
    <outgoing-communication-barring active="false">
        <cp:ruleset>

            <!-- Block All Outgoing (Disabled) -->
            <cp:rule id="all">
                <cp:conditions></cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Block International Outgoing (Disabled) -->
            <cp:rule id="international">
                <cp:conditions>
                    <international/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Block International Except Home Country (Disabled) -->
            <cp:rule id="international-exHC">
                <cp:conditions>
                    <international-exHC/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Block While Roaming (Disabled) -->
            <cp:rule id="roaming">
                <cp:conditions>
                    <roaming/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

        </cp:ruleset>
    </outgoing-communication-barring>

</simservs>

Subscriber Data YAML (HSS Storage Format)

This is the internal representation stored in the HSS xcap_profile field:

NoReplyTimer: 20

call_forwarding:
  cfa:
    enabled: false
    target: tel:+15556666666

  cfb:
    condition: busy
    enabled: true
    target: tel:+15557777777

  cfna:
    condition: no-answer
    enabled: true
    target: tel:+15558888888

  cfnrc:
    condition: not-reachable
    enabled: true
    target: tel:+15559999999

  cfnreg:
    condition: not-registered
    enabled: true
    target: tel:+15559999999

call_barring_incoming:
  all:
    allow: false

  international:
    allow: false
    condition: international

  international-exHC:
    allow: false
    condition: international-exHC

  roaming:
    allow: false
    condition: roaming

call_barring_outgoing:
  all:
    allow: false

  international:
    allow: false
    condition: international

  international-exHC:
    allow: false
    condition: international-exHC

  roaming:
    allow: false
    condition: roaming

Example XCAP PUT Request (Enable CFB)

Request:

PUT /simservs.ngn.etsi.org/users/sip:+15551234567@ims.example.com/simservs.xml/~~/simservs/communication-diversion/cp:ruleset/cfb HTTP/1.1
Host: xcap.ims.example.com:5000
Content-Type: application/xcap-el+xml
Content-Length: 342

<?xml version="1.0" encoding="UTF-8"?>
<cp:rule id="cfb" xmlns:cp="urn:ietf:params:xml:ns:common-policy"
         xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap">
    <cp:conditions>
        <ss:busy/>
    </cp:conditions>
    <cp:actions>
        <ss:forward-to>
            <ss:target>tel:+15557777777</ss:target>
            <ss:notify-caller>false</ss:notify-caller>
        </ss:forward-to>
    </cp:actions>
</cp:rule>

Response:

HTTP/1.1 200 OK
Content-Type: application/xcap-el+xml
ETag: "eti87"
Content-Length: 0

Example XCAP GET Request (Retrieve All CF Rules)

Request:

GET /simservs.ngn.etsi.org/users/sip:+15551234567@ims.example.com/simservs.xml/~~/simservs/communication-diversion HTTP/1.1
Host: xcap.ims.example.com:5000
Accept: application/xcap-el+xml

Response:

HTTP/1.1 200 OK
Content-Type: application/xcap-el+xml
ETag: "eti87"
Content-Length: 1456

<?xml version="1.0" encoding="UTF-8"?>
<ss:communication-diversion xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap"
                            xmlns:cp="urn:ietf:params:xml:ns:common-policy"
                            active="true">
    <ss:NoReplyTimer>20</ss:NoReplyTimer>
    <cp:ruleset>
        <cp:rule id="cfa">
            <cp:conditions></cp:conditions>
            <cp:actions>
                <ss:forward-to>
                    <ss:target>tel:+15556666666</ss:target>
                    <ss:notify-caller>false</ss:notify-caller>
                </ss:forward-to>
            </cp:actions>
        </cp:rule>

        <cp:rule id="cfb">
            <cp:conditions>
                <ss:busy/>
            </cp:conditions>
            <cp:actions>
                <ss:forward-to>
                    <ss:target>tel:+15557777777</ss:target>
                    <ss:notify-caller>false</ss:notify-caller>
                </ss:forward-to>
            </cp:actions>
        </cp:rule>

        <!-- Additional rules omitted for brevity -->
    </cp:ruleset>
</ss:communication-diversion>

Example Partial Update (Change NoReplyTimer)

Request:

PUT /simservs.ngn.etsi.org/users/sip:+15551234567@ims.example.com/simservs.xml/~~/simservs/communication-diversion/NoReplyTimer HTTP/1.1
Host: xcap.ims.example.com:5000
Content-Type: application/xcap-el+xml
Content-Length: 87

<?xml version="1.0" encoding="UTF-8"?>
<ss:NoReplyTimer xmlns:ss="http://uri.etsi.org/ngn/params/xml/simservs/xcap">30</ss:NoReplyTimer>

Response:

HTTP/1.1 200 OK
Content-Type: application/xcap-el+xml
ETag: "eti87"

Configuration Guide

config.yaml Reference

# HSS Backend Servers (Load Balanced)
hss_peers:
  - '10.4.2.140:8080'          # opt-se2-hss01
  - '10.4.2.141:8080'          # opt-se2-hss02

# OCS (Online Charging System) - Currently unused
ocs_peers:
  - '10.4.2.140'
  - '10.4.2.141'

# BSF/GBA Authentication Toggle
bsf_support: False             # Set to True for production GBA

# IMS Domain Configuration
ims_domain: 'ims.example.com'
diameter_realm: 'example.com'

# XML Namespace Prefix Toggle
ss_prefix: True                # Include 'ss:' prefix in generated XML

# Allowed UE IP Ranges (For IP-based authentication)
ue_subnets:
  - '100.64.0.0/22'            # CGNAT range 1
  - '100.64.4.0/22'            # CGNAT range 2
  - '100.64.24.0/24'           # CGNAT range 3

# Trusted Application Server IPs
as_allowed_ips:
  - '10.4.3.60'                # opt-se2-as01

# Unit Testing Configuration
unit_test_data:
  source_ip: "100.64.4.16"
  base_url: "http://localhost:5000"
  msisdn: "15551234567"        # Test subscriber MSISDN

Web Self-Care Portal

For subscribers whose devices don't natively support XCAP, the server provides a web-based self-care portal. Users can browse directly to the XCAP server from their mobile device to manage their settings through an intuitive HTML interface.

Access Method:

Users simply open a web browser on their smartphone and navigate to the XCAP server URL:

http://xcap.ims.example.com:5000/

Automatic Authentication:

When accessing from a mobile device connected to the carrier network, authentication happens automatically via UE IP validation:

User's device already has an active data session (PDP/PDN context)
XCAP server extracts the source IP from the HTTP connection
Server queries HSS PCRF to resolve IP → subscriber identity
User is automatically logged in - no username/password required
Web UI displays current call forwarding, call barring, and caller ID settings

Features:

Call Forwarding Management: Enable/disable forwarding rules, set destination numbers
Call Barring Control: Configure incoming and outgoing call restrictions
No-Reply Timer: Adjust timeout before call forwarding on no answer
Real-time Updates: Changes immediately reflected in subscriber profile
Mobile-Optimized: Responsive design for smartphone browsers

Use Cases:

Legacy Devices: Smartphones without native XCAP client support
iOS Devices: iPhones that don't expose XCAP settings in Settings app
Android Variants: Android builds without carrier-specific XCAP integration
User Preference: Subscribers who prefer web interface over device settings menus
Quick Access: Temporary changes while traveling or roaming

Example Workflow:

This eliminates the need for specialized XCAP client software and provides universal access through standard web browsers.

API Reference

Base URL Structure

http(s)://xcap.ims.example.com:5000/simservs.ngn.etsi.org/users/{sip_uri}/simservs.xml[/~~/selector]

Components:

Root: simservs.ngn.etsi.org (AUID - Application Unique ID)
XUI: users/{sip_uri} (XCAP User Identifier)
Document: simservs.xml
Node Selector: /~~/simservs/communication-diversion/... (XPath-based)

Endpoint Reference Table

Operation	Method	XCAP URL	Description
Get all services	GET	`/users/{sip}/simservs.xml`	Retrieve complete simservs document
Get CF rules	GET	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion`	Get all call forwarding rules
Get specific CF rule	GET	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion/cp:ruleset/{rule_id}`	Get single CF rule (cfa, cfb, etc.)
Update CF rule	PUT	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion/cp:ruleset/{rule_id}`	Update call forwarding rule
Update CF condition	PUT	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion/cp:ruleset/{rule_id}/{element}`	Update rule element (target, condition)
Set NoReplyTimer	PUT	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion/NoReplyTimer`	Change no-answer timeout
Get caller ID	GET	`/users/{sip}/simservs.xml/~~/simservs/originating-identity-presentation-restriction`	Get caller ID restriction setting
Get incoming CB	GET	`/users/{sip}/simservs.xml/~~/simservs/incoming-communication-barring/cp:ruleset/{rule_id}`	Get incoming barring rule
Update incoming CB	PUT	`/users/{sip}/simservs.xml/~~/simservs/incoming-communication-barring/cp:ruleset/{rule_id}`	Update incoming barring rule
Get outgoing CB	GET	`/users/{sip}/simservs.xml/~~/simservs/outgoing-communication-barring/cp:ruleset/{rule_id}`	Get outgoing barring rule
Update outgoing CB	PUT	`/users/{sip}/simservs.xml/~~/simservs/outgoing-communication-barring/cp:ruleset/{rule_id}`	Update outgoing barring rule

HTTP Headers

Request Headers

Content-Type: application/xcap-el+xml
Accept: application/xcap-el+xml
X-3GPP-Intended-Identity: sip:+15551234567@ims.example.com

Response Headers

Content-Type: application/xcap-el+xml
ETag: "eti87"

Error Responses

HTTP Code	Meaning	Description
200 OK	Success	Operation completed successfully
401 Unauthorized	Authentication Required	BSF/GBA authentication challenge (if enabled)
404 Not Found	Resource Not Found	Subscriber or document does not exist
409 Conflict	Conflict	Document version mismatch (ETag conflict)
500 Internal Server Error	Server Error	HSS communication failure or processing error

Web UI Endpoints

Endpoint	Method	Purpose
`/`	GET	Subscriber info page (IP-based lookup)
`/call_forwarding`	GET	Display call forwarding management form
`/call_forwarding`	POST	Update call forwarding rule via web UI
`/api`	GET	Swagger UI documentation

Logging Format

2026-01-07 10:15:32,456 12345   {/var/log/XCAP.log:123}   INFO   GetSubscriberData called for MSISDN: 15551234567

Fields: timestamp, process ID, file location, log level, message

Performance Considerations

Stateless Design: No session state maintained in XCAP server
Load Distribution: Random HSS peer selection per request
Template Caching: Document templates loaded once at startup
XML Processing: In-memory parsing and formatting
Database Queries: One HSS query per GET, two per PUT (read-modify-write)

Conclusion

This XCAP Application Server provides a production-ready implementation of 3GPP IMS Supplementary Services management. Key highlights:

Strengths:

Full compliance with ETSI/3GPP XCAP standards
REST API-based HSS integration for cloud-native deployment
Multiple authentication options including BSF/GBA and UE IP-based validation
Web-based self-care portal for universal device compatibility
High availability with load-balanced HSS peers

Deployment Scenarios:

Mobile Network Operators (MNOs) and Mobile Virtual Network Operators (MVNOs)
Enterprise IMS deployments
VoLTE/VoWiFi service platforms
Cloud-native telecommunications infrastructure
Private LTE/5G networks

References

3GPP and ETSI Specifications

Specification	Title	Description	URL
ETSI TS 183 063	Telecommunications and Internet converged Services and Protocols for Advanced Networking (TISPAN); IMS-based PSTN/ISDN simulation services	Primary specification defining the simservs XML schema for IMS supplementary services	ETSI Portal
3GPP TS 24.623	Extensible Markup Language (XML) Configuration Access Protocol (XCAP) over the Ut interface for Manipulating Supplementary Services	Defines the XCAP Ut interface between UE and application server for supplementary services configuration	3GPP Portal
3GPP TS 24.238	Session Initiation Protocol (SIP) based user configuration; Stage 3	Specifies SIP-based mechanisms for user configuration management in IMS	3GPP Portal
3GPP TS 33.220	Generic Authentication Architecture (GAA); Generic Bootstrapping Architecture (GBA)	Defines the BSF and GBA framework for bootstrapping security credentials	3GPP Portal
3GPP TS 24.229	IP multimedia call control protocol based on Session Initiation Protocol (SIP) and Session Description Protocol (SDP); Stage 3	Core IMS call control specification including service triggers and supplementary service execution	3GPP Portal
3GPP TS 29.228	IP Multimedia (IM) Subsystem Cx and Dx interfaces; Signalling flows and message contents	Defines Diameter Cx/Dx interface between S-CSCF and HSS (related to user profile retrieval)	3GPP Portal
3GPP TS 29.328	IP Multimedia (IM) Subsystem Sh interface; Signalling flows and message contents	Defines Diameter Sh interface between AS and HSS for user data access	3GPP Portal

IETF RFCs

RFC	Title	Description	URL
RFC 4825	The Extensible Markup Language (XML) Configuration Access Protocol (XCAP)	Base XCAP protocol specification defining HTTP-based XML document manipulation	IETF Datatracker
RFC 4745	Common Policy: A Document Format for Expressing Privacy Preferences	Defines the common-policy XML namespace used for rule conditions in XCAP documents	IETF Datatracker
RFC 2617	HTTP Authentication: Basic and Digest Access Authentication	Defines Digest authentication mechanism used in BSF/GBA challenges	IETF Datatracker
RFC 3261	SIP: Session Initiation Protocol	Core SIP specification fundamental to IMS architecture	IETF Datatracker
RFC 6733	Diameter Base Protocol	Defines Diameter protocol used in traditional Sh/Cx interfaces (background context)	IETF Datatracker

Standard	Organization	Title	Relevance
OMA-TS-XDM_Core-V2_1	Open Mobile Alliance	XML Document Management (XDM) Specification	Defines XDM architecture for XCAP document management in OMA context
ISO/IEC 19757-2	ISO/IEC	Document Schema Definition Languages (DSDL) — Part 2: Regular-grammar-based validation — RELAX NG	XML schema validation for XCAP documents
ITU-T E.164	ITU-T	The international public telecommunication numbering plan	Defines global telephone number format used in tel: URIs

Table of Contents​

Executive Summary​

XCAP in 3GPP Networks​

What is XCAP?​

Role in 3GPP IMS Architecture​

XCAP Service Categories​

3GPP Standards Compliance​

System Architecture​

High-Level Component View​

Data Flow Architecture​

Component Responsibilities​

HSS Integration​

HSS Communication Pattern​

HSS REST API Endpoints​

1. Retrieve Subscriber by MSISDN​

2. Update Subscriber Profile​

3. PCRF Subscriber Lookup (IP-based)​

4. Get Base Subscriber Info​

5. Get IMS Subscriber by IMSI​

HSS Load Balancing​

Why REST Instead of Diameter?​

BSF Authentication​

Generic Bootstrapping Architecture (GBA)​

BSF Implementation Status​

Digest Authentication Parameters​

Authentication Architecture​

1. UE IP-based Authentication via PCRF (Recommended)​

2. IP Subnet Whitelisting (Trusted Networks)​

3. SIP URI to MSISDN Resolution​

4. X-3GPP-Intended-Identity Header​

Enabling BSF Authentication​

XCAP Document Types​

Simservs Root Document Structure​

Document Type Details​

1. Communication Diversion (Call Forwarding)​

2. Incoming Communication Barring​

3. Outgoing Communication Barring​

4. Originating Identity Presentation Restriction (Caller ID)​

Call Flow Diagrams​

Call Forwarding Configuration Flow​

Web UI Self-Care Flow​

Call Barring Enforcement Flow​

BSF GBA Authentication Flow (When Enabled)​

Example XCAP Documents​

Complete Simservs Document (De-identified)​

Subscriber Data YAML (HSS Storage Format)​

Example XCAP PUT Request (Enable CFB)​

Example XCAP GET Request (Retrieve All CF Rules)​

Example Partial Update (Change NoReplyTimer)​

Configuration Guide​

config.yaml Reference​

Web Self-Care Portal​

API Reference​

Base URL Structure​

Endpoint Reference Table​

HTTP Headers​

Request Headers​

Response Headers​

Error Responses​

Web UI Endpoints​

Logging Format​

Performance Considerations​

Conclusion​

References​

3GPP and ETSI Specifications​

IETF RFCs​

Related Standards​

Table of Contents

Executive Summary

XCAP in 3GPP Networks

What is XCAP?

Role in 3GPP IMS Architecture

XCAP Service Categories

3GPP Standards Compliance

System Architecture

High-Level Component View

Data Flow Architecture

Component Responsibilities

HSS Integration

HSS Communication Pattern

HSS REST API Endpoints

1. Retrieve Subscriber by MSISDN

2. Update Subscriber Profile

3. PCRF Subscriber Lookup (IP-based)

4. Get Base Subscriber Info

5. Get IMS Subscriber by IMSI

HSS Load Balancing

Why REST Instead of Diameter?

BSF Authentication

Generic Bootstrapping Architecture (GBA)

BSF Implementation Status

Digest Authentication Parameters

Authentication Architecture

1. UE IP-based Authentication via PCRF (Recommended)

2. IP Subnet Whitelisting (Trusted Networks)

3. SIP URI to MSISDN Resolution

4. X-3GPP-Intended-Identity Header

Enabling BSF Authentication

XCAP Document Types

Simservs Root Document Structure

Document Type Details

1. Communication Diversion (Call Forwarding)

2. Incoming Communication Barring

3. Outgoing Communication Barring

4. Originating Identity Presentation Restriction (Caller ID)

Call Flow Diagrams

Call Forwarding Configuration Flow

Web UI Self-Care Flow

Call Barring Enforcement Flow

BSF GBA Authentication Flow (When Enabled)

Example XCAP Documents

Complete Simservs Document (De-identified)

Subscriber Data YAML (HSS Storage Format)

Example XCAP PUT Request (Enable CFB)

Example XCAP GET Request (Retrieve All CF Rules)

Example Partial Update (Change NoReplyTimer)

Configuration Guide

config.yaml Reference

Web Self-Care Portal

API Reference

Base URL Structure

Endpoint Reference Table

HTTP Headers

Request Headers

Response Headers

Error Responses

Web UI Endpoints

Logging Format

Performance Considerations

Conclusion

References

3GPP and ETSI Specifications

IETF RFCs

Related Standards