Class BCrypt

java.lang.Object
org.bouncycastle.crypto.generators.BCrypt
public final class BCrypt extends Object
Core of password hashing scheme Bcrypt, designed by Niels Provos and David Mazières, corresponds to the C reference implementation.

This implementation does not correspondent to the 1999 published paper "A Future-Adaptable Password Scheme" of Niels Provos and David Mazières, see: https://www.usenix.org/legacy/events/usenix99/provos/provos_html/node1.html. In contrast to the paper, the order of key setup and salt setup is reversed: state <- ExpandKey(state, 0, key) state <- ExpandKey(state, 0, salt) This corresponds to the OpenBSD reference implementation of Bcrypt.

Note: There is no successful cryptanalysis (status 2015), but the amount of memory and the band width of Bcrypt may be insufficient to effectively prevent attacks with custom hardware like FPGAs, ASICs

This implementation uses some parts of Bouncy Castle's BlowfishEngine.

  • Method Summary

    Modifier and Type
    Method
    Description
    static byte[]
    generate(byte[] pwInput, byte[] salt, int cost)
    Deprecated.
    as a direct replacement use generate(byte[], byte[], int, boolean) so the terminator choice is explicit at the call site — pass true to have the spec-required 0x00 terminator appended (equivalent to feeding pwInput through passwordToByteArray(char[])), false when the supplied bytes already include it.
    static byte[]
    generate(byte[] pwInput, byte[] salt, int cost, boolean addTerminator)
    Calculates the bcrypt hash of an input, optionally appending the bcrypt password terminator (a single 0x00 byte) to pwInput before the EksBlowfishSetup password schedule.
    static byte[]
    passwordToByteArray(char[] password)
    Converts a character password to bytes incorporating the required trailing zero byte.
    static byte[]
    pbkdfGenerate(byte[] password, byte[] salt, int rounds, int outputLength)
    The OpenSSH bcrypt_pbkdf password-based key derivation function, as used to protect the openssh-key-v1 private key format (kdfname "bcrypt").

    Methods inherited from class Object

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

  • Method Details

    • passwordToByteArray

      public static byte[] passwordToByteArray(char[] password)
      Converts a character password to bytes incorporating the required trailing zero byte.
      Parameters:
      password - the password to be encoded.
      Returns:
      a byte representation of the password in UTF8 + trailing zero.

    • generate

      public static byte[] generate(byte[] pwInput, byte[] salt, int cost)
      Deprecated.
      as a direct replacement use generate(byte[], byte[], int, boolean) so the terminator choice is explicit at the call site — pass true to have the spec-required 0x00 terminator appended (equivalent to feeding pwInput through passwordToByteArray(char[])), false when the supplied bytes already include it. For general password hashing prefer OpenBSDBCrypt, which handles termination, salt formatting and the modular crypt output line; this raw primitive remains available for test-vector validation and interop with implementations that emit the 24-byte hash directly (issue #1741).
      Calculates the bcrypt hash of an input, passing the password bytes through to the EksBlowfishSetup password schedule unchanged. The bcrypt specification requires the password input to be null-terminated; this overload does not append the terminator, so the caller must supply pwInput already terminated (for example via passwordToByteArray(char[])). Without a trailing 0x00 byte, distinct passwords whose encodings differ only by repetition (e.g. "abc" and "abcabc") collide and produce identical hashes.

      This implements the raw bcrypt function as defined in the bcrypt specification, not the crypt encoded version implemented in OpenBSD, see OpenBSDBCrypt for that.

      Parameters:
      pwInput - the password bytes (up to 72 bytes) to use for this invocation.
      salt - the 128 bit salt to use for this invocation.
      cost - the bcrypt cost parameter. The cost of the bcrypt function grows as 2^cost. Legal values are 4..31 inclusive.
      Returns:
      the output of the raw bcrypt operation: a 192 bit (24 byte) hash.

    • generate

      public static byte[] generate(byte[] pwInput, byte[] salt, int cost, boolean addTerminator)
      Calculates the bcrypt hash of an input, optionally appending the bcrypt password terminator (a single 0x00 byte) to pwInput before the EksBlowfishSetup password schedule. For general password hashing use OpenBSDBCrypt rather than this primitive; this entry point is intended for callers driving the raw bcrypt function against published test vectors or interoperating with another implementation that produces the 24-byte raw hash directly.

      Setting addTerminator true is equivalent to feeding bytes produced by passwordToByteArray(char[]) and is the right choice for any caller that has not already terminated the input. Setting it false passes pwInput through unchanged — appropriate when the supplied bytes are already terminated, or when reproducing a test vector that fixes the exact input.

      When pwInput.length is exactly 72 (the bcrypt 72-byte input limit), addTerminator is ignored and the input is used as-is — there is no room for an additional byte without exceeding the limit. Two 72-byte inputs sharing a common prefix may therefore collide in the same way an unterminated shorter input does.

      Parameters:
      pwInput - the password bytes (up to 72 bytes) to use for this invocation.
      salt - the 128 bit salt to use for this invocation.
      cost - the bcrypt cost parameter. The cost of the bcrypt function grows as 2^cost. Legal values are 4..31 inclusive.
      addTerminator - whether to append the bcrypt password-terminator byte (0x00) to pwInput before the password schedule. Ignored when pwInput.length is exactly 72.
      Returns:
      the output of the raw bcrypt operation: a 192 bit (24 byte) hash.

    • pbkdfGenerate

      public static byte[] pbkdfGenerate(byte[] password, byte[] salt, int rounds, int outputLength)
      The OpenSSH bcrypt_pbkdf password-based key derivation function, as used to protect the openssh-key-v1 private key format (kdfname "bcrypt"). It layers SHA-512 over a 32-byte bcrypt_hash primitive and distributes the output non-linearly; it is not interchangeable with PBKDF2-over-bcrypt or with the OpenBSD password hash produced by generate(byte[], byte[], int, boolean) / OpenBSDBCrypt.
      Parameters:
      password - the passphrase bytes (the OpenSSH client uses the raw UTF-8 bytes, with no trailing NUL).
      salt - the salt taken from the key's kdfoptions; must be non-empty.
      rounds - the iteration count from the key's kdfoptions; must be at least 1.
      outputLength - the number of key bytes to derive (the cipher key length plus IV length); must be between 1 and 1024 inclusive.
      Returns:
      outputLength derived key bytes.