soc.server
Class BCrypt

java.lang.Object
  soc.server.BCrypt

public class BCrypt
extends java.lang.Object

BCrypt implements OpenBSD-style Blowfish password hashing using the scheme described in "A Future-Adaptable Password Scheme" by Niels Provos and David Mazieres.

This password hashing system tries to thwart off-line password cracking using a computationally-intensive hashing algorithm, based on Bruce Schneier's Blowfish cipher. The work factor of the algorithm is parameterised, so it can be increased as computers get faster.

Usage is really simple. To hash a password for the first time, call the hashpw method with a random salt, like this:

String pw_hash = BCrypt.hashpw(plain_password, BCrypt.gensalt());


To check whether a plaintext password matches one that has been hashed previously, use the checkpw method:

if (BCrypt.checkpw(candidate_password, stored_hash))
System.out.println("It matches");
else
System.out.println("It does not match");


The gensalt() method takes an optional parameter (log_rounds) that determines the computational complexity of the hashing:

String strong_salt = BCrypt.gensalt(10)
String stronger_salt = BCrypt.gensalt(12)


The amount of work increases exponentially (2**log_rounds), so each increment is twice as much work. The default log_rounds is 10, and the valid range is 4 to 31.

Version:

0.2

Author:

Damien Miller

Field Summary

private static char[]	base64_code
private static int	BCRYPT_SALT_LEN
private static int[]	bf_crypt_ciphertext
private static int	BLOWFISH_NUM_ROUNDS
private static int	GENSALT_DEFAULT_LOG2_ROUNDS
private static byte[]	index_64
private int[]	P
private static int[]	P_orig
private int[]	S
private static int[]	S_orig

Constructor Summary

BCrypt()

Method Summary

private static byte	char64(char x) Look up the 3 bits base64-encoded by the specified character, range-checking againt conversion table
static boolean	checkpw(java.lang.String plaintext, java.lang.String hashed) Check that a plaintext password matches a previously hashed one
private byte[]	crypt_raw(byte[] password, byte[] salt, int log_rounds) Perform the central password hashing step in the bcrypt scheme
private static byte[]	decode_base64(java.lang.String s, int maxolen) Decode a string encoded using bcrypt's base64 scheme to a byte array.
private void	ekskey(byte[] data, byte[] key) Perform the "enhanced key schedule" step described by Provos and Mazieres in "A Future-Adaptable Password Scheme" http://www.openbsd.org/papers/bcrypt-paper.ps
private void	encipher(int[] lr, int off) Blowfish encipher a single 64-bit block encoded as two 32-bit halves
private static java.lang.String	encode_base64(byte[] d, int len) Encode a byte array using bcrypt's slightly-modified base64 encoding scheme.
static java.lang.String	gensalt() Generate a salt for use with the BCrypt.hashpw() method, selecting a reasonable default for the number of hashing rounds to apply
static java.lang.String	gensalt(int log_rounds) Generate a salt for use with the BCrypt.hashpw() method
static java.lang.String	gensalt(int log_rounds, java.security.SecureRandom random) Generate a salt for use with the BCrypt.hashpw() method
static java.lang.String	hashpw(java.lang.String password, java.lang.String salt) Hash a password using the OpenBSD bcrypt scheme
private void	init_key() Initialise the Blowfish key schedule
private void	key(byte[] key) Key the Blowfish cipher
private static int	streamtoword(byte[] data, int[] offp) Cycically extract a word of key material

Methods inherited from class java.lang.Object

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

Field Detail

GENSALT_DEFAULT_LOG2_ROUNDS

private static final int GENSALT_DEFAULT_LOG2_ROUNDS

See Also:

Constant Field Values

BCRYPT_SALT_LEN

private static final int BCRYPT_SALT_LEN

See Also:

Constant Field Values

BLOWFISH_NUM_ROUNDS

private static final int BLOWFISH_NUM_ROUNDS

See Also:

Constant Field Values

P_orig

private static final int[] P_orig

S_orig

private static final int[] S_orig

bf_crypt_ciphertext

