argon2id 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76d76a4abc46d90ed4599f134b0bdf29c308d3d580181ba7dfab8f3ba12d7689
-  data.tar.gz: 346056ab708ca4bc0d371875a32dbae0cf2d21c28e3d5049538f02024344e08e
+  metadata.gz: 5b9b058cdc380df5dc92dfcf47a6b60c57f7e8c5ed659802cca2c77732fd873b
+  data.tar.gz: d4bc55c9096dcf7a0704ba3ff7a28e2043cae95e3c03ec6f73e1efef74a77184
 SHA512:
-  metadata.gz: 9a2c086660509a67f697fe74262bcbb0c4e2910d731269994556eed179b712b4d23de7506deb42c336376ee9c0a943701cfded584e51f0f7199486f67f4aa132
-  data.tar.gz: d108365e5d029efe1fb02e3d3588961bcbb8c263ea027176f4963c9bfe7d4ecb1176948135603d72407982242ae24d90fdf41710e9780765f9ff6d822d93296c
+  metadata.gz: 349abb0266fe08fd79f8153963e51983fdd64c7a5f5ee2aa4fa9b0e132f8ac28adc3f559dcd41240b20f562946815a4d44e0e77d6cde236040c1c59fcade30a5
+  data.tar.gz: 7e8a8898f44918705d1b182eb1e30b82bd5a9e888e137d35fcc2ef32c1264e8e5922a9815614c72355b2f26ba1e298f12c91fc8bcae46c0f403b39c3449700b2

data/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.1.2] - 2024-11-01
+
+### Added
+
+- The original salt for an `Argon2id::Password` can now be retrieved with
+  `Argon2id::Password#salt`
+
+### Changed
+
+- Encoded hashes are now validated when initialising an `Argon2id::Password`,
+  raising an `ArgumentError` if they are invalid
+
+## [0.1.2] - 2024-11-01
+
+### Fixed
+
+- Validate that the encoded hash passed to `Argon2id::Password.new` is a
+  null-terminated C string, raising an `ArgumentError` if it contains extra null
+  bytes
+
 ## [0.1.1] - 2024-11-01
 
 ### Added
@@ -24,5 +44,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.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
 [0.1.1]: https://github.com/mudge/argon2id/releases/tag/v0.1.1
 [0.1.0]: https://github.com/mudge/argon2id/releases/tag/v0.1.0

data/README.md

@@ -5,17 +5,17 @@ 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.1.1  
+**Current version:** 0.2.0  
 **Bundled Argon2 version:** libargon2.1 (20190702)
 
 ```ruby
-Argon2::Password.create("opensesame").to_s
+Argon2id::Password.create("opensesame").to_s
 #=> "$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU"
 
-Argon2::Password.create("opensesame") == "opensesame"
+Argon2id::Password.create("opensesame") == "opensesame"
 #=> true
 
-Argon2::Password.new("$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU") == "opensesame"
+Argon2id::Password.new("$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU") == "opensesame"
 #=> true
 ```
 
@@ -142,6 +142,14 @@ password.is_password?("opensesame")    #=> true
 password.is_password?("notopensesame") #=> false
 ```
 
+The original salt for a password can be retrieved with `Argon2id::Password#salt`:
+
+```ruby
+password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+password.salt
+#=> "somesalt"
+```
+
 ### Errors
 
 Any errors returned from Argon2 will be raised as `Argon2id::Error`, e.g.
@@ -176,11 +184,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.1.0
-Fetching argon2id-0.1.0-arm64-darwin.gem
-Downloaded argon2id-0.1.0-arm64-darwin
-$ sha256sum argon2id-0.1.0-arm64-darwin.gem
-652ba4ebe4176c3fa944652b5db3bee52670c1e6b76632f921dd1455ec0810aa  argon2id-0.1.0-arm64-darwin.gem
+$ gem fetch argon2id -v 0.1.1
+Fetching argon2id-0.1.1-arm64-darwin.gem
+Downloaded argon2id-0.1.1-arm64-darwin
+$ sha256sum argon2id-0.1.1-arm64-darwin.gem
+8d47464edf847ca52c1d41cac1a9feff376e9a1e7c0a98ab58df846990caa1bb  argon2id-0.1.1-arm64-darwin.gem
 ```
 
 [GPG](https://www.gnupg.org/) signatures are attached to each release (the
@@ -190,8 +198,8 @@ from a public keyserver, e.g. `gpg --keyserver keyserver.ubuntu.com --recv-key
 0x39AC3530070E0F75`):
 
 ```console
