Servidor de Aplicação XCAP - Documentação de Uso e Arquitetura

Índice

Resumo Executivo
XCAP em Redes 3GPP
Arquitetura do Sistema
Integração HSS
Autenticação BSF
Tipos de Documentos XCAP
Diagramas de Fluxo de Chamadas
Exemplo de Documentos XCAP
Guia de Configuração
Referência da API

Resumo Executivo

Este Servidor de Aplicação XCAP (Protocolo de Acesso à Configuração XML) fornece gerenciamento de Serviços Suplementares IMS (Subsistema Multimídia IP) para redes de telecomunicações. Ele permite que os assinantes gerenciem o encaminhamento de chamadas, bloqueio de chamadas e configurações de apresentação de ID do chamador por meio de documentos XML padronizados.

Principais Recursos:

Conformidade com 3GPP: Implementa ETSI TS 183 063 para Serviços Suplementares IMS
Integração HSS: Comunicação baseada em API REST com o Servidor de Assinantes Home
Pronto para BSF: Estrutura para autenticação de Arquitetura de Inicialização Genérica (GBA)
Multi-Serviço: Encaminhamento de Chamadas, Bloqueio de Chamadas (entrada/saída), controle de ID do Chamador
Alta Disponibilidade: Balanceamento de carga entre múltiplos pares HSS
Interface Web: Portal de autoatendimento para gerenciamento de assinantes

XCAP em Redes 3GPP

O que é XCAP?

XCAP (Protocolo de Acesso à Configuração XML) é um protocolo padronizado baseado em HTTP definido pelo IETF (RFC 4825) e adotado pelo 3GPP para gerenciar dados de configuração do usuário em redes IMS. Ele permite que dispositivos móveis e aplicativos criem, leiam, atualizem e excluam documentos XML armazenados em servidores de rede.

Papel na Arquitetura IMS 3GPP

Categorias de Serviços XCAP

O servidor XCAP gerencia três categorias principais de Serviços Suplementares IMS:

Desvio de Comunicação (Encaminhamento de Chamadas)
- Incondicional (CFU)
- Ocupado (CFB)
- Sem Resposta (CFNA)
- Não Atingível (CFNRc)
- Não Registrado (CFNReg)
Bloqueio de Comunicação (Bloqueio de Chamadas)
- Entrada: Todas as chamadas, Internacional, Internacional exceto País de Origem, Durante Roaming
- Saída: Todas as chamadas, Internacional, Internacional exceto País de Origem, Durante Roaming
Serviços de Apresentação de Identidade
- Apresentação de Identidade de Origem (OIP) - Mostrar ID do chamador
- Restrição de Apresentação de Identidade de Origem (OIR) - Ocultar ID do chamador

Conformidade com os Padrões 3GPP

Padrão	Título	Relevância
ETSI TS 183 063	Serviços de simulação PSTN/ISDN baseados em IMS	Especificação principal para o esquema XML simservs
3GPP TS 24.623	Protocolo de Acesso à Configuração (XCAP) sobre Ut	Especificações da interface XCAP
3GPP TS 24.238	Configuração do usuário baseada em Protocolo de Iniciação de Sessão (SIP)	Gerenciamento de configuração do usuário
3GPP TS 33.220	Arquitetura de Autenticação Genérica (GAA)	Estrutura de autenticação BSF/GBA
RFC 4825	O Protocolo de Acesso à Configuração XML (XCAP)	Definição base do protocolo XCAP
RFC 4745	Política Comum: Um Formato de Documento para Expressar Preferências de Privacidade	Namespace XML para condições de regras

Arquitetura do Sistema

Visão de Alto Nível dos Componentes

Arquitetura de Fluxo de Dados

Responsabilidades dos Componentes

Componente	Propósito	Porta/Protocolo
Servidor XCAP	Servidor de aplicação principal, endpoints da API REST	5000/HTTP
Manipulador XML	Conversão e manipulação de documentos XML	N/A
Cliente HSS	Recupera/atualiza dados do assinante via API REST	8080/HTTP
Motor de Templates	Gera XML XCAP a partir de dados do assinante	N/A
Autenticação BSF	Autenticação opcional de digest GBA	N/A
Interface Web	Portal de autoatendimento para assinantes	5000/HTTP

Integração HSS

Padrão de Comunicação HSS

