Crypt.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.codec.digest;

  18. import org.apache.commons.codec.Charsets;

  19. /**
  20.  * GNU libc crypt(3) compatible hash method.
  21.  * <p>
  22.  * See {@link #crypt(String, String)} for further details.
  23.  * <p>
  24.  * This class is immutable and thread-safe.
  25.  *
  26.  * @version $Id: Crypt.java 1744646 2016-05-20 00:11:45Z sebb $
  27.  * @since 1.7
  28.  */
  29. public class Crypt {

  30.     /**
  31.      * Encrypts a password in a crypt(3) compatible way.
  32.      * <p>
  33.      * A random salt and the default algorithm (currently SHA-512) are used. See {@link #crypt(String, String)} for
  34.      * details.
  35.      *
  36.      * @param keyBytes
  37.      *            plaintext password
  38.      * @return hash value
  39.      * @throws RuntimeException
  40.      *             when a {@link java.security.NoSuchAlgorithmException} is caught.
  41.      */
  42.     public static String crypt(final byte[] keyBytes) {
  43.         return crypt(keyBytes, null);
  44.     }

  45.     /**
  46.      * Encrypts a password in a crypt(3) compatible way.
  47.      * <p>
  48.      * If no salt is provided, a random salt and the default algorithm (currently SHA-512) will be used. See
  49.      * {@link #crypt(String, String)} for details.
  50.      *
  51.      * @param keyBytes
  52.      *            plaintext password
  53.      * @param salt
  54.      *            salt value
  55.      * @return hash value
  56.      * @throws IllegalArgumentException
  57.      *             if the salt does not match the allowed pattern
  58.      * @throws RuntimeException
  59.      *             when a {@link java.security.NoSuchAlgorithmException} is caught.
  60.      */
  61.     public static String crypt(final byte[] keyBytes, final String salt) {
  62.         if (salt == null) {
  63.             return Sha2Crypt.sha512Crypt(keyBytes);
  64.         } else if (salt.startsWith(Sha2Crypt.SHA512_PREFIX)) {
  65.             return Sha2Crypt.sha512Crypt(keyBytes, salt);
  66.         } else if (salt.startsWith(Sha2Crypt.SHA256_PREFIX)) {
  67.             return Sha2Crypt.sha256Crypt(keyBytes, salt);
  68.         } else if (salt.startsWith(Md5Crypt.MD5_PREFIX)) {
  69.             return Md5Crypt.md5Crypt(keyBytes, salt);
  70.         } else {
  71.             return UnixCrypt.crypt(keyBytes, salt);
  72.         }
  73.     }

  74.     /**
  75.      * Calculates the digest using the strongest crypt(3) algorithm.
  76.      * <p>
  77.      * A random salt and the default algorithm (currently SHA-512) are used.
  78.      *
  79.      * @see #crypt(String, String)
  80.      * @param key
  81.      *            plaintext password
  82.      * @return hash value
  83.      * @throws RuntimeException
  84.      *             when a {@link java.security.NoSuchAlgorithmException} is caught.
  85.      */
  86.     public static String crypt(final String key) {
  87.         return crypt(key, null);
  88.     }

  89.     /**
  90.      * Encrypts a password in a crypt(3) compatible way.
  91.      * <p>
  92.      * The exact algorithm depends on the format of the salt string:
  93.      * <ul>
  94.      * <li>SHA-512 salts start with {@code $6$} and are up to 16 chars long.
  95.      * <li>SHA-256 salts start with {@code $5$} and are up to 16 chars long
  96.      * <li>MD5 salts start with {@code $1$} and are up to 8 chars long
  97.      * <li>DES, the traditional UnixCrypt algorithm is used with only 2 chars
  98.      * <li>Only the first 8 chars of the passwords are used in the DES algorithm!
  99.      * </ul>
  100.      * The magic strings {@code "$apr1$"} and {@code "$2a$"} are not recognized by this method as its output should be
  101.      * identical with that of the libc implementation.
  102.      * <p>
  103.      * 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
  104.      * {@code "$"} sign is encountered. It is therefore valid to enter a complete hash value as salt to e.g. verify a
  105.      * password with:
  106.      *
  107.      * <pre>
  108.      * storedPwd.equals(crypt(enteredPwd, storedPwd))
  109.      * </pre>
  110.      * <p>
  111.      * The resulting string starts with the marker string ({@code $n$}), where n is the same as the input salt.
  112.      * The salt is then appended, followed by a {@code "$"} sign.
  113.      * This is followed by the actual hash value.
  114.      * For DES the string only contains the salt and actual hash.
  115.      * The total length is dependent on the algorithm used:
  116.      * <ul>
  117.      * <li>SHA-512: 106 chars
  118.      * <li>SHA-256: 63 chars
  119.      * <li>MD5: 34 chars
  120.      * <li>DES: 13 chars
  121.      * </ul>
  122.      * <p>
  123.      * Example:
  124.      *
  125.      * <pre>
  126.      *      crypt("secret", "$1$xxxx") =&gt; "$1$xxxx$aMkevjfEIpa35Bh3G4bAc."
  127.      *      crypt("secret", "xx") =&gt; "xxWAum7tHdIUw"
  128.      * </pre>
  129.      * <p>
  130.      * This method comes in a variation that accepts a byte[] array to support input strings that are not encoded in
  131.      * UTF-8 but e.g. in ISO-8859-1 where equal characters result in different byte values.
  132.      *
  133.      * @see "The man page of the libc crypt (3) function."
  134.      * @param key
  135.      *            plaintext password as entered by the used
  136.      * @param salt
  137.      *            salt value
  138.      * @return hash value, i.e. encrypted password including the salt string
  139.      * @throws IllegalArgumentException
  140.      *             if the salt does not match the allowed pattern
  141.      * @throws RuntimeException
  142.      *             when a {@link java.security.NoSuchAlgorithmException} is caught. *
  143.      */
  144.     public static String crypt(final String key, final String salt) {
  145.         return crypt(key.getBytes(Charsets.UTF_8), salt);
  146.     }
  147. }