Configuring Sentinel XCAP Server

A profile table XCAPConfigProfileTable contains the configuration for the XCAP service and its NAF filter in a profile called XCAPConfig.

Configuring the NAF filter

Parameter Type Description

TrustedDestinationIPs

List<String> each must be a literal IPv4 or IPv6 address.

Defaults to an empty list.

Incoming requests to IP addresses in this list are trusted and bypass BSF/NAF authentication. If requests from VoLTE’s XCAP Data Update feature are on a separate interface to those from UEs, the address of the interface from VoLTE may be set here to allow it to connect without BSF/NAF authentication.

TrustedSourceIPs

List<String> each must be a literal IPv4 or IPv6 address.

Defaults to an empty list.

Requests from IP addresses in this list are trusted and bypass BSF/NAF authentication. May be used to enable VoLTE’s XCAP Data Update feature to connect without BSF/NAF authentication.

ForcedAuthPaths

List<String>

Defaults to an empty list.

If the request URL’s path starts with one of the values configured here, authentication cannot be bypassed. Overrides authentication bypass in TrustedSourceIPs and TrustedDestinationIPs.

ServiceType

int

Default 0

These parameters are used by the NAF filter to select which public identities in USS elements are added to the the X-3GPP-Asserted-Identity header passed to the XCAP service. See GUSS usage in the NAF Authentication Filter.

ServiceID

int

Default 0

NAFGroup:

String

Default ""

MaxNonceCountValue

int

Default 100

If the Nonce count (nc) in an authorization request exceeds this value, the attempt fails. Note that this value is decimal, but the nc parameter value in an Authorization header is in hex.

NonceLifetimeMillis

int

Default 180000

A nonce stored in cassandra is valid for this many milliseconds.

NonceCassandraKeyspace

String

Default "opencloud_nonce_info"

The cassandra keyspace which the NAF filter uses for storing nonces.

ReadUaCipherSuiteNameFromHeader

boolean

Default true

When the UE connects to the server via a proxy, the proxy must add the negotiated cipher suite for its UE connection to a X-Ua-OpenSSL-Cipher-Suite header on the connection to the server, and this parameter should be true. In this case the NAF filter can obtain the UE’s negotiated cipher suite from that header.

When the UE connects directly to the server, this parameter should be false and the negotiated cipher suite is obtained directly from the TLS stack.

ForcedTLSSuiteName

String

Default ""

When not empty, this setting overrides the cipher suite to a fixed value. Use only in consultation with Metaswitch support.

CassandraQueryTimeoutMillis

int

Default 5000

The timeout in milliseconds for cassandra queries to get the bootstrap information.

Configuring behaviour

Parameter Type Description

UseSerialShCMRequests

boolean

Default false

Determines whether requests for the HSS documents needed to create a user’s simservs document are performed in parallel (false) or sequentially (true).

A value of true can be used to improve determinism when testing, at the expense of latency.

UseLegacyNonSpecCompatibilityMode

boolean

Default true

Enables a mode where the XCAP service behaves more like the older VoLTE/REM based XCAP Service, in its support for non standard requests.

NormalizationEnabled

boolean

Default true

Whether to apply normalization to numbers contained in CDIV rule targets and ICB/OCB conditions. See Normalization.

SimservsSchemaValidationEnabled

boolean

Default true

When true, any modified simservs document is validated against the simservs schema before the constituent HSS documents are updated. If validation fails, the request fails with 409 Conflict.

Configuring connectivity

Parameter Type Description

ShCMDestinationUrl

String

Default "http://localhost:8088"

The address of the Sh-Cache Microservice used to access the HSS.

Configuring RAs

Sh Cache Microservice REST RA

XCAP uses an entity of this RA called sh-cache-microservice-rest-ra to get HSS documents from Sh-Cache Microservice. The ShCMDestinationUrl above is all that needs configuring.

Cassandra-CQL RA

The NAF filter shares the cassandra-cql-ra entity with BSF, see Cassandra-CQL RA

HTTP RA

The HTTP RA is used to receive HTTP requests from UEs and to send HTTP responses. The name of the HTTP RA entity created by default is xcap-http-ra.

Below are the HTTP RA configuration properties that are relevant to the Sentinel XCAP .

Property name Description Default value 
BindAddresses

A set of node IDs together with the IP and port that the HTTP RA will bind to on those nodes. If using this property, do not specify ListenAddress or ListenPort.

The format is {<node-id>}<ip-address>:<port> for each node, comma-separated. For example:

{101}192.168.0.1:8001,{102}192.168.0.2:8001

 
Not set.
 
ListenAddress

The hostname or IP address that the HTTP RA will bind to. If BindAddresses is specified, then this property is ignored.

 
localhost
 
ListenPort

The TCP port number that the HTTP RA will listen on.

If BindAddresses is specified, then this property is ignored.

 
8080
 
SecureListenPort

The TCP port number that the HTTP RA will listen on for HTTPS requests. If this is set, then Keystore and KeyStorePassword must also be set.

 
Not set.
 
KeyStore

