Javadoc cleanup of new crypt classes.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/codec/trunk@1374394 13f79535-47bb-0310-9956-ffa450edef68

Author: netomi

src/main/java/org/apache/commons/codec/digest/Crypt.java

@@ -20,7 +20,7 @@
 
 /**
  * GNU libc crypt(3) compatible hash method.
- *
+ * <p>
  * See {@link #crypt(String, String)} for further details.
  *
  * <p>This class is immutable and thread-safe.</p>
@@ -32,29 +32,29 @@ public class Crypt {
 
     /**
      * Encrypts a password in a crypt(3) compatible way.
-     *
+     * <p>
      * A random salt and the default algorithm (currently SHA-512) are used. See
      * {@link #crypt(String, String)} for details.
      *
      * @param keyBytes
-     *            The plaintext password.
-     * @return The hash value.
+     *            plaintext password
+     * @return hash value
      */
     public static String crypt(byte[] keyBytes) throws Exception {
         return crypt(keyBytes, null);
     }
 
     /**
      * Encrypts a password in a crypt(3) compatible way.
-     *
+     * <p>
      * A random salt and the default algorithm (currently SHA-512) are used. See
      * {@link #crypt(String, String)} for details.
      *
      * @param keyBytes
-     *            The plaintext password.
+     *            plaintext password
      * @param salt
-     *            The salt value
-     * @return The hash value.
+     *            salt value
+     * @return hash value
      */
     public static String crypt(byte[] keyBytes, String salt) throws Exception {
         if (salt == null) {
@@ -72,13 +72,13 @@ public static String crypt(byte[] keyBytes, String salt) throws Exception {
 
     /**
      * Calculates the digest using the strongest crypt(3) algorithm.
-     *
+     * <p>
      * A random salt and the default algorithm (currently SHA-512) are used.
      *
      * @see #crypt(String, String)
      * @param key
-     *            The plaintext password.
-     * @return The hash value.
+     *            plaintext password
+     * @return hash value
      */
     public static String crypt(String key) throws Exception {
         return crypt(key, null);
@@ -96,18 +96,22 @@ public static String crypt(String key) throws Exception {
      * <li>DES, the traditional UnixCrypt algorithm is used else with only 2 chars
      * <li>Only the first 8 chars of the passwords are used in the DES algorithm!
      * </ul>
-     * The magic strings "$apr1$" and "$2a$" are not recognised by this method as its output should be identical with
-     * that of the libc implementation.
+     * The magic strings "$apr1$" and "$2a$" are not recognised by this method as its
+     * output should be identical with that of the libc implementation.
      *
      * <p>
-     * The rest of the salt string is drawn from the set [a-zA-Z0-9./] and is cut at the maximum length of if a "$" sign
-     * is encountered. It is therefore valid to enter a complete hash value as salt to e.g. verify a password with:
-     * storedPwd.equals(crypt(enteredPwd, storedPwd))
+     * The rest of the salt string is drawn from the set [a-zA-Z0-9./] and is cut at the
+     * maximum length of if a "$" sign is encountered. It is therefore valid to enter a
+     * complete hash value as salt to e.g. verify a password with:
+     *
+     * <pre>
+     *      storedPwd.equals(crypt(enteredPwd, storedPwd))
+     * </pre>
      *
      * <p>
-     * The resulting string starts with the marker string ($6$), continues with the salt value and ends with a "$" sign
-     * followed by the actual hash value. For DES the string only contains the salt and actual hash. It's toal length is
-     * dependend on the algorithm used:
+     * The resulting string starts with the marker string ($6$), continues with the salt
+     * value and ends with a "$" sign followed by the actual hash value. For DES the string
+     * only contains the salt and actual hash. It's total length is dependent on the algorithm used:
      * <ul>
      * <li>SHA-512: 106 chars
      * <li>SHA-256: 63 chars
@@ -123,15 +127,16 @@ public static String crypt(String key) throws Exception {
      *      crypt("secret", "xx") => "xxWAum7tHdIUw"
      * </pre>
      *
-     * This method comes in a variation that accepts a byte[] array to support input strings that are not encoded in
-     * UTF-8 but e.g. in ISO-8859-1 where equal characters result in different byte values.
+     * <p>
+     * This method comes in a variation that accepts a byte[] array to support input strings that
+     * are not encoded in UTF-8 but e.g. in ISO-8859-1 where equal characters result in different byte values.
      *
      * @see "The man page of the libc crypt (3) function."
      * @param key
-     *            The plaintext password as entered by the used.
+     *            plaintext password as entered by the used
      * @param salt
-     *            The salt value
-     * @return The hash value i.e. encrypted password including the salt string
+     *            salt value
+     * @return hash value, i.e. encrypted password including the salt string
      */
     public static String crypt(String key, String salt) throws Exception {
         return crypt(key.getBytes(Charsets.UTF_8), salt);

src/main/java/org/apache/commons/codec/digest/Md5Crypt.java

@@ -29,15 +29,12 @@
  * Based on the public domain ("beer-ware") C implementation from Poul-Henning Kamp which was found at:
  * </p>
  * <p>
- * http://www.freebsd.org/cgi/cvsweb.cgi/src/lib/libcrypt/crypt-md5.c?rev=1.1;content-type=text%2Fplain</br>
+ * http://www.freebsd.org/cgi/cvsweb.cgi/src/lib/libcrypt/crypt-md5.c?rev=1.1;content-type=text%2Fplain<br/>
  * Source: $FreeBSD: src/lib/libcrypt/crypt-md5.c,v 1.1 1999/01/21 13:50:09 brandon Exp $
  * </p>
- * <p>
- * Conversion to Kotlin and from there to Java in 2012.
- * </p>
- * <p>
- * The C style comments are from the original C code, the ones with "//" from the port.
- * </p>
+ * <p>Conversion to Kotlin and from there to Java in 2012.</p>
+ *
+ * <p>The C style comments are from the original C code, the ones with "//" from the port.</p>
  *
  * <p>This class is immutable and thread-safe.</p>
  *
@@ -91,24 +88,25 @@ public static String apr1Crypt(String keyBytes) throws Exception {
     }
 
     /**
-     * Generates an Apache htpasswd compatible "$apr1$" MD5 based hash value. *
-     *
-     * The algorithm is identical to the crypt(3) "$1$" one but produces different outputs due to the different salt
-     * prefix.
+     * Generates an Apache htpasswd compatible "$apr1$" MD5 based hash value.
+     * <p>
+     * The algorithm is identical to the crypt(3) "$1$" one but produces different
+     * outputs due to the different salt prefix.
      *
      * @param keyBytes
-     *            The plaintext string that should be hashed.
+     *            plaintext string that should be hashed.
      * @param salt
-     *            Salt string including the prefix and optionally garbage at the end. Will be generated randomly if
-     *            null.
+     *            salt string including the prefix and optionally garbage at the end.
+     *            Will be generated randomly if null.
+     * @return computed hash value
      */
     public static String apr1Crypt(String keyBytes, String salt) throws Exception {
         return apr1Crypt(keyBytes.getBytes(Charsets.UTF_8), salt);
     }
 
     /**
      * Generates a libc6 crypt() compatible "$1$" hash value.
-     *
+     * <p>
      * See {@link Crypt#crypt(String, String)} for details.
      */
     public static String md5Crypt(final byte[] keyBytes) throws Exception {
@@ -117,22 +115,23 @@ public static String md5Crypt(final byte[] keyBytes) throws Exception {
 
     /**
      * Generates a libc crypt() compatible "$1$" MD5 based hash value.
-     *
+     * <p>
      * See {@link Crypt#crypt(String, String)} for details.
      *
      * @param keyBytes
-     *            The plaintext string that should be hashed.
+     *            plaintext string that should be hashed.
      * @param salt
-     *            Salt string including the prefix and optionally garbage at the end. Will be generated randomly if
-     *            null.
+     *            salt string including the prefix and optionally garbage at the end.
+     *            Will be generated randomly if null.
+     * @return computed hash value
      */
     public static String md5Crypt(byte[] keyBytes, String salt) throws Exception {
         return md5Crypt(keyBytes, salt, MD5_PREFIX);
     }
 
     /**
      * Generates a libc6 crypt() "$1$" or Apache htpasswd "$apr1$" hash value.
-     *
+     * <p>
      * See {@link Crypt#crypt(String, String)} or {@link #apr1Crypt(String, String)} for details.
      */
     public static String md5Crypt(final byte[] keyBytes, final String salt, final String prefix) throws Exception {

src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java

@@ -84,7 +84,7 @@ public class Sha2Crypt {
 
     /**
      * Generates a libc crypt() compatible "$5$" hash value with random salt.
-     *
+     * <p>
      * See {@link Crypt#crypt(String, String)} for details.
      */
     public static String sha256Crypt(byte[] keyBytes) throws Exception {
@@ -93,7 +93,7 @@ public static String sha256Crypt(byte[] keyBytes) throws Exception {
 
     /**
      * Generates a libc6 crypt() compatible "$5$" hash value.
-     *
+     * <p>
      * See {@link Crypt#crypt(String, String)} for details.
      */
     public static String sha256Crypt(byte[] keyBytes, String salt) throws Exception {
@@ -105,23 +105,24 @@ public static String sha256Crypt(byte[] keyBytes, String salt) throws Exception
 
     /**
      * Generates a libc6 crypt() compatible "$5$" or "$6$" SHA2 based hash value.
-     *
-     * This is a nearly line by line conversion of the original C function. The numbered comments are from the algorithm
-     * description, the short C-style ones from the original C code and the ones with "Remark" from me.
-     *
+     * <p>
+     * This is a nearly line by line conversion of the original C function. The numbered comments
+     * are from the algorithm description, the short C-style ones from the original C code and the
+     * ones with "Remark" from me.
+     * <p>
      * See {@link Crypt#crypt(String, String)} for details.
      *
      * @param keyBytes
-     *            The plaintext that should be hashed.
+     *            plaintext that should be hashed
      * @param salt_string
-     *            The real salt value without prefix or "rounds=".
+     *            real salt value without prefix or "rounds="
      * @param saltPrefix
-     *            Either $5$ or $6$.
+     *            either $5$ or $6$
      * @param blocksize
-     *            A value that differs between $5$ and $6$.
+     *            a value that differs between $5$ and $6$
      * @param algorithm
-     *            The MessageDigest algorithm identifier string.
-     * @return The complete hash value including prefix and salt.
+     *            {@link MessageDigest} algorithm identifier string
+     * @return complete hash value including prefix and salt
      */
     private static String sha2Crypt(byte[] keyBytes, String salt, String saltPrefix, int blocksize, String algorithm)
             throws Exception {
@@ -494,7 +495,7 @@ private static String sha2Crypt(byte[] keyBytes, String salt, String saltPrefix,
 
     /**
      * Generates a libc crypt() compatible "$6$" hash value with random salt.
-     *
+     * <p>
      * See {@link Crypt#crypt(String, String)} for details.
      */
     public static String sha512Crypt(byte[] keyBytes) throws Exception {
@@ -503,7 +504,7 @@ public static String sha512Crypt(byte[] keyBytes) throws Exception {
 
     /**
      * Generates a libc6 crypt() compatible "$6$" hash value.
-     *
+     * <p>
      * See {@link Crypt#crypt(String, String)} for details.
      */
     public static String sha512Crypt(byte[] keyBytes, String salt) throws Exception {

src/main/java/org/apache/commons/codec/digest/UnixCrypt.java

@@ -23,15 +23,15 @@
 /**
  * Unix crypt(3) algorithm implementation.
  *
- * This class only implements the traditional 56 bit DES based algorithm. Please
+ * <p>This class only implements the traditional 56 bit DES based algorithm. Please
  * use DigestUtils.crypt() for a method that distinguishes between all the
- * algorithms supported in the current glibc's crypt().
+ * algorithms supported in the current glibc's crypt().</p>
  *
- * The Java implementation was taken from the JetSpeed Portal project (see
- * org.apache.jetspeed.services.security.ldap.UnixCrypt).
+ * <p>The Java implementation was taken from the JetSpeed Portal project (see
+ * org.apache.jetspeed.services.security.ldap.UnixCrypt).</p>
  *
- * This class is slightly incompatible if the given salt contains characters
- * that are not part of the allowed range [a-zA-Z0-9./].
+ * <p>This class is slightly incompatible if the given salt contains characters
+ * that are not part of the allowed range [a-zA-Z0-9./].</p>
  *
  * <p>This class is immutable and thread-safe.</p>
  *
@@ -342,28 +342,27 @@ private static void permOp(int a, int b, int n, int m, int results[]) {
 
     /**
      * Generates a crypt(3) compatible hash using the DES algorithm.
-     *
+     * <p>
      * As no salt is given, a random one will be used.
      *
-     * @param original Plaintext password
-     *
-     * @return A 13 character string starting with the salt string.
+     * @param original
+     *             plaintext password
+     * @return a 13 character string starting with the salt string
      */
     public static String crypt(byte[] original) {
         return crypt(original, null);
     }
 
     /**
      * Generates a crypt(3) compatible hash using the DES algorithm.
-     *
+     * <p>
      * Using unspecified characters as salt results incompatible hash values.
      *
-     * @param original Plaintext password
-     *
-     * @param salt A two character string drawn from [a-zA-Z0-9./] or null for a
-     * random one.
-     *
-     * @return A 13 character string starting with the salt string.
+     * @param original
+     *             plaintext password
+     * @param salt
+     *             a two character string drawn from [a-zA-Z0-9./] or null for a random one
+     * @return a 13 character string starting with the salt string
      */
     public static String crypt(byte[] original, String salt) {
         if (salt == null) {
@@ -424,12 +423,12 @@ public static String crypt(byte[] original, String salt) {
 
     /**
      * Generates a crypt(3) compatible hash using the DES algorithm.
-     *
+     * <p>
      * As no salt is given, a random one is used.
      *
-     * @param original Plaintext password
-     *
-     * @return A 13 character string starting with the salt string.
+     * @param original
+     *             plaintext password
+     * @return a 13 character string starting with the salt string
      */
     public static String crypt(String original) throws Exception {
         return crypt(original.getBytes(Charsets.UTF_8));
@@ -438,10 +437,11 @@ public static String crypt(String original) throws Exception {
     /**
      * Generates a crypt(3) compatible hash using the DES algorithm.
      *
-     * @param original Plaintext password
-     * @param salt A two character string drawn from [a-zA-Z0-9./] or null for a
-     * random one.
-     * @return A 13 character string starting with the salt string.
+     * @param original
+     *             plaintext password
+     * @param salt
+     *             a two character string drawn from [a-zA-Z0-9./] or null for a random one
+     * @return a 13 character string starting with the salt string
      */
     public static String crypt(String original, String salt) throws Exception {
         return crypt(original.getBytes(Charsets.UTF_8), salt);