[CODEC-133] Add classes for MD5/SHA1/SHA-512-based Unix crypt(3) hash variants.

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

Author: garydgregory

src/changes/changes.xml

@@ -51,6 +51,9 @@ The <action> type attribute can be add,update,fix,remove.
     </release>
     -->
     <release version="1.7" date="TBD" description="Feature and fix release.">
+      <action dev="ggregory" type="fix" issue="CODEC-133" due-to="lathspell">
+        Add classes for MD5/SHA1/SHA-512-based Unix crypt(3) hash variants.
+      </action>
       <action dev="ggregory" type="fix" issue="CODEC-96" due-to="sebb">
         Base64 encode() method is no longer thread-safe, breaking clients using it as a shared BinaryEncoder.
         Note: the fix breaks binary compatibility, however the changes are to a class (BaseNCodec) which is

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

@@ -0,0 +1,74 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.codec.digest;
+
+import java.util.Random;
+
+/**
+ * Base64 like method to convert binary bytes into ASCII chars.
+ * 
+ * TODO: Can Base64 be reused?
+ * 
+ * @version $Id $
+ * @since 1.7
+ */
+class B64 {
+
+    /**
+     * Table with characters for Base64 transformation.
+     */
+    static final String B64T = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+    /**
+     * Base64 like conversion of bytes to ASCII chars.
+     * 
+     * @param b2
+     *            A byte from the result.
+     * @param b1
+     *            A byte from the result.
+     * @param b0
+     *            A byte from the result.
+     * @param outLen
+     *            The number of expected output chars.
+     * @param buffer
+     *            Where the output chars is appended to.
+     */
+    static void b64from24bit(byte b2, byte b1, byte b0, int outLen, StringBuilder buffer) {
+        // The bit masking is necessary because the JVM byte type is signed!
+        int w = ((b2 << 16) & 0x00ffffff) | ((b1 << 8) & 0x00ffff) | (b0 & 0xff);
+        // It's effectively a "for" loop but kept to resemble the original C code.
+        int n = outLen;
+        while (n-- > 0) {
+            buffer.append(B64T.charAt(w & 0x3f));
+            w >>= 6;
+        }
+    }
+
+    /**
+     * Generates a string of random chars from the B64T set.
+     * 
+     * @param num
+     *            Number of chars to generate.
+     */
+    static String getRandomSalt(int num) {
+        StringBuilder saltString = new StringBuilder();
+        for (int i = 1; i <= num; i++) {
+            saltString.append(B64T.charAt(new Random().nextInt(B64T.length())));
+        }
+        return saltString.toString();
+    }
+}

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

@@ -0,0 +1,137 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.codec.digest;
+
+import org.apache.commons.codec.Charsets;
+
+/**
+ * GNU libc crypt(3) compatible hash method.
+ * 
+ * See {@link #crypt(String, String)} for further details.
+ * 
+ * @version $Id $
+ * @since 1.7
+ */
+public class Crypt {
+
+    /**
+     * Encrypts a password in a crypt(3) compatible way.
+     * 
+     * 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.
+     */
+    public static String crypt(byte[] keyBytes) throws Exception {
+        return crypt(keyBytes, null);
+    }
+
+    /**
+     * Encrypts a password in a crypt(3) compatible way.
+     * 
+     * A random salt and the default algorithm (currently SHA-512) are used. See
+     * {@link #crypt(String, String)} for details.
+     * 
+     * @param keyBytes
+     *            The plaintext password.
+     * @param salt
+     *            The salt value
+     * @return The hash value.
+     */
+    public static String crypt(byte[] keyBytes, String salt) throws Exception {
+        if (salt == null) {
+            return Sha2Crypt.sha512Crypt(keyBytes);
+        } else if (salt.startsWith(Sha2Crypt.SHA512_PREFIX)) {
+            return Sha2Crypt.sha512Crypt(keyBytes, salt);
+        } else if (salt.startsWith(Sha2Crypt.SHA256_PREFIX)) {
+            return Sha2Crypt.sha256Crypt(keyBytes, salt);
+        } else if (salt.startsWith(Md5Crypt.MD5_PREFIX)) {
+            return Md5Crypt.md5Crypt(keyBytes, salt);
+        } else {
+            return UnixCrypt.crypt(keyBytes, salt);
+        }
+    }
+
+    /**
+     * Calculates the digest using the strongest crypt(3) algorithm.
+     * 
+     * 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.
+     */
+    public static String crypt(String key) throws Exception {
+        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>
+     * <li>SHA-512 salts start with $6$ and are up to 16 chars long.
+     * <li>SHA-256 salts start with $5$ and are up to 16 chars long
+     * <li>MD5 salts start with "$1$" and are up to 8 chars long
+     * <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.
+     * 
+     * <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))
+     * 
+     * <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:
+     * <ul>
+     * <li>SHA-512: 106 chars
+     * <li>SHA-256: 63 chars
+     * <li>MD5: 34 chars
+     * <li>DES: 13 chars
+     * </ul>
+     * 
+     * <p>
+     * Example:
+     * 
+     * <pre>
+     *      crypt("secret", "$1$xxxx") => "$1$xxxx$aMkevjfEIpa35Bh3G4bAc."
+     *      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.
+     * 
+     * @see "The man page of the libc crypt (3) function."
+     * @param key
+     *            The plaintext password as entered by the used.
+     * @param salt
+     *            The salt value
+     * @return The 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);
+    }
+}