Entity Authentication

Entity authentication identifies the entity associated with a message, and also provides for encryption and integrity protection of message data.

The sender of a message must authenticate themselves using one of two mutually exclusive mechanisms:

• Entity authentication using entity authentication data containing the sender identity and any additional data required for message decryption and authentication.
• Master token authentication using a master token containing the sender identity and session encryption and authentication keys.

It is generally desired to migrate from entity authentication to master token authentication for a number of reasons:

• Some entity authentication schemes do not support message encryption or authentication, and therefore do not provide message integrity protection.
• Execution of cryptographic operations associated with entity authentication data is often more computationally expensive.
• The use of session keys associated with master tokens reduces the amount of data processed by a particular key and thus increases the attack difficulty.

Entity authentication must occur prior to user authentication, although possibly within the same MSL transaction. It is assumed that entity authentication is always possible (i.e. there is no application state where a message cannot include entity authentication data or a master token).

Successful cryptographic verification of the message data using the key(s) associated with the entity authentication data or master token serves to authenticate the entity as well as verify the message data has not been tampered with. The encryption key(s) associated with the entity authentication data or master token are used to encrypt the message data during transmission.

Entity Authentication Data

When using entity authentication data, the message data is encrypted if the entity authentication scheme supports encryption and authenticated and integrity protected if the entity authentication scheme supports authentication. If encryption is supported it is not necessary to perform key exchange prior to the transmission of confidential data. If authentication is supported it is not necessary to perform key exchange prior to the transmission of data that must be integrity protected. The cryptographic algorithms and modes used, and ciphertext and signature envelopes used, are specific to each entity authentication scheme.

The following are some examples of entity authentication schemes and their corresponding entity authentication data contents along with their form of message encryption and authentication if supported. A more detailed description of entity authentication schemes is documented in the Configuration Guide.

Scheme	Entity Authentication Data	Encryption	Authentication
Model Group Keys	Entity identity mapping onto unique keys derived from the identity and a shared secret.	AES-128-CBC	HMAC-SHA256
Pre-shared Keys	Entity identity mapping onto pre-shared secret keys.	AES-128-CBC	HMAC-SHA256
RSA	Entity identity and RSA public key, associated with a trusted private key.	none	RSA signature
Unauthenticated	Entity identity with no associated keys.	none	none
X.509	X.509 certificate containing the entity identity and an RSA public key, signed by a trusted certificate authority.	none	RSA signature

Entity Authentication Data Representation

entityauthdata = {
  "#mandatory" : [ "scheme", "authdata" ],
  "scheme" : "string",
  "authdata" : object
}

Field	Description
authdata	scheme-specific entity authentication data
scheme	entity authentication scheme

Authentication Data

The authentication data must contain enough information to uniquely and securely identify the entity sending the message.

Master Tokens

A master token contains an entity identity and session keys. The entity identified inside the master token is referred to as the master token entity.

The sender of a message may request the establishment of session keys for use with future MSL transactions. To request session keys, the sender can include one or more key request data in the MSL header of the request. The recipient can then issue or renew a master token and session keys, and return the session keys to the sender by including key response data in the MSL header of the response.

When renewing a master token, the issuing entity has an opportunity to decide if the master token should be renewed or not. It may be the entity is no longer recognized or the existing master token is no longer trusted and the master token will not be renewed.

From then on, the sender may use the master token to identify itself and successful decryption and authentication of the message by the recipient implies the identity contained in the master token.

When using a master token, the MSL header is encrypted using the session encryption key and authenticated using the session authentication key. Currently AES/CBC/PKCS5Padding with a AES-128 key is used with a random IV for encryption and HmacSHA256 is used for authentication but other algorithms and modes may also be used if supported by the key exchange mechanism used. One of the ciphertext and signature envelopes described above will be used; some envelope versions include the cipher specification and signature algorithm.

Secret keys are used by the issuing entity to encrypt the master token session data and generate the master token verification data. Other entities cannot decrypt the master token session data or generate the master token verification data unless they also have access to these keys. These secret keys must be adequately protected as unauthorized access to these keys would allow communication involving master tokens to be compromised. It is also recommended that the secret keys be periodically rotated.

The master token entity is expected to persist its master token and associated session keys. After successful master token renewal the previous master token and session keys may be discarded once they are no longer being used by any outstanding messages.

