git ssb

1
# A wrapper for OpenBSD's bcrypt/crypt_blowfish password-hashing algorithm.
2
3
require "ext/bcrypt_ext"
4
require "openssl"
5
6
# A Ruby library implementing OpenBSD's bcrypt()/crypt_blowfish algorithm for
7
# hashing passwords.
8
module BCrypt  
9
  module Errors # :nodoc:
10
    class InvalidSalt   < Exception; end  # The salt parameter provided to bcrypt() is invalid.
11
    class InvalidHash   < Exception; end  # The hash parameter provided to bcrypt() is invalid.
12
    class InvalidCost   < Exception; end  # The cost parameter provided to bcrypt() is invalid.
13
    class InvalidSecret < Exception; end  # The secret parameter provided to bcrypt() is invalid.
14
  end
15
  
16
  # A Ruby wrapper for the bcrypt() extension calls.
17
  class Engine
18
    # The default computational expense parameter.
19
    DEFAULT_COST    = 10
20
    # Maximum possible size of bcrypt() salts.
21
    MAX_SALT_LENGTH = 16
22
    
23
    # C-level routines which, if they don't get the right input, will crash the
24
    # hell out of the Ruby process.
25
    private_class_method :__bc_salt
26
    private_class_method :__bc_crypt
27
    
28
    # Given a secret and a valid salt (see BCrypt::Engine.generate_salt) calculates
29
    # a bcrypt() password hash.
30
    def self.hash(secret, salt)
31
      if valid_secret?(secret)
32
        if valid_salt?(salt)
33
          __bc_crypt(secret, salt)
34
        else
35
          raise Errors::InvalidSalt.new("invalid salt")
36
        end
37
      else
38
        raise Errors::InvalidSecret.new("invalid secret")
39
      end
40
    end
41
    
42
    # Generates a random salt with a given computational cost.
43
    def self.generate_salt(cost = DEFAULT_COST)
44
      if cost.to_i > 0
45
        __bc_salt(cost, OpenSSL::Random.random_bytes(MAX_SALT_LENGTH))
46
      else
47
        raise Errors::InvalidCost.new("cost must be numeric and > 0")
48
      end
49
    end
50
    
51
    # Returns true if +salt+ is a valid bcrypt() salt, false if not.
52
    def self.valid_salt?(salt)
53
      salt =~ /^\$[0-9a-z]{2,}\$[0-9]{2,}\$[A-Za-z0-9\.\/]{22,}$/
54
    end
55
    
56
    # Returns true if +secret+ is a valid bcrypt() secret, false if not.
57
    def self.valid_secret?(secret)
58
      !secret.nil?
59
    end
60
    
61
    # Returns the cost factor which will result in computation times less than +upper_time_limit_in_ms+.
62
    # 
63
    # Example:
64
    # 
65
    #   BCrypt.calibrate(200)  #=> 10
66
    #   BCrypt.calibrate(1000) #=> 12
67
    # 
68
    #   # should take less than 200ms
69
    #   BCrypt::Password.create("woo", :cost => 10)
70
    # 
71
    #   # should take less than 1000ms
72
    #   BCrypt::Password.create("woo", :cost => 12)
73
    def self.calibrate(upper_time_limit_in_ms)
74
      40.times do |i|
75
        start_time = Time.now
76
        Password.create("testing testing", :cost => i+1)
77
        end_time = Time.now - start_time
78
        return i if end_time * 1_000 > upper_time_limit_in_ms
79
      end
80
    end
81
  end
82
  
83
  # A password management class which allows you to safely store users' passwords and compare them.
84
  # 
85
  # Example usage:
86
  # 
87
  #   include BCrypt
88
  # 
89
  #   # hash a user's password  
90
  #   @password = Password.create("my grand secret")
91
  #   @password #=> "$2a$10$GtKs1Kbsig8ULHZzO1h2TetZfhO4Fmlxphp8bVKnUlZCBYYClPohG"
92
  # 
93
  #   # store it safely
94
  #   @user.update_attribute(:password, @password)
95
  # 
96
  #   # read it back
97
  #   @user.reload!
98
  #   @db_password = Password.new(@user.password)
99
  # 
100
  #   # compare it after retrieval
101
  #   @db_password == "my grand secret" #=> true
102
  #   @db_password == "a paltry guess"  #=> false
103
  # 
104
  class Password < String
105
    # The hash portion of the stored password hash.
106
    attr_reader :hash
107
    # The salt of the store password hash (including version and cost).
108
    attr_reader :salt
109
    # The version of the bcrypt() algorithm used to create the hash.
110
    attr_reader :version
111
    # The cost factor used to create the hash.
112
    attr_reader :cost
113
    
114
    class << self
115
      # Hashes a secret, returning a BCrypt::Password instance. Takes an optional <tt>:cost</tt> option, which is a
116
      # logarithmic variable which determines how computational expensive the hash is to calculate (a <tt>:cost</tt> of
117
      # 4 is twice as much work as a <tt>:cost</tt> of 3). The higher the <tt>:cost</tt> the harder it becomes for
118
      # attackers to try to guess passwords (even if a copy of your database is stolen), but the slower it is to check
119
      # users' passwords.
120
      # 
121
      # Example:
122
      # 
123
      #   @password = BCrypt::Password.create("my secret", :cost => 13)
124
      def create(secret, options = { :cost => BCrypt::Engine::DEFAULT_COST })
125
        Password.new(BCrypt::Engine.hash(secret, BCrypt::Engine.generate_salt(options[:cost])))
126
      end
127
    end
128
    
129
    # Initializes a BCrypt::Password instance with the data from a stored hash.
130
    def initialize(raw_hash)
131
      if valid_hash?(raw_hash)
132
        self.replace(raw_hash)
133
        @version, @cost, @salt, @hash = split_hash(self)
134
      else
135
        raise Errors::InvalidHash.new("invalid hash")
136
      end
137
    end
138
    
139
    # Compares a potential secret against the hash. Returns true if the secret is the original secret, false otherwise.
140
    def ==(secret)
141
      super(BCrypt::Engine.hash(secret, @salt))
142
    end
143
    alias_method :is_password?, :==
144
    
145
  private
146
    # Returns true if +h+ is a valid hash.
147
    def valid_hash?(h)
148
      h =~ /^\$[0-9a-z]{2}\$[0-9]{2}\$[A-Za-z0-9\.\/]{53}$/
149
    end
150
    
151
    # call-seq:
152
    #   split_hash(raw_hash) -> version, cost, salt, hash
153
    # 
154
    # Splits +h+ into version, cost, salt, and hash and returns them in that order.
155
    def split_hash(h)
156
      b, v, c, mash = h.split('$')
157
      return v, c.to_i, h[0, 29], mash[-31, 31]
158
    end
159
  end
160
end