| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| package org.apache.shiro.mgt; |
| |
| import org.apache.shiro.authc.AuthenticationException; |
| import org.apache.shiro.authc.AuthenticationInfo; |
| import org.apache.shiro.authc.AuthenticationToken; |
| import org.apache.shiro.authc.RememberMeAuthenticationToken; |
| import org.apache.shiro.codec.Base64; |
| import org.apache.shiro.crypto.AesCipherService; |
| import org.apache.shiro.crypto.CipherService; |
| import org.apache.shiro.io.DefaultSerializer; |
| import org.apache.shiro.io.Serializer; |
| import org.apache.shiro.subject.PrincipalCollection; |
| import org.apache.shiro.subject.Subject; |
| import org.apache.shiro.subject.SubjectContext; |
| import org.apache.shiro.util.ByteSource; |
| import org.slf4j.Logger; |
| import org.slf4j.LoggerFactory; |
| |
| /** |
| * Abstract implementation of the {@code RememberMeManager} interface that handles |
| * {@link #setSerializer(org.apache.shiro.io.Serializer) serialization} and |
| * {@link #setCipherService encryption} of the remembered user identity. |
| * <p/> |
| * The remembered identity storage location and details are left to subclasses. |
| * <h2>Default encryption key</h2> |
| * This implementation uses an {@link AesCipherService 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 |
| * {@code key} is used to both encrypt and decrypt data, BUT NOTE: |
| * <p/> |
| * Because Shiro is an open-source project, if anyone knew that you were using Shiro's default |
| * {@code key}, they could download/view the source, and with enough effort, reconstruct the {@code key} |
| * and decode encrypted data at will. |
| * <p/> |
| * Of course, this key is only really used to encrypt the remembered {@code 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. |
| * <p/> |
| * However, if you do feel this constitutes sensitive information, it is recommended that you provide your own |
| * {@code key} via the {@link #setCipherKey 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 |
| * {@code CipherService}'s {@link org.apache.shiro.crypto.AesCipherService#generateNewKey() generateNewKey} method |
| * and using that result as the {@link #setCipherKey cipherKey} configuration attribute. |
| * |
| * @since 0.9 |
| */ |
| public abstract class AbstractRememberMeManager implements RememberMeManager { |
| |
| /** |
| * private inner log instance. |
| */ |
| private static final Logger log = LoggerFactory.getLogger(AbstractRememberMeManager.class); |
| |
| /** |
| * The following Base64 string was generated by auto-generating an AES Key: |
| * <pre> |
| * AesCipherService aes = new AesCipherService(); |
| * byte[] key = aes.generateNewKey().getEncoded(); |
| * String base64 = Base64.encodeToString(key); |
| * </pre> |
| * The value of 'base64' was copied-n-pasted here: |
| */ |
| private static final byte[] DEFAULT_CIPHER_KEY_BYTES = Base64.decode("kPH+bIxk5D2deZiIxcaaaA=="); |
| |
| /** |
| * Serializer to use for converting PrincipalCollection instances to/from byte arrays |
| */ |
| private Serializer<PrincipalCollection> serializer; |
| |
| /** |
| * Cipher to use for encrypting/decrypting serialized byte arrays for added security |
| */ |
| private CipherService cipherService; |
| |
| /** |
| * Cipher encryption key to use with the Cipher when encrypting data |
| */ |
| private byte[] encryptionCipherKey; |
| |
| /** |
| * Cipher decryption key to use with the Cipher when decrypting data |
| */ |
| private byte[] decryptionCipherKey; |
| |
| /** |
| * Default constructor that initializes a {@link DefaultSerializer} as the {@link #getSerializer() serializer} and |
| * an {@link AesCipherService} as the {@link #getCipherService() cipherService}. |
| */ |
| public AbstractRememberMeManager() { |
| this.serializer = new DefaultSerializer<PrincipalCollection>(); |
| this.cipherService = new AesCipherService(); |
| setCipherKey(DEFAULT_CIPHER_KEY_BYTES); |
| } |
| |
| /** |
| * Returns the {@code Serializer} used to serialize and deserialize {@link PrincipalCollection} instances for |
| * persistent remember me storage. |
| * <p/> |
| * Unless overridden by the {@link #setSerializer} method, the default instance is a |
| * {@link org.apache.shiro.io.DefaultSerializer}. |
| * |
| * @return the {@code Serializer} used to serialize and deserialize {@link PrincipalCollection} instances for |
| * persistent remember me storage. |
| */ |
| public Serializer<PrincipalCollection> getSerializer() { |
| return serializer; |
| } |
| |
| /** |
| * Sets the {@code Serializer} used to serialize and deserialize {@link PrincipalCollection} instances for |
| * persistent remember me storage. |
| * <p/> |
| * Unless overridden by this method, the default instance is a {@link DefaultSerializer}. |
| * |
| * @param serializer the {@code Serializer} used to serialize and deserialize {@link PrincipalCollection} instances |
| * for persistent remember me storage. |
| */ |
| public void setSerializer(Serializer<PrincipalCollection> serializer) { |
| this.serializer = serializer; |
| } |
| |
| /** |
| * Returns the {@code CipherService} to use for encrypting and decrypting serialized identity data to prevent easy |
| * inspection of Subject identity data. |
| * <p/> |
| * Unless overridden by the {@link #setCipherService} method, the default instance is an {@link AesCipherService}. |
| * |
| * @return the {@code Cipher} to use for encrypting and decrypting serialized identity data to prevent easy |
| * inspection of Subject identity data |
| */ |
| public CipherService getCipherService() { |
| return cipherService; |
| } |
| |
| /** |
| * Sets the {@code CipherService} to use for encrypting and decrypting serialized identity data to prevent easy |
| * inspection of Subject identity data. |
| * <p/> |
| * If the CipherService is a symmetric CipherService (using the same key for both encryption and decryption), you |
| * should set your key via the {@link #setCipherKey(byte[])} method. |
| * <p/> |
| * 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 |
| * {@link #setEncryptionCipherKey(byte[])} and {@link #setDecryptionCipherKey(byte[])} methods. |
| * <p/> |
| * <b>N.B.</b> Unless overridden by this method, the default CipherService instance is an |
| * {@link AesCipherService}. This {@code 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. |
| * |
| * @param cipherService the {@code CipherService} to use for encrypting and decrypting serialized identity data to |
| * prevent easy inspection of Subject identity data. |
| */ |
| public void setCipherService(CipherService cipherService) { |
| this.cipherService = cipherService; |
| } |
| |
| /** |
| * Returns the cipher key to use for encryption operations. |
| * |
| * @return the cipher key to use for encryption operations. |
| * @see #setCipherService for a description of the various {@code get/set*Key} methods. |
| */ |
| public byte[] getEncryptionCipherKey() { |
| return encryptionCipherKey; |
| } |
| |
| /** |
| * Sets the encryption key to use for encryption operations. |
| * |
| * @param encryptionCipherKey the encryption key to use for encryption operations. |
| * @see #setCipherService for a description of the various {@code get/set*Key} methods. |
| */ |
| public void setEncryptionCipherKey(byte[] encryptionCipherKey) { |
| this.encryptionCipherKey = encryptionCipherKey; |
| } |
| |
| /** |
| * Returns the decryption cipher key to use for decryption operations. |
| * |
| * @return the cipher key to use for decryption operations. |
| * @see #setCipherService for a description of the various {@code get/set*Key} methods. |
| */ |
| public byte[] getDecryptionCipherKey() { |
| return decryptionCipherKey; |
| } |
| |
| /** |
| * Sets the decryption key to use for decryption operations. |
| * |
| * @param decryptionCipherKey the decryption key to use for decryption operations. |
| * @see #setCipherService for a description of the various {@code get/set*Key} methods. |
| */ |
| public void setDecryptionCipherKey(byte[] decryptionCipherKey) { |
| this.decryptionCipherKey = decryptionCipherKey; |
| } |
| |
| /** |
| * Convenience method that returns the cipher key to use for <em>both</em> encryption and decryption. |
| * <p/> |
| * <b>N.B.</b> This method can only be called if the underlying {@link #getCipherService() 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 |
| * {@link #getEncryptionCipherKey()} and {@link #getDecryptionCipherKey()} methods individually. |
| * <p/> |
| * The default {@link AesCipherService} instance is a symmetric cipher service, so this method can be used if you are |
| * using the default. |
| * |
| * @return the symmetric cipher key used for both encryption and decryption. |
| */ |
| public byte[] getCipherKey() { |
| //Since this method should only be used with symmetric ciphers |
| //(where the enc and dec keys are the same), either is fine, just return one of them: |
| return getEncryptionCipherKey(); |
| } |
| |
| /** |
| * Convenience method that sets the cipher key to use for <em>both</em> encryption and decryption. |
| * <p/> |
| * <b>N.B.</b> This method can only be called if the underlying {@link #getCipherService() 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 {@link #setEncryptionCipherKey(byte[])} and {@link #setDecryptionCipherKey(byte[])} methods individually. |
| * <p/> |
| * The default {@link AesCipherService} instance is a symmetric CipherService, so this method can be used if you |
| * are using the default. |
| * |
| * @param cipherKey the symmetric cipher key to use for both encryption and decryption. |
| */ |
| public void setCipherKey(byte[] cipherKey) { |
| //Since this method should only be used in symmetric ciphers |
| //(where the enc and dec keys are the same), set it on both: |
| setEncryptionCipherKey(cipherKey); |
| setDecryptionCipherKey(cipherKey); |
| } |
| |
| /** |
| * Forgets (removes) any remembered identity data for the specified {@link Subject} instance. |
| * |
| * @param subject the subject instance for which identity data should be forgotten from the underlying persistence |
| * mechanism. |
| */ |
| protected abstract void forgetIdentity(Subject subject); |
| |
| /** |
| * Determines whether or not remember me services should be performed for the specified token. This method returns |
| * {@code true} iff: |
| * <ol> |
| * <li>The token is not {@code null} and</li> |
| * <li>The token is an {@code instanceof} {@link RememberMeAuthenticationToken} and</li> |
| * <li>{@code token}.{@link org.apache.shiro.authc.RememberMeAuthenticationToken#isRememberMe() isRememberMe()} is |
| * {@code true}</li> |
| * </ol> |
| * |
| * @param token the authentication token submitted during the successful authentication attempt. |
| * @return true if remember me services should be performed as a result of the successful authentication attempt. |
| */ |
| protected boolean isRememberMe(AuthenticationToken token) { |
| return token != null && (token instanceof RememberMeAuthenticationToken) && |
| ((RememberMeAuthenticationToken) token).isRememberMe(); |
| } |
| |
| /** |
| * Reacts to the successful login attempt by first always {@link #forgetIdentity(Subject) forgetting} any previously |
| * stored identity. Then if the {@code token} |
| * {@link #isRememberMe(org.apache.shiro.authc.AuthenticationToken) is a RememberMe} token, the associated identity |
| * will be {@link #rememberIdentity(org.apache.shiro.subject.Subject, org.apache.shiro.authc.AuthenticationToken, org.apache.shiro.authc.AuthenticationInfo) remembered} |
| * for later retrieval during a new user session. |
| * |
| * @param subject the subject for which the principals are being remembered. |
| * @param token the token that resulted in a successful authentication attempt. |
| * @param info the authentication info resulting from the successful authentication attempt. |
| */ |
| public void onSuccessfulLogin(Subject subject, AuthenticationToken token, AuthenticationInfo info) { |
| //always clear any previous identity: |
| forgetIdentity(subject); |
| |
| //now save the new identity: |
| if (isRememberMe(token)) { |
| rememberIdentity(subject, token, info); |
| } else { |
| if (log.isDebugEnabled()) { |
| log.debug("AuthenticationToken did not indicate RememberMe is requested. " + |
| "RememberMe functionality will not be executed for corresponding account."); |
| } |
| } |
| } |
| |
| /** |
| * Remembers a subject-unique identity for retrieval later. This implementation first |
| * {@link #getIdentityToRemember resolves} the exact |
| * {@link PrincipalCollection principals} to remember. It then remembers the principals by calling |
| * {@link #rememberIdentity(org.apache.shiro.subject.Subject, org.apache.shiro.subject.PrincipalCollection)}. |
| * <p/> |
| * This implementation ignores the {@link AuthenticationToken} argument, but it is available to subclasses if |
| * necessary for custom logic. |
| * |
| * @param subject the subject for which the principals are being remembered. |
| * @param token the token that resulted in a successful authentication attempt. |
| * @param authcInfo the authentication info resulting from the successful authentication attempt. |
| */ |
| public void rememberIdentity(Subject subject, AuthenticationToken token, AuthenticationInfo authcInfo) { |
| PrincipalCollection principals = getIdentityToRemember(subject, authcInfo); |
| rememberIdentity(subject, principals); |
| } |
| |
| /** |
| * Returns {@code info}.{@link org.apache.shiro.authc.AuthenticationInfo#getPrincipals() getPrincipals()} and |
| * ignores the {@link Subject} argument. |
| * |
| * @param subject the subject for which the principals are being remembered. |
| * @param info the authentication info resulting from the successful authentication attempt. |
| * @return the {@code PrincipalCollection} to remember. |
| */ |
| protected PrincipalCollection getIdentityToRemember(Subject subject, AuthenticationInfo info) { |
| return info.getPrincipals(); |
| } |
| |
| /** |
| * Remembers the specified account principals by first |
| * {@link #convertPrincipalsToBytes(org.apache.shiro.subject.PrincipalCollection) converting} them to a byte |
| * array and then {@link #rememberSerializedIdentity(org.apache.shiro.subject.Subject, byte[]) remembers} that |
| * byte array. |
| * |
| * @param subject the subject for which the principals are being remembered. |
| * @param accountPrincipals the principals to remember for retrieval later. |
| */ |
| protected void rememberIdentity(Subject subject, PrincipalCollection accountPrincipals) { |
| byte[] bytes = convertPrincipalsToBytes(accountPrincipals); |
| rememberSerializedIdentity(subject, bytes); |
| } |
| |
| /** |
| * Converts the given principal collection the byte array that will be persisted to be 'remembered' later. |
| * <p/> |
| * This implementation first {@link #serialize(org.apache.shiro.subject.PrincipalCollection) serializes} the |
| * principals to a byte array and then {@link #encrypt(byte[]) encrypts} that byte array. |
| * |
| * @param principals the {@code PrincipalCollection} to convert to a byte array |
| * @return the representative byte array to be persisted for remember me functionality. |
| */ |
| protected byte[] convertPrincipalsToBytes(PrincipalCollection principals) { |
| byte[] bytes = serialize(principals); |
| if (getCipherService() != null) { |
| bytes = encrypt(bytes); |
| } |
| return bytes; |
| } |
| |
| /** |
| * Persists the identity bytes to a persistent store for retrieval later via the |
| * {@link #getRememberedSerializedIdentity(SubjectContext)} method. |
| * |
| * @param subject the Subject for which the identity is being serialized. |
| * @param serialized the serialized bytes to be persisted. |
| */ |
| protected abstract void rememberSerializedIdentity(Subject subject, byte[] serialized); |
| |
| /** |
| * Implements the interface method by first {@link #getRememberedSerializedIdentity(SubjectContext) acquiring} |
| * the remembered serialized byte array. Then it {@link #convertBytesToPrincipals(byte[], SubjectContext) converts} |
| * them and returns the re-constituted {@link PrincipalCollection}. If no remembered principals could be |
| * obtained, {@code null} is returned. |
| * <p/> |
| * If any exceptions are thrown, the {@link #onRememberedPrincipalFailure(RuntimeException, SubjectContext)} method |
| * is called to allow any necessary post-processing (such as immediately removing any previously remembered |
| * values for safety). |
| * |
| * @param subjectContext the contextual data, usually provided by a {@link Subject.Builder} implementation, that |
| * is being used to construct a {@link Subject} instance. |
| * @return the remembered principals or {@code null} if none could be acquired. |
| */ |
| public PrincipalCollection getRememberedPrincipals(SubjectContext subjectContext) { |
| PrincipalCollection principals = null; |
| try { |
| byte[] bytes = getRememberedSerializedIdentity(subjectContext); |
| //SHIRO-138 - only call convertBytesToPrincipals if bytes exist: |
| if (bytes != null && bytes.length > 0) { |
| principals = convertBytesToPrincipals(bytes, subjectContext); |
| } |
| } catch (RuntimeException re) { |
| principals = onRememberedPrincipalFailure(re, subjectContext); |
| } |
| |
| return principals; |
| } |
| |
| /** |
| * Based on the given subject context data, retrieves the previously persisted serialized identity, or |
| * {@code null} if there is no available data. The context map is usually populated by a {@link Subject.Builder} |
| * implementation. See the {@link SubjectFactory} class constants for Shiro's known map keys. |
| * |
| * @param subjectContext the contextual data, usually provided by a {@link Subject.Builder} implementation, that |
| * is being used to construct a {@link Subject} instance. To be used to assist with data |
| * lookup. |
| * @return the previously persisted serialized identity, or {@code null} if there is no available data for the |
| * Subject. |
| */ |
| protected abstract byte[] getRememberedSerializedIdentity(SubjectContext subjectContext); |
| |
| /** |
| * If a {@link #getCipherService() cipherService} is available, it will be used to first decrypt the byte array. |
| * Then the bytes are then {@link #deserialize(byte[]) deserialized} and then returned. |
| * |
| * @param bytes the bytes to decrypt if necessary and then deserialize. |
| * @param subjectContext the contextual data, usually provided by a {@link Subject.Builder} implementation, that |
| * is being used to construct a {@link Subject} instance. |
| * @return the de-serialized and possibly decrypted principals |
| */ |
| protected PrincipalCollection convertBytesToPrincipals(byte[] bytes, SubjectContext subjectContext) { |
| if (getCipherService() != null) { |
| bytes = decrypt(bytes); |
| } |
| return deserialize(bytes); |
| } |
| |
| /** |
| * 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 |
| * {@link #forgetIdentity(SubjectContext) forgetIdentity(context)} and then immediately re-throws the |
| * exception to allow the calling component to react accordingly. |
| * <p/> |
| * This method implementation never returns an |
| * object - it always rethrows, but can be overridden by subclasses for custom handling behavior. |
| * <p/> |
| * 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. |
| * |
| * @param e the exception that was thrown. |
| * @param context the contextual data, usually provided by a {@link Subject.Builder} implementation, that |
| * is being used to construct a {@link Subject} instance. |
| * @return nothing - the original {@code RuntimeException} is propagated in all cases. |
| */ |
| protected PrincipalCollection onRememberedPrincipalFailure(RuntimeException e, SubjectContext context) { |
| if (log.isDebugEnabled()) { |
| log.debug("There was a failure while trying to retrieve remembered principals. This could be due to a " + |
| "configuration problem or corrupted principals. This could also be due to a recently " + |
| "changed encryption key. The remembered identity will be forgotten and not used for this " + |
| "request.", e); |
| } |
| forgetIdentity(context); |
| //propagate - security manager implementation will handle and warn appropriately |
| throw e; |
| } |
| |
| /** |
| * Encrypts the byte array by using the configured {@link #getCipherService() cipherService}. |
| * |
| * @param serialized the serialized object byte array to be encrypted |
| * @return an encrypted byte array returned by the configured {@link #getCipherService () cipher}. |
| */ |
| protected byte[] encrypt(byte[] serialized) { |
| byte[] value = serialized; |
| CipherService cipherService = getCipherService(); |
| if (cipherService != null) { |
| ByteSource byteSource = cipherService.encrypt(serialized, getEncryptionCipherKey()); |
| value = byteSource.getBytes(); |
| } |
| return value; |
| } |
| |
| /** |
| * Decrypts the byte array using the configured {@link #getCipherService() cipherService}. |
| * |
| * @param encrypted the encrypted byte array to decrypt |
| * @return the decrypted byte array returned by the configured {@link #getCipherService () cipher}. |
| */ |
| protected byte[] decrypt(byte[] encrypted) { |
| byte[] serialized = encrypted; |
| CipherService cipherService = getCipherService(); |
| if (cipherService != null) { |
| ByteSource byteSource = cipherService.decrypt(encrypted, getDecryptionCipherKey()); |
| serialized = byteSource.getBytes(); |
| } |
| return serialized; |
| } |
| |
| /** |
| * Serializes the given {@code principals} by serializing them to a byte array by using the |
| * {@link #getSerializer() serializer}'s {@link Serializer#serialize(Object) serialize} method. |
| * |
| * @param principals the principal collection to serialize to a byte array |
| * @return the serialized principal collection in the form of a byte array |
| */ |
| protected byte[] serialize(PrincipalCollection principals) { |
| return getSerializer().serialize(principals); |
| } |
| |
| /** |
| * De-serializes the given byte array by using the {@link #getSerializer() serializer}'s |
| * {@link Serializer#deserialize deserialize} method. |
| * |
| * @param serializedIdentity the previously serialized {@code PrincipalCollection} as a byte array |
| * @return the de-serialized (reconstituted) {@code PrincipalCollection} |
| */ |
| protected PrincipalCollection deserialize(byte[] serializedIdentity) { |
| return getSerializer().deserialize(serializedIdentity); |
| } |
| |
| /** |
| * Reacts to a failed login by immediately {@link #forgetIdentity(org.apache.shiro.subject.Subject) 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. |
| * |
| * @param subject the subject which executed the failed login attempt |
| * @param token the authentication token resulting in a failed login attempt - ignored by this implementation |
| * @param ae the exception thrown as a result of the failed login attempt - ignored by this implementation |
| */ |
| public void onFailedLogin(Subject subject, AuthenticationToken token, AuthenticationException ae) { |
| forgetIdentity(subject); |
| } |
| |
| /** |
| * Reacts to a subject logging out of the application and immediately |
| * {@link #forgetIdentity(org.apache.shiro.subject.Subject) forgets} any previously stored identity and returns. |
| * |
| * @param subject the subject logging out. |
| */ |
| public void onLogout(Subject subject) { |
| forgetIdentity(subject); |
| } |
| } |
