Class Sha2Crypt

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

public class Sha2Crypt extends Object
SHA2-based Unix crypt implementation.

Based on the C implementation released into the Public Domain by Ulrich Drepper <drepper@redhat.com> http://www.akkadia.org/drepper/SHA-crypt.txt

Conversion to Kotlin and from there to Java in 2012 by Christian Hammers <ch@lathspell.de> and likewise put into the Public Domain.

This class is immutable and thread-safe.

SHA-crypt hashing has a quadratic input-length step. To bound CPU and memory consumption when plaintext is supplied by an untrusted caller, plaintext is limited to 4096 bytes by default. The limit can be changed with the org.apache.commons.codec.digest.Sha2Crypt.keyMax system property; this property is intended for trusted JVM configuration only.

Since:
1.7
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final int
    Default maximum plaintext (key) length in bytes.
    (package private) static final String
    System property used to override the default maximum plaintext (key) length.
    private static final int
    Default number of rounds if not explicitly specified.
    private static final int
    Maximum number of rounds.
    private static final int
    Default maximum number of rounds accepted from a caller-supplied salt string.
    (package private) static final String
    System property used to override the default maximum number of rounds.
    private static final int
    Minimum number of rounds.
    private static final String
    Prefix for optional rounds specification.
    private static final Pattern
    The pattern to match valid salt values.
    private static final int
    The number of bytes the final hash value will have (SHA-256 variant).
    (package private) static final String
    The prefixes that can be used to identify this crypt() variant (SHA-256).
    private static final int
    The number of bytes the final hash value will have (SHA-512 variant).
    (package private) static final String
    The prefixes that can be used to identify this crypt() variant (SHA-512).
  • Constructor Summary

    Constructors
    Constructor
    Description
    Deprecated.
    Will be private in the next major version.
  • Method Summary

    Modifier and Type
    Method
    Description
    private static int
    Finds the first non-zero digit, retaining one zero for an all-zero value.
    private static int
    Gets the maximum plaintext (key) length in bytes, as configured by the org.apache.commons.codec.digest.Sha2Crypt.keyMax system property.
    private static int
    Gets the maximum number of rounds accepted from a caller-supplied salt string, as configured by the org.apache.commons.codec.digest.Sha2Crypt.roundsMax system property.
    static String
    sha256Crypt(byte[] keyBytes)
    Generates a libc crypt() compatible "$5$" hash value with random salt.
    static String
    sha256Crypt(byte[] keyBytes, String salt)
    Generates a libc6 crypt() compatible "$5$" hash value.
    static String
    sha256Crypt(byte[] keyBytes, String salt, Random random)
    Generates a libc6 crypt() compatible "$5$" hash value.
    private static String
    sha2Crypt(byte[] keyBytes, String salt, String saltPrefix, int blocksize, String algorithm, int maxKeyLen, int maxRounds)
    Generates a libc6 crypt() compatible "$5$" or "$6$" SHA2 based hash value.
    static String
    sha512Crypt(byte[] keyBytes)
    Generates a libc crypt() compatible "$6$" hash value with random salt.
    static String
    sha512Crypt(byte[] keyBytes, String salt)
    Generates a libc6 crypt() compatible "$6$" hash value.
    static String
    sha512Crypt(byte[] keyBytes, String salt, Random random)
    Generates a libc6 crypt() compatible "$6$" hash value.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • KEY_MAX_DEFAULT

      private static final int KEY_MAX_DEFAULT
      Default maximum plaintext (key) length in bytes.
      See Also:
    • KEY_MAX_PROPERTY

      static final String KEY_MAX_PROPERTY
      System property used to override the default maximum plaintext (key) length.
      See Also:
    • ROUNDS_DEFAULT

      private static final int ROUNDS_DEFAULT
      Default number of rounds if not explicitly specified.
      See Also:
    • ROUNDS_MAX

      private static final int ROUNDS_MAX
      Maximum number of rounds.
      See Also:
    • ROUNDS_MAX_DEFAULT

      private static final int ROUNDS_MAX_DEFAULT
      Default maximum number of rounds accepted from a caller-supplied salt string.
      See Also:
    • ROUNDS_MIN

      private static final int ROUNDS_MIN
      Minimum number of rounds.
      See Also:
    • ROUNDS_PREFIX

      private static final String ROUNDS_PREFIX
      Prefix for optional rounds specification.
      See Also:
    • ROUNDS_MAX_PROPERTY

      static final String ROUNDS_MAX_PROPERTY
      System property used to override the default maximum number of rounds.
      See Also:
    • SHA256_BLOCKSIZE

      private static final int SHA256_BLOCKSIZE
      The number of bytes the final hash value will have (SHA-256 variant).
      See Also:
    • SHA256_PREFIX

      static final String SHA256_PREFIX
      The prefixes that can be used to identify this crypt() variant (SHA-256).
      See Also:
    • SHA512_BLOCKSIZE

      private static final int SHA512_BLOCKSIZE
      The number of bytes the final hash value will have (SHA-512 variant).
      See Also:
    • SHA512_PREFIX

      static final String SHA512_PREFIX
      The prefixes that can be used to identify this crypt() variant (SHA-512).
      See Also:
    • SALT_PATTERN

      private static final Pattern SALT_PATTERN
      The pattern to match valid salt values.
  • Constructor Details

    • Sha2Crypt

      @Deprecated public Sha2Crypt()
      Deprecated.
      Will be private in the next major version.
      Consider private.
  • Method Details

    • firstNonZeroIndex

      private static int firstNonZeroIndex(String value)
      Finds the first non-zero digit, retaining one zero for an all-zero value.
      Parameters:
      value - a non-empty decimal string
      Returns:
      the index of the first significant digit
    • getMaxKeyLen

      private static int getMaxKeyLen()
      Gets the maximum plaintext (key) length in bytes, as configured by the org.apache.commons.codec.digest.Sha2Crypt.keyMax system property.
      Returns:
      the maximum plaintext (key) length in bytes.
    • getMaxRounds

      private static int getMaxRounds()
      Gets the maximum number of rounds accepted from a caller-supplied salt string, as configured by the org.apache.commons.codec.digest.Sha2Crypt.roundsMax system property.
      Returns:
      the maximum number of rounds accepted from a caller-supplied salt string.
    • sha256Crypt

      public static String sha256Crypt(byte[] keyBytes)
      Generates a libc crypt() compatible "$5$" hash value with random salt.

      See Crypt.crypt(String, String) for details.

      A salt is generated for you using SecureRandom.

      Parameters:
      keyBytes - Plaintext to hash. Each array element is set to 0 before returning.
      Returns:
      The Complete hash value.
      Throws:
      IllegalArgumentException - Thrown if keyBytes exceeds the configured maximum length
      IllegalArgumentException - Thrown if a NoSuchAlgorithmException is caught.
    • sha256Crypt

      public static String sha256Crypt(byte[] keyBytes, String salt)
      Generates a libc6 crypt() compatible "$5$" hash value.

      See Crypt.crypt(String, String) for details.

      Parameters:
      keyBytes - Plaintext to hash. Each array element is set to 0 before returning.
      salt - real salt value without prefix or "rounds=". The salt may be null, in which case a salt is generated for you using SecureRandom. If one does not want to use SecureRandom, you can pass your own Random in sha256Crypt(byte[], String, Random).
      Returns:
      The Complete hash value including salt.
      Throws:
      IllegalArgumentException - Thrown if keyBytes exceeds the configured maximum length
      IllegalArgumentException - Thrown if the salt does not match the allowed pattern.
      IllegalArgumentException - Thrown if a NoSuchAlgorithmException is caught.
    • sha256Crypt

      public static String sha256Crypt(byte[] keyBytes, String salt, Random random)
      Generates a libc6 crypt() compatible "$5$" hash value.

      See Crypt.crypt(String, String) for details.

      Parameters:
      keyBytes - plaintext to hash. Each array element is set to 0 before returning.
      salt - real salt value without prefix or "rounds=".
      random - The instance of Random to use for generating the salt. Consider using SecureRandom for more secure salts.
      Returns:
      The Complete hash value including salt.
      Throws:
      IllegalArgumentException - Thrown if keyBytes exceeds the configured maximum length
      IllegalArgumentException - Thrown if the salt does not match the allowed pattern.
      IllegalArgumentException - Thrown if a NoSuchAlgorithmException is caught.
      Since:
      1.12
    • sha2Crypt

      private static String sha2Crypt(byte[] keyBytes, String salt, String saltPrefix, int blocksize, String algorithm, int maxKeyLen, int maxRounds)
      Generates a libc6 crypt() compatible "$5$" or "$6$" SHA2 based hash value.

      This is a nearly line by line conversion of the original C function. The numbered comments are from the algorithm description, the short C-style ones from the original C code and the ones with "Remark" from me.

      See Crypt.crypt(String, String) for details.

      Parameters:
      keyBytes - plaintext to hash. Each array element is set to 0 before returning.
      salt - real salt value without prefix or "rounds="; may not be null.
      saltPrefix - either $5$ or $6$.
      blocksize - A value that differs between $5$ and $6$.
      algorithm - MessageDigest algorithm identifier string.
      maxKeyLen - The maximum plaintext (key) length in bytes.
      maxRounds - The maximum number of rounds accepted from a caller-supplied salt string.
      Returns:
      The Complete hash value including prefix and salt.
      Throws:
      IllegalArgumentException - Thrown if the given salt is null or does not match the allowed pattern.
      IllegalArgumentException - Thrown if a NoSuchAlgorithmException is caught.
      See Also:
    • sha512Crypt

      public static String sha512Crypt(byte[] keyBytes)
      Generates a libc crypt() compatible "$6$" hash value with random salt.

      See Crypt.crypt(String, String) for details.

      A salt is generated for you using SecureRandom.

      Parameters:
      keyBytes - Plaintext to hash. Each array element is set to 0 before returning.
      Returns:
      Complete hash value.
      Throws:
      IllegalArgumentException - Thrown if keyBytes exceeds the configured maximum length
      IllegalArgumentException - Thrown if a NoSuchAlgorithmException is caught.
    • sha512Crypt

      public static String sha512Crypt(byte[] keyBytes, String salt)
      Generates a libc6 crypt() compatible "$6$" hash value.

      See Crypt.crypt(String, String) for details.

      Parameters:
      keyBytes - Plaintext to hash. Each array element is set to 0 before returning.
      salt - Real salt value without prefix or "rounds=". The salt may be null, in which case a salt is generated for you using SecureRandom; if you want to use a Random object other than SecureRandom then we suggest you provide it using sha512Crypt(byte[], String, Random).
      Returns:
      Complete hash value including salt.
      Throws:
      IllegalArgumentException - Thrown if keyBytes exceeds the configured maximum length
      IllegalArgumentException - Thrown if the salt does not match the allowed pattern.
      IllegalArgumentException - Thrown if a NoSuchAlgorithmException is caught.
    • sha512Crypt

      public static String sha512Crypt(byte[] keyBytes, String salt, Random random)
      Generates a libc6 crypt() compatible "$6$" hash value.

      See Crypt.crypt(String, String) for details.

      Parameters:
      keyBytes - Plaintext to hash. Each array element is set to 0 before returning.
      salt - Real salt value without prefix or "rounds=". The salt may be null, in which case a salt is generated for you using SecureRandom.
      random - The instance of Random to use for generating the salt. Consider using SecureRandom for more secure salts.
      Returns:
      Complete hash value including salt.
      Throws:
      IllegalArgumentException - Thrown if the salt does not match the allowed pattern.
      IllegalArgumentException - Thrown if a NoSuchAlgorithmException is caught.
      Since:
      1.12