|
|
@@ -20,8 +20,7 @@ import org.springframework.dao.DataAccessException;
|
|
|
|
|
|
/**
|
|
|
* <p>
|
|
|
- * Interface for performing authentication operations on a password, so that
|
|
|
- * digest algorithms may be abstracted.
|
|
|
+ * Interface for performing authentication operations on a password.
|
|
|
* </p>
|
|
|
*
|
|
|
* @author colin sampaleanu
|
|
|
@@ -32,26 +31,27 @@ public interface PasswordEncoder {
|
|
|
|
|
|
/**
|
|
|
* <p>
|
|
|
- * Validates a specified 'raw' password against an encoded password
|
|
|
- * previously returned form {@link #encodePassword(String, Object)}. The
|
|
|
- * raw password will first be encoded, and then both values will be
|
|
|
- * compared.
|
|
|
+ * Validates a specified "raw" password against an encoded password.
|
|
|
+ * </p>
|
|
|
+ *
|
|
|
+ * <P>
|
|
|
+ * The encoded password should have previously been generated by {@link
|
|
|
+ * #encodePassword(String, Object)}. This method will encode the
|
|
|
+ * <code>rawPass</code> (using the optional <code>saltSource</code>), and
|
|
|
+ * then compared it with the presented <code>encPass</code>.
|
|
|
* </p>
|
|
|
*
|
|
|
* <p>
|
|
|
- * The specified salt will potentially be used by the implementation to
|
|
|
- * 'salt' the initial value before encoding. If a salt value is provided,
|
|
|
- * it must be the same as the value used when calling {@link
|
|
|
- * #encodePassword(String, Object)} to produce the first encoded value.
|
|
|
- * Note that a specific implementation may choose to ignore the salt
|
|
|
- * value, or provide its own.
|
|
|
+ * For a discussion of salts, please refer to {@link
|
|
|
+ * #encodePassword(String, Object)}.
|
|
|
* </p>
|
|
|
*
|
|
|
* @param encPass a pre-encoded password
|
|
|
* @param rawPass a raw password to encode and compare against the
|
|
|
* pre-encoded password
|
|
|
- * @param an object optionally used by the implementation to 'salt' the raw
|
|
|
- * password before encoding. A null value is legal.
|
|
|
+ * @param saltSource optionally used by the implementation to 'salt' the
|
|
|
+ * raw password before encoding. A <code>null</code> value is
|
|
|
+ * legal.
|
|
|
*
|
|
|
* @return DOCUMENT ME!
|
|
|
*/
|
|
|
@@ -61,24 +61,38 @@ public interface PasswordEncoder {
|
|
|
/**
|
|
|
* <p>
|
|
|
* Encodes the specified raw password with an implementation specific
|
|
|
- * algorithm. This will generally be a one-way message digest such as MD5
|
|
|
- * or SHA, but may also be a plaintext variant which does no encoding at
|
|
|
- * all, but rather returns the same password it was fed. The latter is
|
|
|
- * useful to plug in when the original password must be stored as-is.
|
|
|
+ * algorithm.
|
|
|
+ * </p>
|
|
|
+ *
|
|
|
+ * <P>
|
|
|
+ * This will generally be a one-way message digest such as MD5 or SHA, but
|
|
|
+ * may also be a plaintext variant which does no encoding at all, but
|
|
|
+ * rather returns the same password it was fed. The latter is useful to
|
|
|
+ * plug in when the original password must be stored as-is.
|
|
|
* </p>
|
|
|
*
|
|
|
* <p>
|
|
|
* The specified salt will potentially be used by the implementation to
|
|
|
- * 'salt' the initial value before encoding, in order to prevent
|
|
|
- * dictionary attacks. If a salt value is provided, the same salt value
|
|
|
- * must be use when calling the {@link #isPasswordValid(String, String,
|
|
|
- * Object)} function. Note that a specific implementation may choose to
|
|
|
- * ignore the salt value, or provide its own.
|
|
|
+ * "salt" the initial value before encoding. A salt is usually a
|
|
|
+ * user-specific value which is added to the password before the digest is
|
|
|
+ * computed. This means that computation of digests for common dictionary
|
|
|
+ * words will be different than those in the backend store, because the
|
|
|
+ * dictionary word digests will not reflect the addition of the salt. If a
|
|
|
+ * per-user salt is used (rather than a system-wide salt), it also means
|
|
|
+ * users with the same password will have different digest encoded
|
|
|
+ * passwords in the backend store.
|
|
|
+ * </p>
|
|
|
+ *
|
|
|
+ * <P>
|
|
|
+ * If a salt value is provided, the same salt value must be use when
|
|
|
+ * calling the {@link #isPasswordValid(String, String, Object)} method.
|
|
|
+ * Note that a specific implementation may choose to ignore the salt value
|
|
|
+ * (via <code>null</code>), or provide its own.
|
|
|
* </p>
|
|
|
*
|
|
|
* @param rawPass the password to encode
|
|
|
- * @param an object optionally used by the implementation to 'salt' the raw
|
|
|
- * password before encoding. A null value is legal.
|
|
|
+ * @param salt optionally used by the implementation to "salt" the raw
|
|
|
+ * password before encoding. A <code>null</code> value is legal.
|
|
|
*
|
|
|
* @return DOCUMENT ME!
|
|
|
*/
|
Ben Alex