sorcery-argon2 1.0.0

data/lib/argon2/ffi_engine.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'ffi'
+require 'ffi-compiler/loader'
+
+module Argon2
+  ##
+  # Direct external bindings. Call these methods via the Engine class to ensure
+  # points are dealt with.
+  #
+  module Ext
+    extend FFI::Library
+    ffi_lib FFI::Compiler::Loader.find(FFI::Platform.windows? ? 'libargon2_wrap' : 'argon2_wrap')
+
+    # int argon2i_hash_raw(const uint32_t t_cost, const uint32_t m_cost,
+    #   const uint32_t parallelism, const void *pwd,
+    #   const size_t pwdlen, const void *salt,
+    #   const size_t saltlen, void *hash, const size_t hashlen);
+
+    attach_function :argon2i_hash_raw, %i[
+      uint uint uint pointer
+      size_t pointer size_t pointer size_t
+    ], :int, :blocking => true
+
+    # int argon2id_hash_raw(const uint32_t t_cost, const uint32_t m_cost,
+    #   const uint32_t parallelism, const void *pwd,
+    #   const size_t pwdlen, const void *salt,
+    #   const size_t saltlen, void *hash, const size_t hashlen)
+    attach_function :argon2id_hash_raw, %i[
+      uint uint uint pointer
+      size_t pointer size_t pointer size_t
+    ], :int, :blocking => true
+
+    # void argon2_wrap(uint8_t *out, char *pwd, size_t pwdlen,
+    # uint8_t *salt, uint32_t saltlen, uint32_t t_cost,
+    #    uint32_t m_cost, uint32_t lanes,
+    #    uint8_t *secret, uint32_t secretlen)
+    attach_function :argon2_wrap, %i[
+      pointer pointer size_t pointer uint uint
+      uint uint pointer size_t
+    ], :int, :blocking => true
+
+    # int argon2i_verify(const char *encoded, const void *pwd,
+    # const size_t pwdlen);
+    attach_function :wrap_argon2_verify, %i[pointer pointer size_t
+      pointer size_t], :int, :blocking => true
+  end
+
+  ##
+  # The engine class shields users from the FFI interface.
+  # It is generally not advised to directly use this class.
+  #
+  class Engine
+    def self.hash_argon2i(password, salt, t_cost, m_cost, out_len = nil)
+      out_len = (out_len || Constants::OUT_LEN).to_i
+      raise ::Argon2::Errors::InvalidOutputLength if out_len < 1
+
+      result = ''
+      FFI::MemoryPointer.new(:char, out_len) do |buffer|
+        ret = Ext.argon2i_hash_raw(t_cost, 1 << m_cost, 1, password,
+                                   password.length, salt, salt.length,
+                                   buffer, out_len)
+        raise ::Argon2::Errors::ExtError, ERRORS[ret.abs] unless ret.zero?
+
+        result = buffer.read_string(out_len)
+      end
+      result.unpack('H*').join
+    end
+
+    def self.hash_argon2id(password, salt, t_cost, m_cost, out_len = nil)
+      out_len = (out_len || Constants::OUT_LEN).to_i
+      raise ::Argon2::Errors::InvalidOutputLength if out_len < 1
+
+      result = ''
+      FFI::MemoryPointer.new(:char, out_len) do |buffer|
+        ret = Ext.argon2id_hash_raw(t_cost, 1 << m_cost, 1, password,
+                                    password.length, salt, salt.length,
+                                    buffer, out_len)
+        raise ::Argon2::Errors::ExtError, ERRORS[ret.abs] unless ret.zero?
+
+        result = buffer.read_string(out_len)
+      end
+      result.unpack('H*').join
+    end
+
+    def self.hash_argon2id_encode(password, salt, t_cost, m_cost, secret)
+      result = ''
+      secretlen = secret.nil? ? 0 : secret.bytesize
+      passwordlen = password.nil? ? 0 : password.bytesize
+      raise ::Argon2::Errors::InvalidSaltSize if salt.length != Constants::SALT_LEN
+
+      FFI::MemoryPointer.new(:char, Constants::ENCODE_LEN) do |buffer|
+        ret = Ext.argon2_wrap(buffer, password, passwordlen,
+                              salt, salt.length, t_cost, (1 << m_cost),
+                              1, secret, secretlen)
+        raise ::Argon2::Errors::ExtError, ERRORS[ret.abs] unless ret.zero?
+
+        result = buffer.read_string(Constants::ENCODE_LEN)
+      end
+      result.delete "\0"
+    end
+
+    def self.argon2_verify(pwd, hash, secret)
+      secretlen = secret.nil? ? 0 : secret.bytesize
+      passwordlen = pwd.nil? ? 0 : pwd.bytesize
+
+      ret = Ext.wrap_argon2_verify(hash, pwd, passwordlen, secret, secretlen)
+      return false if ERRORS[ret.abs] == 'ARGON2_DECODING_FAIL'
+      raise ::Argon2::Errors::ExtError, ERRORS[ret.abs] unless ret.zero?
+
+      true
+    end
+  end
+end

