Cleanup of throws clauses in new crypt classes. Additional javadoc fixes.

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

Author: netomi

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

@@ -16,14 +16,16 @@
  */
 package org.apache.commons.codec.digest;
 
+import java.security.NoSuchAlgorithmException;
+
 import org.apache.commons.codec.Charsets;
 
 /**
  * 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>
+ * <p>
+ * This class is immutable and thread-safe.
  *
  * @version $Id$
  * @since 1.7
@@ -39,24 +41,27 @@ public class Crypt {
      * @param keyBytes
      *            plaintext password
      * @return hash value
+     * @throws NoSuchAlgorithmException if no algorithm implementation is available
      */
-    public static String crypt(byte[] keyBytes) throws Exception {
+    public static String crypt(byte[] keyBytes) throws NoSuchAlgorithmException {
         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.
+     * If no salt is provided, a random salt and the default algorithm (currently SHA-512) will be used.
+     * See {@link #crypt(String, String)} for details.
      *
      * @param keyBytes
      *            plaintext password
      * @param salt
      *            salt value
      * @return hash value
+     * @throws IllegalArgumentException if the salt does not match the allowed pattern
+     * @throws NoSuchAlgorithmException if no algorithm implementation is available
      */
-    public static String crypt(byte[] keyBytes, String salt) throws Exception {
+    public static String crypt(byte[] keyBytes, String salt) throws NoSuchAlgorithmException {
         if (salt == null) {
             return Sha2Crypt.sha512Crypt(keyBytes);
         } else if (salt.startsWith(Sha2Crypt.SHA512_PREFIX)) {
@@ -79,14 +84,14 @@ public static String crypt(byte[] keyBytes, String salt) throws Exception {
      * @param key
      *            plaintext password
      * @return hash value
+     * @throws NoSuchAlgorithmException if no algorithm implementation is available
      */
-    public static String crypt(String key) throws Exception {
+    public static String crypt(String key) throws NoSuchAlgorithmException {
         return crypt(key, null);
     }
 
     /**
      * Encrypts a password in a crypt(3) compatible way.
-     *
      * <p>
      * The exact algorithm depends on the format of the salt string:
      * <ul>
@@ -98,16 +103,13 @@ public static String crypt(String key) throws Exception {
      * </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.
-     *
      * <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:
-     *
      * <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
@@ -118,15 +120,12 @@ public static String crypt(String key) throws Exception {
      * <li>MD5: 34 chars
      * <li>DES: 13 chars
      * </ul>
-     *
      * <p>
      * Example:
-     *
      * <pre>
      *      crypt("secret", "$1$xxxx") => "$1$xxxx$aMkevjfEIpa35Bh3G4bAc."
      *      crypt("secret", "xx") => "xxWAum7tHdIUw"
      * </pre>
-     *
      * <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.
@@ -137,8 +136,10 @@ public static String crypt(String key) throws Exception {
      * @param salt
      *            salt value
      * @return hash value, i.e. encrypted password including the salt string
+     * @throws IllegalArgumentException if the salt does not match the allowed pattern
+     * @throws NoSuchAlgorithmException if no algorithm implementation is available
      */
-    public static String crypt(String key, String salt) throws Exception {
+    public static String crypt(String key, String salt) throws NoSuchAlgorithmException {
         return crypt(key.getBytes(Charsets.UTF_8), salt);
     }
 }

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

@@ -17,6 +17,7 @@
 package org.apache.commons.codec.digest;
 
 import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
 import java.util.Arrays;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -27,63 +28,67 @@
  * The libc crypt() "$1$" and Apache "$apr1$" MD5-based hash algorithm.
  * <p>
  * Based on the public domain ("beer-ware") C implementation from Poul-Henning Kamp which was found at:
- * </p>
+ * <a href="http://www.freebsd.org/cgi/cvsweb.cgi/src/lib/libcrypt/crypt-md5.c?rev=1.1;content-type=text%2Fplain">
+ * crypt-md5.c @ freebsd.org</a><br/>
  * <p>
- * 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>This class is immutable and thread-safe.</p>
+ * Source:
+ * <pre>$FreeBSD: src/lib/libcrypt/crypt-md5.c,v 1.1 1999/01/21 13:50:09 brandon Exp $</pre>
+ * <p>
+ * Conversion to Kotlin and from there to Java in 2012.
+ * <p>
+ * The C style comments are from the original C code, the ones with "//" from the port.
+ * <p>
+ * This class is immutable and thread-safe.
  *
  * @version $Id$
  * @since 1.7
  */
 public class Md5Crypt {
 
-    /**
-     * The Identifier of the Apache variant.
-     */
+    /** The Identifier of the Apache variant. */
     static final String APR1_PREFIX = "$apr1$";
 
-    /**
-     * The number of bytes of the final hash.
-     */
+    /** The number of bytes of the final hash. */
     private static final int BLOCKSIZE = 16;
 
-    /**
-     * The MessageDigest MD5_ALGORITHM.
-     */
+    /** The MessageDigest MD5_ALGORITHM. */
     private static final String MD5_ALGORITHM = "MD5";
 
-    /**
-     * The Identifier of this crypt() variant.
-     */
+    /** The Identifier of this crypt() variant. */
     static final String MD5_PREFIX = "$1$";
 
-    /**
-     * The number of rounds of the big loop.
-     */
+    /** The number of rounds of the big loop. */
     private static final int ROUNDS = 1000;
 
-    /** See {@link #apr1Crypt(String, String)} for details. */
-    public static String apr1Crypt(byte[] keyBytes) throws Exception {
+    /**
+     * See {@link #apr1Crypt(String, String)} for details.
+     *
+     * @throws NoSuchAlgorithmException if no "MD5" algorithm implementation is available
+     */
+    public static String apr1Crypt(byte[] keyBytes) throws NoSuchAlgorithmException {
         return apr1Crypt(keyBytes, APR1_PREFIX + B64.getRandomSalt(8));
     }
 
-    /** See {@link #apr1Crypt(String, String)} for details. */
-    public static String apr1Crypt(byte[] keyBytes, String salt) throws Exception {
+    /**
+     * See {@link #apr1Crypt(String, String)} for details.
+     *
+     * @throws IllegalArgumentException if the salt does not match the allowed pattern
+     * @throws NoSuchAlgorithmException if no "MD5" algorithm implementation is available
+     */
+    public static String apr1Crypt(byte[] keyBytes, String salt) throws NoSuchAlgorithmException {
         // to make the md5Crypt regex happy
         if (salt != null && !salt.startsWith(APR1_PREFIX)) {
             salt = APR1_PREFIX + salt;
         }
         return Md5Crypt.md5Crypt(keyBytes, salt, APR1_PREFIX);
     }
 
-    /** See {@link #apr1Crypt(String, String)} for details. */
-    public static String apr1Crypt(String keyBytes) throws Exception {
+    /**
+     * See {@link #apr1Crypt(String, String)} for details.
+     *
+     * @throws NoSuchAlgorithmException if no "MD5" algorithm implementation is available
+     */
+    public static String apr1Crypt(String keyBytes) throws NoSuchAlgorithmException {
         return apr1Crypt(keyBytes.getBytes(Charsets.UTF_8));
     }
 
@@ -99,17 +104,21 @@ public static String apr1Crypt(String keyBytes) throws Exception {
      *            salt string including the prefix and optionally garbage at the end.
      *            Will be generated randomly if null.
      * @return computed hash value
+     * @throws IllegalArgumentException if the salt does not match the allowed pattern
+     * @throws NoSuchAlgorithmException if no "MD5" algorithm implementation is available
      */
-    public static String apr1Crypt(String keyBytes, String salt) throws Exception {
+    public static String apr1Crypt(String keyBytes, String salt) throws NoSuchAlgorithmException {
         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.
+     *
+     * @throws NoSuchAlgorithmException if no "MD5" algorithm implementation is available
      */
-    public static String md5Crypt(final byte[] keyBytes) throws Exception {
+    public static String md5Crypt(final byte[] keyBytes) throws NoSuchAlgorithmException {
         return md5Crypt(keyBytes, MD5_PREFIX + B64.getRandomSalt(8));
     }
 
@@ -124,26 +133,32 @@ public static String md5Crypt(final byte[] keyBytes) throws Exception {
      *            salt string including the prefix and optionally garbage at the end.
      *            Will be generated randomly if null.
      * @return computed hash value
+     * @throws IllegalArgumentException if the salt does not match the allowed pattern
+     * @throws NoSuchAlgorithmException if no "MD5" algorithm implementation is available
      */
-    public static String md5Crypt(byte[] keyBytes, String salt) throws Exception {
+    public static String md5Crypt(byte[] keyBytes, String salt) throws NoSuchAlgorithmException {
         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.
+     *
+     * @throws IllegalArgumentException if the salt does not match the allowed pattern
+     * @throws NoSuchAlgorithmException if no "MD5" algorithm implementation is available
      */
-    public static String md5Crypt(final byte[] keyBytes, final String salt, final String prefix) throws Exception {
+    public static String md5Crypt(final byte[] keyBytes, final String salt, final String prefix)
+            throws NoSuchAlgorithmException {
         int keyLen = keyBytes.length;
 
         // Extract the real salt from the given string which can be a complete hash string.
         String saltString;
         if (salt == null) {
             saltString = B64.getRandomSalt(8);
         } else {
-            Pattern p = Pattern.compile("^" + prefix.replace("$", "\\$") + "([\\.\\/a-zA-Z0-9]{1,8}).*");
-            Matcher m = p.matcher(salt);
+            final Pattern p = Pattern.compile("^" + prefix.replace("$", "\\$") + "([\\.\\/a-zA-Z0-9]{1,8}).*");
+            final Matcher m = p.matcher(salt);
             if (m == null || !m.find()) {
                 throw new IllegalArgumentException("Invalid salt value: " + salt);
             }