Make default costs RFC 9106's second preferred option; introduce named cost profiles (#62)

* Make default costs RFC 9106's second preferred option

RFC 9106 is the formal standard for describing Argon2. It also gives the official recommended cost parameters that should be sufficient for all environments. This commit introduces the concept of named profiles for a set of cost parameters/values and changes the default costs to `:rfc_9106_low_memory`, the second preferred option in the RFC. The RFC's first choice can be quite computationally expensive and, mirroring Python's `argon2-cffi`, we leave that as an opt-in choice.

A developer can use one of the named profiles, or continue to hand specify costs:

```ruby
hasher = Argon2::Password.new(profile: :rfc_9106_high_memory)
hasher.create("password")
    => "$argon2id$v=19$m=2097152,t=1,p=4$LvHa74Yax7uCWPN7P6/oQQ$V1dMt4dfuYSmLpwUTpKUzg+RrXjWzWHlE6NLowBzsAg"

hasher = Argon2::Password.new(t_cost: 2, m_cost: 16, p_cost: 1)
hasher.create("password")
    => "$argon2i$v=19$m=65536,t=2,p=1$jL7lLEAjDN+pY2cG1N8D2g$iwj1ueduCvm6B9YVjBSnAHu+6mKzqGmDW745ALR38Uo"
```

The list of named cost profiles are:

* `:rfc_9106_high_memory`: the first recommended option but is expensive
* `:rfc_9106_low_memory`: the second recommended option (default)
* `:pre_rfc_9106`: the previous default costs for `ruby-argon2` <= v2.2.0, before offering RFC 9106 named profiles
* `:unsafe_cheapest`: Strictly for testing, the minimum costs allowed by Argon2 for the fastest hashing speed

A developer can see the list of profiles with `Argon2::Profiles.to_a` and the actual cost values with `.to_h` or `[name]`. As guidance changes over time (OWASP has its own recommended values), the list of profiles may expand or even change their values.

* Satisfy rubocop

Author: f3ndot

README.md

@@ -27,26 +27,50 @@ Require this in your Gemfile like a typical Ruby gem:
 require 'argon2'
 ```
 
-To generate a hash using specific time and memory cost:
+To utilise default costs ([RFC 9106](https://www.rfc-editor.org/rfc/rfc9106#name-parameter-choice)'s lower-memory, second recommended parameters):
 
 ```ruby
-hasher = Argon2::Password.new(t_cost: 2, m_cost: 16, p_cost: 1)
+hasher = Argon2::Password.new
 hasher.create("password")
-    => "$argon2i$v=19$m=65536,t=2,p=1$jL7lLEAjDN+pY2cG1N8D2g$iwj1ueduCvm6B9YVjBSnAHu+6mKzqGmDW745ALR38Uo"
 ```
 
-To utilise default costs:
+Alternatively, use this shortcut:
 
 ```ruby
-hasher = Argon2::Password.new
+Argon2::Password.create("password")
+    => "$argon2i$v=19$m=65536,t=2,p=1$61qkSyYNbUgf3kZH3GtHRw$4CQff9AZ0lWd7uF24RKMzqEiGpzhte1Hp8SO7X8bAew"
+```
+
+If your use case can afford the higher memory consumption/cost, you can/should specify to use RFC 9106's first recommended parameters:
+
+```ruby
+hasher = Argon2::Password.new(profile: :rfc_9106_high_memory)
 hasher.create("password")
+    => "$argon2id$v=19$m=2097152,t=1,p=4$LvHa74Yax7uCWPN7P6/oQQ$V1dMt4dfuYSmLpwUTpKUzg+RrXjWzWHlE6NLowBzsAg"
 ```
 
-Alternatively, use this shortcut:
+To generate a hash using one of the other `Argon::Profiles` names:
 
 ```ruby
