argon2id 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4db6c17aba7494ec3513051e649f3ceda78b2da64a0fd1b326cf4d1d87c157c3
-  data.tar.gz: 20128abfe853bf2cd2013b2ac366a7a5220025ed8c222d65c4ccbdff99cbdbfd
+  metadata.gz: 37869678ea2afe9b0cd0ae0aa40d74dc697413d1184782bb9cce45e09c1bcba0
+  data.tar.gz: '095f548a9967a7f228d03893530314731e18a1796a4eadc58fae1147f4450df5'
 SHA512:
-  metadata.gz: 29a68d9fc61f3effd8eb6fcb017e13a02cd7e4a24b529059694b682ab452a0184fb63ad437dc406a75fd8f75e0759e683af5bb409d52abcfe43cc3aa578cf3de
-  data.tar.gz: 8b5a8fbc302163efa94e344ae1bcf4c523a84d487402b98f4e80881dc2eec4d485551e18c8f249e5b515fd797fb826ed6d580f2c5289d6663f2648b12d96fac5
+  metadata.gz: 0ed644a214ce98c680ff9ab5e6cb423e683f318bfd191d94711139494483a07b6496c064cda803fd8819858aeceabaa67464dcc6afd23b07ac1a9ecce690c070
+  data.tar.gz: 10cdce7ed52f9d9774b1b4846b100a03797913351a16eba1fa2fce251c901a38787f4a4adf00899e5282e90e0e2c9fed524958a43006bb39a29e7c88d15dce29

data/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2024-11-01
+
+### Added
+
+- Expose all parameters of a hash through new readers on `Argon2id::Password`:
+  namely, `type`, `version`, `m_cost`, `t_cost`, and `parallelism`
+
+### Changed
+
+- Remove the dependency on the `base64` gem by inlining the definition of
+  `Base64.decode64` (thanks to @etiennebarrie for the tip)
+
 ## [0.2.1] - 2024-11-01
 
 ### Added
@@ -51,6 +63,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   reference C implementation of Argon2, the password-hashing function that won
   the Password Hashing Competition.
 
+[0.3.0]: https://github.com/mudge/argon2id/releases/tag/v0.3.0
 [0.2.1]: https://github.com/mudge/argon2id/releases/tag/v0.2.1
 [0.2.0]: https://github.com/mudge/argon2id/releases/tag/v0.2.0
 [0.1.2]: https://github.com/mudge/argon2id/releases/tag/v0.1.2

data/README.md