private static final int[] bf_crypt_ciphertext

base64_code

private static final char[] base64_code

index_64

private static final byte[] index_64

P

private int[] P

S

private int[] S

Constructor Detail

BCrypt

public BCrypt()

Method Detail

encode_base64

private static java.lang.String encode_base64(byte[] d,
                                              int len)
                                       throws java.lang.IllegalArgumentException

Encode a byte array using bcrypt's slightly-modified base64 encoding scheme. Note that this is *not* compatible with the standard MIME-base64 encoding.

Parameters:

d - the byte array to encode

len - the number of bytes to encode

Returns:

base64-encoded string

Throws:

java.lang.IllegalArgumentException - if the length is invalid

char64

private static byte char64(char x)

Look up the 3 bits base64-encoded by the specified character, range-checking againt conversion table

Parameters:

x - the base64-encoded value

Returns:

the decoded value of x

decode_base64

private static byte[] decode_base64(java.lang.String s,
                                    int maxolen)
                             throws java.lang.IllegalArgumentException

Decode a string encoded using bcrypt's base64 scheme to a byte array. Note that this is *not* compatible with the standard MIME-base64 encoding.

Parameters:

s - the string to decode

maxolen - the maximum number of bytes to decode

Returns:

an array containing the decoded bytes

Throws:

java.lang.IllegalArgumentException - if maxolen is invalid

encipher

private final void encipher(int[] lr,
                            int off)

Blowfish encipher a single 64-bit block encoded as two 32-bit halves

Parameters:

lr - an array containing the two 32-bit half blocks

off - the position in the array of the blocks

streamtoword

private static int streamtoword(byte[] data,
                                int[] offp)

Cycically extract a word of key material

Parameters:

data - the string to extract the data from

offp - a "pointer" (as a one-entry array) to the current offset into data

Returns:

the next word of material from data

init_key

private void init_key()

Initialise the Blowfish key schedule

key

private void key(byte[] key)

Key the Blowfish cipher

Parameters:

key - an array containing the key

ekskey

private void ekskey(byte[] data,
                    byte[] key)

Perform the "enhanced key schedule" step described by Provos and Mazieres in "A Future-Adaptable Password Scheme" http://www.openbsd.org/papers/bcrypt-paper.ps

Parameters:

data - salt information

key - password information

crypt_raw

private byte[] crypt_raw(byte[] password,
                         byte[] salt,
                         int log_rounds)

Perform the central password hashing step in the bcrypt scheme

Parameters:

password - the password to hash

salt - the binary salt to hash with the password

log_rounds - the binary logarithm of the number of rounds of hashing to apply

Returns:

an array containing the binary hashed password

hashpw

public static java.lang.String hashpw(java.lang.String password,
                                      java.lang.String salt)

Hash a password using the OpenBSD bcrypt scheme

Parameters:

password - the password to hash

salt - the salt to hash with (perhaps generated using BCrypt.gensalt)

Returns:

the hashed password

gensalt

public static java.lang.String gensalt(int log_rounds,
                                       java.security.SecureRandom random)

Generate a salt for use with the BCrypt.hashpw() method

Parameters:

log_rounds - the log2 of the number of rounds of hashing to apply - the work factor therefore increases as 2**log_rounds.

random - an instance of SecureRandom to use

Returns:

an encoded salt value

gensalt

public static java.lang.String gensalt(int log_rounds)

Generate a salt for use with the BCrypt.hashpw() method

Parameters:

log_rounds - the log2 of the number of rounds of hashing to apply - the work factor therefore increases as 2**log_rounds.

Returns:

an encoded salt value

gensalt

public static java.lang.String gensalt()

Generate a salt for use with the BCrypt.hashpw() method, selecting a reasonable default for the number of hashing rounds to apply

Returns:

an encoded salt value

checkpw

public static boolean checkpw(java.lang.String plaintext,
                              java.lang.String hashed)

Check that a plaintext password matches a previously hashed one

Parameters:

plaintext - the plaintext password to verify

hashed - the previously-hashed password

Returns:

true if the passwords match, false otherwise