-Argon2::Password.create("password")
-    => "$argon2i$v=19$m=65536,t=2,p=1$61qkSyYNbUgf3kZH3GtHRw$4CQff9AZ0lWd7uF24RKMzqEiGpzhte1Hp8SO7X8bAew"
+# Only use this profile in testing env, it's unsafe!
+hasher = Argon2::Password.new(profile: :unsafe_cheapest)
+hasher.create("password")
+    => "$argon2id$v=19$m=8,t=1,p=1$HZZHG3oTqptqgrxWxFic5g$EUokHMU6m6w2AVIEk1MpZBhVwW9Nj+ESRjPwTBVtWpY"
+```
+
+The list of named cost profiles are:
+
+* `:rfc_9106_high_memory`: the first recommended option but is expensive
+* `:rfc_9106_low_memory`: the second recommended option (default)
+* `:pre_rfc_9106`: the previous default costs for `ruby-argon2` <= v2.2.0, before offering RFC 9106 named profiles
+* `:unsafe_cheapest`: Strictly for testing, the minimum costs allowed by Argon2 for the fastest hashing speed
+
+To generate a hash using specific time and memory cost:
+
+```ruby
+hasher = Argon2::Password.new(t_cost: 2, m_cost: 16, p_cost: 1)
+hasher.create("password")
+    => "$argon2i$v=19$m=65536,t=2,p=1$jL7lLEAjDN+pY2cG1N8D2g$iwj1ueduCvm6B9YVjBSnAHu+6mKzqGmDW745ALR38Uo"
 ```
 
 You can then use this function to verify a password against a given hash. Will return either true or false.

lib/argon2.rb

@@ -6,14 +6,15 @@
 require 'argon2/errors'
 require 'argon2/engine'
 require 'argon2/hash_format'
+require 'argon2/profiles'
 
 module Argon2
   # Front-end API for the Argon2 module.
   class Password
     # Expose constants for the options supported and default used for passwords.
-    DEFAULT_T_COST = 2
-    DEFAULT_M_COST = 16
-    DEFAULT_P_COST = 1
+    DEFAULT_T_COST = Argon2::Profiles::RFC_9106_LOW_MEMORY[:t_cost]
+    DEFAULT_M_COST = Argon2::Profiles::RFC_9106_LOW_MEMORY[:m_cost]
+    DEFAULT_P_COST = Argon2::Profiles::RFC_9106_LOW_MEMORY[:p_cost]
     MIN_T_COST = 1
     MAX_T_COST = 750
     MIN_M_COST = 3
@@ -22,14 +23,9 @@ class Password
     MAX_P_COST = 8
 
     def initialize(options = {})
-      @t_cost = options[:t_cost] || DEFAULT_T_COST
-      raise ArgonHashFail, "Invalid t_cost" if @t_cost < MIN_T_COST || @t_cost > MAX_T_COST
+      options.update(Profiles[options[:profile]]) if options.key?(:profile)
 
-      @m_cost = options[:m_cost] || DEFAULT_M_COST
-      raise ArgonHashFail, "Invalid m_cost" if @m_cost < MIN_M_COST || @m_cost > MAX_M_COST
-
-      @p_cost = options[:p_cost] || DEFAULT_P_COST
-      raise ArgonHashFail, "Invalid p_cost" if @p_cost < MIN_P_COST || @p_cost > MAX_P_COST
+      init_costs(options)
 
       @salt_do_not_supply = options[:salt_do_not_supply]
       @secret = options[:secret]
@@ -61,5 +57,18 @@ def self.verify_password(pass, hash, secret = nil)
 
       Argon2::Engine.argon2_verify(pass, hash, secret)
     end
+
+    protected
+
+    def init_costs(options = {})
+      @t_cost = options[:t_cost] || DEFAULT_T_COST
+      raise ArgonHashFail, "Invalid t_cost" if @t_cost < MIN_T_COST || @t_cost > MAX_T_COST
+
+      @m_cost = options[:m_cost] || DEFAULT_M_COST
+      raise ArgonHashFail, "Invalid m_cost" if @m_cost < MIN_M_COST || @m_cost > MAX_M_COST
+
+      @p_cost = options[:p_cost] || DEFAULT_P_COST
+      raise ArgonHashFail, "Invalid p_cost" if @p_cost < MIN_P_COST || @p_cost > MAX_P_COST
+    end
   end
 end

lib/argon2/profiles.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Argon2
+  # Contains named profiles of different common cost parameter sets
+  class Profiles
+    def self.[](name)
+      name = name.upcase.to_sym
+      raise NotImplementedError unless const_defined?(name)
+
+      const_get(name)
+    end
+
+    def self.to_a
+      constants.map(&:downcase)
+    end
+
+    def self.to_h
+      to_a.reduce({}) { |h, name| h.update(name => self[name]) }
+    end
+
+    # https://datatracker.ietf.org/doc/html/rfc9106#name-argon2-algorithm
+    # FIRST RECOMMENDED option per RFC 9106.
+    RFC_9106_HIGH_MEMORY = {
+      t_cost: 1,
+      m_cost: 21, # 2 GiB
+      p_cost: 4
+    }.freeze
+
+    # SECOND RECOMMENDED option per RFC 9106.
+    RFC_9106_LOW_MEMORY = {
+      t_cost: 3,
+      m_cost: 16, # 64 MiB
+      p_cost: 4
+    }.freeze
+
+    # The default values ruby-argon2 had before using RFC 9106 recommendations
+    PRE_RFC_9106 = {
+      t_cost: 2,
+      m_cost: 16, # 64 MiB
+      p_cost: 1
+    }.freeze
+
+    # Only use for fast testing. Insecure otherwise!
+    UNSAFE_CHEAPEST = {
+      t_cost: 1,
+      m_cost: 3, # 8 KiB
+      p_cost: 1
+    }.freeze
+  end
+end

test/api_test.rb

@@ -14,8 +14,8 @@ def test_create_default
     assert pass = Argon2::Password.new
     assert_instance_of Argon2::Password, pass
     assert_equal 16, pass.m_cost
-    assert_equal 2, pass.t_cost
-    assert_equal 1, pass.p_cost
+    assert_equal 3, pass.t_cost
+    assert_equal 4, pass.p_cost
     assert_nil pass.secret
   end
 
@@ -28,6 +28,15 @@ def test_create_args
     assert_nil pass.secret
   end
 
+  def test_create_profile_arg
+    assert pass = Argon2::Password.new(profile: :rfc_9106_high_memory)
+    assert_instance_of Argon2::Password, pass
+    assert_equal 21, pass.m_cost
+    assert_equal 1, pass.t_cost
+    assert_equal 4, pass.p_cost
+    assert_nil pass.secret
+  end
+
   def test_secret
     assert pass = Argon2::Password.new(secret: "A secret")
     assert_equal pass.secret, "A secret"

test/profiles_test.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class ProfilesTest < Minitest::Test
+  def test_hash_access
+    assert_equal Argon2::Profiles::RFC_9106_LOW_MEMORY, Argon2::Profiles[:RFC_9106_LOW_MEMORY]
+  end
+
+  def test_to_a
+    # rubocop:disable Naming/VariableNumber
+    assert_equal %i[
+      pre_rfc_9106
+      rfc_9106_high_memory
+      rfc_9106_low_memory
+      unsafe_cheapest
+    ], Argon2::Profiles.to_a.sort
+    # rubocop:enable Naming/VariableNumber
+  end
+
+  def test_to_h
+    hash = Argon2::Profiles.to_h
+    assert_equal Argon2::Profiles::RFC_9106_HIGH_MEMORY, hash[:rfc_9106_high_memory]
+  end
+
+  def test_structure
+    Argon2::Profiles.to_h.values do |profile|
+      assert_equal %i[t_cost m_cost p_cost], profile.keys
+      assert(profile.values.all? { |v| v.instance_of?(Integer) })
+    end
+  end
+end