org.apache.shiro.mgt
Class AbstractRememberMeManager

java.lang.Object
  org.apache.shiro.mgt.AbstractRememberMeManager

All Implemented Interfaces:

RememberMeManager

public abstract class AbstractRememberMeManager
extends Object
implements RememberMeManager

Abstract implementation of the RememberMeManager interface that handles serialization and encryption of the remembered user identity.

The remembered identity storage location and details are left to subclasses.

Default encryption key

This implementation uses an AesCipherService for strong encryption by default. It also uses a default generated symmetric key to both encrypt and decrypt data. As AES is a symmetric cipher, the same key is used to both encrypt and decrypt data, BUT NOTE:

Because Shiro is an open-source project, if anyone knew that you were using Shiro's default key, they could download/view the source, and with enough effort, reconstruct the key and decode encrypted data at will.

Of course, this key is only really used to encrypt the remembered PrincipalCollection which is typically a user id or username. So if you do not consider that sensitive information, and you think the default key still makes things 'sufficiently difficult', then you can ignore this issue.

However, if you do feel this constitutes sensitive information, it is recommended that you provide your own key via the setCipherKey method to a key known only to your application, guaranteeing that no third party can decrypt your data. You can generate your own key by calling the CipherService's generateNewKey method and using that result as the cipherKey configuration attribute.

Since:

0.9

Constructor Summary

AbstractRememberMeManager()
Default constructor that initializes a DefaultSerializer as the serializer and an AesCipherService as the cipherService.

Method Summary

protected PrincipalCollection	convertBytesToPrincipals(byte[] bytes, SubjectContext subjectContext) If a cipherService is available, it will be used to first decrypt the byte array.
protected byte[]	convertPrincipalsToBytes(PrincipalCollection principals) Converts the given principal collection the byte array that will be persisted to be 'remembered' later.
protected byte[]	decrypt(byte[] encrypted) Decrypts the byte array using the configured cipherService.
protected PrincipalCollection	deserialize(byte[] serializedIdentity) De-serializes the given byte array by using the serializer's deserialize method.
protected byte[]	encrypt(byte[] serialized) Encrypts the byte array by using the configured cipherService.
protected abstract void	forgetIdentity(Subject subject) Forgets (removes) any remembered identity data for the specified Subject instance.
byte[]	getCipherKey() Convenience method that returns the cipher key to use for both encryption and decryption.
CipherService	getCipherService() Returns the CipherService to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data.
byte[]	getDecryptionCipherKey() Returns the decryption cipher key to use for decryption operations.
byte[]	getEncryptionCipherKey() Returns the cipher key to use for encryption operations.
protected PrincipalCollection	getIdentityToRemember(Subject subject, AuthenticationInfo info) Returns info.getPrincipals() and ignores the Subject argument.
PrincipalCollection	getRememberedPrincipals(SubjectContext subjectContext) Implements the interface method by first acquiring the remembered serialized byte array.
protected abstract byte[]	getRememberedSerializedIdentity(SubjectContext subjectContext) Based on the given subject context data, retrieves the previously persisted serialized identity, or null if there is no available data.
Serializer<PrincipalCollection>	getSerializer() Returns the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.
protected boolean	isRememberMe(AuthenticationToken token) Determines whether or not remember me services should be performed for the specified token.
void	onFailedLogin(Subject subject, AuthenticationToken token, AuthenticationException ae) Reacts to a failed login by immediately forgetting any previously remembered identity.
void	onLogout(Subject subject) Reacts to a subject logging out of the application and immediately forgets any previously stored identity and returns.
protected PrincipalCollection	onRememberedPrincipalFailure(RuntimeException e, SubjectContext context) Called when an exception is thrown while trying to retrieve principals.
void	onSuccessfulLogin(Subject subject, AuthenticationToken token, AuthenticationInfo info) Reacts to the successful login attempt by first always forgetting any previously stored identity.
void	rememberIdentity(Subject subject, AuthenticationToken token, AuthenticationInfo authcInfo) Remembers a subject-unique identity for retrieval later.
protected void	rememberIdentity(Subject subject, PrincipalCollection accountPrincipals) Remembers the specified account principals by first converting them to a byte array and then remembers that byte array.
protected abstract void	rememberSerializedIdentity(Subject subject, byte[] serialized) Persists the identity bytes to a persistent store for retrieval later via the getRememberedSerializedIdentity(SubjectContext) method.
protected byte[]	serialize(PrincipalCollection principals) Serializes the given principals by serializing them to a byte array by using the serializer's serialize method.
void	setCipherKey(byte[] cipherKey) Convenience method that sets the cipher key to use for both encryption and decryption.
void	setCipherService(CipherService cipherService) Sets the CipherService to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data.
void	setDecryptionCipherKey(byte[] decryptionCipherKey) Sets the decryption key to use for decryption operations.
void	setEncryptionCipherKey(byte[] encryptionCipherKey) Sets the encryption key to use for encryption operations.
void	setSerializer(Serializer<PrincipalCollection> serializer) Sets the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.shiro.mgt.RememberMeManager

