Error Messages

The MSL error header carries the MSL data used for entity authentication and error details.

Error Header Representation

errorheader = {
  "#mandatory" : [ "entityauthdata", "errordata", "signature" ],
  "entityauthdata" : entityauthdata,
  "errordata" : "binary",
  "signature" : "binary"
}

Field	Description
entityauthdata	entity authentication data (entityauthdata)
errordata	error data or ciphertext envelope containing the error data (errordata)
signature	signature envelope verifying the errordata

Entity Authentication Data

The MSL error header is encrypted and verified according to the entity authentication data included in the MSL error header. Some entity authentication schemes do not support encryption or verification.

Error Data

errordata = {
  "#mandatory" : [ "messageid", "errorcode" ],
  "timestamp" : "int64(0,2^53^)",
  "messageid" : "int64(0,2^53^)",
  "errorcode" : "int32(0,-)",
  "internalcode" : "int32(0,-)",
  "errormsg" : "string",
  "usermsg" : "string",
}

Field	Description
errorcode	error code
errormsg	developer-consumable error message
internalcode	service-specific error code
messageid	message ID
timestamp	creation time in seconds since the epoch
usermsg	user-consumable error message

Timestamp

The header creation timestamp based off the sender’s clock. The recipient may use this value to determine if master tokens and user ID tokens issued by the sender are renewable or expired.

There is no guarantee the sender time is the real time and the existence of this value does not imply the sender and recipient times should be synchronized.

Error Code

The error code identifies the error that occurred. The receiving entity should use this code to decide upon the correct error handling logic.

Error Code	Action	Meaning
1	Fail	The message is erroneous and will be rejected if retried.
2	Transient Failure	The message is expected to succeed if retried after a delay.
3	Entity Re-authenticate	The message is expected to succeed if entity re-authentication is performed.
4	User Re-authenticate	The message is expected to succeed if user re-authentication is performed.
5	Key Exchange Required	The message is expected to succeed if key exchange is performed.
6	Entity Data Re-authenticate	The message is expected to succeed if entity re-authentication is performed with new entity authentication data.
7	User Data Re-authenticate	The message is expected to succeed if user re-authentication is performed with new user authentication data.
8	Expired	The message is expected to succeed if retried with a renewed master token or renewable message.
9	Replayed	The non-replayable message is expected to succeed if retried with a larger non-replayable ID.
10	SSO Token Rejected	The message is expected to succeed if user re-authentication is performed with new user authentication data containing a valid single-sign-on token.

Fail

The message is malformed or contains data that cannot be accepted by the recipient. This includes situations where the recipient does not support an authentication scheme, key exchange scheme, or cryptographic operation used by the message.

Transient Failure

The recipient cannot successfully process the message at this time but should be able to at a later time. MSL will not automatically attempt to retry.

Entity Re-authenticate

The message’s master token is rejected by the recipient. The sender should perform entity authentication using entity authentication data. The previous master token, user ID token, and bound service tokens should be discarded if authentication succeeds.

User Re-authenticate

The message’s user ID token is rejected by the recipient or identifies a different user than the message’s user authentication data. The sender should perform user authentication using user authentication data. The previous user ID token and user-bound service tokens should be discarded if authentication succeeds.

Key Exchange Required

This error code is only applicable in trusted network mode and indicates that the recipient requires encryption to send its response. The sender should perform key exchange by sending a renewable message containing key request data.

Entity Data Re-authenticate

The message’s entity authentication scheme is supported but the entity authentication data is rejected by the recipient for a correctable reason. The sender should perform entity authentication using the same entity authentication scheme but with new entity authentication data.

User Data Re-authenticate

The message’s user authentication scheme is supported by the entity authentication data is rejected by the recipient. The sender should perform user authentication using the same user authentication scheme but with new user authentication data. This may require prompting the user for credentials.

Expired

The non-renewable message’s master token is expired. The sender should perform key exchange by sending a renewable message containing key request data.

Replayed

The non-replayable message’s non-replayable ID is too old. The sender should use a larger non-replayable ID.

SSO Token Rejected

The single-sign-on token included in the user authentication data was rejected because it is expired, malformed, or invalid. The sender should perform user authentication using the same user authentication scheme but with new user authentication data containing a new single-sign-on token.

Internal Code

An internal error code defined by the sending entity’s MSL stack implementation. This code may be used to help identify the problem encountered.

Error Message

Text defined by the sending entity’s MSL stack implementation that is not intended for user consumption. This text may be used to help identify the problem encountered.

User Message

User consumable text defined by the sending application or MSL stack implementation that may be displayed to the user upon receipt of the error message. If included this text should be localized.