com.netflix.msl.tokens

Interface TokenFactory

All Known Implementing Classes:

ClientTokenFactory

public interface TokenFactory

The token factory creates and renews master tokens and user ID tokens.

Method Summary

Modifier and Type	Method and Description
MslError	acceptNonReplayableId(MslContext ctx, MasterToken masterToken, long nonReplayableId) Return true if the non-replayable ID is larger by no more than 65536 than the largest non-replayable ID accepted so far for the provided master token.
MasterToken	createMasterToken(MslContext ctx, EntityAuthenticationData entityAuthData, javax.crypto.SecretKey encryptionKey, javax.crypto.SecretKey hmacKey, MslObject issuerData) Create a new master token with the specified identity and session keys.
MslUser	createUser(MslContext ctx, java.lang.String userdata) Create a new MSL user instance from the serialized user data.
UserIdToken	createUserIdToken(MslContext ctx, MslUser user, MasterToken masterToken) Create a new user ID token bound to the provided master token.
MslError	isMasterTokenRenewable(MslContext ctx, MasterToken masterToken) Check if the master token would be renewed by a call to #renewMasterToken(MslContext, MasterToken, SecretKey, SecretKey).
MslError	isMasterTokenRevoked(MslContext ctx, MasterToken masterToken) Return false if the master token has been revoked.
MslError	isUserIdTokenRevoked(MslContext ctx, MasterToken masterToken, UserIdToken userIdToken) Return false if the user ID token has been revoked.
MasterToken	renewMasterToken(MslContext ctx, MasterToken masterToken, javax.crypto.SecretKey encryptionKey, javax.crypto.SecretKey hmacKey, MslObject issuerData) Renew a master token assigning it the new session keys.
UserIdToken	renewUserIdToken(MslContext ctx, UserIdToken userIdToken, MasterToken masterToken) Renew a user ID token and bind it to the provided master token.

Method Detail

isMasterTokenRevoked

MslError isMasterTokenRevoked(MslContext ctx,
                              MasterToken masterToken)
                       throws MslMasterTokenException,
                              MslException

Return false if the master token has been revoked.

A master token may be revoked at any time after creation and before renewal for various reasons, including but not limited to entity revocation or knowledge that a master token or its session keys has been compromised. The entity will be forced to re-authenticate if its master token is rejected.

This method is slightly different than isMasterTokenRenewable(MslContext, MasterToken) because it will be called for every received message and should not check the renewability of the master token.

This method should return the exact MslError identifying the reason the master token has been revoked. The response code associated with the error will be honored.

Parameters:

ctx - MSL context.

masterToken - the master token to check.

Returns:

null if the master token has not been revoked. Otherwise return a MSL error.

Throws:

MslMasterTokenException - if the master token is not trusted.

MslException - if there is an error performing the revocation check.

acceptNonReplayableId

MslError acceptNonReplayableId(MslContext ctx,
                               MasterToken masterToken,
                               long nonReplayableId)
                        throws MslMasterTokenException,
                               MslException

Return true if the non-replayable ID is larger by no more than 65536 than the largest non-replayable ID accepted so far for the provided master token.

Non-replayable IDs should be tracked by the master token entity identity and serial number. Before accepting any non-replayable IDs the largest value accepted so far shall be considered zero. The maximum non- replayable ID is equal to MslConstants.MAX_LONG_VALUE which the IDs wrap around to zero. The wrap around must be considered when comparing the non-replayable ID to the largest non-replayable ID accepted so far.

It is also permitted to accept non-replayable IDs less than the largest non-replayable ID accepted so far if those non-replayable IDs have not been seen. The set of smaller non-replayable IDs accepted should be limited in size based on a reasonable expectation for the the number of concurrent non-replayable messages the entity may create.

This method should return the exact MslError identifying the reason the non-replayable ID was rejected. The response code associated with the error will be honored. If the master token entity cannot be expected to recover if the message is sent with a new non-replayable ID then the response code ResponseCode.ENTITYDATA_REAUTH should be used.

Parameters:

ctx - MSL context.

masterToken - the master token.

nonReplayableId - non-replayable ID.

Returns:

null if the non-replayable ID has been accepted. Otherwise return a MSL error.

Throws:

MslMasterTokenException - if the master token is not trusted.

MslException - if there is an error comparing or updating the non- replayable ID associated with this master token.

See Also:

#createMasterToken(MslContext, EntityAuthenticationData, SecretKey, SecretKey, JSONObject), MslError.MESSAGE_REPLAYED, MslError.MESSAGE_REPLAYED_UNRECOVERABLE

createMasterToken

MasterToken createMasterToken(MslContext ctx,
                              EntityAuthenticationData entityAuthData,
                              javax.crypto.SecretKey encryptionKey,
                              javax.crypto.SecretKey hmacKey,
                              MslObject issuerData)
                       throws MslEncodingException,
                              MslCryptoException,
                              MslException

Create a new master token with the specified identity and session keys.

Creating a new master token implies all previous master tokens issued to the specified entity are no longer valid and therefore all state data for the non-replayable IDs associated with the entity identity may be discarded.

