001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.codec.digest;
018    
019    import org.apache.commons.codec.Charsets;
020    
021    /**
022     * GNU libc crypt(3) compatible hash method.
023     * <p>
024     * See {@link #crypt(String, String)} for further details.
025     * <p>
026     * This class is immutable and thread-safe.
027     *
028     * @version $Id: Crypt.html 889935 2013-12-11 05:05:13Z ggregory $
029     * @since 1.7
030     */
031    public class Crypt {
032    
033        /**
034         * Encrypts a password in a crypt(3) compatible way.
035         * <p>
036         * A random salt and the default algorithm (currently SHA-512) are used. See {@link #crypt(String, String)} for
037         * details.
038         *
039         * @param keyBytes
040         *            plaintext password
041         * @return hash value
042         * @throws RuntimeException
043         *             when a {@link java.security.NoSuchAlgorithmException} is caught.
044         */
045        public static String crypt(byte[] keyBytes) {
046            return crypt(keyBytes, null);
047        }
048    
049        /**
050         * Encrypts a password in a crypt(3) compatible way.
051         * <p>
052         * If no salt is provided, a random salt and the default algorithm (currently SHA-512) will be used. See
053         * {@link #crypt(String, String)} for details.
054         *
055         * @param keyBytes
056         *            plaintext password
057         * @param salt
058         *            salt value
059         * @return hash value
060         * @throws IllegalArgumentException
061         *             if the salt does not match the allowed pattern
062         * @throws RuntimeException
063         *             when a {@link java.security.NoSuchAlgorithmException} is caught.
064         */
065        public static String crypt(byte[] keyBytes, String salt) {
066            if (salt == null) {
067                return Sha2Crypt.sha512Crypt(keyBytes);
068            } else if (salt.startsWith(Sha2Crypt.SHA512_PREFIX)) {
069                return Sha2Crypt.sha512Crypt(keyBytes, salt);
070            } else if (salt.startsWith(Sha2Crypt.SHA256_PREFIX)) {
071                return Sha2Crypt.sha256Crypt(keyBytes, salt);
072            } else if (salt.startsWith(Md5Crypt.MD5_PREFIX)) {
073                return Md5Crypt.md5Crypt(keyBytes, salt);
074            } else {
075                return UnixCrypt.crypt(keyBytes, salt);
076            }
077        }
078    
079        /**
080         * Calculates the digest using the strongest crypt(3) algorithm.
081         * <p>
082         * A random salt and the default algorithm (currently SHA-512) are used.
083         *
084         * @see #crypt(String, String)
085         * @param key
086         *            plaintext password
087         * @return hash value
088         * @throws RuntimeException
089         *             when a {@link java.security.NoSuchAlgorithmException} is caught.
090         */
091        public static String crypt(String key) {
092            return crypt(key, null);
093        }
094    
095        /**
096         * Encrypts a password in a crypt(3) compatible way.
097         * <p>
098         * The exact algorithm depends on the format of the salt string:
099         * <ul>
100         * <li>SHA-512 salts start with $6$ and are up to 16 chars long.
101         * <li>SHA-256 salts start with $5$ and are up to 16 chars long
102         * <li>MD5 salts start with "$1$" and are up to 8 chars long
103         * <li>DES, the traditional UnixCrypt algorithm is used else with only 2 chars
104         * <li>Only the first 8 chars of the passwords are used in the DES algorithm!
105         * </ul>
106         * The magic strings "$apr1$" and "$2a$" are not recognised by this method as its output should be identical with
107         * that of the libc implementation.
108         * <p>
109         * 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 "$"
110         * sign is encountered. It is therefore valid to enter a complete hash value as salt to e.g. verify a password
111         * with:
112         *
113         * <pre>
114         * storedPwd.equals(crypt(enteredPwd, storedPwd))
115         * </pre>
116         * <p>
117         * The resulting string starts with the marker string ($6$), continues with the salt value and ends with a "$" sign
118         * followed by the actual hash value. For DES the string only contains the salt and actual hash. It's total length
119         * is dependent on the algorithm used:
120         * <ul>
121         * <li>SHA-512: 106 chars
122         * <li>SHA-256: 63 chars
123         * <li>MD5: 34 chars
124         * <li>DES: 13 chars
125         * </ul>
126         * <p>
127         * Example:
128         *
129         * <pre>
130         *      crypt("secret", "$1$xxxx") => "$1$xxxx$aMkevjfEIpa35Bh3G4bAc."
131         *      crypt("secret", "xx") => "xxWAum7tHdIUw"
132         * </pre>
133         * <p>
134         * This method comes in a variation that accepts a byte[] array to support input strings that are not encoded in
135         * UTF-8 but e.g. in ISO-8859-1 where equal characters result in different byte values.
136         *
137         * @see "The man page of the libc crypt (3) function."
138         * @param key
139         *            plaintext password as entered by the used
140         * @param salt
141         *            salt value
142         * @return hash value, i.e. encrypted password including the salt string
143         * @throws IllegalArgumentException
144         *             if the salt does not match the allowed pattern
145         * @throws RuntimeException
146         *             when a {@link java.security.NoSuchAlgorithmException} is caught. *
147         */
148        public static String crypt(String key, String salt) {
149            return crypt(key.getBytes(Charsets.UTF_8), salt);
150        }
151    }