Refactor Argon2::Password

.github/workflows/ruby.yml

@@ -1,21 +1,29 @@
 name: Test Suite
 
-on: push
+# Run against all commits and pull requests.
+on: [push, pull_request]
 
 jobs:
-  test:
+  test_matrix:
 
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.0', 2.7, 2.5]
+        ruby-version:
+          - 2.5
+          - 2.6
+          - 2.7
+          - 3.0
+
+    env:
+      TEST_CHECKS: 100
 
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: ${{ matrix.ruby-version }} 
+        ruby-version: ${{ matrix.ruby-version }}
     - name: Install dependencies
       run: bundle install
     - name: Init submodules
@@ -25,8 +33,37 @@ jobs:
     - name: Test C library
       run: cd ext/argon2_wrap/ && make test && cd ../..
     - name: Run tests
-      run: bundle exec rake
-    - name: Coveralls
+      run: bundle exec rake test
+    - name: Coveralls Parallel
       uses: coverallsapp/github-action@master
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
+        flag-name: run-${{ matrix.ruby-version }}
+        parallel: true
+
+  rubocop:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 3.0
+    - name: Install dependencies
+      run: bundle install
+    - name: Run rubocop
+      run: bundle exec rake rubocop
+
+  finish:
+    runs-on: ubuntu-latest
+    needs: [test_matrix, rubocop]
+    steps:
+      - name: Coveralls Finished
+        uses: coverallsapp/github-action@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          parallel-finished: true
+      - name: Wait for status checks
+        run: echo "All Green!"

Changelog.md

@@ -1,3 +1,15 @@
+# Changelog
+
+## v3.0.0: TBD
+
+**Includes multiple breaking changes, see [README.md](README.md) for migration
+instructions.**
+
+- Refactored Argon2::Password to include additional helpers and simplify hash
+  creation.
+- Renamed top level exception from: `Argon2::ArgonHashHail` to: `Argon2::Error`
+- Added new exceptions that inherit from the top level exception.
+
 ## v2.0.3: 2021-01-02
 - Address potential memory leak. Unlikely to be exploitable.
 

README.md

@@ -72,7 +72,9 @@ argon = Argon2::Password.new(t_cost: 2, m_cost: 16, secret: KEY)
 myhash = argon.create("A password")
 Argon2::Password.verify_password("A password", myhash, KEY)
 ```
+
 ## Ruby 3 Types
+
 I am now shipping signatures in sig/. The following command sets up a testing interface.
 ```sh
 RBS_TEST_TARGET="Argon2::*" bundle exec ruby -r rbs/test/setup bin/console
