Sentinel Authentication Gateway Guide

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.

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.

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.

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.

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

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.

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.

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

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:

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.

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.

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.

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.

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:

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.

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 XCAP servlet.

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 settings for service ID, service type and NAF group. See GUSS usage in the NAF Authentication Filter for details.

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 servlet container knows that the request should to be routed to the XCAP servlet, based on the port used and the rewrite rules in the nginx reverse proxy.

The request header seen by the XCAP servlet looks like this:

The XCAP servlet 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 XCAP servlet 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.

The XCAP servlet generates a 200 OK response with the communication-diversion element, and returns from its service() method. 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.

Finally the HTTP response is transmitted back to the UE. The response seen at the UE will be something like this:

DNS "A" records have been set up for new externally-visible hostnames of the back-end web servers which will serve the request, resolving to the externally-visible IP address of the NAF Authentication Filter. This causes requests to those web servers to arrive at the NAF Authentication Filter.

The Proxy Servlet inspects the Host: HTTP header on the incoming request, to determine the service that the request was intended for. It looks up that hostname in its configuration, to see which back-end server it needs to proxy the request to. At this point, if the Proxy Servlet does not recognise the hostname, then it returns a 404 Not found response.

The servlet strips the leading /rem/authproxy from the URL path, and combines it with the mapped hostname to calculate the final URL that will be requested. It strips the Authorization, Host and X-3GPP-Intended-Identity headers from the request, if present, then makes the request.

When the response comes back, the Proxy Servlet passes it back to the filter, and processing continues with step 8 as above.

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.

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

The BSF service uses OpenCloud’s HTTP resource adaptor to receive HTTP requests and send responses.

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.

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

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.

If the Zh response included a new GUSS document, this is stored in the BSF’s GUSS cache.

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.

The BSF uses the HTTP RA to send the UE a challenge, using values from the authentication vector.

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.

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.

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.

Now the UE has enough information to authenticate with a NAF; see UE sends challenge response using bootstrapped security association.

To view the current BSF configuration, use the listprofileattributes command in rhino-console. For example:

To update one or more profile attributes, use the setprofileattributes command in rhino-console. For example:

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

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

The profile values can be edited manually in Rhino Element Manager or rhino-console. Alternatively update config.properties in your UNRESOLVABLE BXREF: installing-the-bsf-server#update-config[deployment module].

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.

Creating a keyspace is simple, but note the following:

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:

Here is typical naf-key output:

Here is the help output showing the tool options:

There are two main modes of operation:

Here is typical naf-digest output:

Here is the help output showing the tool options:

Here is typical gbad-passwd output:

Here is the help output showing the tool options:

Here is typical gbad-ks output:

Here is the help output showing the tool options: