git ssb

1
# A wrapper for OpenBSD's bcrypt/crypt_blowfish password-hashing algorithm.
2
3
if RUBY_PLATFORM == "java"
4
  require 'java'
5
else
6
  require "openssl"
7
end
8
9
if defined?(RUBY_ENGINE) and RUBY_ENGINE == "maglev"
10
  require 'bcrypt_engine'
11
else
12
  require 'bcrypt_ext'
13
end
14
15
# A Ruby library implementing OpenBSD's bcrypt()/crypt_blowfish algorithm for
16
# hashing passwords.
17
module BCrypt
18
  module Errors
19
    class InvalidSalt   < StandardError; end  # The salt parameter provided to bcrypt() is invalid.
20
    class InvalidHash   < StandardError; end  # The hash parameter provided to bcrypt() is invalid.
21
    class InvalidCost   < StandardError; end  # The cost parameter provided to bcrypt() is invalid.
22
    class InvalidSecret < StandardError; end  # The secret parameter provided to bcrypt() is invalid.
23
  end
24
25
  # A Ruby wrapper for the bcrypt() C extension calls and the Java calls.
26
  class Engine
27
    # The default computational expense parameter.
28
    DEFAULT_COST    = 10
29
    # The minimum cost supported by the algorithm.
30
    MIN_COST        = 4
31
    # Maximum possible size of bcrypt() salts.
32
    MAX_SALT_LENGTH = 16
33
34
    if RUBY_PLATFORM != "java"
35
      # C-level routines which, if they don't get the right input, will crash the
36
      # hell out of the Ruby process.
37
      private_class_method :__bc_salt
38
      private_class_method :__bc_crypt
39
    end
40
41
    # Given a secret and a valid salt (see BCrypt::Engine.generate_salt) calculates
42
    # a bcrypt() password hash.
43
    def self.hash_secret(secret, salt, cost = nil)
44
      if valid_secret?(secret)
45
        if valid_salt?(salt)
46
          if cost.nil?
47
            cost = autodetect_cost(salt)
48
          end
49
50
          if RUBY_PLATFORM == "java"
51
            Java.bcrypt_jruby.BCrypt.hashpw(secret.to_s, 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
62
63
    # Generates a random salt with a given computational cost.
64
    def self.generate_salt(cost = DEFAULT_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
80
81
    # Returns true if +salt+ is a valid bcrypt() salt, false if not.
82
    def self.valid_salt?(salt)
83
      !!(salt =~ /^\$[0-9a-z]{2,}\$[0-9]{2,}\$[A-Za-z0-9\.\/]{22,}$/)
84
    end
85
86
    # Returns true if +secret+ is a valid bcrypt() secret, false if not.
87
    def self.valid_secret?(secret)
88
      secret.respond_to?(:to_s)
89
    end
90
91
    # Returns the cost factor which will result in computation times less than +upper_time_limit_in_ms+.
92
    #
93
    # Example:
94
    #
95
    #   BCrypt.calibrate(200)  #=> 10
96
    #   BCrypt.calibrate(1000) #=> 12
97
    #
98
    #   # should take less than 200ms
99
    #   BCrypt::Password.create("woo", :cost => 10)
100
    #
101
    #   # should take less than 1000ms
102
    #   BCrypt::Password.create("woo", :cost => 12)
103
    def self.calibrate(upper_time_limit_in_ms)
104
      40.times 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
111
112
    # Autodetects the cost from the salt string.
113
    def self.autodetect_cost(salt)
114
      salt[4..5].to_i
115
    end
116
  end
117
118
  # A password management class which allows you to safely store users' passwords and compare them.
119
  #
120
  # Example usage:
121
  #
122
  #   include BCrypt
123
  #
124
  #   # hash a user's password  
125
  #   @password = Password.create("my grand secret")
126
  #   @password #=> "$2a$10$GtKs1Kbsig8ULHZzO1h2TetZfhO4Fmlxphp8bVKnUlZCBYYClPohG"
127
  #
128
  #   # store it safely
129
  #   @user.update_attribute(:password, @password)
130
  #
131
  #   # read it back
132
  #   @user.reload!
133
  #   @db_password = Password.new(@user.password)
134
  #
135
  #   # compare it after retrieval
136
  #   @db_password == "my grand secret" #=> true
137
  #   @db_password == "a paltry guess"  #=> false
138
  #
139
  class Password < String
140
    # The hash portion of the stored password hash.
141
    attr_reader :checksum
142
    # The salt of the store password hash (including version and cost).
143
    attr_reader :salt
144
    # The version of the bcrypt() algorithm used to create the hash.
145
    attr_reader :version
146
    # The cost factor used to create the hash.
147
    attr_reader :cost
148
149
    class << self
150
      # Hashes a secret, returning a BCrypt::Password instance. Takes an optional <tt>:cost</tt> option, which is a
151
      # logarithmic variable which determines how computational expensive the hash is to calculate (a <tt>:cost</tt> of
152
      # 4 is twice as much work as a <tt>:cost</tt> of 3). The higher the <tt>:cost</tt> the harder it becomes for
153
      # attackers to try to guess passwords (even if a copy of your database is stolen), but the slower it is to check
154
      # users' passwords.
155
      #
156
      # Example:
157
      #
158
      #   @password = BCrypt::Password.create("my secret", :cost => 13)
159
      def create(secret, options = { :cost => BCrypt::Engine::DEFAULT_COST })
160
        Password.new(BCrypt::Engine.hash_secret(secret, BCrypt::Engine.generate_salt(options[:cost]), options[:cost]))
161
      end
162
    end
163
164
    # Initializes a BCrypt::Password instance with the data from a stored hash.
165
    def initialize(raw_hash)
166
      if valid_hash?(raw_hash)
167
        self.replace(raw_hash)
168
        @version, @cost, @salt, @checksum = split_hash(self)
169
      else
170
        raise Errors::InvalidHash.new("invalid hash")
171
      end
172
    end
173
174
    # Compares a potential secret against the hash. Returns true if the secret is the original secret, false otherwise.
175
    def ==(secret)
176
      super(BCrypt::Engine.hash_secret(secret, @salt))
177
    end
178
    alias_method :is_password?, :==
179
180
  private
181
    # Returns true if +h+ is a valid hash.
182
    def valid_hash?(h)
183
      h =~ /^\$[0-9a-z]{2}\$[0-9]{2}\$[A-Za-z0-9\.\/]{53}$/
184
    end
185
186
    # call-seq:
187
    #   split_hash(raw_hash) -> version, cost, salt, hash
188
    #
189
    # Splits +h+ into version, cost, salt, and hash and returns them in that order.
190
    def split_hash(h)
191
      _, v, c, mash = h.split('$')
192
      return v, c.to_i, h[0, 29].to_str, mash[-31, 31].to_str
193
    end
194
  end
195
end
196