org.bouncycastle.crypto.generators

## Class BCrypt

- java.lang.Object
- - org.bouncycastle.crypto.generators.BCrypt

-     public final class BCrypt
      extends java.lang.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

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and 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. 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).
    `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 java.lang.Object

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

- - ### Method Detail

    - #### 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 (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.