class BCrypt::Password

A password management class which allows you to safely store users' passwords and compare them.

Example usage:

include BCrypt

# hash a user's password
@password = Password.create("my grand secret")
@password #=> "$2a$12$C5.FIvVDS9W4AYZ/Ib37YuWd/7ozp1UaMhU28UKrfSxp2oDchbi3K"

# store it safely
@user.update_attribute(:password, @password)

# read it back
@user.reload!
@db_password = Password.new(@user.password)

# compare it after retrieval
@db_password == "my grand secret" #=> true
@db_password == "a paltry guess"  #=> false

Attributes

checksum[R]

The hash portion of the stored password hash.

cost[R]

The cost factor used to create the hash.

salt[R]

The salt of the store password hash (including version and cost).

version[R]

The version of the bcrypt() algorithm used to create the hash.

Public Class Methods

create(secret, options = {}) click to toggle source

Hashes a secret, returning a BCrypt::Password instance. Takes an optional :cost option, which is a logarithmic variable which determines how computational expensive the hash is to calculate (a :cost of 4 is twice as much work as a :cost of 3). The higher the :cost the harder it becomes for attackers to try to guess passwords (even if a copy of your database is stolen), but the slower it is to check users' passwords.

Example:

@password = BCrypt::Password.create("my secret", :cost => 13)
   # File lib/bcrypt/password.rb
43 def create(secret, options = {})
44   cost = options[:cost] || BCrypt::Engine.cost
45   raise ArgumentError if cost > BCrypt::Engine::MAX_COST
46   Password.new(BCrypt::Engine.hash_secret(secret, BCrypt::Engine.generate_salt(cost)))
47 end
new(raw_hash) click to toggle source

Initializes a BCrypt::Password instance with the data from a stored hash.

   # File lib/bcrypt/password.rb
55 def initialize(raw_hash)
56   if valid_hash?(raw_hash)
57     self.replace(raw_hash)
58     @version, @cost, @salt, @checksum = split_hash(self)
59   else
60     raise Errors::InvalidHash.new("invalid hash")
61   end
62 end
valid_hash?(h) click to toggle source
   # File lib/bcrypt/password.rb
49 def valid_hash?(h)
50   /^\$[0-9a-z]{2}\$[0-9]{2}\$[A-Za-z0-9\.\/]{53}$/ === h
51 end

Public Instance Methods

==(secret) click to toggle source

Compares a potential secret against the hash. Returns true if the secret is the original secret, false otherwise.

Calls superclass method
   # File lib/bcrypt/password.rb
65 def ==(secret)
66   super(BCrypt::Engine.hash_secret(secret, @salt))
67 end
Also aliased as: is_password?
is_password?(secret)
Alias for: ==

Private Instance Methods

split_hash(raw_hash) → version, cost, salt, hash click to toggle source

Splits h into version, cost, salt, and hash and returns them in that order.

   # File lib/bcrypt/password.rb
81 def split_hash(h)
82   _, v, c, mash = h.split('$')
83   return v.to_str, c.to_i, h[0, 29].to_str, mash[-31, 31].to_str
84 end
valid_hash?(h) click to toggle source

Returns true if h is a valid hash.

   # File lib/bcrypt/password.rb
73 def valid_hash?(h)
74   self.class.valid_hash?(h)
75 end