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

Field Summary

private MslContext	ctx MSL context.
private SecretKey	encryptionKey Encryption key.
private long	expiration Master token expiration in seconds since the epoch.
private SecretKey	hmacKey HMAC key.
private String	identity Entity identity.
private JSONObject	issuerData Issuer data.
private static String	KEY_ENCRYPTION_KEY JSON key symmetric encryption key.
private static String	KEY_EXPIRATION JSON key expiration timestamp.
private static String	KEY_HMAC_KEY JSON key symmetric HMAC key.
private static String	KEY_IDENTITY JSON key identity.
private static String	KEY_ISSUER_DATA JSON key issuer data.
private static String	KEY_RENEWAL_WINDOW JSON key renewal window timestamp.
private static String	KEY_SEQUENCE_NUMBER JSON key sequence number.
private static String	KEY_SERIAL_NUMBER JSON key serial number.
private static String	KEY_SESSIONDATA JSON key session data.
private static String	KEY_SIGNATURE JSON key signature.
private static String	KEY_TOKENDATA JSON key token data.
private static long	MILLISECONDS_PER_SECOND Milliseconds per second.
private long	renewalWindow Master token renewal window in seconds since the epoch.
private long	sequenceNumber Sequence number.
private long	serialNumber Serial number.
private byte[]	sessiondata Session data.
private byte[]	signature Master token signature.
private byte[]	tokendata Token data.
private boolean	verified Token is verified.

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

Field Detail

MILLISECONDS_PER_SECOND

private static final long MILLISECONDS_PER_SECOND

Milliseconds per second.

See Also:

Constant Field Values

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_RENEWAL_WINDOW

private static final String KEY_RENEWAL_WINDOW

JSON key renewal window timestamp.

See Also:

Constant Field Values

KEY_EXPIRATION

private static final String KEY_EXPIRATION

JSON key expiration timestamp.

See Also:

Constant Field Values

KEY_SEQUENCE_NUMBER

private static final String KEY_SEQUENCE_NUMBER

JSON key sequence number.

See Also:

Constant Field Values

KEY_SERIAL_NUMBER

private static final String KEY_SERIAL_NUMBER

JSON key serial number.

See Also:

Constant Field Values

KEY_SESSIONDATA

private static final String KEY_SESSIONDATA

JSON key session data.

See Also:

Constant Field Values

KEY_ISSUER_DATA

private static final String KEY_ISSUER_DATA

JSON key issuer data.

See Also:

Constant Field Values

KEY_IDENTITY

private static final String KEY_IDENTITY

JSON key identity.

See Also:

Constant Field Values

KEY_ENCRYPTION_KEY

private static final String KEY_ENCRYPTION_KEY

JSON key symmetric encryption key.

See Also:

Constant Field Values

KEY_HMAC_KEY

private static final String KEY_HMAC_KEY

JSON key symmetric HMAC key.

See Also:

Constant Field Values

ctx

private final MslContext ctx

MSL context.

tokendata

private final byte[] tokendata

Token data.

signature

private final byte[] signature

Master token signature.

renewalWindow

private final long renewalWindow

Master token renewal window in seconds since the epoch.

expiration

private final long expiration

Master token expiration in seconds since the epoch.

sequenceNumber

private final long sequenceNumber

Sequence number.

serialNumber

private final long serialNumber

Serial number.

sessiondata

private final byte[] sessiondata

Session data.

issuerData

private final JSONObject issuerData

Issuer data.

identity

private final String identity

Entity identity.

encryptionKey

private final SecretKey encryptionKey

Encryption key.

hmacKey

private final SecretKey hmacKey

HMAC key.

verified

private final boolean verified

Token is verified.

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