Improve JavaDocs.

core/src/main/java/org/acegisecurity/providers/encoding/BaseDigestPasswordEncoder.java

@@ -15,12 +15,9 @@
 
 package net.sf.acegisecurity.providers.encoding;
 
-import net.sf.acegisecurity.providers.encoding.*;
-
-
 /**
  * <p>
- * Convenience base for Digest password encoders
+ * Convenience base for digest password encoders.
  * </p>
  *
  * @author colin sampaleanu

core/src/main/java/org/acegisecurity/providers/encoding/Md5PasswordEncoder.java

@@ -25,7 +25,8 @@ import org.apache.commons.codec.digest.DigestUtils;
  * </p>
  * 
  * <p>
- * A null password is encoded to the same value as an empty ("") password.
+ * If a <code>null</code> password is presented, it will be treated as an empty
+ * <code>String</code> ("") password.
  * </p>
  *
  * @author colin sampaleanu
@@ -35,9 +36,6 @@ public class Md5PasswordEncoder extends BaseDigestPasswordEncoder
     implements PasswordEncoder {
     //~ Methods ================================================================
 
-    /* (non-Javadoc)
-     * @see net.sf.acegisecurity.providers.dao.PasswordEncoder#isPasswordValid(java.lang.String, java.lang.String, java.lang.Object)
-     */
     public boolean isPasswordValid(String encPass, String rawPass, Object salt) {
         String pass1 = "" + encPass;
         String pass2 = encodeInternal("" + rawPass);
@@ -45,9 +43,6 @@ public class Md5PasswordEncoder extends BaseDigestPasswordEncoder
         return pass1.equals(pass2);
     }
 
-    /* (non-Javadoc)
-     * @see net.sf.acegisecurity.providers.dao.PasswordEncoder#encodePassword(java.lang.String, java.lang.Object)
-     */
     public String encodePassword(String rawPass, Object salt) {
         return encodeInternal("" + rawPass);
     }

core/src/main/java/org/acegisecurity/providers/encoding/PasswordEncoder.java

@@ -20,8 +20,7 @@ import org.springframework.dao.DataAccessException;
 
 /**
  * <p>
- * Interface for performing authentication operations on a password, so that
+ * Interface for performing authentication operations on a password.
- * digest algorithms may be abstracted.
  * </p>
  *
  * @author colin sampaleanu
@@ -32,26 +31,27 @@ public interface PasswordEncoder {
 
     /**
      * <p>
-     * Validates a specified 'raw' password against an encoded password
+     * Validates a specified "raw" password against an encoded password.
-     * previously returned form {@link #encodePassword(String, Object)}. The
+     * </p>
-     * raw password will first be encoded, and then both values will be
+     * 
-     * compared.
+     * <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
+     * For a discussion of salts, please refer to {@link
-     * 'salt' the initial value before encoding. If a salt value is provided,
+     * #encodePassword(String, Object)}.
-     * 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.
      * </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
+     * @param saltSource optionally used by the implementation to 'salt' the
-     *        password before encoding. A null value is legal.
+     *        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
+     * algorithm.
-     * or SHA, but may also be a plaintext variant which does no encoding at
+     * </p>
-     * 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>
+     * 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
+     * "salt" the initial value before encoding. A salt is usually a
-     * dictionary attacks. If a salt value is provided, the same salt value
+     * user-specific value which is added to the password before the digest is
-     * must be use when calling the  {@link #isPasswordValid(String, String,
+     * computed. This means that computation of digests for common dictionary
-     * Object)} function. Note that a specific implementation may choose to
+     * words will be different than those in the backend store, because the
-     * ignore the salt value, or provide its own.
+     * 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
+     * @param salt optionally used by the implementation to "salt" the raw
-     *        password before encoding. A null value is legal.
+     *        password before encoding. A <code>null</code> value is legal.
      *
      * @return DOCUMENT ME!
      */

core/src/main/java/org/acegisecurity/providers/encoding/PlaintextPasswordEncoder.java

@@ -31,8 +31,11 @@ public class PlaintextPasswordEncoder implements PasswordEncoder {
     //~ Methods ================================================================
 
     /**
-     * Indicates whether the password comparison is case sensitive. Defaults to
+     * Indicates whether the password comparison is case sensitive.
-     * <code>false</code>, meaning an exact case match is required.
+     * 
+     * <P>
+     * Defaults to <code>false</code>, meaning an exact case match is required.
+     * </p>
      *
      * @param ignorePasswordCase set to <code>true</code> for less stringent
      *        comparison
@@ -45,9 +48,6 @@ public class PlaintextPasswordEncoder implements PasswordEncoder {
         return ignorePasswordCase;
     }
 
-    /* (non-Javadoc)
-     * @see net.sf.acegisecurity.providers.dao.PasswordEncoder#isPasswordValid(java.lang.String, java.lang.String, java.lang.Object)
-     */
     public boolean isPasswordValid(String encPass, String rawPass, Object salt) {
         String pass1 = "" + encPass;
         String pass2 = "" + rawPass;
@@ -59,9 +59,6 @@ public class PlaintextPasswordEncoder implements PasswordEncoder {
         }
     }
 
-    /* (non-Javadoc)
-     * @see net.sf.acegisecurity.providers.dao.PasswordEncoder#encodePassword(java.lang.String, java.lang.Object)
-     */
     public String encodePassword(String rawPass, Object salt) {
         return rawPass;
     }

core/src/main/java/org/acegisecurity/providers/encoding/ShaPasswordEncoder.java

@@ -25,7 +25,8 @@ import org.apache.commons.codec.digest.DigestUtils;
  * </p>
  * 
  * <p>
- * A null password is encoded to the same value as an empty ("") password.
+ * If a <code>null</code> password is presented, it will be treated as an empty
+ * <code>String</code> ("") password.
  * </p>
  *
  * @author colin sampaleanu
@@ -35,9 +36,6 @@ public class ShaPasswordEncoder extends BaseDigestPasswordEncoder
     implements PasswordEncoder {
     //~ Methods ================================================================
 
-    /* (non-Javadoc)
-     * @see net.sf.acegisecurity.providers.dao.PasswordEncoder#isPasswordValid(java.lang.String, java.lang.String, java.lang.Object)
-     */
     public boolean isPasswordValid(String encPass, String rawPass, Object salt) {
         String pass1 = "" + encPass;
         String pass2 = encodeInternal("" + rawPass);
@@ -45,9 +43,6 @@ public class ShaPasswordEncoder extends BaseDigestPasswordEncoder
         return pass1.equals(pass2);
     }
 
-    /* (non-Javadoc)
-     * @see net.sf.acegisecurity.providers.dao.PasswordEncoder#encodePassword(java.lang.String, java.lang.Object)
-     */
     public String encodePassword(String rawPass, Object salt) {
         return encodeInternal("" + rawPass);
     }