crypt_checkpass 1

data/lib/crypt_checkpass/bcrypt.rb

@@ -0,0 +1,217 @@
+#! /your/favourite/path/to/ruby
+# -*- mode: ruby; coding: utf-8; indent-tabs-mode: nil; ruby-indent-level: 2 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# Copyright (c) 2018 Urabe, Shyouhei
+#
+# Permission is hereby granted, free of  charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction,  including without limitation the rights
+# to use,  copy, modify,  merge, publish,  distribute, sublicense,  and/or sell
+# copies  of the  Software,  and to  permit  persons to  whom  the Software  is
+# furnished to do so, subject to the following conditions:
+#
+#       The above copyright notice and this permission notice shall be
+#       included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE  IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY  KIND, EXPRESS OR
+# IMPLIED,  INCLUDING BUT  NOT LIMITED  TO THE  WARRANTIES OF  MERCHANTABILITY,
+# FITNESS FOR A  PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO  EVENT SHALL THE
+# AUTHORS  OR COPYRIGHT  HOLDERS  BE LIABLE  FOR ANY  CLAIM,  DAMAGES OR  OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+require 'consttime_memequal'
+
+# 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  {file:README.md}, you can
+# also use `crypto_newhash` to create a new password hash using bcrypt:
+#
+# ```ruby
+# 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:
+#
+# ```ruby
+# %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`.
+#
+# @see https://en.wikipedia.org/wiki/Bcrypt
+# @see https://www.usenix.org/legacy/event/usenix99/provos/provos_html/
+# @example
+#   crypt_newhash 'password', id: 'bcrypt'
+#   # => "$2b$10$JlxIYWbT2EUDNvIwrIYcxuKf8pzf58IV4xVWk9yPy5J/ni0LCmz7G"
+# @example
+#   crypt_checkpass? 'password', '$2b$10$JlxIYWbT2EUDNvIwrIYcxuKf8pzf58IV4xVWk9yPy5J/ni0LCmz7G'
+#   # => true
+class CryptCheckpass::Bcrypt < CryptCheckpass
+
+  # (see CryptCheckpass.understand?)
+  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
+
+  # (see CryptCheckpass.checkpass?)
+  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
+
+  # (see CryptCheckpass.provide?)
+  def self.provide? id
+    return id == 'bcrypt'
+  end
+
+  # (see CryptCheckpass.newhash)
+  #
+  # @param pass   [String]  raw binary password string.
+  # @param id     [String]  name of the algorithm (ignored)
+  # @param rounds [Integer] 4 to 31, inclusive.
+  # @param ident  [String]  "2b" or "2y" or something like that.
+  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
+
+  # This is to implement OpenBSD-style `crypt_newhash()` function.
+  #
+  # @param pass [String]              bare, unhashed binary password.
+  # @param pref [String]              algorithm preference specifier.
+  # @return     [String]              hashed digest string of password.
+  # @raise      [NotImplementedError] pref not understandable.
+  # @see https://github.com/libressl-portable/openbsd/blob/master/src/lib/libc/crypt/cryptutil.c
+  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
+
+  def self.__generate pass, cost, ident
+    salt = BCrypt::Engine.generate_salt(cost)
+    ret  = BCrypt::Engine.hash_secret pass, salt
+    return ret.sub %r/\A\$2.?\$/, "$#{ident}$"
+  end
+  private_class_method :__generate
+end

data/lib/crypt_checkpass/pbkdf2.rb

@@ -0,0 +1,177 @@
+#! /your/favourite/path/to/ruby
+# -*- mode: ruby; coding: utf-8; indent-tabs-mode: nil; ruby-indent-level: 2 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# Copyright (c) 2018 Urabe, Shyouhei
+#
+# Permission is hereby granted, free of  charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction,  including without limitation the rights
+# to use,  copy, modify,  merge, publish,  distribute, sublicense,  and/or sell
+# copies  of the  Software,  and to  permit  persons to  whom  the Software  is
+# furnished to do so, subject to the following conditions:
+#
+#       The above copyright notice and this permission notice shall be
+#       included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE  IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY  KIND, EXPRESS OR
+# IMPLIED,  INCLUDING BUT  NOT LIMITED  TO THE  WARRANTIES OF  MERCHANTABILITY,
+# FITNESS FOR A  PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO  EVENT SHALL THE
+# AUTHORS  OR COPYRIGHT  HOLDERS  BE LIABLE  FOR ANY  CLAIM,  DAMAGES OR  OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+require_relative 'phc_string_format'
+
+# PBKDF2 is the most beloved algorithm by security professionals.
+#
+# ### Newhash:
+#
+# You can use `crypto_newhash` to create a new password hash using PBKDF2:
+#
+# ```ruby
+# crypt_newhash(password, id: 'pbkdf2-sha1', rounds: 1024)
+# ```
+#
+# where:
+#
+#   - `password` is the raw binary password that you want to digest.
+#
+#   - `id`  is "pbkdf2-{digest}".   You can  specify  sha1 /  sha256 /  sha512.
+#     Unlike plain SHA1, PBKDF2 + SHA1  combination still has no known weakness
+#     as of writing so specifying pbkdf-sha1 should just suffice normally.
+#
+#   - `rounds` is for iteration rounds.
+#
+# The generated password hash has following format.
+#
+# ### Format:
+#
+# This algorithm does not have a standard hash format.  Here we follow npm's
+# @phc/pbkdf2.
+#
+# ```ruby
+# %r{
+#   (?<id>   pbkdf2-[\w\d]+ ){0}
+#   (?<i>    i=[1-9][0-9]*  ){0}
+#   (?<salt> [a-zA-Z0-9+/]* ){0}
+#   (?<csum> [a-zA-Z0-9+/]* ){0}
+#
+#   \A [$] \g<id>
+#      [$] \g<i>
+#      [$] \g<salt>
+#      [$] \g<csum>
+#   \z
+# }x
+# ```
+#
+# - This is a strict PHC string format. See also
+#   {CryptCheckpass::PHCStringFormat}
+#
+# - The `id` can either be "pbkdf2-sha1", "pbkdf2-sha256", or "pbkdf2-sha512".
+#
+# - The only parameter `i` is the iteration (rounds) of the calculation.
+#
+# ### Other formats:
+#
+# Python Passlib generates something different, in the same `$pbkdf2-{digest}$`
+# id.  Passlib's and @phc/pbkdf2's are distinguishable because Passlib does not
+# follow PHC String Format.
+#
+# @see https://en.wikipedia.org/wiki/PBKDF2
+# @see https://tools.ietf.org/html/rfc2898
+# @example
+#   crypt_newhash 'password', id: 'pbkdf2-sha1'
+#   # => "$pbkdf2-sha1$i=1024$a9b0ggwILmLgiAwV34bpzA$nJ+GYjlNDao8BJedGVc8UROXpcU"
+# @example
+#   crypt_checkpass? 'password', '$pbkdf2-sha1$i=1024$a9b0ggwILmLgiAwV34bpzA$nJ+GYjlNDao8BJedGVc8UROXpcU'
+#   # => true
+class CryptCheckpass::PBKDF2 < CryptCheckpass
+
+  # (see CryptCheckpass.understand?)
+  def self.understand? str
+    return match? str, %r{
+      (?<id>   pbkdf2-sha(1|256|512) ){0}
+      (?<i>    i=[1-9][0-9]*         ){0}
+      (?<salt> [a-zA-Z0-9+/]*        ){0}
+      (?<csum> [a-zA-Z0-9+/]*        ){0}
+
+      \A [$] \g<id>
+         [$] \g<i>
+         [$] \g<salt>
+         [$] \g<csum>
+      \z
+    }x
+  end
+
+  # (see CryptCheckpass.checkpass?)
+  def self.checkpass? pass, hash
+    require 'consttime_memequal'
+
+    json     = phcdecode hash
+    id       = json[:id]
+    i        = json[:params][:i]
+    salt     = json[:salt]
+    expected = json[:csum]
+    dklen    = expected.bytesize
+    actual   = __derive_key id, i, salt, pass, dklen
+
+    return consttime_memequal? expected, actual
+  end
+
+  # (see CryptCheckpass.provide?)
+  def self.provide? id
+    case id when 'pbkdf2-sha1', 'pbkdf2-sha256', 'pbkdf2-sha512' then
+      return true
+    else
+      return false
+    end
+  end
+
+  # (see CryptCheckpass.newhash)
+  #
+  # @param pass   [String]  raw binary password string.
+  # @param id     [String]  name of the algorithm
+  # @param rounds [Integer] iteration rounds
+  def self.newhash pass, id: 'pbkdf2-sha1', rounds: 1024
+    salt = SecureRandom.random_bytes 16
+    csum = __derive_key id, rounds, salt, pass
+    return phcencode id, { i: rounds }, salt, csum
+  end
+end
+
+# helper routines
+class << CryptCheckpass::PBKDF2
+  include CryptCheckpass::PHCStringFormat
+
+  private
+
+  if RUBY_VERSION >= '2.3.0'
+    def __load_openssl
+      require 'openssl'
+    end
+  else
+    def __load_openssl
+      Kernel.require 'openssl'
+    end
+  end
+
+  def __default_dklen_for digest
+    case digest
+    when 'pbkdf2-sha1'   then return 20, 'sha1'
+    when 'pbkdf2-sha256' then return 32, 'sha256'
+    when 'pbkdf2-sha512' then return 64, 'sha512'
+    else raise "NOTREACHED: %s", id
+    end
+  end
+
+  def __derive_key id, iter, salt, pass, dklen = nil
+    __load_openssl
+
+    n, d    = __default_dklen_for id
+    dklen ||= n
+    return OpenSSL::PKCS5.pbkdf2_hmac pass, salt, iter, dklen, d
+  end
+end

