class BCrypt::Engine

A Ruby wrapper for the bcrypt() C extension calls and the Java calls.

Constants

DEFAULT_COST

The default computational expense parameter.

MAX_COST

The maximum cost supported by the algorithm.

MAX_SALT_LENGTH

Maximum possible size of bcrypt() salts.

MIN_COST

The minimum cost supported by the algorithm.

Public Class Methods

__bc_crypt(p1, p2) click to toggle source

Given a secret and a salt, generates a salted hash (which you can then store safely).

static VALUE bc_crypt(VALUE self, VALUE key, VALUE setting) {
    char * value;
    void * data;
    int size;
    VALUE out;

    data = NULL;
    size = 0xDEADBEEF;

    if(NIL_P(key) || NIL_P(setting)) return Qnil;

    value = crypt_ra(
            NIL_P(key) ? NULL : StringValuePtr(key),
            NIL_P(setting) ? NULL : StringValuePtr(setting),
            &data,
            &size);

    if(!value || !data) return Qnil;

    out = rb_str_new2(value);

    xfree(data);

    return out;
}
__bc_salt(p1, p2, p3) click to toggle source

Given a logarithmic cost parameter, generates a salt for use with bc_crypt.

static VALUE bc_salt(VALUE self, VALUE prefix, VALUE count, VALUE input) {
    char * salt;
    VALUE str_salt;

    salt = crypt_gensalt_ra(
            StringValuePtr(prefix),
            NUM2ULONG(count),
            NIL_P(input) ? NULL : StringValuePtr(input),
            NIL_P(input) ? 0 : RSTRING_LEN(input));

    if(!salt) return Qnil;

    str_salt = rb_str_new2(salt);
    free(salt);

    return str_salt;
}
autodetect_cost(salt) click to toggle source

Autodetects the cost from the salt string.

    # File lib/bcrypt/engine.rb
113 def self.autodetect_cost(salt)
114   salt[4..5].to_i
115 end
calibrate(upper_time_limit_in_ms) click to toggle source

Returns the cost factor which will result in computation times less than upper_time_limit_in_ms.

Example:

BCrypt::Engine.calibrate(200)  #=> 10
BCrypt::Engine.calibrate(1000) #=> 12

# should take less than 200ms
BCrypt::Password.create("woo", :cost => 10)

# should take less than 1000ms
BCrypt::Password.create("woo", :cost => 12)
    # File lib/bcrypt/engine.rb
103 def self.calibrate(upper_time_limit_in_ms)
104   (BCrypt::Engine::MIN_COST..BCrypt::Engine::MAX_COST-1).each do |i|
105     start_time = Time.now
106     Password.create("testing testing", :cost => i+1)
107     end_time = Time.now - start_time
108     return i if end_time * 1_000 > upper_time_limit_in_ms
109   end
110 end
cost() click to toggle source

Returns the cost factor that will be used if one is not specified when creating a password hash. Defaults to DEFAULT_COST if not set.

   # File lib/bcrypt/engine.rb
24 def self.cost
25   @cost || DEFAULT_COST
26 end
cost=(cost) click to toggle source

Set a default cost factor that will be used if one is not specified when creating a password hash.

Example:

BCrypt::Engine::DEFAULT_COST            #=> 12
BCrypt::Password.create('secret').cost  #=> 12

BCrypt::Engine.cost = 8
BCrypt::Password.create('secret').cost  #=> 8

# cost can still be overridden as needed
BCrypt::Password.create('secret', :cost => 6).cost  #=> 6
   # File lib/bcrypt/engine.rb
41 def self.cost=(cost)
42   @cost = cost
43 end
generate_salt(cost = self.cost) click to toggle source

Generates a random salt with a given computational cost.

   # File lib/bcrypt/engine.rb
64 def self.generate_salt(cost = self.cost)
65   cost = cost.to_i
66   if cost > 0
67     if cost < MIN_COST
68       cost = MIN_COST
69     end
70     if RUBY_PLATFORM == "java"
71       Java.bcrypt_jruby.BCrypt.gensalt(cost)
72     else
73       prefix = "$2a$05$CCCCCCCCCCCCCCCCCCCCC.E5YPO9kmyuRGyh0XouQYb4YMJKvyOeW"
74       __bc_salt(prefix, cost, OpenSSL::Random.random_bytes(MAX_SALT_LENGTH))
75     end
76   else
77     raise Errors::InvalidCost.new("cost must be numeric and > 0")
78   end
79 end
hash_secret(secret, salt, _ = nil) click to toggle source

Given a secret and a valid salt (see BCrypt::Engine.generate_salt) calculates a bcrypt() password hash.

   # File lib/bcrypt/engine.rb
47 def self.hash_secret(secret, salt, _ = nil)
48   if valid_secret?(secret)
49     if valid_salt?(salt)
50       if RUBY_PLATFORM == "java"
51         Java.bcrypt_jruby.BCrypt.hashpw(secret.to_s.to_java_bytes, salt.to_s)
52       else
53         __bc_crypt(secret.to_s, salt)
54       end
55     else
56       raise Errors::InvalidSalt.new("invalid salt")
57     end
58   else
59     raise Errors::InvalidSecret.new("invalid secret")
60   end
61 end
valid_salt?(salt) click to toggle source

Returns true if salt is a valid bcrypt() salt, false if not.

   # File lib/bcrypt/engine.rb
82 def self.valid_salt?(salt)
83   !!(salt =~ /^\$[0-9a-z]{2,}\$[0-9]{2,}\$[A-Za-z0-9\.\/]{22,}$/)
84 end
valid_secret?(secret) click to toggle source

Returns true if secret is a valid bcrypt() secret, false if not.

   # File lib/bcrypt/engine.rb
87 def self.valid_secret?(secret)
88   secret.respond_to?(:to_s)
89 end