Class: CryptCheckpass::Bcrypt

Inherits:
CryptCheckpass show all
Defined in:
lib/crypt_checkpass/bcrypt.rb

Overview

BCrypt is a blowfish based password hash function. BSD devs and users tend to love this function. As of writing this is the only hash function that OpenBSD's crypt(3) understands. Also, because ActiveModel::SecurePassword is backended by this algorithm, Ruby on Rails users tends to use it.

Newhash:

In addition to the OpenBSD-ish usage described in README, you can also use crypto_newhash to create a new password hash using bcrypt:

crypt_newhash(password, id: 'bcrypt', rounds: 4, ident: '2b')

where:

- `password` is the raw binary password that you want to digest.

- `id` is "bcrypt" when you want a bcrypt hash.

- `rounds` is an integer ranging 4 to  31 inclusive, which is the number of
iterations.

- `ident` is  the name  of the  variant. Variants  of bcrypt  are described
below.  Note  however that what  we don't  support old variants  that are
known to be  problematic.  This parameter changes the name  of the output
but not the contents.

The generated password hash has following format.

Format:

A bcrypt hashed string has following structure:

%r{
  (?<id>     [2] [abxy]?       ){0}
  (?<cost>   [0-9]{2}          ){0}
  (?<salt>   [A-Za-z0-9./]{22} ){0}
  (?<csum>   [A-Za-z0-9./]{31} ){0}

  \A [$] \g<id>
     [$] \g<cost>
     [$] \g<salt>
         \g<csum>
  \z
}x

- `id` is 2-something that denotes the variant of the hash. See below.

- `cost`  is  a  zero-padded  decimal  integer  that  specifies  number  of
iterations in logs,

- `salt` and `csum` are the salt and checksum strings.  Both are encoded in
base64-like strings  that do  not strictly follow  RFC4648.  There  is no
separating `$` sign  is between them so you have  to count the characters
to  tell which  is  which.   Also, because  they  are  base64, there  are
"unused" bits at the end of each.

Variants:

According to Wikipedia entry, there are 5 variants of bcrypt output:

- Variant `$2$`:  This was the initial  version.  It did not  take Unicodes
into account.  Not currently active.

- Variant  `$2a$`:  Unicode problem  fixed,  but  suffered wraparound  bug.
OpenBSD people decided to abandon this  to move to `$2b$`.  Also suffered
CVE-2011-2483.  The people behind that CVE requested sysadmins to replace
their `$2a$`  with `$2x`, indicating  the data is broken.   Not currently
active.

- Variant `$2b$`: updated algorithm to fix wraparound bug.  Now active.

- Variant `$2x$`: see above.  No new password hash shall generate this one.

- Variant `$2y$`: updated algorithm to fix CVE-2011-2483.  Now active.

Fun facts:

- It is by spec that the algorithm ignores password longer than 72 octets.

- According to Python Passlib, variant  `$2b$` and `$2y$` are "identical in
all but name."

- Rails (bcrypt-ruby) reportedly uses `$2a$` even today.  However they seem
fixed  known  flaws by  themselves,  without  changing names.   So  their
algorithm  is arguably  safe.  Maybe  this can  be seen  as a  synonym of
`$2b$` / `$2y`.

Examples:

crypt_newhash 'password', id: 'bcrypt'
# => "$2b$10$JlxIYWbT2EUDNvIwrIYcxuKf8pzf58IV4xVWk9yPy5J/ni0LCmz7G"
crypt_checkpass? 'password', '$2b$10$JlxIYWbT2EUDNvIwrIYcxuKf8pzf58IV4xVWk9yPy5J/ni0LCmz7G'
# => true

See Also:

Class Method Summary collapse

Methods inherited from CryptCheckpass

crypt_checkpass?, crypt_newhash

Class Method Details

.checkpass?(pass, hash) ⇒ true, false

Checks if the given password matches the hash.

Parameters:

  • pass (String) —

    a password to test.

  • hash (String) —

    a good hash digest string.

Returns:

  • (true) —

    they are identical.

  • (false) —

    they are distinct.

Raises:

  • (NotImplementedError) —

    don't know how to parse hash.



143
144
145
146
147
148
149
150
151
 
# File 'lib/crypt_checkpass/bcrypt.rb', line 143

def self.checkpass? pass, hash
  require 'bcrypt'

  # bcrypt gem accepts `$2a$` and `$2x` only.  We have to tweak.
  expected = hash.sub %r/\A\$2[by]\$/, "$2a$"
  obj      = BCrypt::Password.new expected
  actual   = BCrypt::Engine.hash_secret pass, obj.salt
  return consttime_memequal? expected, actual
end

.new_with_openbsd_pref(pass, pref) ⇒ String

This is to implement OpenBSD-style crypt_newhash() function.

Parameters:

  • pass (String) —

    bare, unhashed binary password.

  • pref (String) —

    algorithm preference specifier.

Returns:

  • (String) —

    hashed digest string of password.

Raises:

  • (NotImplementedError) —

    pref not understandable.

See Also:



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/crypt_checkpass/bcrypt.rb', line 188

def self.new_with_openbsd_pref pass, pref
  require 'bcrypt'

  func, rounds = pref.split ',', 2
  unless match? func, /\A(bcrypt|blowfish)\z/ then
    raise NotImplementedError, <<-"end".strip, func
      hash algorithm %p not supported right now.
    end
  end

  cost = nil
  case rounds
  when NilClass                      then cost = BCrypt::Engine::DEFAULT_COST
  when "a"                           then cost = BCrypt::Engine::DEFAULT_COST
  when /\A([12][0-9]|3[01]|[4-9])\z/ then cost = rounds.to_i
  else
    raise NotImplementedError, <<-"end".strip, rounds
      cost function %p not supported right now.
    end
  end
  return __generate pass, cost, '2b'
end

.newhash(pass, id: 'bcrypt', rounds: nil, ident: '2b') ⇒ String

Note:

There is no way to specify salt. That's a bad idea.

Generate a new password hash string.

Parameters:

  • pass (String) —

    raw binary password string.

  • id (String) (defaults to: 'bcrypt') —

    name of the algorithm (ignored)

  • rounds (Integer) (defaults to: nil) —

    4 to 31, inclusive.

  • ident (String) (defaults to: '2b') —

    "2b" or "2y" or something like that.

Returns:

  • (String) —

    hashed digest string of password.

Raises:

  • (ArgumentError) 


164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/crypt_checkpass/bcrypt.rb', line 164

def self.newhash pass, id: 'bcrypt', rounds: nil, ident: '2b'
  require 'bcrypt'
  len = pass.bytesize
  raise ArgumentError, <<-"end", len if len > 72
    password is %d bytes, which is too long (up to 72)
  end

  rounds ||= BCrypt::Engine::DEFAULT_COST
  case rounds when 4..31 then
    return __generate pass, rounds, ident
  else
    raise ArgumentError, <<-"end", rounds
      integer %d out of range of (4..31)
    end
  end
end

.provide?(id) ⇒ true, false

Checks if the given ID can be handled by this class. A class is free to handle several IDs, like 'argon2i', 'argon2d', ...

Parameters:

  • id (String) —

    hash function ID.

Returns:

  • (true) —

    it does.

  • (false) —

    it desn't.



154
155
156
 
# File 'lib/crypt_checkpass/bcrypt.rb', line 154

def self.provide? id
  return id == 'bcrypt'
end

.understand?(str) ⇒ true, false

Checks if the given hash string can be handled by this class.

Parameters:

  • str (String) —

    a good hashed string.

Returns:

  • (true) —

    it does.

  • (false) —

    it desn't.



130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/crypt_checkpass/bcrypt.rb', line 130

def self.understand? str
  return match? str, %r{
    (?<id>     [2] [abxy]?       ){0}
    (?<cost>   [0-9]{2}          ){0}
    (?<remain> [A-Za-z0-9./]{53} ){0}
    \A [$] \g<id>
       [$] \g<cost>
       [$] \g<remain>
    \z
  }x
end