data/lib/argon2/password.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Argon2
+  ##
+  # Front-end API for the Argon2 module.
+  #
+  class Password
+    # Used as the default time cost if one isn't provided when calling
+    # Argon2::Password.create
+    DEFAULT_T_COST = 2
+    # Used to validate the minimum acceptable time cost
+    MIN_T_COST = 1
+    # Used to validate the maximum acceptable time cost
+    MAX_T_COST = 750
+    # Used as the default memory cost if one isn't provided when calling
+    # Argon2::Password.create
+    DEFAULT_M_COST = 16
+    # Used to validate the minimum acceptable memory cost
+    MIN_M_COST = 3
+    # Used to validate the maximum acceptable memory cost
+    MAX_M_COST = 31
+    # The complete Argon2 digest string (not to be confused with the checksum).
+    attr_reader :digest
+    # The hash portion of the stored password hash.
+    attr_reader :checksum
+    # The salt of the stored password hash.
+    attr_reader :salt
+    # Variant used (argon2i / argon2d / argon2id)
+    attr_reader :variant
+    # The version of the argon2 algorithm used to create the hash.
+    attr_reader :version
+    # The time cost factor used to create the hash.
+    attr_reader :t_cost
+    # The memory cost factor used to create the hash.
+    attr_reader :m_cost
+    # The parallelism cost factor used to create the hash.
+    attr_reader :p_cost
+
+    ##
+    # Class methods
+    #
+    class << self
+      ##
+      # Takes a user provided password and returns an Argon2::Password instance
+      # with the resulting Argon2 hash.
+      #
+      # Usage:
+      #
+      #    Argon2::Password.create(password)
+      #    Argon2::Password.create(password, t_cost: 4, m_cost: 20)
+      #    Argon2::Password.create(password, secret: pepper)
+      #    Argon2::Password.create(password, m_cost: 17, secret: pepper)
+      #
+      # Currently available options:
+      #
+      # * :t_cost
+      # * :m_cost
+      # * :secret
+      #
+      def create(password, options = {})
+        raise Argon2::Errors::InvalidPassword unless password.is_a?(String)
+
+        t_cost = options[:t_cost] || DEFAULT_T_COST
+        m_cost = options[:m_cost] || DEFAULT_M_COST
+
+        raise Argon2::Errors::InvalidTCost if t_cost < MIN_T_COST || t_cost > MAX_T_COST
+        raise Argon2::Errors::InvalidMCost if m_cost < MIN_M_COST || m_cost > MAX_M_COST
+
+        # TODO: Add support for changing the p_cost
+
+        salt = Engine.saltgen
+        secret = options[:secret]
+
+        Argon2::Password.new(
+          Argon2::Engine.hash_argon2id_encode(
+            password, salt, t_cost, m_cost, secret
+          )
+        )
+      end
+
+      ##
+      # Regex to validate if the provided String is a valid Argon2 hash output.
+      #
+      # Supports 1 and argon2id formats.
+      #
+      def valid_hash?(digest)
+        /^\$argon2(id?|d).{,113}/ =~ digest
+      end
+
+      ##
+      # Takes a password, Argon2 hash, and optionally a secret, then uses the
+      # Argon2 C Library to verify if they match.
+      #
+      # Also accepts passing another Argon2::Password instance as the password,
+      # in which case it will compare the final Argon2 hash for each against
+      # each other.
+      #
+      # Usage:
+      #
+      #    Argon2::Password.verify_password(password, argon2_hash)
+      #    Argon2::Password.verify_password(password, argon2_hash, secret)
+      #
+      def verify_password(password, digest, secret = nil)
+        digest = digest.to_s
+        if password.is_a?(Argon2::Password)
+          password == Argon2::Password.new(digest)
+        else
+          Argon2::Engine.argon2_verify(password, digest, secret)
+        end
+      end
+    end
+
+    ######################
+    ## Instance Methods ##
+    ######################
+
+    ##
+    # Initialize an Argon2::Password instance using any valid Argon2 digest.
+    #
+    def initialize(digest)
+      digest = digest.to_s
+
+      raise Argon2::Errors::InvalidHash unless valid_hash?(digest)
+
+      # Split the digest into its component pieces
+      split_digest = split_hash(digest)
+      # Assign each piece to the Argon2::Password instance
+      @digest   = digest
+      @variant  = split_digest[:variant]
+      @version  = split_digest[:version]
+      @t_cost   = split_digest[:t_cost]
+      @m_cost   = split_digest[:m_cost]
+      @p_cost   = split_digest[:p_cost]
+      @salt     = split_digest[:salt]
+      @checksum = split_digest[:checksum]
+    end
+
+    ##
+    # Helper function to allow easily comparing an Argon2::Password against the
+    # provided password and secret.
+    #
+    def matches?(password, secret = nil)
+      self.class.verify_password(password, digest, secret)
+    end
+
+    ##
+    # Compares two Argon2::Password instances to see if they come from the same
+    # digest/hash.
+    #
+    def ==(other)
+      # TODO: Should this return false instead of raising an error?
+      unless other.is_a?(Argon2::Password)
+        raise ArgumentError,
+              'Can only compare an Argon2::Password against another Argon2::Password'
+      end
+
+      digest == other.digest
+    end
+
+    ##
+    # Converts an Argon2::Password instance into a String.
+    #
+    def to_s
+      digest.to_s
+    end
+
+    ##
+    # Converts an Argon2::Password instance into a String.
+    #
+    def to_str
+      digest.to_str
+    end
+
+    private
+
+    ##
+    # Helper method to allow checking if a hash is valid in the initializer.
+    #
+    def valid_hash?(digest)
+      self.class.valid_hash?(digest)
+    end
+
+    # FIXME: Reduce complexity/AbcSize
+    # rubocop:disable Metrics/AbcSize
+
+    ##
+    # Helper method to extract the various values from a digest into attributes.
+    #
+    def split_hash(digest)
+      # TODO: Is there a better way to explode the digest into attributes?
+      _, variant, version, config, salt, checksum = digest.split('$')
+      # Regex magic to extract the values for each setting
+      version = /v=(\d+)/.match(version)
+      t_cost  = /t=(\d+),/.match(config)
+      m_cost  = /m=(\d+),/.match(config)
+      p_cost  = /p=(\d+)/.match(config)
+
+      # Make sure none of the values are missing
+      raise Argon2::Errors::InvalidVersion if version.nil?
+      raise Argon2::Errors::InvalidTCost   if t_cost.nil?
+      raise Argon2::Errors::InvalidMCost   if m_cost.nil?
+      raise Argon2::Errors::InvalidPCost   if p_cost.nil?
+
+      # Undo the 2^m_cost operation when encoding the hash to get the original
+      # m_cost input back.
+      m_cost = Math.log2(m_cost[1].to_i).to_i
+
+      {
+        variant: variant.to_str,
+        version: version[1].to_i,
+        t_cost: t_cost[1].to_i,
+        m_cost: m_cost,
+        p_cost: p_cost[1].to_i,
+        salt: salt.to_str,
+        checksum: checksum.to_str
+      }
+    end
+    # rubocop:enable Metrics/AbcSize
+  end
+end