-$ gpg --verify argon2id-0.1.0-arm64-darwin.gem.sig argon2id-0.1.0-arm64-darwin.gem
-gpg: Signature made Thu 31 Oct 16:09:45 2024 GMT
+$ gpg --verify argon2id-0.1.1-arm64-darwin.gem.sig argon2id-0.1.1-arm64-darwin.gem
+gpg: Signature made Fri  1 Nov 07:24:16 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,6 +53,7 @@ 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/ext/argon2id/argon2id.c

@@ -7,7 +7,7 @@
 
 VALUE mArgon2id, cArgon2idError;
 
-/* call-seq: Argon2id.hash_encode(t_cost, m_cost, parallelism, pwd, salt, output_len)
+/* call-seq: hash_encoded(t_cost, m_cost, parallelism, pwd, salt, output_len)
  *
  * Hashes a password with Argon2id, producing an encoded hash.
  *
@@ -53,7 +53,7 @@ rb_argon2id_hash_encoded(VALUE module, VALUE iterations, VALUE memory, VALUE thr
   return hash;
 }
 
-/* call-seq: Argon2id.verify(encoded, pwd)
+/* call-seq: verify(encoded, pwd)
  *
  * Verifies a password against an encoded string.
  */
@@ -63,7 +63,7 @@ rb_argon2id_verify(VALUE module, VALUE encoded, VALUE pwd) {
 
   UNUSED(module);
 
-  result = argon2id_verify(StringValuePtr(encoded), StringValuePtr(pwd), RSTRING_LEN(pwd));
+  result = argon2id_verify(StringValueCStr(encoded), StringValuePtr(pwd), RSTRING_LEN(pwd));
   if (result == ARGON2_OK) {
     return Qtrue;
   }

data/lib/argon2id/password.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "base64"
 require "openssl"
 
 module Argon2id
@@ -17,15 +18,47 @@ module Argon2id
   #   password == "password"
   #   #=> true
   class Password
+    # A regular expression to match valid hashes.
+    PATTERN = %r{
+      \A
+      \$
+      argon2(?:id|i|d)
+      (?:\$v=\d+)?
+      \$m=\d+
+      ,t=\d+
+      ,p=\d+
+      \$
+      (?<base64_salt>[a-zA-Z0-9+/]+)
+      \$
+      [a-zA-Z0-9+/]+
+      \z
+    }x.freeze
+
+    # The encoded password hash.
     attr_reader :encoded
 
-    # Create a new Password object that hashes a given plain text password.
+    # The salt.
+    attr_reader :salt
+
+    # Create a new Password object that hashes a given plain text password +pwd+.
     #
     # - +:t_cost+: integer (default 2) the "time cost" given as a number of iterations
     # - +:m_cost+: integer (default 19456) the "memory cost" given in kibibytes
     # - +:parallelism+: integer (default 1) the number of threads and compute lanes to use
     # - +:salt_len+: integer (default 16) the salt size in bytes
     # - +:output_len+: integer (default 32) the desired length of the hash in bytes
+    #
+    # For example, with the default configuration:
+    #
+    #   password = Argon2id::Password.create("password")
+    #   password.to_s
+    #   #=> "$argon2id$v=19$m=19456,t=2,p=1$FI8yp1gXbthJCskBlpKPoQ$nOfCCpS2r+I8GRN71cZND4cskn7YKBNzuHUEO3YpY2s"
+    #
+    # When overriding the configuration:
+    #
+    #   password = Argon2id::Password.create("password", t_cost: 3, m_cost: 12288)
+    #   password.to_s
+    #   #=> "$argon2id$v=19$m=12288,t=3,p=1$JigW7fFn+N3NImt+aWpuzw$eM5F1cKeIBALNTU6LuWra75Zi2nymGvQLWzJzVFv0Nc"
     def self.create(pwd, t_cost: Argon2id.t_cost, m_cost: Argon2id.m_cost, parallelism: Argon2id.parallelism, salt_len: Argon2id.salt_len, output_len: Argon2id.output_len)
       new(
         Argon2id.hash_encoded(
@@ -42,8 +75,15 @@ module Argon2id
     # call-seq: Argon2id::Password.new(encoded)
     #
     # Create a new Password with the given encoded password hash.
+    #
+    #   password = Argon2id::Password.new("$argon2id$v=19$m=19456,t=2,p=1$FI8yp1gXbthJCskBlpKPoQ$nOfCCpS2r+I8GRN71cZND4cskn7YKBNzuHUEO3YpY2s")
+    #
+    # Raises an ArgumentError if given an invalid hash.
     def initialize(encoded)
+      raise ArgumentError, "invalid hash" unless PATTERN =~ encoded
+
       @encoded = encoded
+      @salt = Base64.decode64(Regexp.last_match(:base64_salt))
     end
 
     # Return the encoded password hash.
@@ -53,6 +93,10 @@ module Argon2id
 
     # Compare the password with 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
+    #   password == "notpassword" #=> false
     def ==(other)
       Argon2id.verify(encoded, String(other))
     end

data/lib/argon2id/version.rb

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

data/lib/argon2id.rb

@@ -11,10 +11,19 @@ require "argon2id/version"
 require "argon2id/password"
 
 module Argon2id
+  # The default "time cost" of 2 iterations recommended by OWASP.
   DEFAULT_T_COST = 2
-  DEFAULT_M_COST = 19456
+
+  # The default "memory cost" of 19 mebibytes recommended by OWASP.
+  DEFAULT_M_COST = 19_456
+
+  # The default 1 thread and compute lane recommended by OWASP.
   DEFAULT_PARALLELISM = 1
+
+  # The default salt length of 16 bytes.
   DEFAULT_SALT_LEN = 16
+
+  # The default desired hash length of 32 bytes.
   DEFAULT_OUTPUT_LEN = 32
 
   @t_cost = DEFAULT_T_COST

data/test/test_password.rb

@@ -74,13 +74,33 @@ class TestPassword < Minitest::Test
     refute password.is_password?("notopensesame")
   end
 
-  def test_raises_if_verifying_with_invalid_encoded_password
-    password = Argon2id::Password.new("invalid")
+  def test_salt_returns_the_original_salt
+    password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
 
-    error = assert_raises(Argon2id::Error) do
-      password.is_password?("opensesame")
+    assert_equal "somesalt", password.salt
+  end
+
+  def test_salt_returns_raw_bytes
+    password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$KmIxrXv4lrnSJPO0LN7Gdw$lB3724qLPL9MNi10lkvIb4VxIk3q841CLvq0WTCZ0VQ")
+
+    assert_equal "*b1\xAD{\xF8\x96\xB9\xD2$\xF3\xB4,\xDE\xC6w".b, password.salt
+  end
+
+  def test_raises_for_invalid_hashes
+    assert_raises(ArgumentError) do
+      Argon2id::Password.new("not a valid hash")
     end
+  end
+
+  def test_raises_for_partial_hashes
+    assert_raises(ArgumentError) do
+      Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$KmIxrXv4lrnSJPO0LN7Gdw")
+    end
+  end
+
+  def test_salt_supports_versionless_hashes
+    password = Argon2id::Password.new("$argon2id$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
 
-    assert_equal "Decoding failed", error.message
+    assert_equal "somesalt", password.salt
   end
 end

data/test/test_verify.rb

@@ -5,15 +5,17 @@ require "argon2id"
 
 class TestVerify < Minitest::Test
   def test_returns_true_with_correct_password
-    encoded = Argon2id.hash_encoded(2, 256, 1, "password", "somesalt", 32)
-
-    assert Argon2id.verify(encoded, "password")
+    assert Argon2id.verify(
+      "$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4",
+      "password"
+    )
   end
 
   def test_returns_false_with_incorrect_password
-    encoded = Argon2id.hash_encoded(2, 256, 1, "password", "somesalt", 32)
-
-    refute Argon2id.verify(encoded, "notopensesame")
+    refute Argon2id.verify(
+      "$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4",
+      "not password"
+    )
   end
 
   def test_raises_if_given_invalid_encoded
@@ -21,4 +23,13 @@ class TestVerify < Minitest::Test
       Argon2id.verify("", "opensesame")
     end
   end
+
+  def test_raises_if_given_encoded_with_null_byte
+    assert_raises(ArgumentError) do
+      Argon2id.verify(
+        "$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4\x00foo",
+        "password"
+      )
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: argon2id
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Paul Mucur
@@ -10,6 +10,20 @@ 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