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

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

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