Package org.apache.commons.codec.digest

# Class Crypt

java.lang.Object
org.apache.commons.codec.digest.Crypt

public class Crypt extends Object
GNU libc crypt(3) compatible hash method.

See `crypt(String, String)` for further details.

This class is immutable and thread-safe.

Since:
  1.7

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Crypt()`
  Deprecated.
  TODO Make private in 2.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `crypt(byte[] keyBytes)`
  Encrypts a password in a crypt(3) compatible way.
  `static String`
  `crypt(byte[] keyBytes, String salt)`
  Encrypts a password in a crypt(3) compatible way.
  `static String`
  `crypt(String key)`
  Calculates the digest using the strongest crypt(3) algorithm.
  `static String`
  `crypt(String key, String salt)`
  Encrypts a password in a crypt(3) compatible way.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Crypt

    @Deprecated public Crypt()
    Deprecated.
    TODO Make private in 2.0.
    TODO Make private in 2.0.

- ## Method Details

  - ### crypt

    public static String crypt(byte[] keyBytes)
    Encrypts a password in a crypt(3) compatible way.

    A random salt and the default algorithm (currently SHA-512) are used. See `crypt(String, String)` for details.

    A salt is generated for you using `SecureRandom`.

    Parameters:
      `keyBytes` - plaintext password
    Returns:
      hash value
    Throws:
      `IllegalArgumentException` - when a `NoSuchAlgorithmException` is caught.

  - ### crypt

    public static String crypt(byte[] keyBytes, String salt)
    Encrypts a password in a crypt(3) compatible way.

    If no salt is provided, a random salt and the default algorithm (currently SHA-512) will be used. See `crypt(String, String)` for details.

    Parameters:
      `keyBytes` - plaintext password
      `salt` - the salt, which is used to select the algorithm, see `crypt(String, String)` The salt may be null, in which case the method delegates to `Sha2Crypt.sha512Crypt(byte[])`
    Returns:
      hash value
    Throws:
      `IllegalArgumentException` - if the salt does not match the allowed pattern
      `IllegalArgumentException` - when a `NoSuchAlgorithmException` is caught.

  - ### crypt

    public static String crypt(String key)
    Calculates the digest using the strongest crypt(3) algorithm.

    A random salt and the default algorithm (currently SHA-512) are used.

    A salt is generated for you using `SecureRandom`.

    Parameters:
      `key` - plaintext password
    Returns:
      hash value
    Throws:
      `IllegalArgumentException` - when a `NoSuchAlgorithmException` is caught.
    See Also:
      - `crypt(String, String)`

  - ### crypt

    public static String crypt(String key, String salt)
    Encrypts a password in a crypt(3) compatible way.

    The exact algorithm depends on the format of the salt string:

    - SHA-512 salts start with `$6$` and are up to 16 chars long.
    - SHA-256 salts start with `$5$` and are up to 16 chars long
    - MD5 salts start with `$1$` and are up to 8 chars long
    - DES, the traditional UnixCrypt algorithm is used with only 2 chars
    - Only the first 8 chars of the passwords are used in the DES algorithm!

    The magic strings `"$apr1$"` and `"$2a$"` are not recognized by this method as its output should be identical with that of the libc implementation.

    The rest of the salt string is drawn from the set `[a-zA-Z0-9./]` and is cut at the maximum length or if a `"$"` sign is encountered. It is therefore valid to enter a complete hash value as salt to e.g. verify a password with:

         storedPwd.equals(crypt(enteredPwd, storedPwd))

    The resulting string starts with the marker string (`$n$`), where n is the same as the input salt. The salt is then appended, followed by a `"$"` sign. This is followed by the actual hash value. For DES the string only contains the salt and actual hash. The total length is dependent on the algorithm used:

    - SHA-512: 106 chars
    - SHA-256: 63 chars
    - MD5: 34 chars
    - DES: 13 chars

    Example:

              crypt("secret", "$1$xxxx") => "$1$xxxx$aMkevjfEIpa35Bh3G4bAc."
              crypt("secret", "xx") => "xxWAum7tHdIUw"

    This method comes in a variation that accepts a byte[] array to support input strings that are not encoded in UTF-8 but e.g. in ISO-8859-1 where equal characters result in different byte values.

    Parameters:
      `key` - plaintext password as entered by the used
      `salt` - real salt value without prefix or "rounds=". The salt may be null, in which case a salt is generated for you using `SecureRandom`
    Returns:
      hash value, i.e. encrypted password including the salt string
    Throws:
      `IllegalArgumentException` - if the salt does not match the allowed pattern
      `IllegalArgumentException` - when a `NoSuchAlgorithmException` is caught. *
    See Also:
      - "The man page of the libc crypt (3) function."