O servidor XCAP atua como um proxy sem estado entre os clientes XCAP e o HSS. Ele não mantém armazenamento local de dados do assinante, mas consulta o HSS para cada solicitação.

Endpoints da API REST HSS

1. Recuperar Assinante por MSISDN

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

Resposta:

{
  "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. Atualizar Perfil do Assinante

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>"
}

Resposta:

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

3. Pesquisa de Assinante PCRF (baseada em IP)

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

Propósito: Resolve a identidade do assinante a partir do endereço IP do UE para acesso ao UI web.

Resposta:

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

4. Obter Informações Básicas do Assinante

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

Resposta:

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

5. Obter Assinante IMS por IMSI

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

Resposta: Mesma estrutura que o endpoint #1

Balanceamento de Carga HSS

Características:

Sem Estado: Cada solicitação pode ir para qualquer par HSS
Distribuição Aleatória: Balanceado entre os pares disponíveis
Sincronização de Banco de Dados: Os pares HSS compartilham um banco de dados comum
Sem Sessões Fixas: Sem afinidade de cliente ou persistência de sessão

Por que REST em vez de Diameter?

Redes 3GPP tradicionais usam a interface Diameter Sh para comunicação XCAP↔HSS. Esta implementação usa API REST pela simplicidade:

Aspecto	Diameter Sh (Tradicional)	API REST (Esta Implementação)
Protocolo	Diameter (RFC 6733)	HTTP/JSON
Complexidade	Alta - requer pilha Diameter	Baixa - biblioteca HTTP padrão
Formato da Mensagem	AVP (Atributo-Valor-Par) binário	JSON (legível por humanos)
Porta	3868 (SCTP/TCP)	8080 (HTTP)
Caso de Uso	Redes de telecomunicações de grau de operadora	Implantação nativa em nuvem, primeiro com API
Integração	Requer FreeDiameter, OpenDiameter	Cliente REST padrão (requests)
Autenticação	Segurança TLS/Diameter	Tokens de API, OAuth (futuro)

Vantagens da Abordagem REST:

Integração mais fácil com ferramentas modernas de DevOps
Depuração mais simples (curl, Postman)
Compatibilidade com arquitetura nativa em nuvem
Complexidade reduzida da infraestrutura
Amigável para desenvolvedores

Autenticação BSF

Arquitetura de Inicialização Genérica (GBA)

GBA é uma estrutura de autenticação 3GPP (TS 33.220) que permite autenticação mútua entre UE e serviços de rede usando chaves compartilhadas derivadas da infraestrutura de autenticação UMTS/LTE.

Status da Implementação BSF

O servidor fornece opções de autenticação flexíveis com suporte completo ao BSF/GBA disponível quando necessário.

Configuração:

# config.yaml
bsf_support: False

Desafio de Autenticação:

Quando a autenticação BSF está habilitada, o servidor emite HTTP 401 Não Autorizado com:

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

Parâmetros de Autenticação Digest

Quando a autenticação BSF está habilitada, o servidor desafia os clientes com estes parâmetros:

Parâmetro	Valor	Propósito
realm	`3GPP-bootstrapping@xcap.ims.example.com`	Domínio de autenticação
qop	`auth-int`	Qualidade de Proteção: autenticação com proteção de integridade
algorithm	`MD5`	Algoritmo de hash para cálculo de digest
nonce	string aleatória de 32 caracteres	Desafio do servidor para prevenir ataques de repetição
opaque	string aleatória de 32 caracteres	Dados específicos do servidor retornados pelo cliente inalterados
domain	`/`	Espaço URI para o qual as credenciais são válidas

Arquitetura de Autenticação

O servidor XCAP fornece múltiplos mecanismos de autenticação para atender a diferentes cenários de implantação:

1. Autenticação baseada em IP do UE via PCRF (Recomendado)

O servidor XCAP pode autenticar assinantes validando o endereço IP do UE contra sessões ativas no HSS/PCRF. Isso fornece autenticação segura e ciente da sessão sem exigir infraestrutura GBA.

Como Funciona:

Vantagens:

Ciente da Sessão: Apenas UEs autenticados com sessões de dados ativas podem acessar XCAP
Sem Segredos Compartilhados: Não requer chaves pré-compartilhadas ou senhas
Logout Automático: Quando o UE se desliga da rede, a sessão IP termina
Suporte a Roaming: Funciona em redes de origem e visitadas (se PCRF acessível)
Seguro para NAT: IP do UE validado diretamente, não cabeçalhos do lado do cliente

