Skip to main content

Authenticating Subsequent Requests

Once this initial authentication process is complete, future requests to secure endpoints will require the use of the authentication token obtained from the server. Do note that the body of the request and response will be encrypted. Read more in Encrypted Requests and Responses.

Authentication Token​

The authentication token is a JSON Web Token (JWT) that contains the following claims:

  • sub: The subject of the token, which is the username.
  • iat: The issued at time of the token, which is the current time.
  • exp: The expiration time of the token.
    • Currently the token expires after one hour.
  • uuid: Comms UUID used in the Proof-of-Possession (PoP) process.

An example of JWT (which has an invalid JWT signature) is as follows:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICAgInN1YiI6ICJNeUNvb2xVc2VybmFtZSIsCiAgICAiaWF0IjogMTUxNjIzOTAyMiwKICAgICJleHAiOiAxNTE2MjQyNjIyLAogICAgInV1aWQiOiAiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIgp9.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

which has the following data (expressed in JSON):

{
    "sub": "MyCoolUsername",
    "iat": 1516239022,
    "exp": 1516242622,
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Proof-of-Possession (PoP)​

A proof-of-possession (PoP) value needs to be computed in addition to providing the authentication token. This value is computed using a HMAC of the message <METHOD> <PATH> <TIMESTAMP> <NONCE>, where

  • <METHOD> is the HTTP method (e.g., GET, POST, PUT, DELETE) in ALL CAPS;
  • <PATH> is the path of the request (e.g., /some/path/here);
  • <TIMESTAMP> is the current time in seconds since the Unix epoch; and
  • <NONCE> is a random 16 byte value.
For WebSockets

Some WebSocket endpoints require a proof-of-possession as well. In this case, the only change is that the <METHOD> is the string WEBSOCKET.

Why Not Include the Body?

The body of the message need not be included in the HMAC calculation since it is already verified by the encryption:

  • If the request does not include a body, then there is already nothing to check;
  • If the request does include a body, the body should be encrypted using AES-GCM, which authenticates the data sent. Since the data sent uses the secret master key, no malicious actor can spoof the data; thus no need to check.

The HMAC's key is the SRP master key KK and the hash algorithm used is SHA-256. The output PoP value is encoded using Base64 for ease of transmission.

A CyberChef demonstration of the PoP generation process can be found here.

Proving Possession​

Requests to secure endpoints need both the authentication token and a PoP header, and the request/response body will be encrypted using the SRP master key.

To prove that the user is who they claim to be, their request will need to include two headers:

  • Authorization: The format of the header is Bearer <JWT> where <JWT> is the authentication token.
  • X-SRP-PoP: The format of the header is <TIMESTAMP> <NONCE> <PoP> where <PoP> is the Base64 encoded PoP value computed as described above and <TIMESTAMP> and <NONCE> are the timestamp and nonce used to compute the PoP value, respectively.

Failing to provide both headers will result in a 401 Unauthorized response.