Package org.apache.shiro.mgt

Class AbstractRememberMeManager

  • All Implemented Interfaces:
    RememberMeManager
    Direct Known Subclasses:
    CookieRememberMeManager
    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

    • Method Detail

      • 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.

      • 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

        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.

      • 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 warning 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.