com.netflix.msl.tokens
Class MasterToken

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

public class MasterToken
extends Object

The master token provides proof of remote entity identity. A MSL-specific crypto context is used to encrypt the master token data and generate the master token verification data. The remote entity cannot decrypt the master token data or generate the master token verification data.

The master token session keys will be used for MSL message encryption and integrity protection. The use of these session keys implies the MSL message identity as specified in the master token.

Master tokens also contain a sequence number identifying the issue number of the token. This is a monotonically increasing number that is incremented by one each time a master token is renewed.

When in possession of multiple master tokens, the token with the highest sequence number should be considered the newest token. Since the sequence number space is signed 53-bit numbers, if a sequence number is smaller by more than 45-bits (e.g. the new sequence number is <= 128 and the old sequence number is 2^53), it is considered the newest token.

The renewal window indicates the time after which the master token will be renewed if requested by the entity. The expiration is the time after which the master token will be renewed no matter what.

Master tokens also contain a serial number against which all other tokens are bound. Changing the serial number when the master token is renewed invalidates all of those tokens.

The issuer identity identifies the issuer of this master token, which may be useful to services that accept the master token.

While there can be multiple versions of a master token, this class should encapsulate support for all of those versions.

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

• tokendata is the Base64-encoded master token data (mastertokendata)
• signature is the Base64-encoded verification data of the master token data

The token data is represented as mastertokendata = { "#mandatory" : [ "renewalwindow", "expiration", "sequencenumber", "serialnumber", "sessiondata" ], "renewalwindow" : "int64(0,-)", "expiration" : "int64(0,-)", "sequencenumber" : "int64(0,2^53^)", "serialnumber" : "int64(0,2^53^)", "sessiondata" : "base64" } where:

• renewalwindow is when the renewal window opens in seconds since the epoch
• expiration is the expiration timestamp in seconds since the epoch
• sequencenumber is the master token sequence number
• serialnumber is the master token serial number
• sessiondata is the Base64-encoded encrypted session data (sessiondata)

The decrypted session data is represented as sessiondata = { "#mandatory" : [ "identity", "encryptionkey", "hmackey" ], "issuerdata" : object, "identity" : "string", "encryptionkey" : "base64", "hmackey" : "base64" } where:

• issuerdata is the master token issuer data
• identity is the identifier of the remote entity
• encryptionkey is the Base64-encoded AES-128 encryption session key
• hmackey is the Base64-encoded SHA-256 HMAC session key

Constructor Summary

MasterToken(MslContext ctx, Date renewalWindow, Date expiration, long sequenceNumber, long serialNumber, JSONObject issuerData, String identity, SecretKey encryptionKey, SecretKey hmacKey)
Create a new master token with the specified expiration, identity, serial number, and encryption and HMAC keys.

MasterToken(MslContext ctx, JSONObject masterTokenJO)
Create a new master token from the provided JSON.

Method Summary

boolean	equals(Object obj)
SecretKey	getEncryptionKey()
Date	getExpiration()
SecretKey	getHmacKey()
String	getIdentity() Returns the identifier of the authenticated peer.
JSONObject	getIssuerData() Returns the issuer data.
Date	getRenewalWindow()
long	getSequenceNumber()
long	getSerialNumber()
int	hashCode()
boolean	isDecrypted()
boolean	isExpired()
boolean	isNewerThan(MasterToken that) A master token is considered newer if its sequence number is greater than another master token.
boolean	isRenewable()
boolean	isVerified()
String	toJSONString()
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

MasterToken

public MasterToken(MslContext ctx,
                   Date renewalWindow,
                   Date expiration,
                   long sequenceNumber,
                   long serialNumber,
                   JSONObject issuerData,
                   String identity,
                   SecretKey encryptionKey,
                   SecretKey hmacKey)
            throws MslEncodingException,
                   MslCryptoException

Create a new master token with the specified expiration, identity, serial number, and encryption and HMAC keys.

Parameters:

ctx - MSL context.

renewalWindow - the renewal window.

expiration - the expiration.

sequenceNumber - the master token sequence number.

serialNumber - the master token serial number.

issuerData - the issuer data. May be null.

identity - the singular identity this master token represents.

encryptionKey - the session encryption key.

hmacKey - the session HMAC key.

Throws:

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

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

MasterToken

public MasterToken(MslContext ctx,
                   JSONObject masterTokenJO)
            throws MslEncodingException,
                   MslCryptoException,
                   MslException

Create a new master token from the provided JSON.

Parameters:

ctx - MSL context.

masterTokenJO - master token JSON object.

Throws:

MslEncodingException - if there is an error parsing the JSON, the token data is missing or invalid, the signature is missing or invalid, or the session data is missing or invalid.

MslCryptoException - if there is an error verifying the token data or extracting the session keys.

MslException - if the expiration timestamp occurs before the renewal window, or the sequence number is out of range, or the serial number is out of range.

Method Detail

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.

getRenewalWindow

public Date getRenewalWindow()

Returns:

the start of the renewal window.

isRenewable

public boolean isRenewable()

Returns:

true if the renewal window has been entered.

getExpiration

public Date getExpiration()

Returns:

the expiration.

isExpired

public boolean isExpired()

Returns:

true if expired.

getSequenceNumber

public long getSequenceNumber()

Returns:

the sequence number.

getSerialNumber

public long getSerialNumber()

Returns:

the serial number.

isNewerThan

public boolean isNewerThan(MasterToken that)

A master token is considered newer if its sequence number is greater than another master token. If both the sequence numbers are equal, then the master token with the later expiration date is considered newer.

Serial numbers are not taken into consideration when comparing which master token is newer because serial numbers will change when new master tokens are created as opposed to renewed. The caller of this function should already be comparing master tokens that can be used interchangeably (i.e. for the same MSL network).

Parameters:

that - the master token to compare with.

Returns:

true if this master token is newer than the provided one.

getIssuerData

public JSONObject getIssuerData()

Returns the issuer data.

Returns:

the master token issuer data or null if there is none or it is unknown (session data could not be decrypted).

getIdentity

public String getIdentity()

Returns the identifier of the authenticated peer.

Returns:

the Netflix peer identity or null if unknown (session data could not be decrypted).

getEncryptionKey

public SecretKey getEncryptionKey()

Returns:

the symmetric encryption key or null if unknown (session data could not be decrypted).

getHmacKey

public SecretKey getHmacKey()

Returns:

the symmetric HMAC key or null if unknown (session data could not be decrypted).

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 master token with the same serial number and sequence number.

See Also:

Object.equals(java.lang.Object)

hashCode

public int hashCode()

Overrides:

hashCode in class Object