data/lib/crypt_checkpass/phc_string_format.rb

@@ -0,0 +1,180 @@
+#! /your/favourite/path/to/ruby
+# -*- mode: ruby; coding: utf-8; indent-tabs-mode: nil; ruby-indent-level: 2 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+# Copyright (c) 2018 Urabe, Shyouhei
+#
+# Permission is hereby granted, free of  charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction,  including without limitation the rights
+# to use,  copy, modify,  merge, publish,  distribute, sublicense,  and/or sell
+# copies  of the  Software,  and to  permit  persons to  whom  the Software  is
+# furnished to do so, subject to the following conditions:
+#
+#       The above copyright notice and this permission notice shall be
+#       included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE  IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY  KIND, EXPRESS OR
+# IMPLIED,  INCLUDING BUT  NOT LIMITED  TO THE  WARRANTIES OF  MERCHANTABILITY,
+# FITNESS FOR A  PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO  EVENT SHALL THE
+# AUTHORS  OR COPYRIGHT  HOLDERS  BE LIABLE  FOR ANY  CLAIM,  DAMAGES OR  OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# Helper module to handle PHC String Format-compatible strings
+#
+# @note Argon2, which  is the winner of  PHC, ignores this format  and go wild.
+#       It is  highly skeptical  that any  other hash  authors would  switch to
+#       PHC's recommendation.
+#
+# ### Format
+#
+# This is how we understand the PHC String Format:
+#
+# ```ruby
+# %r{
+#   (?<name>    [a-z0-9-]{,32}              ){0}
+#   (?<decimal> 0|-?[1-9][0-9]*             ){0}
+#   (?<b64>     [a-zA-Z0-9/+.-]*            ){0}
+#
+#   (?<id>      \g<name>                    ){0}
+#   (?<param>   \g<name>                    ){0}
+#   (?<value>   \g<decimal> | \g<b64>       ){0}
+#   (?<salt>    \g<b64>                     ){0}
+#   (?<csum>    \g<b64>                     ){0}
+#   (?<pair>    \g<param> = \g<value>       ){0}
+#   (?<pairs>   \g<pair> (?:[,] \g<pair> )* ){0}
+#
+#   \A [$] \g<id>
+#      [$] \g<pairs>
+#      [$] \g<salt>
+#      [$] \g<csum>
+#   \z
+# }x
+# ```
+# 
+#   - `id` is the name of the algorithm.
+#
+#   - `pairs` is a set of key-value pair, that are parameters to the
+#      algorithm.  Keys should be human-readable, while values need not be.
+#
+#   - `salt` and `csum` are the salt and checksum strings.  Both are encoded in
+#     what the spec says the "B64"  encoding, which is a very slightly modified
+#     version  of  RFC4648 (no  trailing  ==...  padding).   They both  can  be
+#     arbitrary length.
+#
+# @see https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md
+module CryptCheckpass::PHCStringFormat
+  private
+
+  # B64 encoder
+  # @param str [String] arbitrary binary string.
+  # @return    [String] str, encoded in B64.
+  def b64encode str
+    var = [ str ].pack 'm0'
+    var.delete! '='
+    return var
+  end
+
+  if RUBY_VERSION >= '2.4.0' then
+    def malloc n
+      String.new capacity: n
+    end
+  else
+    def malloc n
+      String.new
+    end
+  end
+
+  # B64 decoder
+  # @param str [String]        str, encoded in B64.
+  # @return    [String]        decoded binary string
+  # @raise     [ArgumentError] str not in B64 encoding.
+  def b64decode str
+    return nil if str.nil? 
+    n, m = str.length.divmod 4
+    raise ArgumentError, <<-"end".strip, str.length if m == 1
+      malformed string of %d octets passed.
+    end
+    buf = malloc(n * 4)
+    buf << str
+    buf << ('=' * ((4 - m) % 4))
+    return buf.unpack('m0').first
+  end
+
+  # Form a PHC String Formatted string.
+  # @return        [String]              a PHC String Formatted string.
+  # @param  id     [String]              name of hash algorithm.
+  # @param  params [<<String, Integer>>] hash algorithm parameters.
+  # @param  salt   [String]              raw binary salt.
+  # @param  csum   [String]              raw binary checksum
+  # @note   The spec says:
+  #
+  #         > The  function MUST  specify  the order  in  which parameters  may
+  #         > appear.  Producers MUST  NOT allow  parameters to  appear in  any
+  #         > other order.
+  #
+  #         Ensuring that property is up to the caller of this method.
+  def phcencode id, params, salt, csum
+    return [
+      '',
+      id,
+      params.map {|a| a.join '=' }.join(','),
+      b64encode(salt),
+      b64encode(csum)
+    ].join('$')
+  end
+
+  # Decompose a PHC String Formatted string.
+  # @param str [String]        str, encoded in PHC's format.
+  # @return    [Hash]          decoded JSON.
+  def phcdecode str
+    grammar = %r{
+      (?<name>    [a-z0-9-]{,32}              ){0}
+      (?<decimal> 0|-?[1-9][0-9]*             ){0}
+      (?<b64>     [a-zA-Z0-9/+.-]*            ){0}
+
+      (?<id>      \g<name>                    ){0}
+      (?<param>   \g<name>                    ){0}
+      (?<value>   \g<decimal> | \g<b64>       ){0}
+      (?<salt>    \g<b64>                     ){0}
+      (?<csum>    \g<b64>                     ){0}
+      (?<pair>    \g<param> = \g<value>       ){0}
+      (?<pairs>   \g<pair> (?:[,] \g<pair> )* ){0}
+    }x
+
+    md = %r{
+      #{grammar}
+
+      \A [$] \g<id>
+         [$] \g<pairs>
+         [$] \g<salt>
+         [$] \g<csum>
+      \z
+    }xo.match str
+    raise "not in PHC String Format: %p", str unless md
+
+    return {
+      id:     md['id'],
+      params: md['pairs']     \
+              . split(',', -1) \
+              . map {|i|
+                  m = /#{grammar}\A\g<pair>\z/o.match i
+                  next [
+                    m['param'],
+                    m['decimal'] ? m['decimal'].to_i : m['b64']
+                  ]
+              }.each_with_object({}) {|(k, v), h|
+                  h.update(k.to_s.to_sym => v) { |_, w, _|
+                    raise <<-"end".strip, md['params'], k, v, w
+                      %p includes conflicting values for %p: %p versus %p
+                    end
+                  }
+              }, 
+      salt:   b64decode(md['salt']),
+      csum:   b64decode(md['csum']),
+    }
+  end
+end