Propriedades de Segurança:

Verificação de IP de Origem: O IP de origem da conexão TCP não pode ser falsificado em conexão estabelecida
Autorização PCRF: Apenas UEs com contextos PDP/PDN ativos e autorizados têm endereços IP
Validação em Tempo Real: Cada solicitação consulta o estado atual do PCRF
Vinculação de Assinante: Mapeamento IP-para-assinante validado em cada solicitação

Configuração:

# config.yaml
ue_subnets:
  - '100.64.0.0/22'      # Faixa CGNAT do UE 1
  - '100.64.4.0/22'      # Faixa CGNAT do UE 2
  - '100.64.24.0/24'     # Faixa de teste do UE

# Pesquisa PCRF via API HSS
hss_peers:
  - '10.4.2.140:8080'    # HSS com endpoint PCRF
  - '10.4.2.141:8080'

Endpoint da API PCRF:

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

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

Fluxo de Validação:

Extrair IP de origem da conexão TCP da solicitação HTTP
Verificar se o IP está na faixa configurada ue_subnets
Consultar PCRF: GET /pcrf/subscriber_routing/{source_ip}
PCRF retorna subscriber_id se a sessão ativa existir
Recuperar detalhes do assinante: GET /subscriber/{subscriber_id}
Obter IMSI, então consultar: GET /ims_subscriber/ims_subscriber_imsi/{imsi}
Comparar MSISDN na URL XCAP com MSISDN resolvido pelo PCRF
Se corresponder: autenticado ✓

Casos de Uso:

Autoatendimento Web: UE conecta via dados móveis, autenticação automática por IP
Aplicativos Móveis: Clientes XCAP nativos em smartphones
Empresas: Dispositivos CPE com alocações fixas de IP do UE

2. Lista de Permissão de Sub-rede IP (Redes Confiáveis)

Para servidores de aplicativos confiáveis e ambientes de teste:

# config.yaml
as_allowed_ips:
  - '10.4.3.60'          # Servidor de Aplicação SIP
  - '10.4.3.61'          # Servidor de teste

Casos de Uso:

Servidores de Aplicação SIP recuperando perfis de assinantes durante o processamento de chamadas
Ferramentas de gerenciamento de rede interna
Ambientes de desenvolvimento/teste

3. Resolução de URI SIP para MSISDN

O servidor extrai a identidade do assinante da própria URL XCAP:

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

O servidor analisa o URI SIP para extrair o número de telefone E.164 (MSISDN).

4. Cabeçalho X-3GPP-Intended-Identity

O servidor suporta o cabeçalho padrão 3GPP para afirmação de identidade:

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

Este cabeçalho permite que os clientes especifiquem explicitamente a identidade do assinante alvo para a solicitação.

Habilitando a Autenticação BSF

Para habilitar a autenticação GBA em produção:

Implantar Servidor BSF: Implementar servidor de inicialização 3GPP TS 33.220
Configurar Diameter Zh: Conectar BSF ao HSS via Diameter

Atualizar config.yaml:

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

Implementar Recuperação de Chave NAF: Adicionar chamada de API BSF para buscar Ks_NAF para validação
Adicionar Lógica de Validação Digest: Verificar a resposta do cliente usando a chave compartilhada

Tipos de Documentos XCAP

Estrutura do Documento Raiz Simservs

Todos os documentos XCAP estão envoltos no elemento raiz simservs:

<?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">

    <!-- Serviços de Apresentação de Identidade -->
    <originating-identity-presentation active="true"/>
    <originating-identity-presentation-restriction active="true">
        <default-behaviour>presentation-not-restricted</default-behaviour>
    </originating-identity-presentation-restriction>

    <!-- Encaminhamento de Chamadas (Desvio de Comunicação) -->
    <communication-diversion active="true">
        <NoReplyTimer>20</NoReplyTimer>
        <cp:ruleset>
            <!-- Regras de encaminhamento de chamadas -->
        </cp:ruleset>
    </communication-diversion>

    <!-- Bloqueio de Chamadas -->
    <incoming-communication-barring active="false">
        <cp:ruleset>
            <!-- Regras de bloqueio de entrada -->
        </cp:ruleset>
    </incoming-communication-barring>

    <outgoing-communication-barring active="false">
        <cp:ruleset>
            <!-- Regras de bloqueio de saída -->
        </cp:ruleset>
    </outgoing-communication-barring>

