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_SALT_LENGTH
Maximum possible size of bcrypt() salts.
- MIN_COST
The minimum cost supported by the algorithm.
Public Class Methods
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) return Qnil; out = rb_str_new(data, size - 1); xfree(data); return out; }
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); xfree(salt); return str_salt; }
Autodetects the cost from the salt string.
# File lib/bcrypt/engine.rb 118 def self.autodetect_cost(salt) 119 salt[4..5].to_i 120 end
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 108 def self.calibrate(upper_time_limit_in_ms) 109 40.times do |i| 110 start_time = Time.now 111 Password.create("testing testing", :cost => i+1) 112 end_time = Time.now - start_time 113 return i if end_time * 1_000 > upper_time_limit_in_ms 114 end 115 end
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 22 def self.cost 23 @cost || DEFAULT_COST 24 end
Set a default cost factor that will be used if one is not specified when creating a password hash.
Example:
BCrypt::Engine::DEFAULT_COST #=> 10 BCrypt::Password.create('secret').cost #=> 10 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 39 def self.cost=(cost) 40 @cost = cost 41 end
Generates a random salt with a given computational cost.
# File lib/bcrypt/engine.rb 69 def self.generate_salt(cost = self.cost) 70 cost = cost.to_i 71 if cost > 0 72 if cost < MIN_COST 73 cost = MIN_COST 74 end 75 if RUBY_PLATFORM == "java" 76 Java.bcrypt_jruby.BCrypt.gensalt(cost) 77 else 78 prefix = "$2a$05$CCCCCCCCCCCCCCCCCCCCC.E5YPO9kmyuRGyh0XouQYb4YMJKvyOeW" 79 __bc_salt(prefix, cost, OpenSSL::Random.random_bytes(MAX_SALT_LENGTH)) 80 end 81 else 82 raise Errors::InvalidCost.new("cost must be numeric and > 0") 83 end 84 end
Given a secret and a valid salt (see BCrypt::Engine.generate_salt
) calculates a bcrypt() password hash.
# File lib/bcrypt/engine.rb 45 def self.hash_secret(secret, salt, _ = nil) 46 if valid_secret?(secret) 47 if valid_salt?(salt) 48 if RUBY_PLATFORM == "java" 49 # the native C bcrypt implementation used by the MRI version of this gem 50 # interprets secret as a null-terminated string; to ensure consistency, 51 # we drop after any null byte 52 trimmed = secret.to_s.split("\0").first # drop after null byte to emulate C 53 54 # the java hashpw() method taking byte[] expects the null terminator 55 bytes = (trimmed.to_s + "\0").to_java_bytes # add null byte for byte[] API 56 Java.bcrypt_jruby.BCrypt.hashpw(bytes, salt.to_s) 57 else 58 __bc_crypt(secret.to_s, salt) 59 end 60 else 61 raise Errors::InvalidSalt.new("invalid salt") 62 end 63 else 64 raise Errors::InvalidSecret.new("invalid secret") 65 end 66 end
Returns true if salt
is a valid bcrypt() salt, false if not.
# File lib/bcrypt/engine.rb 87 def self.valid_salt?(salt) 88 !!(salt =~ /^\$[0-9a-z]{2,}\$[0-9]{2,}\$[A-Za-z0-9\.\/]{22,}$/) 89 end
Returns true if secret
is a valid bcrypt() secret, false if not.
# File lib/bcrypt/engine.rb 92 def self.valid_secret?(secret) 93 secret.respond_to?(:to_s) 94 end