@@ -5,18 +5,19 @@ function that won the 2015 [Password Hashing Competition][].
 
 [![Build Status](https://github.com/mudge/argon2id/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/mudge/argon2id/actions)
 
-**Current version:** 0.2.1  
+**Current version:** 0.3.0  
 **Bundled Argon2 version:** libargon2.1 (20190702)
 
 ```ruby
-Argon2id::Password.create("opensesame").to_s
-#=> "$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU"
+Argon2id::Password.create("password").to_s
+#=> "$argon2id$v=19$m=19456,t=2,p=1$agNV6OfDL1OwE44WdrFCJw$ITrBwvCsW4b5GjgZuL67RCcvVMEWBWXtASc9TVyI3rY"
 
-Argon2id::Password.create("opensesame") == "opensesame"
-#=> true
+password = Argon2id::Password.new("$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU")
+password == "password"      #=> true
+password == "not password" #=> false
 
-Argon2id::Password.new("$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU") == "opensesame"
-#=> true
+password.m_cost #=> 19456
+password.salt   #=> "e-\xA7\x04U\x81\xA6{v\xF0x\xED\xCC\xD3\x96\xE3"
 ```
 
 ## Table of contents
@@ -142,12 +143,16 @@ password.is_password?("opensesame")    #=> true
 password.is_password?("notopensesame") #=> false
 ```
 
-The original salt for a password can be retrieved with `Argon2id::Password#salt`:
+The various parameters for the password can be retrieved:
 
 ```ruby
 password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
-password.salt
-#=> "somesalt"
+password.type        #=> "argon2id"
+password.version     #=> 19
+password.m_cost      #=> 256
+password.t_cost      #=> 2
+password.parallelism #=> 1
+password.salt        #=> "somesalt"
 ```
 
 ### Errors
@@ -155,9 +160,8 @@ password.salt
 Any errors returned from Argon2 will be raised as `Argon2id::Error`, e.g.
 
 ```ruby
-password = Argon2id::Password.new("not a valid hash encoding")
-password == "opensesame"
-# Decoding failed (Argon2id::Error)
+Argon2id::Password.create("password", salt_len: 0)
+# Salt is too short (Argon2id::Error)
 ```
 
 ## Requirements
@@ -184,11 +188,11 @@ notes](https://github.com/mudge/argon2id/releases) for each version and can be
 checked with `sha256sum`, e.g.
 
 ```console
-$ gem fetch argon2id -v 0.2.0
-Fetching argon2id-0.2.0-arm64-darwin.gem
-Downloaded argon2id-0.2.0-arm64-darwin
-$ sha256sum argon2id-0.2.0-arm64-darwin.gem
-ce1fa632393e814da750f44146dc6de1353e4b24746fb94f6f4ea748b9dad26b  argon2id-0.2.0-arm64-darwin.gem
+$ gem fetch argon2id -v 0.2.1
+Fetching argon2id-0.2.1-arm64-darwin.gem
+Downloaded argon2id-0.2.1-arm64-darwin
+$ sha256sum argon2id-0.2.1-arm64-darwin.gem
+aea93700e989e421dd4e66b99038b9fec1acc9a265fe9d35e2100ceb5c18e5a9  argon2id-0.2.1-arm64-darwin.gem
 ```
 
 [GPG](https://www.gnupg.org/) signatures are attached to each release (the
@@ -198,8 +202,8 @@ from a public keyserver, e.g. `gpg --keyserver keyserver.ubuntu.com --recv-key
 0x39AC3530070E0F75`):
 
 ```console
-$ gpg --verify argon2id-0.2.0-arm64-darwin.gem.sig argon2id-0.2.0-arm64-darwin.gem
-gpg: Signature made Fri  1 Nov 14:48:57 2024 GMT
+$ gpg --verify argon2id-0.2.1-arm64-darwin.gem.sig argon2id-0.2.1-arm64-darwin.gem
+gpg: Signature made Fri  1 Nov 15:06:30 2024 GMT
 gpg:                using RSA key 702609D9C790F45B577D7BEC39AC3530070E0F75
 gpg: Good signature from "Paul Mucur <mudge@mudge.name>" [unknown]
 gpg:                 aka "Paul Mucur <paul@ghostcassette.com>" [unknown]

data/argon2id.gemspec

@@ -53,7 +53,6 @@ Gem::Specification.new do |s|
   ]
   s.rdoc_options = ["--main", "README.md"]
 
-  s.add_runtime_dependency("base64")
   s.add_development_dependency("rake-compiler", "~> 1.2")
   s.add_development_dependency("rake-compiler-dock", "~> 1.5")
   s.add_development_dependency("minitest", "~> 5.25")

data/lib/argon2id/password.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "base64"
 require "openssl"
 
 module Argon2id
@@ -12,23 +11,38 @@ module Argon2id
   #   password.to_s
   #   #=> "$argon2id$v=19$m=19456,t=2,p=1$+Lrjry9Ifq0poLr15OGU1Q$utkDvejJB0ugwm4s9+a+vF6+1a/W+Y3CYa5Wte/85ig"
   #
-  # To verify an encoded Argon2id password hash, use Argon2id::Password.new:
+  # To wrap an encoded Argon2id password hash, use Argon2id::Password.new:
   #
-  #   password = Argon2id::Password.new("$argon2id$v=19$m=19456,t=2,p=1$+Lrjry9Ifq0poLr15OGU1Q$utkDvejJB0ugwm4s9+a+vF6+1a/W+Y3CYa5Wte/85ig")
-  #   password == "password"
-  #   #=> true
+  #   password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+  #
+  # You can then verify it matches a given plain text:
+  #
+  #   password == "password"     #=> true
+  #   password == "not password" #=> false
+  #
+  #   password.is_password?("password")     #=> true
+  #   password.is_password?("not password") #=> false
+  #
+  # You can read various parameters out of a password hash:
+  #
+  #   password.type        #=> "argon2id"
+  #   password.version     #=> 19
+  #   password.m_cost      #=> 19456
+  #   password.t_cost      #=> 2
+  #   password.parallelism #=> 1
+  #   password.salt        #=>  "somesalt"
   class Password
     # A regular expression to match valid hashes.
     PATTERN = %r{
       \A
       \$
-      argon2(?:id|i|d)
-      (?:\$v=\d+)?
-      \$m=\d+
-      ,t=\d+
-      ,p=\d+
+      (argon2(?:id|i|d))
+      (?:\$v=(\d+))?
+      \$m=(\d+)
+      ,t=(\d+)
+      ,p=(\d+)
       \$
-      (?<base64_salt>[a-zA-Z0-9+/]+)
+      ([a-zA-Z0-9+/]+)
       \$
       [a-zA-Z0-9+/]+
       \z
@@ -37,6 +51,21 @@ module Argon2id
     # The encoded password hash.
     attr_reader :encoded
 
+    # The type of the hashing function.
+    attr_reader :type
+
+    # The version number of the hashing function.
+    attr_reader :version
+
+    # The "time cost" of the hashing function.
+    attr_reader :t_cost
+
+    # The "memory cost" of the hashing function.
+    attr_reader :m_cost
+
+    # The number of threads and compute lanes of the hashing function.
+    attr_reader :parallelism
+
     # The salt.
     attr_reader :salt
 
@@ -82,17 +111,20 @@ module Argon2id
     def initialize(encoded)
       raise ArgumentError, "invalid hash" unless PATTERN =~ String(encoded)
 
-      @encoded = Regexp.last_match(0)
-      @salt = Base64.decode64(Regexp.last_match(1))
+      @encoded = $&
+      @type = $1
+      @version = ($2 || 0x10).to_i
+      @m_cost = $3.to_i
+      @t_cost = $4.to_i
+      @parallelism = $5.to_i
+      @salt = $6.unpack1("m")
     end
 
     # Return the encoded password hash.
-    def to_s
-      encoded
-    end
+    alias_method :to_s, :encoded
 
-    # Compare the password with given plain text, returning true if it verifies
-    # successfully.
+    # Compare the password with the given plain text, returning true if it
+    # verifies successfully.
     #
     #   password = Argon2id::Password.new("$argon2id$v=19$m=19456,t=2,p=1$FI8yp1gXbthJCskBlpKPoQ$nOfCCpS2r+I8GRN71cZND4cskn7YKBNzuHUEO3YpY2s")
     #   password == "password"    #=> true

data/lib/argon2id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Argon2id
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/test/test_password.rb

@@ -109,4 +109,64 @@ class TestPassword < Minitest::Test
 
     assert Argon2id::Password.new(password) == "password"
   end
+
+  def test_extracting_type_from_hash
+    password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal "argon2id", password.type
+  end
+
+  def test_extracting_type_from_argoni_hash
+    password = Argon2id::Password.new("$argon2i$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal "argon2i", password.type
+  end
+
+  def test_extracting_version_from_hash
+    password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal 19, password.version
+  end
+
+  def test_extracting_version_from_versionless_hash
+    password = Argon2id::Password.new("$argon2id$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal 16, password.version
+  end
+
+  def test_extracting_time_cost_from_hash
+    password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal 2, password.t_cost
+  end
+
+  def test_extracting_time_cost_from_versionless_hash
+    password = Argon2id::Password.new("$argon2id$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal 2, password.t_cost
+  end
+
+  def test_extracting_memory_cost_from_hash
+    password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal 256, password.m_cost
+  end
+
+  def test_extracting_memory_cost_from_versionless_hash
+    password = Argon2id::Password.new("$argon2id$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal 256, password.m_cost
+  end
+
+  def test_extracting_parallelism_from_hash
+    password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal 1, password.parallelism
+  end
+
+  def test_extracting_parallelism_from_versionless_hash
+    password = Argon2id::Password.new("$argon2id$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    assert_equal 1, password.parallelism
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: argon2id
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Paul Mucur
@@ -10,20 +10,6 @@ bindir: bin
 cert_chain: []
 date: 2024-11-01 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: base64
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake-compiler
   requirement: !ruby/object:Gem::Requirement