The path to a keystore file containing the server certificates for HTTPS connections. This must be set to a location that the BSF Server has Java permissions to access - a good choice is ${rhino.dir.base}/http-ra.ks.

 
Not set.
 
KeyStorePassword

The password required to access the key store.

 
Not set.

Reactivating the RA

Changing any of the above properties will require the RA to be reactivated. To reactivate in rhino-console, use the updateraentityconfigurationproperties command. For example:

> updateraentityconfigurationproperties xcap-http-ra ListenPort 8081
> deactivateraentity bsf-http-ra
> activateraentity bsf-http-ra

Configuring simservs document assembly

Overview

The simservs document is a virtual XML document that users can make XCAP requests against. It is composed of user accessible portions of one or more HSS documents.

The HSS documents are identified by the ServiceIndicator. Simservs mapping rules define the portions of those HSS documents and their corresponding location within the simservs document.

Specifying namespace prefixes to use for the mapping

A profile table SimservsMappingNamespaceProfileTable has profiles to define the XML namespace prefixes used in the SimservsMappingProfileTable.

Parameter Type Description

Prefix

String

An XML namespace prefix

NamespaceURI

String

The corresponding XML namespace URI

Specifying HSS document portions and corresponding simservs location

A profile table SimservsMappingProfileTable has profiles which define a rule mapping a portion of a specific HSS document, to its corresponding location within the simservs document.

Parameter Type Description

ServiceIndication

String

The service indication of the HSS document that the HSSPath is resolved against.

HSSPath

String

An XPath relative location path specifying the location of a single element within the HSS document which will be copied, along with its descendants, into the simservs document. The context for evaluating this expression will be the parent node of the HSS document’s document element, and will include namepace declarations defined in SimservsMappingNamespaceProfileTable.

SimservsPath

String

A restricted XPath relative location path specifying where to place the copied HSS document element in the simservs document. Because this may be used to create new ancestor elements inside the simservs document, the expression must be a / separated list of QNames. Other XPath syntax is not supported.

Order

Natural number

The order the rules are applied, and hence the order of those elements within a common parent node in the simservs document.

Assembing the simservs document

These rules are designed to maintain the rendering of the element and its children’s namespaces between the HSS document and the simservs document where possible, while allowing for renaming in cases where to not rename would break compliance with schemas.

When a user makes a request against their simservs document, the simservs document is assembled using the mapping rules as follows:

  • for each unique value of ServiceIndication within the mapping rules, the corresponding HSS document is retrieved from the ShCM for that user.

  • When all the documents have been retrieved, the document element simservs is created in the simservs namespace.

  • any namespace declaration attributes in the document element of each document are copied to the simservs document element, unless that prefix has been already defined by another document.

  • the mapping rules defined in SimservsMappingProfileTable are applied in ascending order of the Order parameter as follows:

    • The HSSPath expression is evaluated to select the source element and its descendants from the HSS document corresponding to the ServiceIndication.

    • The SimservsPath is split into separate QNames steps.

    • All but the last step are used to create any ancestor elements that do not yet exist in the simservs document as follows:

      • The new element has the simple name specified by the simple name of the QName.

      • If the QName has no namespace prefix, the new element will have the null namespace and no prefix.

      • Otherwise the new element has the namespace specified by the namespace prefix in the QName resolved against the namespace declarations in SimservsMappingNamespaceProfileTable. The new element will have an appropriate namespace prefix, either one from a namespace declaration attribute copied from the HSS document root element if present, or else the prefix defined in the QName if that namespace does not have a defined prefix.

    • The source element is renamed (details below) if it has a different simple name or namespace than specified by the QName in the final step of SimservsPath.

    • The possibly renamed source element and its descendants are inserted in the simservs document to be at the location specified by SimservsPath, after any other siblings.

Renaming elements as they are mapped

If the last step of the SimservsPath and the source element have different namespaces or different simple names, the source element is renamed when it is placed in the simservs document as follows:

  • Let the element in the HSS document selected by the HSSPath be referred to as the source element, and the corresponding new element in the simservs document be referred to as the target element. Let the namespace defined by any namespace prefix used in the last step of the SimservsPath be referred to as the target namespace.

  • The target element will have the simple name specified by the simple name of the last step of the SimservsPath.

  • If the SimservsPath last step has no namespace prefix, the node is renamed to have no namespace, which is rendered as the target element having no prefix, and the default namespace being defined as the null namespace.

  • Otherwise the target element will have the target namespace. An appropriate namespace prefix for the target element is selected as follows:

    • The most applicable prefix for the target namespace is determined, starting at the source element and looking at its ancestors (in the HSS document) until a namespace prefix definition is found that maps to the target namespace. If such a prefix is found, it is used.

    • If no such prefix is found, and the source element’s namespace is the same as the target namespace, then it is the default namespace of the source element in the HSS document. The target element will have no prefix which will render using a default namespace.

    • Otherwise the element is moving to a namespace unknown to it in the context of the HSS document. In this case the prefix defined in the last step of SimservsPath is used.

Previous page Next page