forgetIdentity

Constructor Detail

AbstractRememberMeManager

public AbstractRememberMeManager()

Default constructor that initializes a DefaultSerializer as the serializer and an AesCipherService as the cipherService.

Method Detail

getSerializer

public Serializer<PrincipalCollection> getSerializer()

Returns the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.

Unless overridden by the setSerializer(org.apache.shiro.io.Serializer) method, the default instance is a DefaultSerializer.

Returns:

the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.

setSerializer

public void setSerializer(Serializer<PrincipalCollection> serializer)

Sets the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.

Unless overridden by this method, the default instance is a DefaultSerializer.

Parameters:

serializer - the Serializer used to serialize and deserialize PrincipalCollection instances for persistent remember me storage.

getCipherService

public CipherService getCipherService()

Returns the CipherService to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data.

Unless overridden by the setCipherService(org.apache.shiro.crypto.CipherService) method, the default instance is an AesCipherService.

Returns:

the Cipher to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data

setCipherService

public void setCipherService(CipherService cipherService)

Sets the CipherService to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data.

If the CipherService is a symmetric CipherService (using the same key for both encryption and decryption), you should set your key via the setCipherKey(byte[]) method.

If the CipherService is an asymmetric CipherService (different keys for encryption and decryption, such as public/private key pairs), you should set your encryption and decryption key via the respective setEncryptionCipherKey(byte[]) and setDecryptionCipherKey(byte[]) methods.

N.B. Unless overridden by this method, the default CipherService instance is an AesCipherService. This RememberMeManager implementation already has a configured symmetric key to use for encryption and decryption, but it is recommended to provide your own for added security. See the class-level JavaDoc for more information and why it might be good to provide your own.

Parameters:

cipherService - the CipherService to use for encrypting and decrypting serialized identity data to prevent easy inspection of Subject identity data.

getEncryptionCipherKey

public byte[] getEncryptionCipherKey()

Returns the cipher key to use for encryption operations.

Returns:

the cipher key to use for encryption operations.

See Also:

for a description of the various {@code get/set*Key} methods.

setEncryptionCipherKey

public void setEncryptionCipherKey(byte[] encryptionCipherKey)

Sets the encryption key to use for encryption operations.

Parameters:

encryptionCipherKey - the encryption key to use for encryption operations.

See Also:

for a description of the various {@code get/set*Key} methods.

getDecryptionCipherKey

public byte[] getDecryptionCipherKey()

Returns the decryption cipher key to use for decryption operations.

Returns:

the cipher key to use for decryption operations.

See Also:

for a description of the various {@code get/set*Key} methods.

setDecryptionCipherKey

public void setDecryptionCipherKey(byte[] decryptionCipherKey)

Sets the decryption key to use for decryption operations.

Parameters:

decryptionCipherKey - the decryption key to use for decryption operations.

See Also:

for a description of the various {@code get/set*Key} methods.

getCipherKey

public byte[] getCipherKey()

Convenience method that returns the cipher key to use for both encryption and decryption.

N.B. This method can only be called if the underlying cipherService is a symmetric CipherService which by definition uses the same key for both encryption and decryption. If using an asymmetric CipherService public/private key pair, you cannot use this method, and should instead use the getEncryptionCipherKey() and getDecryptionCipherKey() methods individually.

