Regular Messages
Regular messages are used to perform MSL handshakes and to send application data between two entities.
The local entity’s MSL stack must perform the following in order when sending a message.
If the local entity has a master token the master token should be used in preference over entity authentication data unless stated otherwise.
The MSL stack may only have one outstanding renewable message at any given time.
A message must be marked renewable if any of the following conditions are met:
- The application data must be encrypted and the local entity does not have a master token and its entity authentication scheme does not support encryption.
- The application data must be integrity protected and the local entity does not have a master token and its entity authentication scheme does not support integrity protection.
- The local entity’s master token is expired.
- User authentication data will be sent and the local entity does not have a master token and its entity authentication scheme does not support encryption and integrity protection.
- The application data must be non-replayable and the local entity does not have a master token.
- The application expects to receive service tokens in response to this message and the local entity does not have a master token, or does not have a user ID token and user authentication data will be sent.
A message may be marked renewable if any of the following conditions are met:
- The local entity does not have a master token or its master token is renewable.
- The local entity does not have a user ID token and user authentication data will be sent.
- The local entity has a user ID token that is renewable.
If a message must be marked as renewable but there exists an outstanding renewable message then the MSL stack must delay sending the message until the outstanding renewable message receives a response. If the outstanding renewable message receives a master token in response, the newly received master token may negate one of the conditions requiring the delayed message be marked as renewable. If a master token is received, a new or updated user ID token may have also been received and should now be used if the message is associated with that user.
If a message has been marked as renewable and the local entity does not have a master token or its master token is renewable then key request data should be included.
If a message should be associated with a user, then user authentication data, a user ID token, or both should be included. However user authentication data and thus the application data must be delayed until after a MSL handshake if the local entity does not have a master token or its entity authentication scheme does not support encryption and integrity protection.
A special case exists for the situation where the local entity wishes to set the user identity of the remote entity (see the user assignment example). If the response message will carry a master token for the remote entity, the local entity may explicitly create and attach a user ID token for the remote entity if no such user ID token already exists. An example of when this logic would be used is after the local entity creates a new user for the remote entity.
If a message’s application data requires encryption but the local entity does not have a master token or its entity authentication scheme does not support encryption then the application data must be delayed until after a MSL handshake.
Similarly, if a message’s application data must be non-replayable but the local entity does not have a master token then the application data must be delayed until after a MSL handshake.
The MSL stack shall include all service tokens applicable to a message:
- All unbound service tokens.
- If a master token is included, all master token-bound service tokens bound to that master token.
- If a user ID token is included, all user ID token-bound service tokens bound to that user ID token.
Note that this may result in up to three service tokens of the same name being included, if each service token with the same name is bound to the master token and user ID token differently.
The application may choose to add, exclude, or request the deletion of service tokens by the remote entity before the message is sent. This applies to both handshake and non-handshake messages. New and updated service tokens should be included, and deleted service tokens not included, in future messages as soon as the application finishes manipulating the service tokens for the message.
The local entity’s MSL stack must perform the following in order when receiving a message.
The received MSL header must be verified by performing the following in order. If any of the steps fail the message must be rejected.
- Parse the JSON to extract the entity authentication data or master token, header data, and signature.
- If the MSL header includes entity authentication data perform entity authentication.
- Verify the header data signature.
- Decrypt the header data.
A received message must be rejected if any of the following conditions applies to the MSL header:
- The header structure or data is malformed.
- The header includes a user ID token without including a master token.
- The header includes a user ID token that is not bound to the included master token.
- The header includes a master token-bound service token that is not bound to the included master token.
- The header includes a user ID token-bound service token that is not bound to the included user ID token.
- The header includes a peer user ID token without including a peer master token.
- The header includes a peer user ID token that is not bound to the includes peer master token.
- The header includes a master token-bound peer service token that is not bound to the included peer master token.
- The header includes a user ID token-bound peer service token that is not bound to the included peer user ID token.
N.B. If the message includes key response data, the key response data master token should be used by trusted services entities instead of the message header master token to verify the user ID token and service tokens and by peer-to-peer entities to verify the peer user ID token and peer service tokens.
Trusted services clients will be unable to verify or decrypt the master token included in messages. Such messages must be verified and decrypted using the session keys associated with the master token.
Trusted services servers and peer-to-peer entities should be able to verify and decrypt the master token assigned to the remote entity and therefore extract the session keys associated with the master token to perform message verification and decryption.
If a message includes user authentication data user authentication must be performed and succeed. If a user ID token is also included the identities of the user authentication data and user ID token must be verified against each other.
The message must be rejected if the master token or user ID token has been revoked.
Reasons for revocation include if the entity or user identified by the master token or user ID token is no longer valid or if the master token or its associated session keys is believed to have been compromised.
Trusted services servers and peer-to-peer entities must reject messages with an expired master token if the message is not renewable, does not contain key request data, or the issuing entity will not permit the master token to be renewed (e.g. the master token sequence number is too old).
A non-replayable message must be rejected under any of the following conditions:
- The message does not include a master token.
- The message non-replayable ID is not larger by no more than 65536 than the largest non-replayable ID previously received for the entity identity and serial number of the master token (or is not in the set of unreceived non-replayable IDs if that is supported). The wrap around from 253 to 0 must be considered when comparing the non-replayable ID values.
If a message is received in response to another message, the received message must be rejected if its message ID is not equal to the request message’s message ID + 1.
A message must be rejected under any of the following conditions:
- The remote entity identity was specified, the received message is using entity authentication data, and the message sender’s entity identity is not equal to the specified remote entity identity.
- In peer-to-peer mode only, the remote entity identity was specified and is not equal to the message sender’s entity identity.
After a message is verified and authenticated any new and updated master token, user ID token, and service tokens should be included, and deleted service tokens not included, in future messages.
Each message payload chunk must be independently verified and authenticated. As with the header, the signature must be verified prior to performing decryption. Malformed payloads and payloads with an incorrect message ID or sequence number must be skipped and discarded.
If a message with the handshake flag set is received then the MSL stack must automatically send a handshake response.
When participating in a trusted services network no further messages are expected from the remote entity and the MSL stack must inform the local entity that no application data was received. The next message from the remote entity can be received independently of this handshake message.
When participating in a peer-to-peer network the handshake response may contain key request data from the local entity in which case the next message from the remote entity cannot be received independently. The MSL stack should attempt to receive another message which may or may not contain key response data and peer authentication tokens. If another message is received the MSL stack must deliver it to the application.
If a message without the handshake flag set is received then the MSL stack must deliver it to the application.
If an error occurs while processing a received message the MSL stack must automatically send an error message to the remote entity. The MSL stack must then deliver the error to the local entity application. Any unconsumed message payloads must be discarded.
The local entity’s MSL stack must perform the following in order when responding to a received message.
When available, peer-to-peer entities and trusted services clients must always include its newest master token. Trusted services servers should include the received message’s master token.
If a request message is renewable and includes key request data the response message must include key response data if any of the following conditions are met:
- The request message contains a renewable or expired master token.
- The request message contains entity authentication data.
If a request message includes a user ID token issued by the local entity the response message must renew the user ID token if any of the following conditions are met:
- The request message is renewable and the user ID token is renewable.
- The user ID token is expired.
- The user ID token is not bound to a new master token being returned in the response. (This may occur if the master token was renewed and its serial number changed as a result.)
If a request message is renewable, includes user authentication data, and a master token will be included in the response (either as part of the message header or within key response data) then the response message must include a user ID token for the authenticated remote entity user.
Peer-to-peer entities and trusted servies clients must always include its newest user ID token.
In the special case where the local entity wishes to set the user identity of the remote entity, but no master token will be included in the response message, an error response must be sent and the local application notified.
The response message’s message capabilities must consist of the intersection of the request message’s message capabilities and the local entity’s message capabilities. The response message may only utilize features that are contained in this intersection.
If a message’s application data requires encryption but the local entity does not have a master token or its entity authentication scheme does not support encryption then an error response must be sent and the local application notified.
The message sending logic applies.
When participating in a peer-to-peer network then another message may be received from the remote entity after the response message is sent. The MSL stack should attempt to receive another message.
The following sequence diagrams illustrate some common sender/responder message exchanges. These examples are not the only way to accomplish the illustrated transaction.
The sender wishes to perform entity and user authentication to receive a master token and user ID token.
To accomplish this the sender includes entity authentication data, user authentication data, and key request data in a message that is marked as renewable.
The response includes a user ID token and key response data containing a new master token.
The sender wishes to renew its renewable or expired master token.
To accomplish this the sender includes its current master token and key request data in a message that is marked as renewable.
In a trusted services network the response is authenticated using the current master token and includes key response data containing a new master token.
In a peer-to-peer network the response includes key response data containing a new master token. The current master token and user ID token are included as peer tokens.
The sender wishes to renew its renewable but not expired user ID token. Its master token is not renewable or expired.
To accomplish this the sender includes its current user ID token in a message that is marked renewable.
In a trusted services network the response includes a new user ID token.
In a peer-to-peer network the response includes a new user ID token as a peer token.
The sender wishes to verify that the application user is still the user associated with the current user ID token.
To accomplish this the sender includes its user ID token plus user authentication data in a message.
If the user authentication data matches the user identified by the user ID token, the user verification succeeds. Otherwise an error response is returned.
The sender’s message does not include a user ID token or user authentication data. The responder wishes to assign a user identity to the remote entity’s application user anyway.
In a trusted services network the response includes a new user ID token identifying the assigned user.
In a peer-to-peer network the response includes a new user ID token identifying the assigned user as a peer token.
The sender wishes to send non-replayable application data.
To accomplish this the sender includes its current master token and the next non-replayable ID in a message.
If the non-replayable ID is accepted the operation succeeds. Otherwise an error response is returned.
