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 1744646 2016-05-20 00:11:45Z sebb $
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 $n$}), where n is the same as the input salt.
118     * The salt is then appended, followed by a {@code "$"} sign.
119     * This is followed by the actual hash value.
120     * For DES the string only contains the salt and actual hash.
121     * The total length is dependent on the algorithm used:
122     * <ul>
123     * <li>SHA-512: 106 chars
124     * <li>SHA-256: 63 chars
125     * <li>MD5: 34 chars
126     * <li>DES: 13 chars
127     * </ul>
128     * <p>
129     * Example:
130     *
131     * <pre>
132     *      crypt("secret", "$1$xxxx") =&gt; "$1$xxxx$aMkevjfEIpa35Bh3G4bAc."
133     *      crypt("secret", "xx") =&gt; "xxWAum7tHdIUw"
134     * </pre>
135     * <p>
136     * This method comes in a variation that accepts a byte[] array to support input strings that are not encoded in
137     * UTF-8 but e.g. in ISO-8859-1 where equal characters result in different byte values.
138     *
139     * @see "The man page of the libc crypt (3) function."
140     * @param key
141     *            plaintext password as entered by the used
142     * @param salt
143     *            salt value
144     * @return hash value, i.e. encrypted password including the salt string
145     * @throws IllegalArgumentException
146     *             if the salt does not match the allowed pattern
147     * @throws RuntimeException
148     *             when a {@link java.security.NoSuchAlgorithmException} is caught. *
149     */
150    public static String crypt(final String key, final String salt) {
151        return crypt(key.getBytes(Charsets.UTF_8), salt);
152    }
153}