The default AesCipherService instance is a symmetric cipher service, so this method can be used if you are using the default.

Returns:

the symmetric cipher key used for both encryption and decryption.

setCipherKey

public void setCipherKey(byte[] cipherKey)

Convenience method that sets the cipher key to use for both encryption and decryption.

N.B. This method can only be called if the underlying cipherService is a symmetric CipherService?which by definition uses the same key for both encryption and decryption. If using an asymmetric CipherService?(such as a public/private key pair), you cannot use this method, and should instead use the setEncryptionCipherKey(byte[]) and setDecryptionCipherKey(byte[]) methods individually.

The default AesCipherService instance is a symmetric CipherService, so this method can be used if you are using the default.

Parameters:

cipherKey - the symmetric cipher key to use for both encryption and decryption.

forgetIdentity

protected abstract void forgetIdentity(Subject subject)

Forgets (removes) any remembered identity data for the specified Subject instance.

Parameters:

subject - the subject instance for which identity data should be forgotten from the underlying persistence mechanism.

isRememberMe

protected boolean isRememberMe(AuthenticationToken token)

Determines whether or not remember me services should be performed for the specified token. This method returns true iff:

1. The token is not null and
2. The token is an instanceof RememberMeAuthenticationToken and
3. token.isRememberMe() is true

Parameters:

token - the authentication token submitted during the successful authentication attempt.

Returns:

true if remember me services should be performed as a result of the successful authentication attempt.

onSuccessfulLogin

public void onSuccessfulLogin(Subject subject,
                              AuthenticationToken token,
                              AuthenticationInfo info)

Reacts to the successful login attempt by first always forgetting any previously stored identity. Then if the token is a RememberMe token, the associated identity will be remembered for later retrieval during a new user session.

Specified by:

onSuccessfulLogin in interface RememberMeManager

Parameters:

subject - the subject for which the principals are being remembered.

token - the token that resulted in a successful authentication attempt.

info - the authentication info resulting from the successful authentication attempt.

rememberIdentity

public void rememberIdentity(Subject subject,
                             AuthenticationToken token,
                             AuthenticationInfo authcInfo)

Remembers a subject-unique identity for retrieval later. This implementation first resolves the exact principals to remember. It then remembers the principals by calling rememberIdentity(org.apache.shiro.subject.Subject, org.apache.shiro.subject.PrincipalCollection).

This implementation ignores the AuthenticationToken argument, but it is available to subclasses if necessary for custom logic.

Parameters:

subject - the subject for which the principals are being remembered.

token - the token that resulted in a successful authentication attempt.

authcInfo - the authentication info resulting from the successful authentication attempt.

getIdentityToRemember

protected PrincipalCollection getIdentityToRemember(Subject subject,
                                                    AuthenticationInfo info)

Returns info.getPrincipals() and ignores the Subject argument.

Parameters:

subject - the subject for which the principals are being remembered.

info - the authentication info resulting from the successful authentication attempt.

Returns:

the PrincipalCollection to remember.

rememberIdentity

protected void rememberIdentity(Subject subject,
                                PrincipalCollection accountPrincipals)

Remembers the specified account principals by first converting them to a byte array and then remembers that byte array.

Parameters:

subject - the subject for which the principals are being remembered.

accountPrincipals - the principals to remember for retrieval later.

convertPrincipalsToBytes

protected byte[] convertPrincipalsToBytes(PrincipalCollection principals)

Converts the given principal collection the byte array that will be persisted to be 'remembered' later.

This implementation first serializes the principals to a byte array and then encrypts that byte array.

Parameters:

principals - the PrincipalCollection to convert to a byte array

Returns:

the representative byte array to be persisted for remember me functionality.

rememberSerializedIdentity

protected abstract void rememberSerializedIdentity(Subject subject,
                                                   byte[] serialized)

Persists the identity bytes to a persistent store for retrieval later via the getRememberedSerializedIdentity(SubjectContext) method.

Parameters:

subject - the Subject for which the identity is being serialized.

serialized - the serialized bytes to be persisted.

getRememberedPrincipals

public PrincipalCollection getRememberedPrincipals(SubjectContext subjectContext)

Implements the interface method by first acquiring the remembered serialized byte array. Then it converts them and returns the re-constituted PrincipalCollection. If no remembered principals could be obtained, null is returned.

