Sentinel Authentication Gateway Guide

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

Introduction to 3GPP GAA

the main roles, interfaces, and procedures in 3GPP GAA.

Architecture Overview

the components of the Sentinel Authentication Gateway and how they implement 3GPP GAA.

XCAP Server

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.

Configuration

how to configure low level details for the Sentinel Authentication Gateway BSF Server, NAF Authentication Filter, and Sentinel XCAP Server.

Cassandra Storage

how the Sentinel Authentication Gateway uses a Cassandra database for sharing bootstrapped security association details between the BSF service and NAF Filter.

Tools

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.

Figure 1. Simple GAA network model (3GPP TS 33.222 §5.1)

Table 1. GAA roles
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.

Table 2. GAA interfaces
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 token 3gpp-gba in the User-Agent header
If the UE wishes to use GBA_Digest authentication then it must include the product token 3gpp-gba-digest in the User-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 the WWW-Authenticate header includes the directive realm=3GPP-bootstrapping@naf.home1.net
for GBA_Digest the WWW-Authenticate header includes the directive realm=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:

Figure 2. Simple GAA network model (3GPP TS 33.220 §5.1)

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.

Figure 3. Sentinel Authentication Gateway architecture

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.

Figure 4. Authentication process with the NAF Authentication Filter

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 token 3gpp-gba-digest in its User-Agent header (not shown in this example).
if the UE wishes to use the GBA_ME mechanism, then it must include the product token 3gpp-gba in its User-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.

Initial XCAP request

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.

Challenge from NAF to UE

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:

Challenge response from UE to NAF

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:

Authenticated request passed to Sentinel XCAP Server

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:

Successful XCAP HTTP response

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.

Figure 5. Bootstrapping process with the BSF Server

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.

Initial bootstrap 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).

Diameter Zh request (GBA_ME)

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>

Diameter Zh request (GBA_Digest)

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.

Diameter Zh response

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

Diameter Zh response

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.

Challenge from BSF to UE (GBA_ME example)

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.

Challenge response from UE to BSF

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.

Successful bootstrapping response

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:

Example GUSS XML

<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 the GUSS-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.

XCAP architecture within the IMS

The following diagram illustrates Sentinel Authentication Gateway’s XCAP architecture within the IMS:

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:
1. A request is not allowed to directly or indirectly create or otherwise modify a nonexistent active attribute
2. 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>

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

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>

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

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

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

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

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 — how to configure the BSF Service and the resource adaptors it uses
Tracing — how to configure tracing in the BSF Server and NAF Authentication Filter.
XCAP Configuration — how to configure the Sentinel XCAP Server and the resource adapters it uses.

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

Attribute name	Description	Default value
HSSDestinationRealm	The Diameter `Destination-Realm` value that will be set in Zh requests to the HSS.	zh-realm
HSSDestinationHost	The Diameter `Destination-Host` value that will be set in Zh requests to the HSS.	zh-server
IncludeSIPAuthSchemeIfDefaultWhenResyncing	Include `SIP-Authentication-Scheme` AVP in Zh Resync requests even when the default auth scheme `Digest-AKAv1-MD5` is in use.	false
CassandraQueryTimeoutMS	The Cassandra query timeout in ms.	5000

HSSDestinationRealm

The Diameter Destination-Realm value that will be set in Zh requests to the HSS.

 zh-realm

 HSSDestinationHost

The Diameter Destination-Host value that will be set in Zh requests to the HSS.

 zh-server

 IncludeSIPAuthSchemeIfDefaultWhenResyncing

Include SIP-Authentication-Scheme AVP in Zh Resync requests even when the default auth scheme Digest-AKAv1-MD5 is in use.

 false

 CassandraQueryTimeoutMS

The Cassandra query timeout in ms.

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

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.	0.0.0.0
ListenPort	The TCP port number that the HTTP RA will listen on. If `BindAddresses` is specified, then this property is ignored.	8001
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.

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.

0.0.0.0

ListenPort

The TCP port number that the HTTP RA will listen on. If BindAddresses is specified, then this property is ignored.

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

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.

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

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.	`<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE peer-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.1.0//EN" "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.dtd"> <peer-table> <peer connectAtStartup="true"> <uri>${zh-server.uri}</uri> <address>${zh-server.address}</address> </peer> </peer-table>`
RealmTable	Describes how different applications are routed to Diameter peers. In the BSF’s case we just want everything to go to the HSS.	`<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE realm-table PUBLIC "-//Open Cloud Ltd.//DTD Diameter Realm Table Configuration 1.0//EN" "http://www.opencloud.com/dtd/diameter-realm-table-1.0.dtd"> <realm-table> <default-route> <peer-ref> <hostname>${zh-server.hostname}</hostname> <metric>1</metric> </peer-ref> </default-route> </realm-table>`

PeerTable

Describes the Diameter peers that the RA can connect to. Typically this will be the primary and secondary HSS hosts.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE peer-table PUBLIC
  "-//Open Cloud Ltd.//DTD Diameter Peer Table Configuration 1.1.0//EN"
  "http://www.opencloud.com/dtd/diameter-peer-table-1.1.0.dtd">
<peer-table>
  <peer connectAtStartup="true">
    <uri>${zh-server.uri}</uri>
    <address>${zh-server.address}</address>
  </peer>
</peer-table>

RealmTable

Describes how different applications are routed to Diameter peers. In the BSF’s case we just want everything to go to the HSS.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE realm-table PUBLIC
  "-//Open Cloud Ltd.//DTD Diameter Realm Table Configuration 1.0//EN"
  "http://www.opencloud.com/dtd/diameter-realm-table-1.0.dtd">
<realm-table>
  <default-route>
    <peer-ref>
      <hostname>${zh-server.hostname}</hostname>
      <metric>1</metric>
    </peer-ref>
  </default-route>
</realm-table>

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

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.

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

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.
NanpNormalizationEnabled	`boolean` Default `false`	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	`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`.

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.

NanpNormalizationEnabled

boolean

Default false

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

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

Parameter	Type	Description
ShCMDestinationUrl	`String` Default `"http://localhost:8088"`	The address of the Sh-Cache Microservice used to access the HSS.

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

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.

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.

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

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

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.

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.

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.

Cassandra references

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 and opencloud_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:

GBA_Digest (specified with the -gbadigest flag), which requires that the -k2 flag is also supplied.
Non-GBA_Digest (specified by omitting the -gbadigest flag), which requires that the -k and -op flags are also supplied.

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 -password or -hexpassword. The -password parameter may be used if the password is a simple ASCII string. If the password is a binary value (such as RES/XRES), or contains non-ASCII characters, then -hexpassword must be used instead. This means the password bytes are specified exactly without any character encoding issues.

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