Service Tokens

Service tokens are a means by which an entity may attach state or context to an entity, user, or transaction. They are similar to HTTP cookies but may be optionally bound to an specific master token or user ID token by the master token serial number and user ID token serial number respectively to prevent unauthorized use.

MSL does not provide a mechanism by which individual service tokens can be associated with other service tokens; it is recommended that a service token contain data that is independent of other service token data.

Service tokens may be verifiable and/or encrypted. Verified tokens carry the token data in the clear but are accompanied by verification data to detect tampering. Encrypted tokens encrypt the token data.

Application- or service-specific keys should be used to encrypt the service token data and generate the service token verification data. It may be possible for an entity other than the issuing entity to decrypt the service token data or generate the service token verification data if it has access to the keys. An entity is also free to consume unencrypted token data of an unverified service token, although this is strongly discouraged. It is also recommended that the secret keys be periodically rotated.

The service token management logic differs depending on the type of MSL network and entity involved.

In a trusted services network, the client is responsible for maintaining local state associating service tokens with master tokens and user ID tokens. The client must make sure to include the correct service tokens in any messages it creates. Trusted services servers are not responsible for maintaining any state and will modify or echo the set of service tokens received from the client.

In a peer-to-peer network, both entities are responsible for maintaining local state associating service tokens with its master tokens and user ID tokens. Entities are not responsible for maintaining local state for the remote entity’s service tokens. Each entity must make sure to include the correct service tokens in any messages it creates.

Since entities are permitted to send messages in parallel, receiving applications must always be prepared to accept messages that include old service tokens. Since multiple services or service instances may issue service tokens with the same name, there is no mechanism by which MSL can identify a newer service token versus an older one without imposing data synchronization requirements upon services.

Therefore, although synchronization must be used to ensure the local service token state remains consistent, there is no requirement that the state be atomically updated with a single message’s service tokens. Interleaving updates as a result of two received messages is acceptable.

Service Token Representation

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

Field	Description
signature	signature envelope verifying the tokendata
tokendata	service token data (servicetokendata)

Service Token Data

servicetokendata = {
  "#mandatory" : [ "name", "mtserialnumber", "uitserialnumber", "encrypted", "servicedata" ],
  "name" : "string",
  "mtserialnumber" : "int64(-1,2^53^)",
  "uitserialnumber" : "int64(-1,2^53^)",
  "encrypted" : "boolean",
  "compressionalgo" : "enum(GZIP|LZW)",
  "servicedata" : "binary"
}

Field	Description
compressionalgo	compression algorithm used to compress the data
encrypted	true if the token data is encrypted
mtserialnumber	master token serial number, -1 if unbound
name	service token unique name
servicedata	token data or ciphertext envelope containing the token data
uitserialnumber	user ID token serial number, -1 if unbound

Name

Service token names should follow a reverse fully-qualified domain hierarchy to avoid collisions. e.g. com.netflix.service.tokenname

Master Token Serial Number

The master token serial number binds the service token to a specific master token. The service token must be rejected if it is bound to a master token and its master token serial number does not match the master token included in the message.

User ID Token Serial Number

The user ID token serial number binds the service token to a specific user ID token. The service token must be rejected if it is bound to a user ID token and its user ID token serial number does not match the user ID token included in the message.

Encrypted/Compression Algorithm & Service Data

The service data is opaque to the MSL stack and transmitted as binary.

If the encrypted flag is true then the service data has been encrypted using an application- or service-specific encryption key.

If a compression algorithm is specified then the service data has been compressed prior to encryption.

If the service data is empty, that indicates the service token may be deleted and excluded from all future messages.