</simservs>

Detalhes do Tipo de Documento

1. Desvio de Comunicação (Encaminhamento de Chamadas)

Propósito: Redirecionar chamadas recebidas para destinos alternativos com base em condições

Padrão de URL XCAP:

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

Tipos de Regras:

ID da Regra	Condição	Descrição
cfa	(nenhuma)	Encaminhamento de Chamadas Incondicional - encaminhar todas as chamadas imediatamente
cfb	ocupado	Encaminhamento de Chamadas em Ocupado - encaminhar quando a linha estiver ocupada
cfna	sem-resposta	Encaminhamento de Chamadas em Sem Resposta - encaminhar após expirar NoReplyTimer
cfnrc	não-atingível	Encaminhamento de Chamadas em Não Atingível - encaminhar quando o dispositivo estiver offline
cfnreg	não-registrado	Encaminhamento de Chamadas em Não Registrado - encaminhar quando não registrado no IMS

Estrutura XML:

<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">

        <!-- Encaminhamento Incondicional -->
        <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>

        <!-- Encaminhar em Ocupado -->
        <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. Bloqueio de Comunicação de Entrada

Propósito: Bloquear chamadas recebidas de categorias específicas

Padrão de URL XCAP:

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

Tipos de Regras:

ID da Regra	Condição	Descrição
all	(nenhuma)	Bloquear todas as chamadas recebidas
international	internacional	Bloquear chamadas de números internacionais
international-exHC	internacional-exHC	Bloquear chamadas internacionais exceto do país de origem
roaming	roaming	Bloquear chamadas recebidas durante roaming

Estrutura XML:

<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. Bloqueio de Comunicação de Saída

Propósito: Restringir chamadas de saída para destinos específicos

Padrão de URL XCAP:

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

Tipos de Regras: Mesmos que o bloqueio de entrada

Estrutura XML:

<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. Restrição de Apresentação de Identidade de Origem (ID do Chamador)

Propósito: Controlar se o ID do chamador é mostrado para as partes chamadas

Padrão de URL XCAP:

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

Estrutura XML:

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

Opções:

presentation-restricted - Ocultar ID do chamador (Anônimo)
presentation-not-restricted - Mostrar ID do chamador (Normal)

Diagramas de Fluxo de Chamadas

Fluxo de Configuração de Encaminhamento de Chamadas

Fluxo de Autoatendimento da Interface Web

Fluxo de Aplicação de Bloqueio de Chamadas

Fluxo de Autenticação BSF GBA (Quando Habilitado)

Exemplo de Documentos XCAP

Documento Completo Simservs (Desidentificado)

<?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">

    <!-- Serviços de ID do Chamador -->
    <originating-identity-presentation active="true"/>

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

    <!-- Configuração de Encaminhamento de Chamadas -->
    <communication-diversion active="true">
        <NoReplyTimer>20</NoReplyTimer>
        <cp:ruleset>

            <!-- Encaminhamento Incondicional (Desabilitado) -->
            <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>

            <!-- Encaminhar em Ocupado (Habilitado) -->
            <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>

            <!-- Encaminhar em Sem Resposta (Habilitado) -->
            <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>

            <!-- Encaminhar em Não Atingível (Habilitado) -->
            <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>

            <!-- Encaminhar em Não Registrado (Habilitado) -->
            <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>

    <!-- Bloqueio de Chamadas de Entrada -->
    <incoming-communication-barring active="false">
        <cp:ruleset>

            <!-- Bloquear Todas as Chamadas de Entrada (Desabilitado) -->
            <cp:rule id="all">
                <cp:conditions></cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Bloquear Chamadas Internacionais (Desabilitado) -->
            <cp:rule id="international">
                <cp:conditions>
                    <international/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Bloquear Chamadas Internacionais Exceto País de Origem (Desabilitado) -->
            <cp:rule id="international-exHC">
                <cp:conditions>
                    <international-exHC/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Bloquear Durante Roaming (Desabilitado) -->
            <cp:rule id="roaming">
                <cp:conditions>
                    <roaming/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

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

    <!-- Bloqueio de Chamadas de Saída -->
    <outgoing-communication-barring active="false">
        <cp:ruleset>

            <!-- Bloquear Todas as Chamadas de Saída (Desabilitado) -->
            <cp:rule id="all">
                <cp:conditions></cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Bloquear Chamadas Internacionais de Saída (Desabilitado) -->
            <cp:rule id="international">
                <cp:conditions>
                    <international/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Bloquear Chamadas Internacionais Exceto País de Origem (Desabilitado) -->
            <cp:rule id="international-exHC">
                <cp:conditions>
                    <international-exHC/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

            <!-- Bloquear Durante Roaming (Desabilitado) -->
            <cp:rule id="roaming">
                <cp:conditions>
                    <roaming/>
                </cp:conditions>
                <cp:actions>
                    <allow>false</allow>
                </cp:actions>
            </cp:rule>

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

