From 03efc3e51f3996bc83af298ce08d5094f93a782f Mon Sep 17 00:00:00 2001 From: Ben Alex Date: Sat, 17 Apr 2004 01:28:38 +0000 Subject: [PATCH] Improve JavaDocs. --- .../encoding/BaseDigestPasswordEncoder.java | 5 +- .../encoding/Md5PasswordEncoder.java | 9 +-- .../providers/encoding/PasswordEncoder.java | 64 +++++++++++-------- .../encoding/PlaintextPasswordEncoder.java | 13 ++-- .../encoding/ShaPasswordEncoder.java | 9 +-- 5 files changed, 49 insertions(+), 51 deletions(-) diff --git a/core/src/main/java/org/acegisecurity/providers/encoding/BaseDigestPasswordEncoder.java b/core/src/main/java/org/acegisecurity/providers/encoding/BaseDigestPasswordEncoder.java index e2c9f20984..eb54d6d191 100644 --- a/core/src/main/java/org/acegisecurity/providers/encoding/BaseDigestPasswordEncoder.java +++ b/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.*; - - /** *

- * Convenience base for Digest password encoders + * Convenience base for digest password encoders. *

* * @author colin sampaleanu diff --git a/core/src/main/java/org/acegisecurity/providers/encoding/Md5PasswordEncoder.java b/core/src/main/java/org/acegisecurity/providers/encoding/Md5PasswordEncoder.java index 2f3b949950..1b8e67ff85 100644 --- a/core/src/main/java/org/acegisecurity/providers/encoding/Md5PasswordEncoder.java +++ b/core/src/main/java/org/acegisecurity/providers/encoding/Md5PasswordEncoder.java @@ -25,7 +25,8 @@ import org.apache.commons.codec.digest.DigestUtils; *

* *

- * A null password is encoded to the same value as an empty ("") password. + * If a null password is presented, it will be treated as an empty + * String ("") password. *

* * @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); } diff --git a/core/src/main/java/org/acegisecurity/providers/encoding/PasswordEncoder.java b/core/src/main/java/org/acegisecurity/providers/encoding/PasswordEncoder.java index f577f565e9..f07617aa86 100644 --- a/core/src/main/java/org/acegisecurity/providers/encoding/PasswordEncoder.java +++ b/core/src/main/java/org/acegisecurity/providers/encoding/PasswordEncoder.java @@ -20,8 +20,7 @@ import org.springframework.dao.DataAccessException; /** *

- * Interface for performing authentication operations on a password, so that - * digest algorithms may be abstracted. + * Interface for performing authentication operations on a password. *

* * @author colin sampaleanu @@ -32,26 +31,27 @@ public interface PasswordEncoder { /** *

- * 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. + *

+ * + *

+ * The encoded password should have previously been generated by {@link + * #encodePassword(String, Object)}. This method will encode the + * rawPass (using the optional saltSource), and + * then compared it with the presented encPass. *

* *

- * 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)}. *

* * @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 null value is + * legal. * * @return DOCUMENT ME! */ @@ -61,24 +61,38 @@ public interface PasswordEncoder { /** *

* 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. + *

+ * + *

+ * 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. *

* *

* 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. + *

+ * + *

+ * 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 null), or provide its own. *

* * @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 null value is legal. * * @return DOCUMENT ME! */ diff --git a/core/src/main/java/org/acegisecurity/providers/encoding/PlaintextPasswordEncoder.java b/core/src/main/java/org/acegisecurity/providers/encoding/PlaintextPasswordEncoder.java index b5f8da9b8d..6aefc663bd 100644 --- a/core/src/main/java/org/acegisecurity/providers/encoding/PlaintextPasswordEncoder.java +++ b/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 - * false, meaning an exact case match is required. + * Indicates whether the password comparison is case sensitive. + * + *

+ * Defaults to false, meaning an exact case match is required. + *

* * @param ignorePasswordCase set to true 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; } diff --git a/core/src/main/java/org/acegisecurity/providers/encoding/ShaPasswordEncoder.java b/core/src/main/java/org/acegisecurity/providers/encoding/ShaPasswordEncoder.java index 1ad7a8737b..307371fb29 100644 --- a/core/src/main/java/org/acegisecurity/providers/encoding/ShaPasswordEncoder.java +++ b/core/src/main/java/org/acegisecurity/providers/encoding/ShaPasswordEncoder.java @@ -25,7 +25,8 @@ import org.apache.commons.codec.digest.DigestUtils; *

* *

- * A null password is encoded to the same value as an empty ("") password. + * If a null password is presented, it will be treated as an empty + * String ("") password. *

* * @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); }