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.

Field Summary

private MslConstants.CompressionAlgorithm	compressionAlgo Compression algorithm.
private MslContext	ctx MSL context.
private boolean	encrypted Service token data is encrypted.
private static String	KEY_COMPRESSION_ALGORITHM JSON key compression algorithm.
private static String	KEY_ENCRYPTED JSON key encrypted.
private static String	KEY_MASTER_TOKEN_SERIAL_NUMBER JSON key master token serial number.
private static String	KEY_NAME JSON key token name.
private static String	KEY_SERVICEDATA JSON key service data.
private static String	KEY_SIGNATURE JSON key signature.
private static String	KEY_TOKENDATA JSON key token data.
private static String	KEY_USER_ID_TOKEN_SERIAL_NUMBER JSON key user ID token serial number.
private long	mtSerialNumber The service token master token serial number.
private String	name The service token name.
private byte[]	servicedata The service token data.
private byte[]	signature Token data signature.
private byte[]	tokendata Token data.
private long	uitSerialNumber The service token user ID token serial number.
private boolean	verified Token is verified.

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()
private static ICryptoContext	selectCryptoContext(JSONObject serviceTokenJO, Map<String,ICryptoContext> cryptoContexts) Select the appropriate crypto context for the service token represented by the provided JSON object.
String	toJSONString()
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

KEY_TOKENDATA

private static final String KEY_TOKENDATA

JSON key token data.

See Also:

Constant Field Values

KEY_SIGNATURE

private static final String KEY_SIGNATURE

JSON key signature.

See Also:

Constant Field Values

KEY_NAME

private static final String KEY_NAME

JSON key token name.

See Also:

Constant Field Values

KEY_MASTER_TOKEN_SERIAL_NUMBER

private static final String KEY_MASTER_TOKEN_SERIAL_NUMBER

JSON key master token serial number.

See Also:

Constant Field Values

KEY_USER_ID_TOKEN_SERIAL_NUMBER

private static final String KEY_USER_ID_TOKEN_SERIAL_NUMBER

JSON key user ID token serial number.

See Also:

Constant Field Values

KEY_ENCRYPTED

private static final String KEY_ENCRYPTED

JSON key encrypted.

See Also:

Constant Field Values

KEY_COMPRESSION_ALGORITHM

private static final String KEY_COMPRESSION_ALGORITHM

JSON key compression algorithm.

See Also:

Constant Field Values

KEY_SERVICEDATA

private static final String KEY_SERVICEDATA

JSON key service data.

See Also:

Constant Field Values

ctx

private final MslContext ctx

MSL context.

tokendata

private final byte[] tokendata

Token data.

signature

private final byte[] signature

Token data signature.

name

private final String name

The service token name.

mtSerialNumber

private final long mtSerialNumber

The service token master token serial number.

uitSerialNumber

private final long uitSerialNumber

The service token user ID token serial number.

encrypted

private final boolean encrypted

Service token data is encrypted.

compressionAlgo

private final MslConstants.CompressionAlgorithm compressionAlgo

Compression algorithm.

servicedata

private final byte[] servicedata

The service token data.

verified

private final boolean verified

Token is verified.

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

selectCryptoContext

private static ICryptoContext selectCryptoContext(JSONObject serviceTokenJO,
                                                  Map<String,ICryptoContext> cryptoContexts)
                                           throws MslEncodingException

Select the appropriate crypto context for the service token represented by the provided JSON object.

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

Parameters:

serviceTokenJO - the JSON object.

cryptoContexts - the map of service token names onto crypto contexts used to decrypt and verify service tokens.

Returns:

the correct crypto context for the service token or null.

Throws:

MslEncodingException - if there is a problem parsing the JSON.

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