It is not necessary, although permitted, for the issuing entity to persist master token it issues or associated session keys. The issuing entity will be able to recreate the session keys from the master token included on received messages.

Master Token Representation

mastertoken = {
  "#mandatory" : [ "tokendata", "signature" ],
  "tokendata" : "binary",
  "signature" : "binary"
}

Field	Description
signature	signature envelope verifying the tokendata
tokendata	master token data (mastertokendata)

Master Token Data

mastertokendata = {
  "#mandatory" : [ "renewalwindow", "expiration", "sequencenumber", "serialnumber", "sessiondata" ],
  "renewalwindow" : "int64(0,2^53^)",
  "expiration" : "int64(0,2^53^)",
  "sequencenumber" : "int64(0,2^53^)",
  "serialnumber" : "int64(0,2^53^)",
  "sessiondata" : "binary",
}

Field	Description
expiration	expiration timestamp in seconds since the epoch
renewalwindow	when the renewal window opens in seconds since the epoch
sequencenumber	master token sequence number
serialnumber	master token serial number
sessiondata	ciphertext envelope containing the session data (sessiondata)

Renewal Window, Expiration, & Sequence Number

Renewal and expiration logic is only carried out by the entity that issued the master token.

Master tokens contain a renewal window timestamp and expiration timestamp. The renewal window timestamp identifies the time after which a master token shall be renewed if the message renewal flag is also set. The expiration timestamp identifies the time after which messages using master token authentication are no longer accepted unless the message renewal flag is also set. The values assigned for the renewal window and expiration should strike a balance between frequent renewal which is somewhat expensive and minimizing session key use for increased security.

Master tokens contain a sequence number to prevent entity cloning. When a master token is renewed its sequence number is incremented by 1 and this value is saved by the issuing entity as the newest master token sequence number. When incrementing the sequence number, the maximum sequence number is equal to 2⁵³ after which it wraps around to 0.

The issuing entity may wish to allow master tokens with old sequence numbers to be renewed (within a small window), to address the case where a master token entity may have lost a master token due to communication or storage failures. Closing this window once it is known that the master token entity has received the master token limits the potential for abuse. In all cases the new master token’s sequence number will be one larger than the sequence number previously saved by the issuing entity.

The issuing entity may also wish to check the renewal window and expiration timestamps when renewing master tokens to ensure that a very old master token with the correct sequence number is not accepted for renewal after the master token sequence number has wrapped around. This is unlikely to occur in practice unless master tokens are renewed with extremely high frequency.

When in possession of multiple master tokens, the token with the highest sequence number should be considered the newest token. Since the sequence number space is signed 53-bit numbers, if a sequence number is smaller by more than 45-bits (i.e. the new sequence number is < 128 and the old sequence number is 2⁵³), it is considered the newest token.

New session keys must be created when renewing the master token.

Master Token Renewal & Expiration Pseudocode

boolean acceptMessage = !masterToken.isExpired() || (message.isRenewable() && message.hasKeyRequestData());
boolean renewMasterToken = masterToken.isRenewable() && message.isRenewable() && message.hasKeyRequestData();

If a message is rejected an error will be returned to the sender which will be passed up to the application.

Serial Number

The serial number is a random number against which all other tokens are bound.

A randomly generated serial number should be used when issuing the first master token. The serial number should not be changed when renewing a master token; the primary purpose of the serial number is to prevent migration of user ID tokens and service tokens between entities.

Session Data

sessiondata = {
  "#mandatory" : [ "identity", "encryptionkey", "hmackey" ],
  "issuerdata" : object,
  "identity" : "string",
  "encryptionkey" : "binary",
  "hmackey" : "binary"
}

Field	Description
encryptionkey	encryption session key
hmackey	HMAC session key
identity	master token entity identity
issuerdata	master token issuer data

Issuer Data

The issuer data contains data provided by the issuer which may be useful to services that accept the master token. Some examples would be to identify the authoritative source of the sequence number during renewal or to identify the original issuing entity in a trusted services network.

Identity

The identity of the entity the master token has been issued for. In a trusted services network this identifies the one entity that is involved in all MSL communication. In a peer-to-peer network this identifies the sending entity when the master token is used for message authentication.

Encryption Key & HMAC Key

The session encryption key and HMAC key are included in the master token so the issuing entity (or entities in a trusted services network) can encrypt/decrypt and sign/verify messages using the session keys without having to remember all session keys and master tokens it has issued.