</simservs>

Dados do Assinante YAML (Formato de Armazenamento HSS)

Esta é a representação interna armazenada no campo xcap_profile do HSS:

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

Exemplo de Solicitação XCAP PUT (Habilitar CFB)

Solicitação:

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>

Resposta:

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

Exemplo de Solicitação XCAP GET (Recuperar Todas as Regras de CF)

Solicitação:

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

Resposta:

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>

        <!-- Regras adicionais omitidas para brevidade -->
    </cp:ruleset>
</ss:communication-diversion>

Exemplo de Atualização Parcial (Alterar NoReplyTimer)

Solicitação:

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>

Resposta:

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

Guia de Configuração

Referência config.yaml

# Servidores de Backend HSS (Balanceados)
hss_peers:
  - '10.4.2.140:8080'          # opt-se2-hss01
  - '10.4.2.141:8080'          # opt-se2-hss02

# OCS (Sistema de Cobrança Online) - Atualmente não utilizado
ocs_peers:
  - '10.4.2.140'
  - '10.4.2.141'

# Alternância de Autenticação BSF/GBA
bsf_support: False             # Defina como True para GBA em produção

# Configuração do Domínio IMS
ims_domain: 'ims.example.com'
diameter_realm: 'example.com'

# Alternância de Prefixo de Namespace XML
ss_prefix: True                # Incluir prefixo 'ss:' no XML gerado

# Faixas de IP do UE Permitidas (Para autenticação baseada em IP)
ue_subnets:
  - '100.64.0.0/22'            # Faixa CGNAT 1 do UE
  - '100.64.4.0/22'            # Faixa CGNAT 2 do UE
  - '100.64.24.0/24'           # Faixa CGNAT 3 do UE

# IPs de Servidores de Aplicação Confiáveis
as_allowed_ips:
  - '10.4.3.60'                # opt-se2-as01

# Configuração de Testes de Unidade
unit_test_data:
  source_ip: "100.64.4.16"
  base_url: "http://localhost:5000"
  msisdn: "15551234567"        # MSISDN do assinante de teste

Portal de Autoatendimento Web

Para assinantes cujos dispositivos não suportam nativamente XCAP, o servidor fornece um portal de autoatendimento baseado na web. Os usuários podem navegar diretamente para o servidor XCAP a partir de seus dispositivos móveis para gerenciar suas configurações por meio de uma interface HTML intuitiva.

Método de Acesso:

Os usuários simplesmente abrem um navegador web em seu smartphone e navegam até a URL do servidor XCAP:

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

Autenticação Automática:

Ao acessar de um dispositivo móvel conectado à rede da operadora, a autenticação acontece automaticamente por validação do IP do UE:

O dispositivo do usuário já tem uma sessão de dados ativa (contexto PDP/PDN)
O servidor XCAP extrai o IP de origem da conexão HTTP
O servidor consulta o PCRF do HSS para resolver IP → identidade do assinante
O usuário é automaticamente logado - nenhuma senha/nome de usuário necessário
A interface web exibe o encaminhamento de chamadas atual, bloqueio de chamadas e configurações de ID do chamador

Recursos:

Gerenciamento de Encaminhamento de Chamadas: Habilitar/desabilitar regras de encaminhamento, definir números de destino
Controle de Bloqueio de Chamadas: Configurar restrições de chamadas de entrada e saída
Timer de Sem Resposta: Ajustar o tempo limite antes do encaminhamento de chamadas em caso de não resposta
Atualizações em Tempo Real: Alterações refletidas imediatamente no perfil do assinante
Otimizado para Móveis: Design responsivo para navegadores de smartphones

Casos de Uso:

Dispositivos Legados: Smartphones sem suporte nativo ao cliente XCAP
Dispositivos iOS: iPhones que não expõem configurações XCAP no aplicativo de Configurações
Variações do Android: Builds do Android sem integração XCAP específica da operadora
Preferência do Usuário: Assinantes que preferem a interface web em vez de menus de configurações do dispositivo
Acesso Rápido: Alterações temporárias enquanto viajam ou estão em roaming

Fluxo de Exemplo:

Isso elimina a necessidade de software de cliente XCAP especializado e fornece acesso universal por meio de navegadores web padrão.

Referência da API

Estrutura da URL Base

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

Componentes:

Raiz: simservs.ngn.etsi.org (AUID - Identificador Único da Aplicação)
XUI: users/{sip_uri} (Identificador de Usuário XCAP)
Documento: simservs.xml
Selecionador de Nó: /~~/simservs/communication-diversion/... (baseado em XPath)

Tabela de Referência de Endpoints

Operação	Método	URL XCAP	Descrição
Obter todos os serviços	GET	`/users/{sip}/simservs.xml`	Recuperar documento simservs completo
Obter regras de CF	GET	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion`	Obter todas as regras de encaminhamento de chamadas
Obter regra de CF específica	GET	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion/cp:ruleset/{rule_id}`	Obter uma única regra de CF (cfa, cfb, etc.)
Atualizar regra de CF	PUT	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion/cp:ruleset/{rule_id}`	Atualizar regra de encaminhamento de chamadas
Atualizar condição de CF	PUT	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion/cp:ruleset/{rule_id}/{element}`	Atualizar elemento da regra (target, condition)
Definir NoReplyTimer	PUT	`/users/{sip}/simservs.xml/~~/simservs/communication-diversion/NoReplyTimer`	Alterar tempo limite de não resposta
Obter ID do chamador	GET	`/users/{sip}/simservs.xml/~~/simservs/originating-identity-presentation-restriction`	Obter configuração de restrição de ID do chamador
Obter CB de entrada	GET	`/users/{sip}/simservs.xml/~~/simservs/incoming-communication-barring/cp:ruleset/{rule_id}`	Obter regra de bloqueio de entrada
Atualizar CB de entrada	PUT	`/users/{sip}/simservs.xml/~~/simservs/incoming-communication-barring/cp:ruleset/{rule_id}`	Atualizar regra de bloqueio de entrada
Obter CB de saída	GET	`/users/{sip}/simservs.xml/~~/simservs/outgoing-communication-barring/cp:ruleset/{rule_id}`	Obter regra de bloqueio de saída
Atualizar CB de saída	PUT	`/users/{sip}/simservs.xml/~~/simservs/outgoing-communication-barring/cp:ruleset/{rule_id}`	Atualizar regra de bloqueio de saída

Cabeçalhos HTTP

Cabeçalhos de Solicitação

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

Cabeçalhos de Resposta

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

Respostas de Erro

Código HTTP	Significado	Descrição
200 OK	Sucesso	Operação concluída com sucesso
401 Não Autorizado	Autenticação Necessária	Desafio de autenticação BSF/GBA (se habilitado)
404 Não Encontrado	Recurso Não Encontrado	Assinante ou documento não existe
409 Conflito	Conflito	Desconexão de versão do documento (conflito de ETag)
500 Erro Interno do Servidor	Erro do Servidor	Falha de comunicação HSS ou erro de processamento

Endpoints da Interface Web

Endpoint	Método	Propósito
`/`	GET	Página de informações do assinante (pesquisa baseada em IP)
`/call_forwarding`	GET	Exibir formulário de gerenciamento de encaminhamento de chamadas
`/call_forwarding`	POST	Atualizar regra de encaminhamento de chamadas via interface web
`/api`	GET	Documentação da interface Swagger

Formato de Registro

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

Campos: timestamp, ID do processo, localização do arquivo, nível de log, mensagem

Considerações de Desempenho

Design Sem Estado: Nenhum estado de sessão mantido no servidor XCAP
Distribuição de Carga: Seleção aleatória de par HSS por solicitação
Cache de Templates: Templates de documentos carregados uma vez na inicialização
Processamento XML: Análise e formatação em memória
Consultas ao Banco de Dados: Uma consulta HSS por GET, duas por PUT (ler-modificar-escrever)

Conclusão

Este Servidor de Aplicação XCAP fornece uma implementação pronta para produção do gerenciamento de Serviços Suplementares IMS 3GPP. Principais destaques:

Forças:

