About the Sentinel Authentication Gateway
The Sentinel Authentication Gateway provides 3GPP Generic Authentication Architecture (GAA) support for the Rhino VoLTE TAS. This release allows IMS devices (UEs) to authenticate with their home network and securely login to the XCAP server.
The Sentinel Authentication Gateway consists of three main components:
- BSF Server
-
The Bootstrapping Security Function (BSF) server receives "bootstrap" authentication requests from UEs. These requests ask the BSF to initiate a bootstrap process between the UE and the HSS, which results in a secret key shared by the BSF and the UE. This shared key can then be used to authenticate with a Network Application Function (NAF), or application server. The Sentinel XCAP Server is an example of a NAF.
- NAF Authentication Filter
-
The NAF Authentication Filter implements the NAF authentication processes for the application, using the shared key generated by the bootstrapping process.
Together these components allow a UE to transparently authenticate with XCAP Server and securely perform configuration updates.
- Sentinel XCAP Server
-
The Sentinel XCAP Server is a NAF which provides an XCAP service to allow a UE to access and modify user accessible portions of user documents in the HSS.
Topics
the main roles, interfaces, and procedures in 3GPP GAA. |
|
the components of the Sentinel Authentication Gateway and how they implement 3GPP GAA. |
|
the XCAP Server which allows a client to read, write, and modify application configuration data in their simservs document, a virtual XML document composed of user accessible portions of one or more HSS documents. |
|
how to configure low level details for the Sentinel Authentication Gateway BSF Server, NAF Authentication Filter, and Sentinel XCAP Server. |
|
how the Sentinel Authentication Gateway uses a Cassandra database for sharing bootstrapped security association details between the BSF service and NAF Filter. |
|
the tools provided by Sentinel Authentication Gateway for generating and verifying keys during testing. |
Other documentation for the Sentinel Authentication Gateway can be found on the Sentinel Authentication Gateway product page.
Introduction to 3GPP GAA
This section describes the main roles, interfaces, and procedures in 3GPP GAA.
What is GAA?
The 3GPP Generic Authentication Architecture allows IMS devices (User Equipment or UEs) to authenticate with the network and securely access application servers, without the need for user interaction.
The authentication mechanism relies on secret key material (K) stored on the UE’s tamper-proof USIM. The same key material K is also known by the UE’s Home Subscriber Server or Authentication Centre (HSS/AuC).
When the UE needs to access an application server (Network Application Function or NAF), the UE performs a "bootstrapping" procedure with its HSS. This procedure sets up a security association for the UE, and calculates a new NAF-specific shared key.
The NAF is also able to calculate the same shared key, and uses this to authenticate requests from the UE. The NAF-specific shared key never has to traverse the network, because it can be calculated independently by the UE and NAF, based on the shared secret K.
3GPP GAA specifies how this is achieved.
GAA Roles and Interfaces
The diagram below shows a simplified view of the main roles and their interfaces involved in GAA.
![GAA network model](images/simple-gaa-network-model.drawio.png)
Role name | Meaning | Description |
---|---|---|
UE |
User Equipment |
The device that needs to securely access an application in the network. |
NAF |
Networked Application Function |
An application server. |
BSF |
Bootstrapping Security Function |
The BSF communicates with the UE and its HSS to create a security association based on the shared secret K. |
HSS |
Home Subscriber Server |
The HSS knows the UE’s shared secret K, and uses this to generate new authentication vectors (AVs) when requested by the BSF. The HSS also stores the subscriber’s GBA bootstrap security settings (GUSS), an XML document describing how the shared keys may be used with various service types. |
Interface name | Description |
---|---|
Ua |
Specifies how the UE authenticates with the NAF. Authentication is based on HTTP Digest authentication over HTTPS. Other application-specific interfaces may be defined on top of Ua. For example, Ut defines the interface between the UE and its XCAP server. |
Ub |
Specifies how the UE communicates with the BSF to create a NAF-specific shared key that the UE will use to authenticate over Ua. Based on AKA (Authentication and Key Agreement, RFC 3310) over HTTP. |
Zh |
A Diameter (RFC 6733) interface between the BSF and the HSS. The BSF uses Zh to request a new authentication vector (AV) from the HSS. The AV contains values that will be used to generate the NAF-specific shared key. The BSF also uses Zh to obtain the subscriber’s GUSS document. |
Zn |
The NAF uses Zn to obtain the NAF-specific shared key from the BSF, to authenticate the UE. This interface may be realized using Diameter or SOAP/HTTP. |
GAA Procedures
This section gives a high-level description of the procedures used when a UE attempts to access a NAF that is protected by GAA.
Not every scenario is covered, just the common case. For further information, see the references.
![]() |
In the descriptions below, assume the NAF and BSF have the fully-qualified domain names naf.home1.net and bsf.home1.net respectively. The home1.net domain is the network operator’s domain. |
.1. UE accesses NAF for the first time
The UE sends a request to the NAF naf.home1.net
over HTTPS. No credentials are present in the request.
The NAF sees that the request is unauthorized, and sends back an HTTP 401 Unauthorized response. The response contains a WWW-Authenticate
header, with the directive realm=3GPP-bootstrapping@naf.home1.net
. This tells the UE that it needs to initiate bootstrapping procedure with the BSF, to create a new security association. The response also contains a nonce
value which will be used when the UE contacts the NAF in step 3.
The UE indicates the authentication mechanism to use in all requests to access the NAF through the addition of a product token to the User-Agent
header:
-
If the UE wishes to use
GBA_ME
authentication then it must include the product token3gpp-gba
in theUser-Agent
header -
If the UE wishes to use
GBA_Digest
authentication then it must include the product token3gpp-gba-digest
in theUser-Agent
header on all requests to access the NAF. -
If neither tokens are present in the
User-Agent
header the request is rejected without a challenge
The server responds with a WWW-Authenticate
header if it supports the authentication mechanism requested by the client:
-
for
GBA_ME
theWWW-Authenticate
header includes the directiverealm=3GPP-bootstrapping@naf.home1.net
-
for
GBA_Digest
theWWW-Authenticate
header includes the directiverealm=3GPP-bootstrapping-digest@naf.home1.net
.
.2. UE initiates GBA bootstrap
Here the UE must contact the BSF to create a new security association. This process is known as "bootstrapping" and is specified by the Generic Bootstrapping Architecture (GBA) from 3GPP TS 33.220.
.2.1. UE sends bootstrapping request to BSF
The UE sends an HTTP GET request to the BSF. The request’s Authorization
header will have the subscriber’s private identity (IMPI) in the username
directive. If the UE has previously created a temporary private identity (TMPI), this will be used instead of the IMPI. The nonce
and response
directives in the Authorization
header are empty.
.2.2. BSF sends Zh request to HSS
Next, the BSF sends a Zh request to the HSS using the Diameter protocol. If successful, the Zh response will contain an authentication vector (AV). This contains a 128-bit random number (RAND) and secrets derived from the shared key K.
The AV also includes the expected response (XRES). This is a large number derived from RAND that only the UE should be able to calculate, because of its knowledge of K.
The Zh response may also contain the subscriber’s GBA User Security Settings (GUSS), which, among other things, defines the lifetime of the security association.
.2.3. BSF sends challenge
The BSF sends an HTTP 401 Unauthorized response back to the UE, containing the WWW-Authenticate
header. This header contains the "challenge" in the form of the random value RAND, in the nonce
directive.
.2.4. UE sends challenge-response
The UE performs two calculations. Firstly, the K and RAND values are used to determine the response, known as RES. Secondly, the RES value is then used as the password for calculating the HTTP digest. The UE then sends a new HTTP GET request to the BSF, containing the Authorization
header. The digest from the second calculation is sent in the Authorization
header’s response
directive.
.2.5. BSF validates challenge-response
The BSF calculates the expected HTTP digest using XRES, and compares this with the value received in the response
directive. If the values match, the bootstrapping was successful and the BSF creates and stores a new security association. This contains:
-
the Bootstrapping Transaction Identifier (B-TID) — this becomes the user ID used by the UE to access the NAF
-
the IMPI
-
a new shared key Ks, valid for the lifetime of the security association, used to generate a NAF-specific key.
The BSF sends an HTTP 200 OK response, containing an XML body specifying the new B-TID and the lifetime of the security association.
The GBA bootstrap process is now complete.
.3. UE sends authorized request to the NAF
The UE can now proceed with the original request to the NAF. It calculates the NAF-specific key, known as Ks_NAF.
The new authorized request will contain an Authorization
header using the HTTP Digest (RFC 2617) authentication scheme. The B-TID and Ks_NAF values are used as the username and password when calculating the message digest.
The UE calculates the request’s message digest, and sends this in the response
directive of the Authorization
header.
.4. NAF checks the message digest
When the NAF receives the new request it contacts the BSF using the Zn interface to lookup the B-TID and calculate Ks_NAF.
The NAF performs the same digest calculation as the UE, and should arrive at the same value if the shared key is correct. Assuming the digests match, the request is considered authorized and the NAF can now process it securely.
Subsequent requests
Subsequent requests from the UE to the NAF do not need to go though all the previous steps. Once the UE knows the B-TID and Ks_NAF, it can reuse these values in subsequent requests for the lifetime of the security association. Each new request would just involve steps 3 and 4 above.
Bootstrapping does not need to be performed again until either the security association expires, or the NAF determines it is necessary based on local policy.
Architecture Overview
This section explains the components of the Sentinel Authentication Gateway and how they implement 3GPP GAA.
The 3GPP Generic Authentication Architecture provides a standard way for User Equipment (UEs) to securely access Network Application Functions (NAFs) or application servers.
![]() |
This section assumes some familiarity with GAA roles. See Introduction to 3GPP GAA for background information. |
Sentinel Authentication Gateway's 3GPP GAA implementation
Sentinel Authentication Gateway implements the BSF and NAF roles in 3GPP GAA. The UE talks to these components over the Ub and Ua interfaces, as shown in the network model below, reproduced from 3GPP TS 33.220:
![GAA network model](images/simple-gaa-network-model.drawio.png)
In Sentinel Authentication Gateway, the BSF Server component implements the BSF role, and is implemented as a SLEE service deployed on OpenCloud Rhino. The UE communicates with the BSF using the Ub (bootstrapping) interface over HTTP on port 80.
The NAF role is implemented by the NAF Authentication Filter. The UE communicates with Sentinel XCAP using the Ut interface over HTTP or HTTPS. The NAF Authentication Filter intercepts these requests to authenticate the user (Ua interface), before passing them to the XCAP server.
Both components share state using a Cassandra database. This is functionally equivalent to the Zn interface in the model above. Sharing state in a database allows the BSF and NAF nodes to be stateless, and to easily scale out horizontally.
The diagram below shows the relationship between Sentinel Authentication Gateway components, the UE, the Sh Cache Microservice and the HSS.
![Sentinel Authentication Gateway Architecture](images/sentinel-gaa-arch.png)
The following sections explain the architecture of the BSF Server and NAF Authentication Filter by following a typical authentication and bootstrapping process as a client attempts to access a NAF resource.
Compliance Notes
Zn interface
Sentinel Authentication Gateway currently does not support third-party BSFs or NAFs, because it uses a database to implement NAF to BSF communication instead of the Diameter or HTTP-based Zn interface (3GPP TS 29.109). A future Sentinel Authentication Gateway release may remove this limitation.
Authentication schemes
The BSF Server supports the Digest-AKAv1-MD5 and GBA_Digest authentication schemes.
The NAF Authentication Filter supports the MD5 and SHA256 digest algorithms.
Additional variants may be supported in future Sentinel Authentication Gateway releases.
Bootstrapping procedures
The BSF Server currently supports the GBA (or GBA_ME), and GBA_Digest bootstrapping procedures. A future release will support GBA_U, UICC enhancements to Generic Bootstrapping Architecture (3GPP TS 33.220 §5).
NAF Authentication Filter
The NAF Authentication Filter intercepts requests to the XCAP Server.
The filter performs the role of the NAF, authenticating the requests using GAA procedures. If successful, the authenticated requests and credentials are passed on to the Sentinel XCAP Server.
NAF Authentication Filter operation
To illustrate how the filter works, we can walk through how the NAF Authentication Filter handles a typical request to the Sentinel XCAP server.
An overview of the authentication process, from the filter’s point of view, is shown below.
![Authentication process with the NAF Authentication Filter](images/naf-filter-arch.png)
The steps shown in the diagram are explained in the following sections.
1. UE makes a request
The UE needs to retrieve an XCAP resource, for example to discover configuration settings for an MMTEL service.
The UE selects the authentication mechanism to use through addition of a product token to the User-Agent
header:
-
if the UE wishes to use the
GBA_Digest
mechanism, then it must include the product token3gpp-gba-digest
in itsUser-Agent
header (not shown in this example). -
if the UE wishes to use the
GBA_ME
mechanism, then it must include the product token3gpp-gba
in itsUser-Agent
header -
if the UE includes neither, then the NAF rejects the request without a challenge
Here we assume the UE knows its XCAP server’s address, xcap.home1.net
. This address may be preconfigured in the UE, or the UE may derive it from the subscriber’s private identity as per 3GPP TS 23.003 §13.9.
The UE constructs the XCAP selector for the resource and sends an HTTP GET request to the XCAP server. In this example, the UE wants to retrieve the communication diversion (CDIV) configuration for their public identity sip:user@home1.net
.
GET /simservs.ngn.etsi.org/users/sip:user@home1.net/simservs/~~/communication-diversion HTTP/1.1
Host: xcap.home1.net
User-Agent: vendorstring/2.0 3gbb-gba
The XCAP server will need to confirm that the request is being made by a device associated with the public identity sip:user@home1.net
.
2. NAF filter rejects with challenge
The web container (such as Apache Tomcat) sees that the URL is for a resource protected by the filter, so passes the request to the filter.
The filter sees that the request has not been authenticated, because there is no Authorization
header. The filter generates a 401 unauthorized response, containing a challenge.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Digest algorithm=MD5 realm="3GPP-bootstrapping@xcap.home1.net" qop="auth-int",
nonce="8982ac96f06922330de40902183fa099",
opaque="00fffde7845cc67534bdc78f3a9e233"
The realm
value 3GPP-bootstrapping@xcap.home1.net
tells the UE that bootstrapping is required, and that GBA_ME
is to be used.
At this point the UE must perform the GBA bootstrapping procedure with the BSF. This process is covered separately in the BSF Server section.
Assuming bootstrapping is successful, the authentication process carries on.
When using GBA_Digest
the WWW-Authenticate
header includes the realm
value 3GPP-bootstrapping-digest@xcap.home1.net
. The same applies to subsequent requests sent by the UE.
3. UE sends challenge response using bootstrapped security association
After completing bootstrapping, the UE can retry the request using its bootstrapped security association.
The UE should now know the Bootstrapping Transaction Identifier (B-TID), which is used as the username for the HTTP Digest authentication scheme.
The password used is derived from shared secrets generated in the bootstrapping process, and information about the connection to the NAF. This password is known as the NAF-specific shared key, or Ks_NAF.
The UE generates a challenge response using the standard HTTP Digest (RFC 2617) scheme. The username, password, nonce, opaque, and other values from the challenge are combined to calculate the response value:
GET /simservs.ngn.etsi.org/users/sip:user@home1.net/simservs/~~/communication-diversion HTTP/1.1
Host: xcap.home1.net
Authorization: Digest username="CH8Bm4AA/38BADV/f4DBAQ==@bsf.home1.net",
realm="3GPP-bootstrapping@xcap.home1.net",
algorithm=MD5, qop=auth-int,
uri="/simservs.ngn.etsi.org/users/sip:user@home1.net/simservs/~~/communication-diversion"
nonce="8982ac96f06922330de40902183fa099",
opaque="00fffde7845cc67534bdc78f3a9e233",
nc=00000001,
cnonce="9856f65d8925a"
response="43ef1da9e534fb321476a1679ff8256"
4. NAF filter retrieves bootstrap information
The filter receives the challenge response over HTTP, and must now verify that it is correct.
To do this, the filter queries the bootstrap_info
Cassandra table to find an entry for the username (B-TID). If an entry exists, it will contain the user’s private identity (IMPI) and also the shared secrets that will be used to calculate Ks_NAF, the password.
The filter also looks up the user’s GBA User Security Settings (GUSS) in the GUSS cache, populated by the BSF. If no bootstrap information or GUSS is found, the filter must reject the request as it does not have enough information to continue.
5. NAF filter validates the bootstrapped user information
Now the filter calculates Ks_NAF, and uses this value as the password in its HTTP Digest calculation. If everything is correct, the filter will calculate the same value that the UE sent in the challenge response. This means the request has been successfully authenticated — the filter can now pass the request to the Sentinel XCAP Server.
Before doing so, the filter must also determine which IMS public identities (IMPUs) are associated with the request. This is determined by the ussList
element from the user’s GUSS, and also the filter’s configuration for service ID, service type and NAF group. See GUSS usage in the NAF Authentication Filter for details.
6. Filter passes request and credentials to Sentinel XCAP Server
The user is now authenticated, and the filter knows the public identities associated with the request. The filter adds the X-3GPP-Asserted-Identity
header to the request, with the known public identities.
The request header seen by the Sentinel XCAP Server looks like this:
GET /simservs.ngn.etsi.org/users/sip:user@home1.net/simservs/~~/communication-diversion HTTP/1.1
Host: xcap.home1.net
X-3GPP-Asserted-Identity: "tel:358504836551", "sip:user@home1.net"
Authorization: Digest username="CH8Bm4AA/38BADV/f4DBAQ==@bsf.home1.net",
realm="3GPP-bootstrapping@xcap.home1.net",
algorithm=MD5, qop=auth-int,
uri="/simservs.ngn.etsi.org/users/sip:user@home1.net/simservs/~~/communication-diversion"
nonce="8982ac96f06922330de40902183fa099",
opaque="00fffde7845cc67534bdc78f3a9e233",
nc=00000001,
cnonce="9856f65d8925a"
response="43ef1da9e534fb321476a1679ff8256"
7. Sentinel XCAP Server requests user data over Sh
The Sentinel XCAP Server sees that one of the asserted identities ("sip:user@home.net") matches the XCAP User Identity (XUI) in the Request-URI, so allows the request to proceed. If the XUI did not match an asserted identity, the request would be rejected immediately.
The Sentinel XCAP Server uses the Sh Cache Microservice to retrieve the supplementary services transparent data for this identity from the HSS. Assuming the data is found, it applies the XCAP selector to extract the requested portion of the XML document, in this case the communication-diversion
element.
8. Sentinel XCAP Server returns response to filter
The Sentinel XCAP Server generates a 200 OK response with the communication-diversion
element. At this point control returns to the filter.
If the requested qop
(Quality of Protection) parameter was auth-int
, the filter must calculate a response digest so that the UE can verify the integrity of the response. The filter calculates the digest over the response body, and adds the Authentication-Info
header to the response.
9. Response sent back to UE
Finally the HTTP response is transmitted back to the UE. The response seen at the UE will be something like this:
HTTP/1.1 200 OK
Authentication-Info: qop=auth-int, cnonce="9856f65d8925a", nc=00000001
rspauth="a8478cea0d1f23ba975af498954c62d"
Content-Type: application/vnd.etsi.simservs+xml
Content-Length: 123
<communication-diversion>
...
</communication-diversion>
BSF Server
The BSF Server is a SLEE service that handles the GBA bootstrapping procedures (3GPP TS 33.220).
It receives bootstrapping requests from UEs (Ub interface), and contacts the HSS to generate authentication information (Zh interface). If bootstrapping for the UE is successful, the BSF writes an entry to a database, with an expiry time. When the UE later attempts to access the NAF, the NAF reads this database entry as part of its authentication procedure.
BSF Server operation
An overview of the bootstrapping process is shown below.
![Bootstrapping process with the BSF Server](images/bsf-arch.png)
As in NAF Authentication Filter operation, we will describe the BSF by walking through a typical bootstrapping transaction.
1. UE sends bootstrapping request
A NAF has instructed the UE to initiate the bootstrapping process (see NAF filter rejects with challenge).
The UE derives its BSF server’s address, which will be bsf.home1.net
for this example. The address is derived from the subscriber’s private identity as per 3GPP TS 23.003 §16.2.
The UE sends an initial bootstrap request to its BSF. This request contains an empty Authorization
header containing the private identity and realm, but empty nonce
and response
parameters. The empty parameters indicate to the BSF that this is a new bootstrapping request.
GET / HTTP/1.1
Host: bsf.home1.net
User-Agent: Some-user-agent/1.0 3gpp-gba-tmpi
Authorization: Digest username="user@home1.net", realm="bsf.home1.net",
nonce="", uri="/", response=""
If the UE wishes to use the GBA_Digest
mechanism for its authentication, then it must include the text 3gpp-gba-digest
in its User-Agent
header (not shown in this example).
![]() |
UEs may also use a TMPI (temporary private identity) instead of their actual private identity. This is supported, but not shown in this example. TMPI to IMPI mappings are stored in the impi_by_tmpi Cassandra table. |
The BSF service uses OpenCloud’s HTTP resource adaptor to receive HTTP requests and send responses.
2. BSF checks GUSS cache
The BSF needs to contact the HSS to request authentication information, but first it checks its GUSS cache to obtain the GBA User Security Settings for the subscriber.
If a cached GUSS entry is present, the BSF will send the GUSS timestamp to the HSS in the Zh request, to check if it is still up to date. If there is no GUSS entry, or it does not have a timestamp, the HSS will return its latest GUSS in the Zh response.
The BSF uses OpenCloud’s Cassandra-CQL resource adaptor to perform Cassandra queries.
3. BSF sends Zh request to HSS
The BSF sends a Zh request (see 3GPP TS 29.109 §4.2) using the Diameter Base resource adaptor. The Diameter Base RA can be configured to support many Diameter applications. In a Sentinel Authentication Gateway installation it is automatically configured to support the Zh Diameter application and AVPs.
The exact Zh request parameters will depend on which authentication method was requested by the UE: GBA_ME (which requires an AKA
auth vector) or GBA_Digest (which requires a SIP-Digest
auth vector).
Multimedia-Auth-Request (Command-Id 303, Application-Id 16777221 (Zh))
Session-Id: "12345@bsf.home1.net"
Vendor-Specific-Application-Id: (grouped)
Vendor-Id: 10415 (3GPP)
Auth-Application-Id: 16777221 (Zh)
Auth-Session-State: NO_STATE_MAINTAINED
Origin-Host: "bsf.home1.net"
Origin-Realm: "home1.net"
Destination-Realm: "home1.net"
Destination-Host: "hss.home1.net"
User-Name: "user@home1.net"
GUSS-Timestamp: <timestamp>
Multimedia-Auth-Request (Command-Id 303, Application-Id 16777221 (Zh))
Session-Id: "12345@bsf.home1.net"
Vendor-Specific-Application-Id: (grouped)
Vendor-Id: 10415 (3GPP)
Auth-Application-Id: 16777221 (Zh)
Auth-Session-State: NO_STATE_MAINTAINED
Origin-Host: "bsf.home1.net"
Origin-Realm: "home1.net"
Destination-Realm: "home1.net"
Destination-Host: "hss.home1.net"
User-Name: "user@home1.net"
GUSS-Timestamp: <timestamp>
SIP-Auth-Data-Item: (grouped)
3GPP-SIP-Authentication-Scheme: "SIP Digest"
4. HSS returns Zh response
The HSS generates a new authentication vector (AV) and sends this in the Zh response. If the GUSS has been updated since the GUSS timestamp sent in the Zh request, the new GUSS is included in the response.
4a. GBA_ME Zh response
The returned AKA AV is made up of these values:
-
RAND
— a randomly generated 16-byte value -
AUTN
— the authentication token, contains a sequence number that the UE can verify -
CK
— the confidentiality key -
IK
— the integrity key -
XRES
— the expected response from the UE.
Multimedia-Auth-Answer (Command-Id 303, Application-Id 16777221 (Zh))
Session-Id: "12345@bsf.home1.net"
Vendor-Specific-Application-Id: (grouped)
Vendor-Id: 10415 (3GPP)
Application-Id: 16777221 (Zh)
Auth-Session-State: NO_STATE_MAINTAINED
Origin-Host: "hss.home1.net"
Origin-Realm: "home1.net"
Result-Code: 2000
SIP-Auth-Data-Item: (grouped)
SIP-Authenticate: RAND || AUTN
Confidentiality-Key: CK
Integrity-Key: IK
SIP-Authorization: XRES
GBA-UserSecSettings: <guss id="user@home1.net">...</guss>
4b. GBA_Digest Zh response
The returned SIP-Digest AV is made up of these values:
-
HA1
— a hashed value derived from the username and password -
Realm
— the authentication realm for the user
Multimedia-Auth-Answer (Command-Id 303, Application-Id 16777221 (Zh))
Session-Id: "12345@bsf.home1.net"
Vendor-Specific-Application-Id: (grouped)
Vendor-Id: 10415 (3GPP)
Application-Id: 16777221 (Zh)
Auth-Session-State: NO_STATE_MAINTAINED
Origin-Host: "hss.home1.net"
Origin-Realm: "home1.net"
Result-Code: 2000
SIP-Digest-Authenticate: (grouped)
Digest-Realm: Realm
Digest-HA1: HA1
GBA-UserSecSettings: <guss id="user@home1.net">...</guss>
5. BSF stores new GUSS
If the Zh response included a new GUSS document, this is stored in the BSF’s GUSS cache.
6. BSF stores authentication vector
The BSF stores the AV values in the auth_vector
Cassandra table, with an expiry time (default 60s). When the challenge response arrives, any BSF node in the cluster can process it using the stored authentication vector details.
7. BSF sends challenge
The BSF uses the HTTP RA to send the UE a challenge, using values from the authentication vector.
7a. GBA_ME
For GBA_ME authentication, this uses the Digest Authentication and Key Agreement (AKA) scheme specified in RFC 3310.
The realm
value is derived from the domain part of the subscriber’s identity, i.e. the id
value in the GUSS data in the Zh response, prefixed with bsf.
. As a special case, if the subscriber’s identity domain ends with 3gppnetwork.org
(case-insensitive), then pub.
will be inserted before 3gppnetwork.org
.
HTTP/1.1 401 Unauthorized
Server: sentinel-gaa-bsf/1.0.0 3gpp-gba-tmpi
Date: Thu, 08 Jan 2004 10:13:17 GMT
WWW-Authenticate: Digest realm="bsf.home1.net",
nonce=base64(RAND || AUTN),
algorithm=AKAv1-MD5,
qop="auth-int",
opaque="37a63ff9d543ca979f467b05632670d1"
7b. GBA_Digest
For GBA_Digest authentication, this uses the HTTP-Digest scheme defined by RFC 2617.
The realm
value in the challenge comes directly from the realm
value in the Zh response.
8. UE sends challenge response
The UE extracts the RAND and AUTN values from the nonce
parameter. Because the UE shares the secret K with the HSS, it can independently calculate CK, IK, and RES.
The UE sends a challenge response in its next HTTP GET request.
GET / HTTP/1.1
Host: bsf.home1.net
User-Agent: Some-user-agent/1.0 3gpp-gba-tmpi
Authorization: Digest username="user@home1.net", realm="bsf.home1.net",
nonce=base64(RAND || AUTN), uri="/",
nc=00000001, cnonce="6e47229c626bb136c135"
response=(digest calculated using RES value)
9. BSF checks response, generates B-TID
The BSF receives the challenge response over HTTP, and checks that the digest value in the response
directive matches the value calculated by the BSF using XRES. If the digest values match, this means the UE has successfully authenticated. This value could have only been computed with knowledge of shared secret K, stored on the HSS and the UE’s tamper-proof SIM.
The BSF creates a Bootstrap Transaction Identifier (B-TID), which is used as the UE’s user name in subsequent NAF requests. The B-TID identifies a security association between the UE and the BSF. The lifetime of this security association is determined by the user’s GUSS, configured on the HSS.
The B-TID, RAND, CK and IK values are written to a record in the bootstrap_info
Cassandra table. The record is expired automatically according to the security association’s lifetime. The NAF Authentication Filter will read this record when authenticating requests to the NAF; see NAF filter retrieves bootstrap information.
10. BSF sends success response to UE
Finally the BSF sends an HTTP 200 OK response to the UE. This response contains the bootstrapped security association info in XML form, as per 3GPP TS 24.109 Annex C.
HTTP/1.1 200 OK
Server: sentinel-gaa-bsf/1.0.0 3gpp-gba-tmpi
Authentication-Info: rspauth="eb52a0caba3df288aff385925c1d05f9"
nc=00000001, cnonce="6e47229c626bb136c135"
Content-Type: application/vnd.3gpp.bsf+xml
Content-Length: 123
<?xml version="1.0" encoding="UTF-8"?>
<BootstrappingInfo xmlns="uri:3gpp-gba">
<btid>CH8Bm4AA/38BADV/f4DBAQ==@bsf.home1.net</btid>
<lifetime>2016-02-14T13:20:00Z</lifetime>
</BootstrappingInfo>
Now the UE has enough information to authenticate with a NAF; see UE sends challenge response using bootstrapped security association.
GUSS Usage
GUSS stands for "GBA (Generic Bootstrapping Architecture) User Security Settings."
These settings are provisioned for each subscriber in the HSS. This section covers how the Sentinel Authentication Gateway components access and use the GUSS.
What is the GUSS?
The GUSS for a particular subscriber determines what applications (NAFs) they can access, and may also define custom network- or application-specific parameters. It also specifies the lifetime of a bootstrapped security association, sometimes referred to as the "key lifetime."
The authoritative source for GUSS is the HSS. Consult your HSS documentation for details on provisioning GUSS.
The external representation of the GUSS is an XML document using the schema defined in 3GPP TS 29.109 Annex A. Here is an example:
<guss id="358500004836551@home1.net" xmlns="urn:3gpp:gba:GBAGUSSSchema-R9:2010-02">
<bsfInfo>
<lifeTime>86400</lifeTime>
</bsfInfo>
<Extension>
<timestamp>2008-09-10T11:12:13Z</timestamp>
</Extension>
<ussList>
<uss id="0" type="0" nafGroup="A">
<uids>
<uid>tel:+358504836551</uid>
<uid>sip:user@home1.net</uid>
</uids>
</uss>
<uss id="1" type="1" nafGroup="B">
<uids>
<uid>sip:other@home1.net</uid>
</uids>
<flags>
<flag>1</flag>
</flags>
</uss>
</ussList>
</guss>
![]() |
The lifetime of a security association created for this subscriber, in seconds. |
![]() |
The timestamp showing when the GUSS was last updated. |
![]() |
A USS entry containing two public identities. |
![]() |
A USS entry containing another public identity. |
![]() |
Flags that apply to the service type. |
The GUSS cache
The BSF Server maintains a cache of GUSS documents for subscribers that it has authenticated. This cache is implemented as a Cassandra table, by default called guss_by_impi
[1]. As the name implies, this table is indexed by the IMPI, the subscriber’s IMS private identity.
The GUSS cache serves two purposes:
-
When querying the HSS over Zh, the BSF can use the GUSS timestamp mechanism so that the HSS only returns the GUSS if it has changed since the last timestamp. Otherwise the cached GUSS can be used.
-
When any NAF Authentication Filter node needs the GUSS, it can be obtained from the replicated Cassandra database without the involvement of the BSF or HSS.
GUSS usage in the BSF Server
![]() |
Refer to the listing above to see the elements discussed here. |
The BSF Server uses these parts of the GUSS:
- Lifetime
-
The
/guss/bsfInfo/lifeTime
element specifies how long a bootstrapped security association is valid for, in seconds. If a UE attempts to authenticate with a NAF, using a security association that has expired, the NAF must instruct the UE to repeat the bootstrapping process over the Ub interface. While the security association is valid, the UE can authenticate with NAFs without needing to contact the BSF again. - Timestamp
-
The optional
/guss/Extension/timestamp
element specifies when the HSS last updated the GUSS. This is used to implement the simple caching mechanism specified in 3GPP TS 29.109 §4.2. If present, the BSF sends the last timestamp to the HSS in theGUSS-Timestamp
AVP in the Diameter Zh request. If the HSS supports this mechanism, and the GUSS has not been modified since the timestamp, then the Zh response just includes a flag to say the cached GUSS is still valid. Otherwise the Zh response will include the latest GUSS from the HSS.
If the cached GUSS does not have the timestamp
element, the BSF omits the GUSS-Timestamp
AVP from the Diameter Zh request. This forces the HSS to return the current GUSS in the Zh response. Upon receiving the GUSS in the Zh response, the BSF will store it in the GUSS cache table.
If the GUSS for a subscriber cannot be found, or the lifeTime
element is missing, the BSF uses a default lifetime of 86400s (24 hours).
GUSS usage in the NAF Authentication Filter
![]() |
Refer to the listing above to see the elements discussed here. |
The NAF Authentication Filter retrieves the GUSS from the GUSS cache table, and looks at the /guss/ussList
element. This may contain zero or more uss
element for different types of service or NAF groups.
The filter selects the uss
element(s) that match its configured service ID, type and NAF group. The uid
elements inside the uss
element specify the public identities for the subscriber that apply to the particular NAF.
If no matching uss
elements were selected, then the filter cannot determine a public identity for its NAF (XCAP in our case), so it must reject the request. If one or more uss
elements matched, all of the public identities are added to the X-3GPP-Asserted-Identity
header, which will be used by XCAP to authorize the request.
If the filter could not retrieve the GUSS for this subscriber, then it rejects the request. The GUSS is essential because it specifies the public identities that are accessing the NAF.
XCAP Support
Sentinel Authentication Gateway includes the following features to support XCAP.
![]() |
See also the XCAP Query Examples. |
XCAP architecture within the IMS
The following diagram illustrates Sentinel Authentication Gateway’s XCAP architecture within the IMS:
![ims xcap architecture](images/architecture-overview/xcap-support/ims-xcap-architecture.png)
![]() |
XCAP’s use within IMS is described in 3GPP TS 33.222. |
The Ut interface provides a user’s device with the ability to manipulate a configuration document. This document may contain user specific service settings such as privacy setting, communication barring and forwarding rules. TS 33.222 does not define how the MMTel-AS stores this document. However, 3GPP TS 29.364 defines a standardised XML schema for representing both the User and Operator settings for these services. TS 29.364 also defines the XML schema for transporting the user specific settings via the XCAP interface. This is called the "simservs" document. TS 29.364 also defines that an Application Server can store this service data on the HSS through the Sh interface as transparent data.
Sentinel AGW and XCAP
Sentinel AGW provides an XCAP server web application that implements the XCAP protocol towards the UE, and supports the XML schemas for user and operator data defined in TS 29.364, and stores and retrieves this information according to 29.364 in the HSS using Sh Transparent Data.
The diagram above shows several XCAP servers, as MMTEL-AS and Other-AS.
The Sentinel Authentication Gateway is co-located with the XCAP server application rather than being a discrete AP. See [Architecture Overview] for further information.
HTTP URIs and XCAP
If the XCAP host is running on xcap.server.net, the base XCAP URL for the XCAP Server application will be
https://xcap.server.net
The standard distribution of Sentinel AGW as an image contains nginx acting as a reverse proxy to support this base URL. If Sentinel AGW is installed in any other manner, the base XCAP URL for the XCAP Server application will be
https://xcap.server.net:8443
unless a similar reverse proxy is manually installed.
Active attributes inside the MMTel-Services document
There is a subtlety worth noting with respect to the per-service "active" attribute in the User portion of each MMTel Service.
The active attribute is specified as an optional boolean attribute in the XML schema for the simservs and MMTel-Services documents.
In an XML document, this means they can have three possible values:
-
does not exist (that is, attribute is not declared)
-
exists with the value
true
-
exists with the value
false
.
The specifications assign special meaning to these ‘active’ attributes when the attribute in the document does not exist:
-
during session processing - logic should treat a nonexistent attribute as though the value is
true
. -
XCAP requests from the user equipment are subject to special rules when the attribute does not exist:
-
A request is not allowed to directly or indirectly create or otherwise modify a nonexistent
active
attribute -
A request is allowed to configure other portions of that service’s data.
-
Regardless of the active
flag’s state (nonexistent, true
, or false
) a request can configure other portions of the service. For example, if Communication Diversion has no ‘active’ attribute, a request can configure communication diversion rules.
In summary, if an active flag is nonexistent this means that the user equipment cannot disable the feature. If the operator wants the user equipment to be able to enable or disable the feature, then the ‘active’ attribute should exist (and therefore be either true
or false
).
Other notable restrictions of XCAP
If a user’s MMTel-Services document does not contain a named service (for example, <communication-diversion>
) the UE cannot indirectly or directly create this element. Child elements of a named service can be modified/created/removed, provided that the named service is present.
The IMS Operator Determined Barring service has both session processing and XCAP related behaviour. The XCAP related Operator Determined barring behaviour enables the operator to disallow a user’s capability to view and change their service settings.
XCAP Query Examples
Below are examples of XCAP queries with Sentinel AGW.
![]() |
These examples assume that the XCAP Server is running on localhost with port 443. |
Get simservs document
Method |
GET |
---|---|
URL |
https://localhost/simservs.ngn.etsi.org/users/sip:user111000@home1.net/simservs.xml |
Headers |
X-3GPP-Asserted-Identity: sip:user111000@home1.net |
Payload |
N/A |
|
|
Response |
HTTP/1.1 200 OK |
Headers |
ETag: xxxxxxxxx Content-Type: application/vnd.etsi.simservs+xml |
Payload |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns2:simservs xmlns:ns2="http://uri.etsi.org/ngn/params/xml/simservs/xcap"> <originating-identity-presentation active="true"/> <originating-identity-presentation-restriction active="true"> <default-behaviour>presentation-not-restricted</default-behaviour> </originating-identity-presentation-restriction> </ns2:simservs> |
Get active state of OIP supplementary service
Method |
GET |
---|---|
URL |
https://localhost/simservs.ngn.etsi.org/users/sip:user111000@home1.net/simservs.xml/~~/simservs/originating-identity-presentation/@active |
Headers |
X-3GPP-Asserted-Identity: sip:user111000@home1.net |
Payload |
N/A |
|
|
Response |
HTTP/1.1 200 OK |
Headers |
ETag: xxxxxxxxx Content-Type: application/xcap-att+xml |
Payload |
true |
Get default-behaviour of OIR supplementary service
Method |
GET |
---|---|
URL |
https://localhost/simservs.ngn.etsi.org/users/sip:user111000@home1.net/simservs.xml/~~/simservs/originating-identity-presentation-restriction/default-behaviour |
Headers |
X-3GPP-Asserted-Identity: sip:user111000@home1.net |
Payload |
N/A |
|
|
Response |
HTTP/1.1 200 OK |
Headers |
ETag: xxxxxxxxx Content-Type: application/xcap-el+xml |
Payload |
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <default-behaviour>presentation-not-restricted</default-behaviour> |
Enable OIP supplementary service
Method |
PUT |
---|---|
URL |
https://localhost/simservs.ngn.etsi.org/users/sip:user111000@home1.net/simservs.xml/~~/simservs/originating-identity-presentation/@active |
Headers |
X-3GPP-Asserted-Identity: sip:user111000@home1.net Content-Type: application/xcap-att+xml |
Payload |
true |
|
|
Response |
HTTP/1.1 200 OK |
Headers |
ETag: xxxxxxxxx |
Payload |
N/A |
Disable OIP supplementary service
Method |
PUT |
---|---|
URL |
https://localhost/simservs.ngn.etsi.org/users/sip:user111000@home1.net/simservs.xml/~~/simservs/originating-identity-presentation/@active |
Headers |
X-3GPP-Asserted-Identity: sip:user111000@home1.net Content-Type: application/xcap-att+xml |
Payload |
false |
|
|
Response |
HTTP/1.1 200 OK |
Headers |
ETag: xxxxxxxxx |
Payload |
N/A |
Set OIR default-behaviour to presentation-restricted
Method |
PUT |
---|---|
URL |
https://localhost/simservs.ngn.etsi.org/users/sip:user111000@home1.net/simservs.xml/~~/simservs/originating-identity-presentation-restriction/default-behaviour |
Headers |
X-3GPP-Asserted-Identity: sip:user111000@home1.net Content-Type: application/xcap-el+xml |
Payload |
<default-behaviour>presentation-restricted</default-behaviour> |
|
|
Response |
HTTP/1.1 200 OK |
Headers |
ETag: xxxxxxxxx |
Payload |
N/A |
Set OIR default-behaviour to presentation-not-restricted
Method |
PUT |
---|---|
URL |
https://localhost/simservs.ngn.etsi.org/users/sip:user111000@home1.net/simservs.xml/~~/simservs/originating-identity-presentation-restriction/default-behaviour |
Headers |
X-3GPP-Asserted-Identity: sip:user111000@home1.net Content-Type: application/xcap-el+xml |
Payload |
<default-behaviour>presentation-not-restricted</default-behaviour> |
|
|
Response |
HTTP/1.1 200 OK |
Headers |
ETag: xxxxxxxxx |
Payload |
N/A |
XCAP Server
This section explains the XCAP Server which allows a client to read, write, and modify application configuration data in their simservs document, a virtual XML document composed of user accessible portions of one or more HSS documents.
It uses OpenCloud’s Sh Cache Microservice to communicate with the HSS.
![]() |
For information on this piece of the Sentinel product architecture, please see XCAP Support. |
Example XCAP queries
XCAP Query Examples provide several examples of XCAP queries to get and modify the simservs document.
Normalization
The XCAP server tries to normalize any numbers contained in CDIV rule targets and ICB/OCB conditions before accepting the request. If any number cannot be normalized, the request is rejected. Normalization is done using the Normalization Component.
Normalization is controlled by the NormalizationEnabled
profile attribute in the XCAPConfig
profile in the XCAPConfigProfileTable
profile table.
North American Numbering Plan Normalization
The XCAP server includes North American Numbering Plan (NANP) normalisation rules that can be used to update the CDIV rule targets. The feature is activated using the NanpNormalizationEnabled
property in the XCAPConfig
profile in the XCAPConfigProfileTable
profile table.
The NANP normalization rules are as follows:
-
if the numbers length equals 10 and does not start with the country code then add the country code with international prefix.
For example if the number is '22333444445' then the CDIV target is set to '+122333444445'
-
if the numbers length equals 10 and starts with the country code e.g. '1' then add international prefix.
For example if the number is '1223334444' then the CDIV target set is to '+12233344444'.
MMTelCDIV Non-Provisionable Retarget URIs
The MMTelCDIV feature can be configured with a list of NonProvisionableRetargetURIs
. As the name implies, any XCAP request containing a diversion rule with a target equal to a URI on this list, after they are both normalized, is rejected.
Operator Determined Barring
When any request is received, the XCAP server checks if the subscriber is barred from using the XCAP server (due to Barring of Supplementary Services Management
being set), or when updating diversion rules, is barred from registering diverted numbers (Diverted to Address Registration Barring
). To do so, it queries the Sh Cache Microservice for the IMS-ODB-Information
service indication. If the XCAP server determines the request is not allowed, it is rejected with response code 403.
Configuring the Sentinel Authentication Gateway
This section explains how to configure low level details for the Sentinel Authentication Gateway BSF Server, NAF Authentication Filter, and Sentinel XCAP Server.
This documentation is primarily for support purposes to assist with low level configuration tasks. Customers should refer to the Rhino VoLTE TAS Configuration and Management Guide to configure the Appliances rather than this documentation.
It includes:
BSF Configuration
This section explains how to configure the BSF Service and the resource adaptors it uses.
Below are instructions for configuring BSF SLEE profile attributes and the HTTP, Cassandra-CQL, and Diameter Base resource adaptors.
BSF SLEE profile
The BSF Server uses a SLEE profile for most of its configuration. The profile ID is bsf-config/default
. It may be updated using Rhino Element Manager or rhino-console
commands.
Below are descriptions and defaults for the available profile attributes, followed by instructions for viewing and updating the current configuration.
Attribute name | Description | Default value |
---|---|---|
HSSDestinationRealm |
The Diameter |
zh-realm |
HSSDestinationHost |
The Diameter |
zh-server |
IncludeSIPAuthSchemeIfDefaultWhenResyncing |
Include |
false |
CassandraQueryTimeoutMS |
The Cassandra query timeout in ms. |
5000 |
Viewing the current configuration
To view the current BSF configuration, use the listprofileattributes
command in rhino-console. For example:
> listprofileattributes bsf-config default
CassandraQueryTimeoutMS=5000
HSSDestinationHost=zh-server
HSSDestinationRealm=zh-realm
Updating profile attributes
To update one or more profile attributes, use the setprofileattributes
command in rhino-console. For example:
> setprofileattributes bsf-config default HSSDestinationRealm home1.net HSSDestinationHost hss.home1.net
Set 2 attributes in profile bsf-config/default
![]() |
Changes to BSF profile attributes take effect immediately. No service restart is required. |
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 bsf-http-ra
.
Below are the HTTP RA configuration properties that are relevant to the BSF Server .
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 The format is
|
Not set. |
ListenAddress |
The hostname or IP address that the HTTP RA will bind to. If |
0.0.0.0 |
ListenPort |
The TCP port number that the HTTP RA will listen on. If |
8001 |
SecureListenPort |
The TCP port number that the HTTP RA will listen on for HTTPS requests. If this is set, then |
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 |
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 bsf-http-ra ListenPort 9000
> deactivateraentity bsf-http-ra
> activateraentity bsf-http-ra
Cassandra-CQL RA
The Cassandra-CQL RA is used to perform queries against the Cassandra database. The name of the Cassandra-CQL RA entity created by default is cassandra-cql-ra
.
Below are the Cassandra-CQL RA configuration properties that are relevant to the BSF Server.
Property name | Description | Default value |
---|---|---|
keyspace |
The Cassandra keyspace that will be used for all queries. |
opencloud_gaa_bootstrap_info |
cassandraContactPoints |
Comma separated list of hostname/ip addresses and ports of cassandra nodes used to discover the cluster topology. |
localhost:9042 |
policy.protocol.port |
The TCP port used to connect to a Cassandra node. |
9042 |
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 cassandra-cql-ra cassandraContactPoints 10.0.0.1:9042,10.0.0.2:9042
> deactivateraentity cassandra-cql-ra
> activateraentity cassandra-cql-ra
![]() |
See the Cassandra CQL Resource Adaptor Guide for more information. |
Diameter Base RA
The Diameter Base RA is used to communicate with the HSS using the Zh Diameter application (3GPP TS 29.109). The name of the Diameter Base RA entity created by default is diameterbase
.
Most of the Diameter Base RA’s configuration is defined in XML strings stored in a SLEE profile. The default profile ID used for configuration is DiameterConfig/DiameterZhConfig
.
Below are the profile attributes that affect the BSF Server operation.
Profile attribute | Description | Default value |
---|---|---|
PeerTable |
Describes the Diameter peers that the RA can connect to. Typically this will be the primary and secondary HSS hosts. |
|
RealmTable |
Describes how different applications are routed to Diameter peers. In the BSF’s case we just want everything to go to the HSS. |
|
![]() |
The ${zh-server.address} and similar properties in the XML above are obtained from the config.properties file of the deployment module. After deployment in the SLEE, these profiles will contain the substituted values. |
Updating profile attributes
The profile values can be edited manually in Rhino Element Manager or rhino-console but ideally should be managed with declarative config.
![]() |
See the Diameter Resource Adaptors Guide for more information. |
XCAP Configuration
This section explains how to configure the XCAP Service and the resource adaptors it uses.
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 |
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 |
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 |
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 |
ServiceType |
Default |
These parameters are used by the NAF filter to select which public identities in USS elements are added to the the |
ServiceID |
Default |
|
NAFGroup: |
Default |
|
MaxNonceCountValue |
Default |
If the Nonce count ( |
NonceLifetimeMillis |
Default |
A nonce stored in cassandra is valid for this many milliseconds. |
NonceCassandraKeyspace |
Default |
The cassandra keyspace which the NAF filter uses for storing nonces. |
ReadUaCipherSuiteNameFromHeader |
Default |
When the UE connects to the server via a proxy, the proxy must add the negotiated cipher suite for its UE connection to a When the UE connects directly to the server, this parameter should be |
ForcedTLSSuiteName |
Default |
When not empty, this setting overrides the cipher suite to a fixed value. Use only in consultation with Metaswitch support. |
CassandraQueryTimeoutMillis |
Default |
The timeout in milliseconds for cassandra queries to get the bootstrap information. |
Configuring behaviour
Parameter | Type | Description |
---|---|---|
UseSerialShCMRequests |
Default |
Determines whether requests for the HSS documents needed to create a user’s simservs document are performed in parallel ( A value of |
UseLegacyNonSpecCompatibilityMode |
Default |
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 |
Default |
Whether to apply normalization to numbers contained in CDIV rule targets and ICB/OCB conditions. See Normalization. |
NanpNormalizationEnabled |
Default |
Whether to apply the North American Numbering Plan normalization rules to update numbers contained in CDIV rule targets that are 10 digits in length. See North American Numbering Plan Normalization. |
SimservsSchemaValidationEnabled |
Default |
When |
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 The format is
|
Not set. |
ListenAddress |
The hostname or IP address that the HTTP RA will bind to. If |
localhost |
ListenPort |
The TCP port number that the HTTP RA will listen on. If |
8080 |
SecureListenPort |
The TCP port number that the HTTP RA will listen on for HTTPS requests. If this is set, then |
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 |
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 |
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 |
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 theOrder
parameter as follows:-
The
HSSPath
expression is evaluated to select the source element and its descendants from the HSS document corresponding to theServiceIndication
. -
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 theSimservsPath
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.
-
Tracing
This section explains how to configure tracing in the BSF Server.
Configuring BSF Server tracing
The BSF Server is a SLEE service which uses the standard SLEE tracing features. When setting tracer levels in rhino-console, you must specify the service and SBB IDs that you want to trace. The BSF’s service ID is:
name=sentinel-gaa-bsf,vendor=OpenCloud,version=4.1
Its SBB IDs are:
name=sentinel-gaa-bootstrap-sbb,vendor=OpenCloud,version=4.1
name=sentinel-gaa-zh-sbb,vendor=OpenCloud,version=4.1
Fortunately you do not need to enter the entire service or SBB IDs when setting tracer levels. The settracerlevel
command in rhino-console supports tab-completion and can match simple patterns. For example, to enable "Finest" tracing for all SBBs in the BSF service in rhino-console
, you could use:
settracerlevel sbb service=ServiceID[name=sentinel-gaa-bsf,*],sbb=* root Finest
Cassandra Storage
This page describes how the Sentinel Authentication Gateway uses a Cassandra database for sharing bootstrapped security association details between the BSF service and NAF Filter.
Below are details of the database configuration, performance recommendations, and schema.
Cassandra database configuration
An administrator is required to download and set up a Cassandra Database.
![]() |
Check the Sentinel Authentication Gateway Compatibility Guide for supported versions of Cassandra. |
![]() |
Before installation, read Cassandra’s Getting Started page. |
For a test system, a single Cassandra database instance may be sufficient if redundancy is not a requirement.
Minimal production recommendations
For a minimal production system, in order to tolerate a single failure in the Cassandra database there should be at least three nodes configured per site. The Cassandra replication factor should be 3
.
Higher replication factors can be used on larger clusters. The recommended consistency level for this storage system is the LOCAL_QUORUM
consistency level. All read and write queries are programmed to use LOCAL_QUORUM
as the consistency level.
It is assumed that in a multi-site deployment, an appropriate Snitch
and topology strategy are used. As a basis, we suggest use of the NetworkTopologyStrategy
and GossipingPropertyFileSnitch
, then reading the relevant links below to review this selection.
Performance recommendations
OpenCloud recommend that Cassandra’s data commit log directories are on different physical devices (different disks). If this is not possible, then different partitions on the same device is acceptable.
(OpenCloud performance testing shows that there are benefits to using different partitions on the same device when there are 1000 or more Cassandra DB transactions per second.)
Data schema
Cassandra’s tables exist in a 'keyspace', which for illustrative purposes can be thought of as a 'database' in SQL implementations.
Creating the keyspaces
Creating a keyspace is simple, but note the following:
-
The keyspaces must be named
opencloud_gaa_bootstrap_info
andopencloud_nonce_info
. -
For a production environment, the keyspaces can be created such that it is replicated. A sample CQL command for creating such a keyspace is:
CREATE KEYSPACE IF NOT EXISTS opencloud_gaa_bootstrap_info WITH REPLICATION={'class' : 'SimpleStrategy', 'replication_factor' : 3 }; CREATE KEYSPACE IF NOT EXISTS opencloud_nonce_info WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 3 };
-
For testing purposes, replication may not be necessary. A sample CQL command for creating such keyspaces is:
CREATE KEYSPACE IF NOT EXISTS opencloud_gaa_bootstrap_info WITH REPLICATION={'class' : 'SimpleStrategy', 'replication_factor' : 1 }; CREATE KEYSPACE IF NOT EXISTS opencloud_nonce_info WITH REPLICATION={'class' : 'SimpleStrategy' ,'replication_factor' : 1 };
Creating the tables
Once the keyspaces have been created, the required tables can be created. The following CQL statements provide both the structure and insight into the tables that are required:
USE opencloud_gaa_bootstrap_info;
CREATE TABLE IF NOT EXISTS impi_by_tmpi (
tmpi text,
impi text,
PRIMARY KEY (tmpi)
)
WITH gc_grace_seconds = 172800; // 2 days
CREATE TABLE IF NOT EXISTS guss_by_impi (
impi text,
guss_data blob,
PRIMARY KEY (impi)
)
WITH gc_grace_seconds = 172800; // 2 days
CREATE TABLE IF NOT EXISTS auth_vector (
id blob,
impi text,
tmpi text,
realm text,
rand blob,
autn blob,
xres blob,
ck blob,
ik blob,
ha1 blob,
key_lifetime int,
used boolean,
PRIMARY KEY (id)
)
WITH gc_grace_seconds = 172800; // 2 days
CREATE TABLE IF NOT EXISTS bootstrap_info (
btid text,
impi text,
ck blob,
ik blob,
rand blob,
PRIMARY KEY (btid)
)
WITH gc_grace_seconds = 172800; // 2 days
USE opencloud_nonce_info;
CREATE TABLE IF NOT EXISTS nonce_storage (
nonce text,
timestamp double,
remoteAddr text,
seen text,
PRIMARY KEY(nonce)
)
WITH gc_grace_seconds = 172800; // 2 days
Tools
This section describes the tools provided by Sentinel Authentication Gateway for generating and verifying keys during testing.
All of these are command-line Java-based tools, in the build
directory of the SDK:
build/bin/sentinel-gaa-tools
![]() |
The tools will need execute permissions added (for example, 'chmod 755 naf-key') |
NAF Key
The naf-key
tool generates a NAF-specific shared key for a bootstrapping session. You use this key as the password
input for the NAF Digest tool.
Example usage
Here is typical naf-key
output:
./naf-key -ciphersuite TLS_RSA_PSK_WITH_AES_256_CBC_SHA -algorithm milenage -k 01230123012301230123012301230123 -op 01230123012301230123012301230123 -nonce d34d35d36d37d38d39d3ad3bd3cd3dd1 -impi foo -naf localhost -d
Used 'milenage' to calculate:
RAND[d35db7d35db7d35db7d35db7d35db7d3]
XRES[9e36e4504d6c1642]
CK[54db12b604c37068d5de7002ad73d549]
IK[f48eaf850176834c9f17771b43951a6e]
14:26:31,522 DEBUG <main> [sentinel.gaa.keydata] generateKsNAF:
14:26:31,522 DEBUG <main> [sentinel.gaa.keydata] ck: CK[5f12bf48d85e711bec89ebe7d2ce23be]
14:26:31,522 DEBUG <main> [sentinel.gaa.keydata] ik: IK[142c4a118862568e3e58488ae96fc5e9]
14:26:31,522 DEBUG <main> [sentinel.gaa.keydata] ks: Ks[5f12bf48d85e711bec89ebe7d2ce23be142c4a118862568e3e58488ae96fc5e9]
14:26:31,522 DEBUG <main> [sentinel.gaa.keydata] rand: RAND[d34d35d36d37d38d39d3ad3bd3cd3dd1]
14:26:31,522 DEBUG <main> [sentinel.gaa.keydata] impi: foo
14:26:31,523 DEBUG <main> [sentinel.gaa.keydata] nafAddress: localhost
fd6843b2e9b2580141821dfbe37cd16cb099f0d897fb4be68f80948d2d8ce1d3
Available flags
Here is the help output showing the tool options:
Usage: naf-key [options] Options: -algorithm The HSS algorithm Default: milenage -ciphersuite The TLS ciphersuite name used for the UE<->NAF HTTPS connection -d Show debugging output Default: false -gbadigest Process as GBA_Digest Default: false -h, -help Display this usage message Default: false * -impi The IMPI (private identity) for this security association -k The 128-bit subscriber key -k2 The 256-bit Ks key for GBA_Digest -list-ciphersuites List supported cipher suite names Default: false * -naf The NAF address used by the UE (Host header) * -nonce The NONCE value (base64) -o Output format for shared key (base64 or hex) Default: base64 -op The 128-bit Operator Variant Algorithm Configuration Field
There are two main modes of operation:
![]() |
At the moment, for calculations not using the GBA_Digest algorithm, only the milenage algorithm is supported. |
NAF Digest Calculation
The naf-digest
calculation tool creates an HTTP message digest response.
Example usage
Here is typical naf-digest
output:
./naf-digest -method GET -body bodyOfMessage -realm foo -qop auth-int -username btid -uri / -password kSny510OWEdJfE64NaObkys/wh2cJ4+M+qSjTsJ2GjI= -nc 1 -cnonce foo -nonce bar -d
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] calculateMessageDigest:
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] hashFunc:Hashing.md5()
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] username: btid
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] password: "kSny510OWEdJfE64NaObkys/wh2cJ4+M+qSjTsJ2GjI=" (0x6b536e793531304f5745644a664536344e614f626b79732f776832634a342b4d2b71536a54734a32476a493d)
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] realm: foo
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] method: GET
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] uri: /
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] qop: auth-int
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] nonce: bar
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] nc: 1
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] cnonce: foo
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] body: [626f64794f664d657373616765]
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] HA1: [cc6a87adf243559f903fc0007be77083]
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] HA2: [27bf6af15f6e290f34330a07b896e363]
14:31:55,631 DEBUG <main> [sentinel.gaa.naf.digest] => DIGEST: [4a5ca659f406b6625d143adbd4124f3c]
4a5ca659f406b6625d143adbd4124f3c
Available flags
Here is the help output showing the tool options:
Usage: naf-digest [options] Options: -body The entity-body of the challenge response Default: <empty string> * -cnonce Client nonce string in challenge response -d Show debugging output Default: false -gbadigest Use GBA_Digest values and algorithms Default: false -h, -help Display this usage message Default: false -hexpassword The password in hex encoding (commonly the output from the 'naf-key' tool). Cannot be used with '-password'. -method The HTTP method (For example GET or PUT) * -nc Nonce count string from challenge * -nonce Nonce string from challenge -o Output format for digest value (base64 or hex) Default: hex -password The password string. Cannot be used with '-hexpassword'. -qop Quality of protection Default: auth-int * -realm The authentication realm * -uri The Request-URI * -username B-TID value from the challenge response
![]() |
The password used in the digest calculation is specified using either |
GBA_Digest passwd Calculation
The gbad-passwd
calculation tool calculates the passwd value required for GBA_Digest calculations. This will usually be used as input to the gbad-shared-key
tool (see later).
Example usage
Here is typical gbad-passwd
output:
./gbad-passwd -username testIMPI -realm test.realm -password 65666768696a
Base64: n2fgl9BvBytQI4zc/SbHYknQ8stFWNtDFP4yGCNzapU=
Hex: 9f67e097d06f072b50238cdcfd26c76249d0f2cb4558db4314fe321823736a95
Available flags
Here is the help output showing the tool options:
Usage: gbad-passwd [options] Options: -d Show debugging output Default: false -h, -help Display this usage message Default: false * -password The user's password, as a hex string * -realm The authentication realm * -username The username
GBA_Digest Shared Key Calculation
The gbad-ks
calculation tool calculates the Ks
value required for GBA_Digest calculations. This will usually be used as input to the naf-key
tool described earlier.
Example usage
Here is typical gbad-ks
output:
./gbad-ks -username testIMPI -realm test.realm -passwd 9f67e097d06f072b50238cdcfd26c76249d0f2cb4558db4314fe321823736a95 -resp 8995645af39863494658aa3204b5fce309037621e1188d460b8cc846410ade89
Base64: 2FIpxB30hQVbXuU6zzFr7AUlTq1uA/ZxwIKq1r7+3ns=
Hex: d85229c41df485055b5ee53acf316bec05254ead6e03f671c082aad6befede7b
Available flags
Here is the help output showing the tool options:
Usage: gbad-ks [options] Options: -d Show debugging output Default: false -h, -help Display this usage message Default: false * -passwd The calculated passwd (as a hex string) * -realm The authentication realm * -resp The 256-bit RFC7616 resp value. Quotes will be added automatically. * -username The username