com.netflix.msl.tokens
Class ServiceToken

java.lang.Object
  com.netflix.msl.tokens.ServiceToken

public class ServiceToken
extends Object

Service tokens are service-defined tokens carried as part of any MSL message. These tokens should be used to carry service state.

Service tokens are optionally bound to a specific master token and user ID token by their serial numbers.

Service tokens are either verified or encrypted. Verified tokens carry their data in the clear but are accompanied by a signature allowing the issuer to ensure the data has not been tampered with. Encrypted tokens encrypt their data as well as contain a signature.

Service tokens should use application- or service-specific crypto contexts and not the crypto context associated with the entity credentials or master token.

Service tokens are represented as servicetoken = { "#mandatory" : [ "tokendata", "signature" ], "tokendata" : "base64, "signature" : "base64" } where:

• tokendata is the Base64-encoded service token data (servicetokendata)
• signature is the Base64-encoded verification data of the service token data

The token data is represented as servicetokendata = { "#mandatory" : [ "name", "mtserialnumber", "uitserialnumber", "encrypted", "servicedata" ], "name" : "string", "mtserialnumber" : "int64(0,2^53^)", "uitserialnumber" : "int64(0,2^53^)", "encrypted" : "boolean", "compressionalgo" : "enum(GZIP|LZW)", "servicedata" : "base64" } where:

• name is the token name
• mtserialnumber is the master token serial number or -1 if unbound
• utserialnumber is the user ID token serial number or -1 if unbound
• encrypted indicates if the service data is encrypted or not
• compressionalgo indicates the algorithm used to compress the data
• servicedata is the Base64-encoded optionally encrypted service data

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

Constructor Summary

ServiceToken(MslContext ctx, JSONObject serviceTokenJO, MasterToken masterToken, UserIdToken userIdToken, ICryptoContext cryptoContext)
Construct a new service token from the provided JSON object.

ServiceToken(MslContext ctx, JSONObject serviceTokenJO, MasterToken masterToken, UserIdToken userIdToken, Map<String,ICryptoContext> cryptoContexts)
Construct a new service token from the provided JSON object and attempt to decrypt and verify the signature of the service token using the appropriate crypto context.

ServiceToken(MslContext ctx, String name, byte[] data, MasterToken masterToken, UserIdToken userIdToken, boolean encrypted, MslConstants.CompressionAlgorithm compressionAlgo, ICryptoContext cryptoContext)
Construct a new service token with the specified name and data.

Method Summary

boolean	equals(Object obj)
MslConstants.CompressionAlgorithm	getCompressionAlgo()
byte[]	getData() Returns the service data if the token data was not encrypted or we were able to decrypt it.
long	getMasterTokenSerialNumber() Returns the serial number of the master token this service token is bound to.
String	getName()
long	getUserIdTokenSerialNumber() Returns the serial number of the user ID token this service token is bound to.
int	hashCode()
boolean	isBoundTo(MasterToken masterToken)
boolean	isBoundTo(UserIdToken userIdToken)
boolean	isDecrypted()
boolean	isDeleted()
boolean	isEncrypted()
boolean	isMasterTokenBound()
boolean	isUnbound()
boolean	isUserIdTokenBound() Returns true if this token is bound to a user ID token.
boolean	isVerified()
String	toJSONString()
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ServiceToken

public ServiceToken(MslContext ctx,
                    String name,
                    byte[] data,
                    MasterToken masterToken,
                    UserIdToken userIdToken,
                    boolean encrypted,
                    MslConstants.CompressionAlgorithm compressionAlgo,
                    ICryptoContext cryptoContext)
             throws MslEncodingException,
                    MslCryptoException,
                    MslException

Construct a new service token with the specified name and data. If a master token is provided, the service token is bound to the master token's serial number. If a user ID token is provided, the service token is bound to the user ID token's serial number.

For encrypted tokens, the token data is encrypted using the provided crypto context. For verified tokens, the token data is signed using the provided crypto context.

Parameters:

ctx - the MSL context.

name - the service token name--must be unique.

data - the service token data (unencrypted).

masterToken - the master token. May be null.

userIdToken - the user ID token. May be null.

encrypted - true if the token should be encrypted.

compressionAlgo - the compression algorithm. May be null for no compression.

cryptoContext - the crypto context.

Throws:

MslEncodingException - if there is an error encoding the JSON data.

MslCryptoException - if there is an error encrypting or signing the token data.

MslException - if there is an error compressing the data.

ServiceToken

public ServiceToken(MslContext ctx,
                    JSONObject serviceTokenJO,
                    MasterToken masterToken,
                    UserIdToken userIdToken,
                    Map<String,ICryptoContext> cryptoContexts)
             throws MslEncodingException,
                    MslCryptoException,
                    MslException

Construct a new service token from the provided JSON object and attempt to decrypt and verify the signature of the service token using the appropriate crypto context. If the data cannot be decrypted or the signature cannot be verified, the token will still be created.

If the service token name exists as a key in the map of crypto contexts, the mapped crypto context will be used. Otherwise the default crypto context mapped from the empty string key will be used.

If a matching crypto context is found, the token data will be decrypted and its signature verified.

If the service token is bound to a master token or user ID token it will be verified against the provided master token or user ID tokens which must not be null.

Parameters:

ctx - the MSL context.

serviceTokenJO - the JSON object.

masterToken - the master token. May be null.

userIdToken - the user ID token. May be null.

cryptoContexts - a map of service token names onto crypto contexts.

Throws:

MslEncodingException - if there is a problem parsing the JSON.

MslCryptoException - if there is an error decrypting or verifying the token data.

MslException - if the service token is bound to a master token or user ID token and the provided tokens are null or the serial numbers do not match, or if bound to a user ID token but not to a master token, or if the service data is missing, or if the compression algorithm is not known or there is an error uncompressing the data.

ServiceToken

public ServiceToken(MslContext ctx,
                    JSONObject serviceTokenJO,
                    MasterToken masterToken,
                    UserIdToken userIdToken,
                    ICryptoContext cryptoContext)
             throws MslCryptoException,
                    MslEncodingException,
                    MslException

Construct a new service token from the provided JSON object.

If a crypto context is provided, the token data will be decrypted and its signature verified. If the data cannot be decrypted or the signature cannot be verified, the token will still be created.

If the service token is bound to a master token or user ID token it will be verified against the provided master token or user ID tokens which must not be null.

Parameters:

ctx - the MSL context.

serviceTokenJO - the JSON object.

masterToken - the master token. May be null.

userIdToken - the user ID token. May be null.

cryptoContext - the crypto context. May be null.

Throws:

MslCryptoException - if there is a problem decrypting or verifying the token data.

MslEncodingException - if there is a problem parsing the JSON, the token data is missing or invalid, or the signature is invalid.

MslException - if the service token is bound to a master token or user ID token and the provided tokens are null or the serial numbers do not match, or if bound to a user ID token but not to a master token, or if the service data is missing, or if the service token master token serial number is out of range, or if the service token user ID token serial number is out of range, or if the compression algorithm is not known or there is an error uncompressing the data.

Method Detail

isEncrypted

public boolean isEncrypted()

Returns:

true if the content is encrypted.

isDecrypted

public boolean isDecrypted()

Returns:

true if the decrypted content is available. (Implies verified.)

isVerified

public boolean isVerified()

Returns:

true if the token has been verified.

getName

public String getName()

Returns:

the application token name.

isDeleted

public boolean isDeleted()

Returns:

true if this token has been marked for deletion.

See Also:

getData()

getCompressionAlgo

public MslConstants.CompressionAlgorithm getCompressionAlgo()

Returns:

the compression algorithm. May be null if not compressed.

getData

public byte[] getData()

Returns the service data if the token data was not encrypted or we were able to decrypt it. Zero-length data indicates this token should be deleted.

Returns:

the service data or null if we don't have it.

See Also:

isDeleted()

getMasterTokenSerialNumber

public long getMasterTokenSerialNumber()

Returns the serial number of the master token this service token is bound to.

Returns:

the master token serial number or -1 if unbound.

isMasterTokenBound

public boolean isMasterTokenBound()

Returns:

true if this token is bound to a master token.

isBoundTo

public boolean isBoundTo(MasterToken masterToken)

Parameters:

masterToken - master token. May be null.

Returns:

true if this token is bound to the provided master token.

getUserIdTokenSerialNumber

public long getUserIdTokenSerialNumber()

Returns the serial number of the user ID token this service token is bound to.

Returns:

the user ID token serial number or -1 if unbound.

isUserIdTokenBound

public boolean isUserIdTokenBound()

Returns true if this token is bound to a user ID token. This implies the token is bound to a master token as well.

Returns:

true if this token is bound to a user ID token.

isBoundTo

public boolean isBoundTo(UserIdToken userIdToken)

Parameters:

userIdToken - user ID token. May be null.

Returns:

true if this token is bound to the provided user ID token.

isUnbound

public boolean isUnbound()

Returns:

true if this token is not bound to a master token or user ID token.

toJSONString

public String toJSONString()

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

Parameters:

obj - the reference object with which to compare.

Returns:

true if the other object is a service token with the same name and bound to the same tokens.

See Also:

Object.equals(java.lang.Object)

hashCode

public int hashCode()

Overrides:

hashCode in class Object