    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 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 1635205 2014-10-29 17:14:16Z ggregory $
    029 * @since 1.7
    030 */
    031public 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 {@code $6$} and are up to 16 chars long.
    101     * <li>SHA-256 salts start with {@code $5$} and are up to 16 chars long
    102     * <li>MD5 salts start with {@code $1$} and are up to 8 chars long
    103     * <li>DES, the traditional UnixCrypt algorithm is used 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 {@code "$apr1$"} and {@code "$2a$"} are not recognized by this method as its output should be
    107     * identical with that of the libc implementation.
    108     * <p>
    109     * 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
    110     * {@code "$"} sign is encountered. It is therefore valid to enter a complete hash value as salt to e.g. verify a
    111     * password with:
    112     *
    113     * <pre>
    114     * storedPwd.equals(crypt(enteredPwd, storedPwd))
    115     * </pre>
    116     * <p>
    117     * The resulting string starts with the marker string ({@code $6$}), continues with the salt value and ends with a
    118     * {@code "$"} sign followed by the actual hash value. For DES the string only contains the salt and actual hash.
    119     * It's total length 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") =&gt; "$1$xxxx$aMkevjfEIpa35Bh3G4bAc."
    131     *      crypt("secret", "xx") =&gt; "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}