    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 */
    017package org.apache.commons.codec.digest;
    018
    019import java.nio.charset.StandardCharsets;
    020import java.security.SecureRandom;
    021import java.util.concurrent.ThreadLocalRandom;
    022
    023/**
    024 * GNU libc crypt(3) compatible hash method.
    025 * <p>
    026 * See {@link #crypt(String, String)} for further details.
    027 * <p>
    028 * This class is immutable and thread-safe.
    029 *
    030 * @since 1.7
    031 */
    032public class Crypt {
    033
    034    /**
    035     * Encrypts a password in a crypt(3) compatible way.
    036     * <p>
    037     * A random salt and the default algorithm (currently SHA-512) are used. See {@link #crypt(String, String)} for
    038     * details.
    039     * </p>
    040     * <p>
    041     * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
    042     * {@link SecureRandom} to generate your own salts and calling {@link #crypt(byte[], String)}.
    043     * </p>
    044     *
    045     * @param keyBytes
    046     *            plaintext password
    047     * @return hash value
    048     * @throws IllegalArgumentException
    049     *             when a {@link java.security.NoSuchAlgorithmException} is caught.
    050     */
    051    public static String crypt(final byte[] keyBytes) {
    052        return crypt(keyBytes, null);
    053    }
    054
    055    /**
    056     * Encrypts a password in a crypt(3) compatible way.
    057     * <p>
    058     * If no salt is provided, a random salt and the default algorithm (currently SHA-512) will be used. See
    059     * {@link #crypt(String, String)} for details.
    060     *
    061     * @param keyBytes
    062     *            plaintext password
    063     * @param salt
    064     *            real salt value without prefix or "rounds=". The salt may be null,
    065     *            in which case a salt is generated for you using {@link ThreadLocalRandom};
    066     *            for more secure salts consider using {@link SecureRandom} to
    067     *            generate your own salts.
    068     * @return hash value
    069     * @throws IllegalArgumentException
    070     *             if the salt does not match the allowed pattern
    071     * @throws IllegalArgumentException
    072     *             when a {@link java.security.NoSuchAlgorithmException} is caught.
    073     */
    074    public static String crypt(final byte[] keyBytes, final String salt) {
    075        if (salt == null) {
    076            return Sha2Crypt.sha512Crypt(keyBytes);
    077        } else if (salt.startsWith(Sha2Crypt.SHA512_PREFIX)) {
    078            return Sha2Crypt.sha512Crypt(keyBytes, salt);
    079        } else if (salt.startsWith(Sha2Crypt.SHA256_PREFIX)) {
    080            return Sha2Crypt.sha256Crypt(keyBytes, salt);
    081        } else if (salt.startsWith(Md5Crypt.MD5_PREFIX)) {
    082            return Md5Crypt.md5Crypt(keyBytes, salt);
    083        } else {
    084            return UnixCrypt.crypt(keyBytes, salt);
    085        }
    086    }
    087
    088    /**
    089     * Calculates the digest using the strongest crypt(3) algorithm.
    090     * <p>
    091     * A random salt and the default algorithm (currently SHA-512) are used.
    092     * </p>
    093     * <p>
    094     * A salt is generated for you using {@link ThreadLocalRandom}; for more secure salts consider using
    095     * {@link SecureRandom} to generate your own salts and calling {@link #crypt(String, String)}.
    096     * </p>
    097     *
    098     * @see #crypt(String, String)
    099     * @param key
    100     *            plaintext password
    101     * @return hash value
    102     * @throws IllegalArgumentException
    103     *             when a {@link java.security.NoSuchAlgorithmException} is caught.
    104     */
    105    public static String crypt(final String key) {
    106        return crypt(key, null);
    107    }
    108
    109    /**
    110     * Encrypts a password in a crypt(3) compatible way.
    111     * <p>
    112     * The exact algorithm depends on the format of the salt string:
    113     * <ul>
    114     * <li>SHA-512 salts start with {@code $6$} and are up to 16 chars long.
    115     * <li>SHA-256 salts start with {@code $5$} and are up to 16 chars long
    116     * <li>MD5 salts start with {@code $1$} and are up to 8 chars long
    117     * <li>DES, the traditional UnixCrypt algorithm is used with only 2 chars
    118     * <li>Only the first 8 chars of the passwords are used in the DES algorithm!
    119     * </ul>
    120     * The magic strings {@code "$apr1$"} and {@code "$2a$"} are not recognized by this method as its output should be
    121     * identical with that of the libc implementation.
    122     * <p>
    123     * The rest of the salt string is drawn from the set {@code [a-zA-Z0-9./]} and is cut at the maximum length of if a
    124     * {@code "$"} sign is encountered. It is therefore valid to enter a complete hash value as salt to e.g. verify a
    125     * password with:
    126     *
    127     * <pre>
    128     * storedPwd.equals(crypt(enteredPwd, storedPwd))
    129     * </pre>
    130     * <p>
    131     * The resulting string starts with the marker string ({@code $n$}), where n is the same as the input salt.
    132     * The salt is then appended, followed by a {@code "$"} sign.
    133     * This is followed by the actual hash value.
    134     * For DES the string only contains the salt and actual hash.
    135     * The total length is dependent on the algorithm used:
    136     * <ul>
    137     * <li>SHA-512: 106 chars
    138     * <li>SHA-256: 63 chars
    139     * <li>MD5: 34 chars
    140     * <li>DES: 13 chars
    141     * </ul>
    142     * <p>
    143     * Example:
    144     *
    145     * <pre>
    146     *      crypt("secret", "$1$xxxx") =&gt; "$1$xxxx$aMkevjfEIpa35Bh3G4bAc."
    147     *      crypt("secret", "xx") =&gt; "xxWAum7tHdIUw"
    148     * </pre>
    149     * <p>
    150     * This method comes in a variation that accepts a byte[] array to support input strings that are not encoded in
    151     * UTF-8 but e.g. in ISO-8859-1 where equal characters result in different byte values.
    152     *
    153     * @see "The man page of the libc crypt (3) function."
    154     * @param key
    155     *            plaintext password as entered by the used
    156     * @param salt
    157     *            real salt value without prefix or "rounds=". The salt may be null, in which case a
    158     *            salt is generated for you using {@link ThreadLocalRandom}; for more secure salts
    159     *            consider using {@link SecureRandom} to generate your own salts.
    160     * @return hash value, i.e. encrypted password including the salt string
    161     * @throws IllegalArgumentException
    162     *             if the salt does not match the allowed pattern
    163     * @throws IllegalArgumentException
    164     *             when a {@link java.security.NoSuchAlgorithmException} is caught. *
    165     */
    166    public static String crypt(final String key, final String salt) {
    167        return crypt(key.getBytes(StandardCharsets.UTF_8), salt);
    168    }
    169}