If any exceptions are thrown, the onRememberedPrincipalFailure(RuntimeException, SubjectContext) method is called to allow any necessary post-processing (such as immediately removing any previously remembered values for safety).

Specified by:

getRememberedPrincipals in interface RememberMeManager

Parameters:

subjectContext - the contextual data, usually provided by a Subject.Builder implementation, that is being used to construct a Subject instance.

Returns:

the remembered principals or null if none could be acquired.

getRememberedSerializedIdentity

protected abstract byte[] getRememberedSerializedIdentity(SubjectContext subjectContext)

Based on the given subject context data, retrieves the previously persisted serialized identity, or null if there is no available data. The context map is usually populated by a Subject.Builder implementation. See the SubjectFactory class constants for Shiro's known map keys.

Parameters:

subjectContext - the contextual data, usually provided by a Subject.Builder implementation, that is being used to construct a Subject instance. To be used to assist with data lookup.

Returns:

the previously persisted serialized identity, or null if there is no available data for the Subject.

convertBytesToPrincipals

protected PrincipalCollection convertBytesToPrincipals(byte[] bytes,
                                                       SubjectContext subjectContext)

If a cipherService is available, it will be used to first decrypt the byte array. Then the bytes are then deserialized and then returned.

Parameters:

bytes - the bytes to decrypt if necessary and then deserialize.

subjectContext - the contextual data, usually provided by a Subject.Builder implementation, that is being used to construct a Subject instance.

Returns:

the de-serialized and possibly decrypted principals

onRememberedPrincipalFailure

protected PrincipalCollection onRememberedPrincipalFailure(RuntimeException e,
                                                           SubjectContext context)

Called when an exception is thrown while trying to retrieve principals. The default implementation logs a debug message and forgets ('unremembers') the problem identity by calling forgetIdentity(context) and then immediately re-throws the exception to allow the calling component to react accordingly.

This method implementation never returns an object - it always rethrows, but can be overridden by subclasses for custom handling behavior.

This most commonly would be called when an encryption key is updated and old principals are retrieved that have been encrypted with the previous key.

Parameters:

e - the exception that was thrown.

context - the contextual data, usually provided by a Subject.Builder implementation, that is being used to construct a Subject instance.

Returns:

nothing - the original RuntimeException is propagated in all cases.

encrypt

protected byte[] encrypt(byte[] serialized)

Encrypts the byte array by using the configured cipherService.

Parameters:

serialized - the serialized object byte array to be encrypted

Returns:

an encrypted byte array returned by the configured () cipher.

decrypt

protected byte[] decrypt(byte[] encrypted)

Decrypts the byte array using the configured cipherService.

Parameters:

encrypted - the encrypted byte array to decrypt

Returns:

the decrypted byte array returned by the configured () cipher.

serialize

protected byte[] serialize(PrincipalCollection principals)

Serializes the given principals by serializing them to a byte array by using the serializer's serialize method.

Parameters:

principals - the principal collection to serialize to a byte array

Returns:

the serialized principal collection in the form of a byte array

deserialize

protected PrincipalCollection deserialize(byte[] serializedIdentity)

De-serializes the given byte array by using the serializer's deserialize method.

Parameters:

serializedIdentity - the previously serialized PrincipalCollection as a byte array

Returns:

the de-serialized (reconstituted) PrincipalCollection

onFailedLogin

public void onFailedLogin(Subject subject,
                          AuthenticationToken token,
                          AuthenticationException ae)

Reacts to a failed login by immediately forgetting any previously remembered identity. This is an additional security feature to prevent any remenant identity data from being retained in case the authentication attempt is not being executed by the expected user.

Specified by:

onFailedLogin in interface RememberMeManager

Parameters:

subject - the subject which executed the failed login attempt

token - the authentication token resulting in a failed login attempt - ignored by this implementation

ae - the exception thrown as a result of the failed login attempt - ignored by this implementation

onLogout

public void onLogout(Subject subject)

Reacts to a subject logging out of the application and immediately forgets any previously stored identity and returns.

Specified by:

onLogout in interface RememberMeManager

Parameters:

subject - the subject logging out.