argon2 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f926025634562667dbc1575383b09a6d3178248f1551325726f1dc194472b0e5
-  data.tar.gz: a4876cbbaf99df1062ac39f668e3af254c5b45b1d431bf5e7180e3076fd20d3d
+  metadata.gz: 77cb6034627eab11765cd70555304c694e3f3f20febe4fed4fa986f7c77bc8b1
+  data.tar.gz: 80f8821f1a3f14f45947644f7e2c538ce3287c2c42a32f6d62f12b34c9e16d9c
 SHA512:
-  metadata.gz: e5c592dc870390af4ad6fbce1ea4b3b4b5be6fa25574f18ac44d0509dab1adef3bb21e1e1c5a84b01d364e335f4b4b01460a0a4207c96734ae67f0b4ff12289a
-  data.tar.gz: c59f5baeea0c7ff436f77a4dadc267c5619ceccf2749ee25a428173abbf4842606a48bbd90f74a89cbd6347cc31dc643447b926cb6caccdcbcf04d7eabfb19a8
+  metadata.gz: 72fa1e22c23e7c7e47fd03270a90af60e95d7891493d877eb961c6b4087999557ca2accb9b5ed1a7bc94fd2e5f05d98688360f941069a946f37bf20f1b0c9506
+  data.tar.gz: dfff839d55b2f7ca06183d1cd6006aa45a79bf249081f039cdd486d53100dc2ea293f789d9a8ffa87aa69fb6d2d4413c35c296e214fb527ee172789d5f7b74cb

data/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.
@@ -81,6 +105,9 @@ steep check
 ```
 These tools will need to be installed manually at this time and will be added to Gemfiles after much further testing.
 
+## Version 2.2.0
+This version changed the way the build system works to deal with a new version of Rubygems. See https://github.com/technion/ruby-argon2/issues/56.
+
 ## 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.
 

data/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

data/lib/argon2/version.rb

@@ -3,5 +3,5 @@
 # Standard Gem version constant.
 
 module Argon2
-  VERSION = "2.2.0"
+  VERSION = "2.3.0"
 end

data/lib/argon2.rb

@@ -6,19 +6,26 @@ require 'argon2/version'
 require 'argon2/errors'
 require 'argon2/engine'
 require 'argon2/hash_format'
+require 'argon2/profiles'
 
 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
+    # Expose constants for the options supported and default used for passwords.
+    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
+    MAX_M_COST = 31
+    MIN_P_COST = 1
+    MAX_P_COST = 8
 
-      @m_cost = options[:m_cost] || 16
-      raise ArgonHashFail, "Invalid m_cost" if @m_cost < 1 || @m_cost > 31
+    def initialize(options = {})
+      options.update(Profiles[options[:profile]]) if options.key?(:profile)
 
-      @p_cost = options[:p_cost] || 1
-      raise ArgonHashFail, "Invalid p_cost" if @p_cost < 1 || @p_cost > 8
+      init_costs(options)
 
       @salt_do_not_supply = options[:salt_do_not_supply]
       @secret = options[:secret]
@@ -50,5 +57,18 @@ module Argon2
 
       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

data/sig/argon2.rbs

@@ -1,21 +1,41 @@
-# Classes
 module Argon2
+  # Front-end API for the Argon2 module.
   class Password
     @t_cost: Integer
     @m_cost: Integer
     @p_cost: Integer
     @salt: nil | String
     @secret: nil | String
+    @salt_do_not_supply: nil | String
+
+    # Expose constants for the options supported and default used for passwords.
+    DEFAULT_T_COST: 2
+
+    DEFAULT_M_COST: 16
+
+    DEFAULT_P_COST: 1
+
+    MIN_T_COST: 1
+
+    MAX_T_COST: 750
+
+    MIN_M_COST: 1
+
+    MAX_M_COST: 31
+
+    MIN_P_COST: 1
+
+    MAX_P_COST: 8
 
     def initialize: (?::Hash[untyped, untyped] options) -> void
+
     def create: (String pass) -> untyped
-    def self.create: (String pass) -> untyped
-    def self.valid_hash?: (string hash) -> Integer?
-    def self.verify_password: (untyped pass, untyped hash, ?nil secret) -> untyped
-  end
-  class Engine
-    def self.saltgen: () -> String
-  end
-  class ArgonHashFail < StandardError
+
+    # Helper class, just creates defaults and calls hash()
+    def self.create: (String pass, ?::Hash[untyped, untyped] options) -> String
+
+    def self.valid_hash?: (String hash) -> bool
+
+    def self.verify_password: (String pass, String hash, ?String|nil secret) -> bool
   end
 end

data/sig/engine.rbs

@@ -0,0 +1,9 @@
+module Argon2
+  # SecureRandom is a Ruby module. I have no idea why steep now thinks it's an unknown constant, nor why rbs
+  # prototype has no interest in outputting this.
+  SecureRandom: untyped
+  # Generates a random, binary string for use as a salt.
+  class Engine
+    def self.saltgen: () -> untyped
+  end
+end

data/sig/errors.rbs

@@ -0,0 +1,6 @@
+module Argon2
+  class ArgonHashFail < StandardError
+  end
+
+  ERRORS: ::Array["ARGON2_OK" | "ARGON2_OUTPUT_PTR_NULL" | "ARGON2_OUTPUT_TOO_SHORT" | "ARGON2_OUTPUT_TOO_LONG" | "ARGON2_PWD_TOO_SHORT" | "ARGON2_PWD_TOO_LONG" | "ARGON2_SALT_TOO_SHORT" | "ARGON2_SALT_TOO_LONG" | "ARGON2_AD_TOO_SHORT" | "ARGON2_AD_TOO_LONG" | "ARGON2_SECRET_TOO_SHORT" | "ARGON2_SECRET_TOO_LONG" | "ARGON2_TIME_TOO_SMALL" | "ARGON2_TIME_TOO_LARGE" | "ARGON2_MEMORY_TOO_LITTLE" | "ARGON2_MEMORY_TOO_MUCH" | "ARGON2_LANES_TOO_FEW" | "ARGON2_LANES_TOO_MANY" | "ARGON2_PWD_PTR_MISMATCH" | "ARGON2_SALT_PTR_MISMATCH" | "ARGON2_SECRET_PTR_MISMATCH" | "ARGON2_AD_PTR_MISMATCH" | "ARGON2_MEMORY_ALLOCATION_ERROR" | "ARGON2_FREE_MEMORY_CBK_NULL" | "ARGON2_ALLOCATE_MEMORY_CBK_NULL" | "ARGON2_INCORRECT_PARAMETER" | "ARGON2_INCORRECT_TYPE" | "ARGON2_OUT_PTR_MISMATCH" | "ARGON2_THREADS_TOO_FEW" | "ARGON2_THREADS_TOO_MANY" | "ARGON2_MISSING_ARGS" | "ARGON2_ENCODING_FAIL" | "ARGON2_DECODING_FAIL" | "ARGON2_THREAD_FAIL"]
+end

data/sig/ffi.rbs

@@ -1,8 +1,8 @@
 module Argon2
   # Direct external bindings. Call these methods via the Engine class to ensure points are dealt with
-  module Ext
-    extend FFI::Library
-  end
+#  module Ext
+#    extend FFI::Library
+#  end
 
   # The engine class shields users from the FFI interface.
   # It is generally not advised to directly use this class.

data/sig/hash_format.rbs

@@ -0,0 +1,31 @@
+module Argon2
+  #
+  # Get the values from an Argon2 compatible string.
+  #
+  class HashFormat
+    attr_reader variant: untyped
+
+    attr_reader version: untyped
+
+    attr_reader t_cost: untyped
+
+    attr_reader m_cost: untyped
+
+    attr_reader p_cost: untyped
+
+    attr_reader salt: untyped
+
+    attr_reader checksum: untyped
+
+    # FIXME: Reduce complexity/AbcSize
+    # rubocop:disable Metrics/AbcSize
+    def initialize: (untyped digest) -> void
+
+    #
+    # Checks whether a given digest is a valid Argon2 hash.
+    #
+    # Supports 1 and argon2id formats.
+    #
+    def self.valid_hash?: (untyped digest) -> untyped
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: argon2
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Technion
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-27 00:00:00.000000000 Z
+date: 2023-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -250,17 +250,21 @@ files:
 - lib/argon2/errors.rb
 - lib/argon2/ffi_engine.rb
 - lib/argon2/hash_format.rb
+- lib/argon2/profiles.rb
 - lib/argon2/version.rb
 - sig/argon2.rbs
 - sig/constants.rbs
+- sig/engine.rbs
+- sig/errors.rbs
 - sig/ffi.rbs
+- sig/hash_format.rbs
 - sig/version.rbs
 homepage: https://github.com/technion/ruby-argon2
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -275,8 +279,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.5
-signing_key: 
+rubygems_version: 3.3.15
+signing_key:
 specification_version: 4
 summary: Argon2 Password hashing binding
 test_files: []