Total conformidade com os padrões XCAP ETSI/3GPP
Integração HSS baseada em API REST para implantação nativa em nuvem
Múltiplas opções de autenticação, incluindo BSF/GBA e validação baseada em IP do UE
Portal de autoatendimento baseado na web para compatibilidade universal de dispositivos
Alta disponibilidade com pares HSS balanceados

Cenários de Implantação:

Operadoras de Rede Móvel (MNOs) e Operadoras de Rede Móvel Virtual (MVNOs)
Implantações IMS em empresas
Plataformas de serviços VoLTE/VoWiFi
Infraestrutura de telecomunicações nativa em nuvem
Redes privadas LTE/5G

Referências

Especificações 3GPP e ETSI

Especificação	Título	Descrição	URL
ETSI TS 183 063	Serviços de simulação PSTN/ISDN baseados em telecomunicações e Internet	Especificação principal definindo o esquema XML simservs para serviços suplementares IMS	Portal ETSI
3GPP TS 24.623	Protocolo de Acesso à Configuração (XCAP) sobre a interface Ut para Manipulação de Serviços Suplementares	Define a interface XCAP entre UE e servidor de aplicação para configuração de serviços suplementares	Portal 3GPP
3GPP TS 24.238	Configuração do usuário baseada em Protocolo de Iniciação de Sessão (SIP); Estágio 3	Especifica mecanismos baseados em SIP para gerenciamento de configuração do usuário em IMS	Portal 3GPP
3GPP TS 33.220	Arquitetura de Autenticação Genérica (GAA); Arquitetura de Inicialização Genérica (GBA)	Define a estrutura BSF e GBA para inicialização de credenciais de segurança	Portal 3GPP
3GPP TS 24.229	Protocolo de controle de chamada multimídia baseado em Protocolo de Iniciação de Sessão (SIP) e Protocolo de Descrição de Sessão (SDP); Estágio 3	Especificação central de controle de chamadas IMS incluindo gatilhos de serviço e execução de serviços suplementares	Portal 3GPP
3GPP TS 29.228	Interfaces Cx e Dx do Subsistema Multimídia (IM); Fluxos de sinalização e conteúdos de mensagens	Define a interface Diameter Cx/Dx entre S-CSCF e HSS (relacionado à recuperação do perfil do usuário)	Portal 3GPP
3GPP TS 29.328	Interface Sh do Subsistema Multimídia (IM); Fluxos de sinalização e conteúdos de mensagens	Define a interface Diameter Sh entre AS e HSS para acesso a dados do usuário	Portal 3GPP

RFCs do IETF

RFC	Título	Descrição	URL
RFC 4825	O Protocolo de Acesso à Configuração XML (XCAP)	Especificação base do protocolo XCAP definindo manipulação de documentos XML baseada em HTTP	IETF Datatracker
RFC 4745	Política Comum: Um Formato de Documento para Expressar Preferências de Privacidade	Define o namespace XML de política comum usado para condições de regras em documentos XCAP	IETF Datatracker
RFC 2617	Autenticação HTTP: Autenticação Básica e Digest	Define o mecanismo de autenticação Digest usado em desafios BSF/GBA

Índice​

Resumo Executivo​

XCAP em Redes 3GPP​

O que é XCAP?​

Papel na Arquitetura IMS 3GPP​

Categorias de Serviços XCAP​

Conformidade com os Padrões 3GPP​

Arquitetura do Sistema​

Visão de Alto Nível dos Componentes​

Arquitetura de Fluxo de Dados​

Responsabilidades dos Componentes​

Integração HSS​

Padrão de Comunicação HSS​

Endpoints da API REST HSS​

1. Recuperar Assinante por MSISDN​

2. Atualizar Perfil do Assinante​

3. Pesquisa de Assinante PCRF (baseada em IP)​

4. Obter Informações Básicas do Assinante​

5. Obter Assinante IMS por IMSI​

Balanceamento de Carga HSS​

Por que REST em vez de Diameter?​

Autenticação BSF​

Arquitetura de Inicialização Genérica (GBA)​

Status da Implementação BSF​

Parâmetros de Autenticação Digest​

Arquitetura de Autenticação​

1. Autenticação baseada em IP do UE via PCRF (Recomendado)​

2. Lista de Permissão de Sub-rede IP (Redes Confiáveis)​

3. Resolução de URI SIP para MSISDN​

4. Cabeçalho X-3GPP-Intended-Identity​

