    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.java 1429868 2013-01-07 16:08:05Z 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(final 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(final byte[] keyBytes, final 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(final 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(final String key, final String salt) {
    149            return crypt(key.getBytes(Charsets.UTF_8), salt);
    150        }
    151    }