Parameters:

ctx - MSL context.

entityAuthData - the entity authentication data.

encryptionKey - the session encryption key.

hmacKey - the session HMAC key.

issuerData - optional master token issuer data that should be included in the master token. May be null.

Returns:

the new master token.

Throws:

MslEncodingException - if there is an error encoding the data.

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

MslException - if there is an error creating the master token.

See Also:

acceptNonReplayableId(MslContext, MasterToken, long)

isMasterTokenRenewable

MslError isMasterTokenRenewable(MslContext ctx,
                                MasterToken masterToken)
                         throws MslMasterTokenException,
                                MslException

Check if the master token would be renewed by a call to #renewMasterToken(MslContext, MasterToken, SecretKey, SecretKey).

This method should return the exact MslError identifying the reason the master token will not be renewed.

Parameters:

ctx - MSL context.

masterToken - the master token to check.

Returns:

null if the master token would be renewed. Otherwise return a MSL error.

Throws:

MslMasterTokenException - if the master token is not trusted.

MslException - if there is an error checking the master token renewability.

See Also:

#renewMasterToken(MslContext, MasterToken, SecretKey, SecretKey, JSONObject)

renewMasterToken

MasterToken renewMasterToken(MslContext ctx,
                             MasterToken masterToken,
                             javax.crypto.SecretKey encryptionKey,
                             javax.crypto.SecretKey hmacKey,
                             MslObject issuerData)
                      throws MslEncodingException,
                             MslCryptoException,
                             MslMasterTokenException,
                             MslException

Renew a master token assigning it the new session keys.

This method should also perform any additional entity checks such as if the entity has been revoked.

Parameters:

ctx - MSL context.

masterToken - the master token to renew.

encryptionKey - the session encryption key.

hmacKey - the session HMAC key.

issuerData - optional master token issuer data that should be merged into or overwrite any existing issuer data. May be null.

Returns:

the new master token.

Throws:

MslEncodingException - if there is an error encoding the data.

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

MslMasterTokenException - if the master token is not trusted or the factory does not wish to renew it.

MslException - if there is an error renewing the master token.

See Also:

isMasterTokenRenewable(MslContext, MasterToken)

isUserIdTokenRevoked

MslError isUserIdTokenRevoked(MslContext ctx,
                              MasterToken masterToken,
                              UserIdToken userIdToken)
                       throws MslMasterTokenException,
                              MslUserIdTokenException,
                              MslException

Return false if the user ID token has been revoked.

A user ID token may be revoked at any time after creation and before renewal for various reasons, including but not limited to user deletion. The user will be forced to re-authenticate if its user ID token is rejected.

This method should return the exact MslError identifying the reason the user ID token has been revoked.

Parameters:

ctx - MSL context.

masterToken - the associated master token.

userIdToken - the user ID token to check.

Returns:

null if the user ID token has not been revoked. Otherwise return a MSL error.

Throws:

MslMasterTokenException - if the master token is not trusted.

MslUserIdTokenException - if the user ID token is not trusted.

MslException - if there is an error performing the revocation check.

createUserIdToken

UserIdToken createUserIdToken(MslContext ctx,
                              MslUser user,
                              MasterToken masterToken)
                       throws MslEncodingException,
                              MslCryptoException,
                              MslMasterTokenException,
                              MslException

Create a new user ID token bound to the provided master token.

Parameters:

ctx - MSL context.

user - MSL user.

masterToken - the master token to bind the user token against.

Returns:

the new user ID token.

Throws:

MslEncodingException - if there is an error encoding the data.

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

MslMasterTokenException - if the master token is not trusted.

MslException - if there is an error creating the user ID token.

renewUserIdToken

UserIdToken renewUserIdToken(MslContext ctx,
                             UserIdToken userIdToken,
                             MasterToken masterToken)
                      throws MslEncodingException,
                             MslCryptoException,
                             MslUserIdTokenException,
                             MslMasterTokenException,
                             MslException

Renew a user ID token and bind it to the provided master token.

This method should also perform any additional user checks such as if the user no longer exists or must re-login.

Parameters:

ctx - MSL context.

userIdToken - the user ID token to renew.

masterToken - the master token to bind the user token against.

Returns:

the new user ID token.

Throws:

MslEncodingException - if there is an error encoding the data.

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

MslUserIdTokenException - if the user ID token is not decrypted or the factory does not wish to renew it.

MslMasterTokenException - if the master token is not trusted.

MslException - if there is an error renewing the user ID token.

createUser

MslUser createUser(MslContext ctx,
                   java.lang.String userdata)
            throws MslEncodingException,
                   MslException

Create a new MSL user instance from the serialized user data.

This method is called when reconstructing a user ID token. Thrown MslExceptions should keep that in mind when deciding upon the MslError to reference.

Parameters:

ctx - MSL context.

userdata - serialized user data.

Returns:

the MSL user.

Throws:

MslEncodingException - if there is an error parsing the user data.

MslException - if there is an error creating the MSL user.