PasswordService.java

/*
 * 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.authc.credential;

import org.apache.shiro.util.ByteSource;

/**
 * A {@code PasswordService} supports common use cases when using passwords as a credentials mechanism.
 * <p/>
 * Most importantly, implementations of this interface are expected to employ best-practices to ensure that
 * passwords remain as safe as possible in application environments.
 * <h2>Usage</h2>
 * A {@code PasswordService} is used at two different times during an application's lifecycle:
 * <ul>
 * <li>When creating a user account or resetting their password</li>
 * <li>When a user logs in, when passwords must be compared</li>
 * </ul>
 * <h3>Account Creation or Password Reset</h3>
 * Whenever you create a new user account or reset that account's password, we must translate the end-user submitted
 * raw/plaintext password value to a string format that is much safer to store.  You do that by calling the
 * {@link #encryptPassword(Object)} method to create the safer value.  For
 * example:
 * <pre>
 * String submittedPlaintextPassword = ...
 * String encryptedValue = passwordService.encryptPassword(submittedPlaintextPassword);
 * ...
 * userAccount.setPassword(encryptedValue);
 * userAccount.save(); //create or update to your data store
 * </pre>
 * Be sure to save this encrypted password in your data store and never the original/raw submitted password.
 * <h3>Login Password Comparison</h3>
 * Shiro performs the comparison during login automatically.  Along with your {@code PasswordService}, you just
 * have to configure a {@link PasswordMatcher} on a realm that has password-based accounts.   During a login attempt,
 * shiro will use the {@code PasswordMatcher} and the {@code PasswordService} to automatically compare submitted
 * passwords.
 * <p/>
 * For example, if using Shiro's INI, here is how you might configure the PasswordMatcher and PasswordService:
 * <pre>
 * [main]
 * ...
 * passwordService = org.apache.shiro.authc.credential.DefaultPasswordService
 * # configure the passwordService to use the settings you desire
 * ...
 * passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher
 * passwordMatcher.passwordService = $passwordService
 * ...
 * # Finally, set the matcher on a realm that requires password matching for account authentication:
 * myRealm = ...
 * myRealm.credentialsMatcher = $passwordMatcher
 * </pre>
 *
 * @see DefaultPasswordService
 * @see PasswordMatcher
 * @since 1.2
 */
public interface PasswordService {

    /**
     * Converts the specified plaintext password (usually acquired from your application's 'new user' or 'password reset'
     * workflow) into a formatted string safe for storage.  The returned string can be safely saved with the
     * corresponding user account record (e.g. as a 'password' attribute).
     * <p/>
     * It is expected that the String returned from this method will be presented to the
     * {@link #passwordsMatch(Object, String) passwordsMatch(plaintext,encrypted)} method when performing a
     * password comparison check.
     * <h3>Usage</h3>
     * The input argument type can be any 'byte backed' {@code Object} - almost always either a
     * String or character array representing passwords (character arrays are often a safer way to represent passwords
     * as they can be cleared/nulled-out after use.  Any argument type supported by
     * {@link ByteSource.Util#isCompatible(Object)} is valid.
     * <p/>
     * For example:
     * <pre>
     * String rawPassword = ...
     * String encryptedValue = passwordService.encryptPassword(rawPassword);
     * </pre>
     * or, identically:
     * <pre>
     * char[] rawPasswordChars = ...
     * String encryptedValue = passwordService.encryptPassword(rawPasswordChars);
     * </pre>
     * <p/>
     * The resulting {@code encryptedValue} should be stored with the account to be retrieved later during a
     * login attempt.  For example:
     * <pre>
     * String encryptedValue = passwordService.encryptPassword(rawPassword);
     * ...
     * userAccount.setPassword(encryptedValue);
     * userAccount.save(); //create or update to your data store
     * </pre>
     *
     * @param plaintextPassword the raw password as 'byte-backed' object (String, character array, {@link ByteSource},
     *                          etc) usually acquired from your application's 'new user' or 'password reset' workflow.
     * @return the encrypted password, formatted for storage.
     * @throws IllegalArgumentException if the argument cannot be easily converted to bytes as defined by
     *                                  {@link ByteSource.Util#isCompatible(Object)}.
     * @see ByteSource.Util#isCompatible(Object)
     */
    String encryptPassword(Object plaintextPassword) throws IllegalArgumentException;

    /**
     * Returns {@code true} if the {@code submittedPlaintext} password matches the existing {@code saved} password,
     * {@code false} otherwise.
     * <h3>Usage</h3>
     * The {@code submittedPlaintext} argument type can be any 'byte backed' {@code Object} - almost always either a
     * String or character array representing passwords (character arrays are often a safer way to represent passwords
     * as they can be cleared/nulled-out after use.  Any argument type supported by
     * {@link ByteSource.Util#isCompatible(Object)} is valid.
     * <p/>
     * For example:
     * <pre>
     * String submittedPassword = ...
     * passwordService.passwordsMatch(submittedPassword, encryptedPassword);
     * </pre>
     * or similarly:
     * <pre>
     * char[] submittedPasswordCharacters = ...
     * passwordService.passwordsMatch(submittedPasswordCharacters, encryptedPassword);
     * </pre>
     *
     * @param submittedPlaintext a raw/plaintext password submitted by an end user/Subject.
     * @param encrypted          the previously encrypted password known to be associated with an account.
     *                           This value is expected to have been previously generated from the
     *                           {@link #encryptPassword(Object) encryptPassword} method (typically
     *                           when the account is created or the account's password is reset).
     * @return {@code true} if the {@code submittedPlaintext} password matches the existing {@code saved} password,
     *         {@code false} otherwise.
     * @see ByteSource.Util#isCompatible(Object)
     */
    boolean passwordsMatch(Object submittedPlaintext, String encrypted);
}