View Javadoc

    1   /* Copyright 2004 Acegi Technology Pty Limited
    2    *
    3    * Licensed under the Apache License, Version 2.0 (the "License");
    4    * you may not use this file except in compliance with the License.
    5    * You may obtain a copy of the License at
    6    *
    7    *     http://www.apache.org/licenses/LICENSE-2.0
    8    *
    9    * Unless required by applicable law or agreed to in writing, software
    10   * distributed under the License is distributed on an "AS IS" BASIS,
    11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12   * See the License for the specific language governing permissions and
    13   * limitations under the License.
    14   */
    15
    16  package org.acegisecurity.providers.encoding;
    17
    18  import org.springframework.dao.DataAccessException;
    19
    20
    21  /***
    22   * <p>
    23   * Interface for performing authentication operations on a password.
    24   * </p>
    25   *
    26   * @author colin sampaleanu
    27   * @version $Id: PasswordEncoder.java,v 1.5 2005/11/17 00:55:49 benalex Exp $
    28   */
    29  public interface PasswordEncoder {
    30      //~ Methods ================================================================
    31
    32      /***
    33       * <p>
    34       * Validates a specified "raw" password against an encoded password.
    35       * </p>
    36       *
    37       * <P>
    38       * The encoded password should have previously been generated by {@link
    39       * #encodePassword(String, Object)}. This method will encode the
    40       * <code>rawPass</code> (using the optional <code>salt</code>),  and then
    41       * compared it with the presented <code>encPass</code>.
    42       * </p>
    43       *
    44       * <p>
    45       * For a discussion of salts, please refer to {@link
    46       * #encodePassword(String, Object)}.
    47       * </p>
    48       *
    49       * @param encPass a pre-encoded password
    50       * @param rawPass a raw password to encode and compare against the
    51       *        pre-encoded password
    52       * @param salt optionally used by the implementation to "salt" the raw
    53       *        password before encoding. A <code>null</code> value is legal.
    54       *
    55       * @return DOCUMENT ME!
    56       */
    57      public boolean isPasswordValid(String encPass, String rawPass, Object salt)
    58          throws DataAccessException;
    59
    60      /***
    61       * <p>
    62       * Encodes the specified raw password with an implementation specific
    63       * algorithm.
    64       * </p>
    65       *
    66       * <P>
    67       * This will generally be a one-way message digest such as MD5 or SHA, but
    68       * may also be a plaintext variant which does no encoding at all, but
    69       * rather returns the same password it was fed. The latter is useful to
    70       * plug in when the original password must be stored as-is.
    71       * </p>
    72       *
    73       * <p>
    74       * The specified salt will potentially be used by the implementation to
    75       * "salt" the initial value before encoding. A salt is usually a
    76       * user-specific value which is added to the password before the digest is
    77       * computed. This means that computation of digests for common dictionary
    78       * words will be different than those in the backend store, because the
    79       * dictionary word digests will not reflect the addition of the salt. If a
    80       * per-user salt is used (rather than a system-wide salt), it also means
    81       * users with the same password will have different digest encoded
    82       * passwords in the backend store.
    83       * </p>
    84       *
    85       * <P>
    86       * If a salt value is provided, the same salt value must be use when
    87       * calling the  {@link #isPasswordValid(String, String, Object)} method.
    88       * Note that a specific implementation may choose to ignore the salt value
    89       * (via <code>null</code>), or provide its own.
    90       * </p>
    91       *
    92       * @param rawPass the password to encode
    93       * @param salt optionally used by the implementation to "salt" the raw
    94       *        password before encoding. A <code>null</code> value is legal.
    95       *
    96       * @return DOCUMENT ME!
    97       */
    98      public String encodePassword(String rawPass, Object salt)
    99          throws DataAccessException;
    100 }