data/lib/argon2/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Argon2
+  ##
+  # Standard Gem version constant.
+  #
+  VERSION = '1.0.0'
+end

data/sorcery-argon2.gemspec

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'argon2/version'
+
+version  = Argon2::VERSION
+repo_url = 'https://github.com/sorcery/argon2'
+
+Gem::Specification.new do |s|
+  s.version     = version
+  s.platform    = Gem::Platform::RUBY
+  s.name        = 'sorcery-argon2'
+  s.summary     = 'A Ruby wrapper for the Argon2 Password hashing algorithm'
+  s.description =
+    'Provides a minimal ruby wrapper for the Argon2 password hashing algorithm.'
+
+  s.required_ruby_version = '>= 2.5.0'
+
+  s.license  = 'MIT'
+  s.author   = 'Josh Buker'
+  s.email    = 'crypto@joshbuker.com'
+  s.homepage = repo_url
+  s.metadata = {
+    'bug_tracker_uri' => "#{repo_url}/issues",
+    'changelog_uri' => "#{repo_url}/releases/tag/v#{version}",
+    'documentation_uri' => 'https://rubydoc.info/gems/sorcery-argon2',
+    'source_code_uri' => "#{repo_url}/tree/v#{version}"
+  }
+
+  s.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  s.files << `find ext`.split
+
+  s.bindir        = 'exe'
+  s.executables   = s.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_dependency 'ffi',          '~> 1.14'
+  s.add_dependency 'ffi-compiler', '~> 1.0'
+
+  # Gems required for testing the wrapper locally.
+  s.add_development_dependency 'bundler',        '~> 2.0'
+  s.add_development_dependency 'minitest',       '~> 5.8'
+  s.add_development_dependency 'rake',           '~> 13.0.1'
+  s.add_development_dependency 'rubocop',        '~> 1.7'
+  s.add_development_dependency 'simplecov',      '~> 0.20'
+  s.add_development_dependency 'simplecov-lcov', '~> 0.8'
+
+  # Argon2 C Extension
+  s.extensions << 'ext/argon2_wrap/extconf.rb'
+end