@@ -83,6 +85,45 @@ steep check
 ```
 These tools will need to be installed manually at this time and will be added to Gemfiles after much further testing.
 
+## Version 3.0 - Breaking API changes, addition of new helper functions
+
+### Argon2::Password API refactored
+
+**Argon2::Password.new and Argon2::Password.create are now different.**
+
+Argon2::Passwords can now be created without initializing an instance first.
+
+```ruby
+# Take instances where we abstract creating the password by first exposing an Object instance
+instance = Argon2::Password.new(m_cost: some_m_cost)
+instance.create(input_password)
+
+# And remove the abstraction step
+Argon2::Password.create(input_password, m_cost: some_m_cost)
+```
+
+### Errors restructured
+
+**The root level error for Argon2 has been renamed.**
+
+Argon2::ArgonHashFail has been renamed to Argon2::Error
+
+```ruby
+# Find any instances of Argon2::ArgonHashFail, for example...
+def login(username, password)
+  [...]
+rescue Argon2::ArgonHashFail
+  [...]
+end
+
+# And do a straight 1:1 replacement
+def login(username, password)
+  [...]
+rescue Argon2::Error
+  [...]
+end
+```
+
 ## Version 2.0 - Argon 2id
 Version 2.x upwards will now default to the Argon2id hash format. This is consistent with current recommendations regarding Argon2 usage. It remains capable of verifying existing hashes.
 

Rakefile

@@ -13,4 +13,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task :default => %i[test rubocop]

Steepfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 target :lib do
   signature "sig"
 

argon2.gemspec

@@ -16,7 +16,14 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/technion/ruby-argon2'
   spec.license       = 'MIT'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  # TODO: Remove post install message after `v3.0.0` is released.
+  spec.post_install_message =
+    'Version 3.0 of the Argon2 ruby wrapper includes breaking changes on the '\
+    'usage/generation of passwords. If you use Argon2 directly, you will need '\
+    'to follow the "migrating to v3" guide in the project README. Otherwise '\
+    'you can safely ignore this message.'
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.files << `find ext`.split
 
   spec.bindir        = "exe"

lib/argon2.rb

@@ -1,48 +1,17 @@
 # frozen_string_literal: true
 
+##
+# This Ruby Gem provides FFI bindings and a simplified interface to the Argon2
+# algorithm. Argon2 is the official winner of the Password Hashing Competition,
+# a several year project to identify a successor to bcrypt/PBKDF/scrypt methods
+# of securely storing passwords. This is an independent project and not official
+# from the PHC team.
+#
+module Argon2; end
+
 require 'argon2/constants'
 require 'argon2/ffi_engine'
 require 'argon2/version'
 require 'argon2/errors'
 require 'argon2/engine'
-
-module Argon2
-  # Front-end API for the Argon2 module.
-  class Password
-    def initialize(options = {})
-      @t_cost = options[:t_cost] || 2
-      raise ArgonHashFail, "Invalid t_cost" if @t_cost < 1 || @t_cost > 750
-
-      @m_cost = options[:m_cost] || 16
-      raise ArgonHashFail, "Invalid m_cost" if @m_cost < 1 || @m_cost > 31
-
-      @salt = options[:salt_do_not_supply] || Engine.saltgen
-      @secret = options[:secret]
-    end
-
-    def create(pass)
-      raise ArgonHashFail, "Invalid password (expected string)" unless
-        pass.is_a?(String)
-
-      Argon2::Engine.hash_argon2id_encode(
-        pass, @salt, @t_cost, @m_cost, @secret)
-    end
-
-    # Helper class, just creates defaults and calls hash()
-    def self.create(pass)
-      argon2 = Argon2::Password.new
-      argon2.create(pass)
-    end
-
-    # Supports 1 and argon2id formats.
-    def self.valid_hash?(hash)
-      /^\$argon2(id?|d).{,113}/ =~ hash
-    end
-
-    def self.verify_password(pass, hash, secret = nil)
-      raise ArgonHashFail, "Invalid hash" unless valid_hash?(hash)
-
-      Argon2::Engine.argon2_verify(pass, hash, secret)
-    end
-  end
-end
+require 'argon2/password'

lib/argon2/constants.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Argon2
+  ##
   # Constants utilised in several parts of the Argon2 module
-  # SALT_LEN is a standard recommendation from the Argon2 spec.
-
+  #
   module Constants
-    SALT_LEN = 16
-    OUT_LEN = 32 # Binary, unencoded output
+    SALT_LEN   = 16  # Standard recommendation from the Argon2 spec
+    OUT_LEN    = 32  # Binary, unencoded output
     ENCODE_LEN = 108 # Encoded output
   end
 end

lib/argon2/engine.rb

@@ -3,8 +3,14 @@
 require 'securerandom'
 
 module Argon2
-  # Generates a random, binary string for use as a salt.
+  ##
+  # The engine class shields users from the FFI interface.
+  # It is generally not advised to directly use this class.
+  #
   class Engine
+    ##
+    # Generates a random, binary string for use as a salt.
+    #
     def self.saltgen
       SecureRandom.random_bytes(Argon2::Constants::SALT_LEN)
     end

lib/argon2/errors.rb

@@ -1,10 +1,87 @@
 # frozen_string_literal: true
 
-# Defines an array of errors that matches the enum list of errors from
-# argon2.h. This allows return values to propagate errors through the FFI.
-
 module Argon2
-  class ArgonHashFail < StandardError; end
+  ##
+  # Generic error to catch anything the Argon2 ruby library throws.
+  #
+  class Error < StandardError; end
+
+  ##
+  # Various errors for invalid parameters passed to the library.
+  #
+  module Errors
+    ##
+    # Raised when an invalid Argon2 hash has been passed to Argon2::Password.new
+    #
+    class InvalidHash < Argon2::Error; end
+
+    ##
+    # Raised when a valid Argon2 hash was passed to Argon2::Password, but the
+    # version information is missing or corrupted.
+    #
+    class InvalidVersion < InvalidHash; end
+
+    ##
+    # Abstract error class that isn't raised directly, but allows you to catch
+    # any cost error, regardless of which value was invalid.
+    #
+    class InvalidCost < InvalidHash; end
+
+    ##
+    # Raised when an invalid time cost has been passed to
+    # Argon2::Password.create, or the hash passed to Argon2::Password.new
+    # was valid but the time cost information is missing or corrupted.
+    #
+    class InvalidTCost < InvalidCost; end
+
+    ##
+    # Raised when an invalid memory cost has been passed to
+    # Argon2::Password.create, or the hash passed to Argon2::Password.new
+    # was valid but the memory cost information is missing or corrupted.
+    #
+    class InvalidMCost < InvalidCost; end
+
+    ##
+    # Raised when an invalid parallelism cost has been passed to
+    # Argon2::Password.create, or the hash passed to Argon2::Password.new
+    # was valid but the parallelism cost information is missing or corrupted.
+    #
+    class InvalidPCost < InvalidCost; end
+
+    ##
+    # Raised when a non-string object is passed to Argon2::Password.create
+    #
+    class InvalidPassword < Argon2::Error
+      def initialize(msg = "Invalid password (expected a String)")
+        super
+      end
+    end
+
+    ##
+    # Raised when an invalid salt length was passed to
+    # Argon2::Engine.hash_argon2id_encode
+    #
+    class InvalidSaltSize < Argon2::Error; end
+
+    ##
+    # Raised when the output length passed to Argon2::Engine.hash_argon2i or
+    # Argon2::Engine.hash_argon2id is invalid.
+    #
+    class InvalidOutputLength < Argon2::Error; end
+
+    ##
+    # Error raised by/caught from the Argon2 C Library.
+    #
+    # See Argon2::ERRORS for a full list of related error codes.
+    #
+    class ExtError < Argon2::Error; end
+  end
+
+  ##
+  # Defines an array of errors that matches the enum list of errors from
+  # argon2.h. This allows return values to propagate errors through the FFI. Any
+  # error from this list will be thrown as an Argon2::Errors::ExtError
+  #
   ERRORS = %w[
     ARGON2_OK
     ARGON2_OUTPUT_PTR_NULL
@@ -40,5 +117,5 @@ class ArgonHashFail < StandardError; end
     ARGON2_ENCODING_FAIL
     ARGON2_DECODING_FAIL
     ARGON2_THREAD_FAIL
-    ].freeze
+  ].freeze
 end