Habilitando a Autenticação BSF​

Tipos de Documentos XCAP​

Estrutura do Documento Raiz Simservs​

Detalhes do Tipo de Documento​

1. Desvio de Comunicação (Encaminhamento de Chamadas)​

2. Bloqueio de Comunicação de Entrada​

3. Bloqueio de Comunicação de Saída​

4. Restrição de Apresentação de Identidade de Origem (ID do Chamador)​

Diagramas de Fluxo de Chamadas​

Fluxo de Configuração de Encaminhamento de Chamadas​

Fluxo de Autoatendimento da Interface Web​

Fluxo de Aplicação de Bloqueio de Chamadas​

Fluxo de Autenticação BSF GBA (Quando Habilitado)​

Exemplo de Documentos XCAP​

Documento Completo Simservs (Desidentificado)​

Dados do Assinante YAML (Formato de Armazenamento HSS)​

Exemplo de Solicitação XCAP PUT (Habilitar CFB)​

Exemplo de Solicitação XCAP GET (Recuperar Todas as Regras de CF)​

Exemplo de Atualização Parcial (Alterar NoReplyTimer)​

Guia de Configuração​

Referência config.yaml​

Portal de Autoatendimento Web​

Referência da API​

Estrutura da URL Base​

Tabela de Referência de Endpoints​

Cabeçalhos HTTP​

Cabeçalhos de Solicitação​

Cabeçalhos de Resposta​

Respostas de Erro​

Endpoints da Interface Web​

Formato de Registro​

Considerações de Desempenho​

Conclusão​

Referências​

Especificações 3GPP e ETSI​

RFCs do IETF​

Índice

Resumo Executivo

XCAP em Redes 3GPP

O que é XCAP?

Papel na Arquitetura IMS 3GPP

Categorias de Serviços XCAP

Conformidade com os Padrões 3GPP

Arquitetura do Sistema

Visão de Alto Nível dos Componentes

Arquitetura de Fluxo de Dados

Responsabilidades dos Componentes

Integração HSS

Padrão de Comunicação HSS

Endpoints da API REST HSS

1. Recuperar Assinante por MSISDN

2. Atualizar Perfil do Assinante

3. Pesquisa de Assinante PCRF (baseada em IP)

4. Obter Informações Básicas do Assinante

5. Obter Assinante IMS por IMSI

Balanceamento de Carga HSS

Por que REST em vez de Diameter?

Autenticação BSF

Arquitetura de Inicialização Genérica (GBA)

Status da Implementação BSF

Parâmetros de Autenticação Digest

Arquitetura de Autenticação

1. Autenticação baseada em IP do UE via PCRF (Recomendado)

2. Lista de Permissão de Sub-rede IP (Redes Confiáveis)

3. Resolução de URI SIP para MSISDN

4. Cabeçalho X-3GPP-Intended-Identity

Habilitando a Autenticação BSF

Tipos de Documentos XCAP

Estrutura do Documento Raiz Simservs

Detalhes do Tipo de Documento

1. Desvio de Comunicação (Encaminhamento de Chamadas)

2. Bloqueio de Comunicação de Entrada

3. Bloqueio de Comunicação de Saída

4. Restrição de Apresentação de Identidade de Origem (ID do Chamador)

Diagramas de Fluxo de Chamadas

Fluxo de Configuração de Encaminhamento de Chamadas

Fluxo de Autoatendimento da Interface Web

Fluxo de Aplicação de Bloqueio de Chamadas

Fluxo de Autenticação BSF GBA (Quando Habilitado)

Exemplo de Documentos XCAP

Documento Completo Simservs (Desidentificado)

Dados do Assinante YAML (Formato de Armazenamento HSS)

Exemplo de Solicitação XCAP PUT (Habilitar CFB)

Exemplo de Solicitação XCAP GET (Recuperar Todas as Regras de CF)

Exemplo de Atualização Parcial (Alterar NoReplyTimer)

Guia de Configuração

Referência config.yaml

Portal de Autoatendimento Web

Referência da API

Estrutura da URL Base

Tabela de Referência de Endpoints

Cabeçalhos HTTP

Cabeçalhos de Solicitação

Cabeçalhos de Resposta

Respostas de Erro

Endpoints da Interface Web

Formato de Registro

Considerações de Desempenho

Conclusão

Referências

Especificações 3GPP e ETSI

RFCs do IETF