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.
- MAX_SECRET_BYTESIZE
Maximum possible size of bcrypt() secrets. Older versions of the bcrypt library would truncate passwords longer than 72 bytes, but newer ones do not. We truncate like the old library for forward compatibility. This way users upgrading from Ubuntu 18.04 to 20.04 will not have their user passwords invalidated, for example. A max secret length greater than 255 leads to bcrypt returning nil. github.com/bcrypt-ruby/bcrypt-ruby/issues/225#issuecomment-875908425
- 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; VALUE out; struct bc_crypt_args args; if(NIL_P(key) || NIL_P(setting)) return Qnil; /* duplicate the parameters for thread safety. If another thread has a * reference to the parameters and mutates them while we are working, * that would be very bad. Duping the strings means that the reference * isn't shared. */ key = rb_str_new_frozen(key); setting = rb_str_new_frozen(setting); args.data = NULL; args.size = 0xDEADBEEF; args.key = NIL_P(key) ? NULL : StringValueCStr(key); args.setting = NIL_P(setting) ? NULL : StringValueCStr(setting); #ifdef HAVE_RUBY_THREAD_H value = rb_thread_call_without_gvl(bc_crypt_nogvl, &args, NULL, NULL); #else value = bc_crypt_nogvl((void *)&args); #endif if(!value || !args.data) return Qnil; out = rb_str_new2(value); free(args.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; struct bc_salt_args args; /* duplicate the parameters for thread safety. If another thread has a * reference to the parameters and mutates them while we are working, * that would be very bad. Duping the strings means that the reference * isn't shared. */ prefix = rb_str_new_frozen(prefix); input = rb_str_new_frozen(input); args.prefix = StringValueCStr(prefix); args.count = NUM2ULONG(count); args.input = NIL_P(input) ? NULL : StringValuePtr(input); args.size = NIL_P(input) ? 0 : RSTRING_LEN(input); #ifdef HAVE_RUBY_THREAD_H salt = rb_thread_call_without_gvl(bc_salt_nogvl, &args, NULL, NULL); #else salt = bc_salt_nogvl((void *)&args); #endif if(!salt) return Qnil; str_salt = rb_str_new2(salt); free(salt); return str_salt; }
Autodetects the cost from the salt string.
# File lib/bcrypt/engine.rb, line 122 def self.autodetect_cost(salt) salt[4..5].to_i 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, line 112 def self.calibrate(upper_time_limit_in_ms) (BCrypt::Engine::MIN_COST..BCrypt::Engine::MAX_COST-1).each do |i| start_time = Time.now Password.create("testing testing", :cost => i+1) end_time = Time.now - start_time return i if end_time * 1_000 > upper_time_limit_in_ms end 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, line 32 def self.cost @cost || DEFAULT_COST 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 #=> 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, line 49 def self.cost=(cost) @cost = cost end
Generates a random salt with a given computational cost.
# File lib/bcrypt/engine.rb, line 74 def self.generate_salt(cost = self.cost) cost = cost.to_i if cost > 0 if cost < MIN_COST cost = MIN_COST end if RUBY_PLATFORM == "java" Java.bcrypt_jruby.BCrypt.gensalt(cost) else __bc_salt("$2a$", cost, OpenSSL::Random.random_bytes(MAX_SALT_LENGTH)) end else raise Errors::InvalidCost.new("cost must be numeric and > 0") end end
Given a secret and a valid salt (see ::generate_salt) calculates a bcrypt() password hash. Secrets longer than 72 bytes are truncated.
# File lib/bcrypt/engine.rb, line 55 def self.hash_secret(secret, salt, _ = nil) if valid_secret?(secret) if valid_salt?(salt) if RUBY_PLATFORM == "java" Java.bcrypt_jruby.BCrypt.hashpw(secret.to_s.to_java_bytes, salt.to_s) else secret = secret.to_s secret = secret.byteslice(0, MAX_SECRET_BYTESIZE) if secret && secret.bytesize > MAX_SECRET_BYTESIZE __bc_crypt(secret, salt) end else raise Errors::InvalidSalt.new("invalid salt") end else raise Errors::InvalidSecret.new("invalid secret") end end
Returns true if salt
is a valid bcrypt() salt, false if not.
# File lib/bcrypt/engine.rb, line 91 def self.valid_salt?(salt) !!(salt =~ /\A\$[0-9a-z]{2,}\$[0-9]{2,}\$[A-Za-z0-9\.\/]{22,}\z/) end
Returns true if secret
is a valid bcrypt() secret, false if
not.
# File lib/bcrypt/engine.rb, line 96 def self.valid_secret?(secret) secret.respond_to?(:to_s) end