metadata

@@ -0,0 +1,191 @@
+--- !ruby/object:Gem::Specification
+name: sorcery-argon2
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Josh Buker
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-04-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: ffi-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Provides a minimal ruby wrapper for the Argon2 password hashing algorithm.
+email: crypto@joshbuker.com
+executables: []
+extensions:
+- ext/argon2_wrap/extconf.rb
+extra_rdoc_files: []
+files:
+- ".document"
+- ".github/ISSUE_TEMPLATE/bug_report.md"
+- ".github/ISSUE_TEMPLATE/feature_request.md"
+- ".github/ISSUE_TEMPLATE/need_help.md"
+- ".github/PULL_REQUEST_TEMPLATE.md"
+- ".github/workflows/ruby.yml"
+- ".gitignore"
+- ".gitmodules"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.md
+- MAINTAINING.md
+- README.md
+- Rakefile
+- SECURITY.md
+- bin/console
+- bin/setup
+- bin/test
+- ext/argon2_wrap/Makefile
+- ext/argon2_wrap/argon_wrap.c
+- ext/argon2_wrap/extconf.rb
+- ext/argon2_wrap/test.c
+- lib/argon2.rb
+- lib/argon2/constants.rb
+- lib/argon2/engine.rb
+- lib/argon2/errors.rb
+- lib/argon2/ffi_engine.rb
+- lib/argon2/password.rb
+- lib/argon2/version.rb
+- sorcery-argon2.gemspec
+homepage: https://github.com/sorcery/argon2
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sorcery/argon2/issues
+  changelog_uri: https://github.com/sorcery/argon2/releases/tag/v1.0.0
+  documentation_uri: https://rubydoc.info/gems/sorcery-argon2
+  source_code_uri: https://github.com/sorcery/argon2/tree/v1.0.0
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: A Ruby wrapper for the Argon2 Password hashing algorithm
+test_files: []