argon2id 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d82db47aaab5dae5c5123f1a7e333256d736be27a93ba3817b9b569501d5ef1
-  data.tar.gz: 0dad93f3f34a8c3bc592b5b839aeecdf4975cf42c93f6690cfdb5bbb033be2b4
+  metadata.gz: 76d76a4abc46d90ed4599f134b0bdf29c308d3d580181ba7dfab8f3ba12d7689
+  data.tar.gz: 346056ab708ca4bc0d371875a32dbae0cf2d21c28e3d5049538f02024344e08e
 SHA512:
-  metadata.gz: 3fb64986c811e4fa6f510d73475184305f23a233e6f9486cbd10e1bdd8d8f24e59b755fb71cd67eb4edadb22122d0313c815f789e6d86cd14b5e99ab57e0ef6d
-  data.tar.gz: b0b406c29495e2c8f5b79bc6ffe30cfbae4fc4bb889005159b07f7e148d09f20d0ad88044e699f0b0553b40849d5abf702f576d2e496e856126ad461f306e0f9
+  metadata.gz: 9a2c086660509a67f697fe74262bcbb0c4e2910d731269994556eed179b712b4d23de7506deb42c336376ee9c0a943701cfded584e51f0f7199486f67f4aa132
+  data.tar.gz: d108365e5d029efe1fb02e3d3588961bcbb8c263ea027176f4963c9bfe7d4ecb1176948135603d72407982242ae24d90fdf41710e9780765f9ff6d822d93296c

data/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.1] - 2024-11-01
+
+### Added
+
+- RDoc documentation for the API
+
+### Fixed
+
+- Saved a superfluous extra byte when allocating the buffer for the encoded
+  hash
+
 ## [0.1.0] - 2024-10-31
 
 ### Added
@@ -13,4 +24,5 @@ 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.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

@@ -1,18 +1,22 @@
-# Argon2id - Ruby bindings to the award-winning password-hashing function
+# Argon2id - Ruby bindings to the OWASP recommended password-hashing function
 
 Ruby bindings to the reference C implementation of [Argon2][], the password-hashing
 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.0  
+**Current version:** 0.1.1  
 **Bundled Argon2 version:** libargon2.1 (20190702)
 
 ```ruby
 Argon2::Password.create("opensesame").to_s
 #=> "$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU"
-Argon2::Password.create("opensesame") == "opensesame"    #=> true
-Argon2::Password.create("opensesame") == "notopensesame" #=> false
+
+Argon2::Password.create("opensesame") == "opensesame"
+#=> true
+
+Argon2::Password.new("$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU") == "opensesame"
+#=> true
 ```
 
 ## Table of contents
@@ -156,6 +160,17 @@ This gem requires the following to run:
 
 ### Native gems
 
+Where possible, a pre-compiled native gem will be provided for the following platforms:
+
+* Linux
+    * `aarch64-linux` and `arm-linux` (requires [glibc](https://www.gnu.org/software/libc/) 2.29+)
+    * `x86-linux` and `x86_64-linux` (requires [glibc](https://www.gnu.org/software/libc/) 2.17+)
+    * [musl](https://musl.libc.org/)-based systems such as [Alpine](https://alpinelinux.org) are supported as long as a [glibc-compatible library is installed](https://wiki.alpinelinux.org/wiki/Running_glibc_programs)
+* macOS `x86_64-darwin` and `arm64-darwin`
+* Windows `x64-mingw32` and `x64-mingw-ucrt`
+
+### Verifying the gems
+
 SHA256 checksums are included in the [release
 notes](https://github.com/mudge/argon2id/releases) for each version and can be
 checked with `sha256sum`, e.g.
@@ -165,7 +180,7 @@ $ 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
-e71e4acaa5cae6ca763bc078bde121fb76ea07bad72bc471c9efd2ba444be604  argon2id-0.1.0-arm64-darwin.gem
+652ba4ebe4176c3fa944652b5db3bee52670c1e6b76632f921dd1455ec0810aa  argon2id-0.1.0-arm64-darwin.gem
 ```
 
 [GPG](https://www.gnupg.org/) signatures are attached to each release (the
@@ -176,7 +191,7 @@ from a public keyserver, e.g. `gpg --keyserver keyserver.ubuntu.com --recv-key
 
 ```console
 $ gpg --verify argon2id-0.1.0-arm64-darwin.gem.sig argon2id-0.1.0-arm64-darwin.gem
-gpg: Signature made Thu 31 Oct 11:16:18 2024 BST
+gpg: Signature made Thu 31 Oct 16:09:45 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]
@@ -229,7 +244,7 @@ Issues](https://github.com/mudge/argon2id/issues).
 
 ## License
 
-This library is licensed under the BSD 3-Clause License, see `LICENSE.txt`.
+This library is licensed under the BSD 3-Clause License, see `LICENSE`.
 
 Copyright © 2024, Paul Mucur.
 

data/Rakefile

@@ -1,6 +1,6 @@
 require "rake/extensiontask"
 require "rake_compiler_dock"
-require "rake/testtask"
+require "minitest/test_task"
 
 CLEAN.add("lib/**/*.{o,so,bundle}", "pkg")
 
@@ -27,9 +27,7 @@ Rake::ExtensionTask.new("argon2id", gemspec) do |e|
   e.cross_platform = cross_platforms
 end
 
-Rake::TestTask.new do |t|
-  t.warning = true
-end
+Minitest::TestTask.create
 
 begin
   require "ruby_memcheck"

data/argon2id.gemspec

@@ -51,6 +51,7 @@ Gem::Specification.new do |s|
     "test/test_password.rb",
     "test/test_verify.rb"
   ]
+  s.rdoc_options = ["--main", "README.md"]
 
   s.add_development_dependency("rake-compiler", "~> 1.2")
   s.add_development_dependency("rake-compiler-dock", "~> 1.5")

data/ext/argon2id/argon2id.c

@@ -7,6 +7,17 @@
 
 VALUE mArgon2id, cArgon2idError;
 
+/* call-seq: Argon2id.hash_encode(t_cost, m_cost, parallelism, pwd, salt, output_len)
+ *
+ * Hashes a password with Argon2id, producing an encoded hash.
+ *
+ * - +t_cost+: number of iterations
+ * - +m_cost+: sets memory usage to +m_cost+ kibibytes
+ * - +parallelism+: number of threads and compute lanes
+ * - +pwd+: the password
+ * - +salt+: the salt
+ * - +output_len+: desired length of the hash in bytes
+ */
 static VALUE
 rb_argon2id_hash_encoded(VALUE module, VALUE iterations, VALUE memory, VALUE threads, VALUE pwd, VALUE salt, VALUE hashlen)
 {
@@ -24,7 +35,7 @@ rb_argon2id_hash_encoded(VALUE module, VALUE iterations, VALUE memory, VALUE thr
   outlen = FIX2INT(hashlen);
 
   encodedlen = argon2_encodedlen(t_cost, m_cost, parallelism, (uint32_t)RSTRING_LEN(salt), (uint32_t)outlen, Argon2_id);
-  encoded = malloc(encodedlen + 1);
+  encoded = malloc(encodedlen);
   if (!encoded) {
     rb_raise(rb_eNoMemError, "not enough memory to allocate for encoded password");
   }
@@ -36,12 +47,16 @@ rb_argon2id_hash_encoded(VALUE module, VALUE iterations, VALUE memory, VALUE thr
     rb_raise(cArgon2idError, "%s", argon2_error_message(result));
   }
 
-  hash = rb_str_new(encoded, strlen(encoded));
+  hash = rb_str_new_cstr(encoded);
   free(encoded);
 
   return hash;
 }
 
+/* call-seq: Argon2id.verify(encoded, pwd)
+ *
+ * Verifies a password against an encoded string.
+ */
 static VALUE
 rb_argon2id_verify(VALUE module, VALUE encoded, VALUE pwd) {
   int result;

data/lib/argon2id/password.rb

@@ -3,9 +3,29 @@
 require "openssl"
 
 module Argon2id
+  # The Password class encapsulates an encoded Argon2id password hash.
+  #
+  # To hash a plain text password, use Argon2id::Password.create:
+  #
+  #   password = Argon2id::Password.create("password")
+  #   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:
+  #
+  #   password = Argon2id::Password.new("$argon2id$v=19$m=19456,t=2,p=1$+Lrjry9Ifq0poLr15OGU1Q$utkDvejJB0ugwm4s9+a+vF6+1a/W+Y3CYa5Wte/85ig")
+  #   password == "password"
+  #   #=> true
   class Password
     attr_reader :encoded
 
+    # Create a new Password object that hashes a given plain text password.
+    #
+    # - +: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
     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(
@@ -19,14 +39,20 @@ module Argon2id
       )
     end
 
+    # call-seq: Argon2id::Password.new(encoded)
+    #
+    # Create a new Password with the given encoded password hash.
     def initialize(encoded)
       @encoded = encoded
     end
 
+    # Return the encoded password hash.
     def to_s
       encoded
     end
 
+    # Compare the password with given plain text, returning true if it verifies
+    # successfully.
     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.0"
+  VERSION = "0.1.1"
 end

data/lib/argon2id.rb

@@ -24,6 +24,19 @@ module Argon2id
   @output_len = DEFAULT_OUTPUT_LEN
 
   class << self
-    attr_accessor :t_cost, :m_cost, :parallelism, :salt_len, :output_len
+    # The default number of iterations used by Argon2id::Password.create
+    attr_accessor :t_cost
+
+    # The default memory cost in kibibytes used by Argon2id::Password.create
+    attr_accessor :m_cost
+
+    # The default number of threads and compute lanes used by Argon2id::Password.create
+    attr_accessor :parallelism
+
+    # The default salt size in bytes used by Argon2id::Password.create
+    attr_accessor :salt_len
+
+    # The default desired length of the hash in bytes used by Argon2id::Password.create
+    attr_accessor :output_len
   end
 end

data/test/test_hash_encoded.rb

@@ -5,34 +5,28 @@ require "argon2id"
 
 class TestHashEncoded < Minitest::Test
   def test_valid_password_and_salt_encodes_successfully
-    encoded = Argon2id.hash_encoded(2, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(16), 32)
+    encoded = Argon2id.hash_encoded(2, 256, 1, "password", "somesalt", 32)
 
-    assert encoded.start_with?("$argon2id$")
+    assert_equal "$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4", encoded
   end
 
   def test_valid_password_does_not_include_trailing_null_byte
-    encoded = Argon2id.hash_encoded(2, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(16), 32)
+    encoded = Argon2id.hash_encoded(2, 256, 1, "password", "somesalt", 32)
 
     refute encoded.end_with?("\x00")
   end
 
   def test_raises_with_too_short_output
     error = assert_raises(Argon2id::Error) do
-      Argon2id.hash_encoded(2, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(16), 1)
+      Argon2id.hash_encoded(2, 256, 1, "password", "somesalt", 1)
     end
 
     assert_equal "Output is too short", error.message
   end
 
-  def test_raises_with_too_large_output
-    assert_raises(RangeError) do
-      Argon2id.hash_encoded(2, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(16), 4294967296)
-    end
-  end
-
   def test_raises_with_too_few_lanes
     error = assert_raises(Argon2id::Error) do
-      Argon2id.hash_encoded(2, 19456, 0, "opensesame", OpenSSL::Random.random_bytes(16), 32)
+      Argon2id.hash_encoded(2, 256, 0, "password", "somesalt", 32)
     end
 
     assert_equal "Too few lanes", error.message
@@ -40,51 +34,25 @@ class TestHashEncoded < Minitest::Test
 
   def test_raises_with_too_small_memory_cost
     error = assert_raises(Argon2id::Error) do
-      Argon2id.hash_encoded(2, 0, 1, "opensesame", OpenSSL::Random.random_bytes(16), 32)
+      Argon2id.hash_encoded(2, 0, 1, "password", "somesalt", 32)
     end
 
     assert_equal "Memory cost is too small", error.message
   end
 
-  def test_raises_with_too_large_memory_cost
-    assert_raises(RangeError) do
-      Argon2id.hash_encoded(2, 4294967296, 1, "opensesame", OpenSSL::Random.random_bytes(16), 32)
-    end
-  end
-
   def test_raises_with_too_small_time_cost
     error = assert_raises(Argon2id::Error) do
-      Argon2id.hash_encoded(0, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(16), 32)
+      Argon2id.hash_encoded(0, 256, 1, "password", "somesalt", 32)
     end
 
     assert_equal "Time cost is too small", error.message
   end
 
-  def test_raises_with_too_large_time_cost
-    assert_raises(RangeError) do
-      Argon2id.hash_encoded(4294967296, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(16), 32)
-    end
-  end
-
-  def test_raises_with_too_long_password
-    error = assert_raises(Argon2id::Error) do
-      Argon2id.hash_encoded(2, 19456, 1, "a" * 4294967296, OpenSSL::Random.random_bytes(16), 32)
-    end
-
-    assert_equal "Password is too long", error.message
-  end
-
   def test_raises_with_too_short_salt
     error = assert_raises(Argon2id::Error) do
-      Argon2id.hash_encoded(2, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(1), 32)
+      Argon2id.hash_encoded(0, 256, 1, "password", "", 32)
     end
 
     assert_equal "Salt is too short", error.message
   end
-
-  def test_raises_with_too_long_salt
-    assert_raises(RangeError) do
-      Argon2id.hash_encoded(2, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(4294967296), 32)
-    end
-  end
 end

data/test/test_password.rb

@@ -13,33 +13,33 @@ class TestPassword < Minitest::Test
   end
 
   def test_create_options_can_override_parameters
-    password = Argon2id::Password.create("opensesame", t_cost: 3, m_cost: 12288)
+    password = Argon2id::Password.create("opensesame", t_cost: 2, m_cost: 256)
 
-    assert password.to_s.include?("t=3")
-    assert password.to_s.include?("m=12288")
+    assert password.to_s.include?("t=2")
+    assert password.to_s.include?("m=256")
   end
 
   def test_create_uses_argon2id_configuration
-    Argon2id.parallelism = 4
-    Argon2id.m_cost = 9216
+    Argon2id.t_cost = 2
+    Argon2id.m_cost = 256
 
     password = Argon2id::Password.create("opensesame")
 
-    assert password.to_s.include?("p=4")
-    assert password.to_s.include?("m=9216")
+    assert password.to_s.include?("t=2")
+    assert password.to_s.include?("m=256")
   ensure
-    Argon2id.parallelism = Argon2id::DEFAULT_PARALLELISM
+    Argon2id.t_cost = Argon2id::DEFAULT_T_COST
     Argon2id.m_cost = Argon2id::DEFAULT_M_COST
   end
 
   def test_create_coerces_pwd_to_string
-    password = Argon2id::Password.create(123)
+    password = Argon2id::Password.create(123, t_cost: 2, m_cost: 256)
 
     assert password.to_s.start_with?("$argon2id$")
   end
 
   def test_create_coerces_costs_to_integer
-    password = Argon2id::Password.create("opensesame", t_cost: "5", m_cost: "7168", parallelism: "1", salt_len: "16", output_len: "32")
+    password = Argon2id::Password.create("opensesame", t_cost: "2", m_cost: "256", parallelism: "1", salt_len: "8", output_len: "32")
 
     assert password.to_s.start_with?("$argon2id$")
   end
@@ -51,25 +51,25 @@ class TestPassword < Minitest::Test
   end
 
   def test_equals_correct_password
-    password = Argon2id::Password.create("opensesame")
+    password = Argon2id::Password.create("opensesame", t_cost: 2, m_cost: 256)
 
     assert password == "opensesame"
   end
 
   def test_does_not_equal_invalid_password
-    password = Argon2id::Password.create("opensesame")
+    password = Argon2id::Password.create("opensesame", t_cost: 2, m_cost: 256)
 
     refute password == "notopensesame"
   end
 
   def test_is_password_returns_true_with_correct_password
-    password = Argon2id::Password.create("opensesame")
+    password = Argon2id::Password.create("opensesame", t_cost: 2, m_cost: 256)
 
     assert password.is_password?("opensesame")
   end
 
   def test_is_password_returns_false_with_incorrect_password
-    password = Argon2id::Password.create("opensesame")
+    password = Argon2id::Password.create("opensesame", t_cost: 2, m_cost: 256)
 
     refute password.is_password?("notopensesame")
   end

data/test/test_verify.rb

@@ -5,13 +5,13 @@ require "argon2id"
 
 class TestVerify < Minitest::Test
   def test_returns_true_with_correct_password
-    encoded = Argon2id.hash_encoded(2, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(16), 32)
+    encoded = Argon2id.hash_encoded(2, 256, 1, "password", "somesalt", 32)
 
-    assert Argon2id.verify(encoded, "opensesame")
+    assert Argon2id.verify(encoded, "password")
   end
 
   def test_returns_false_with_incorrect_password
-    encoded = Argon2id.hash_encoded(2, 19456, 1, "opensesame", OpenSSL::Random.random_bytes(16), 32)
+    encoded = Argon2id.hash_encoded(2, 256, 1, "password", "somesalt", 32)
 
     refute Argon2id.verify(encoded, "notopensesame")
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: argon2id
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Paul Mucur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-10-31 00:00:00.000000000 Z
+date: 2024-11-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -100,7 +100,9 @@ metadata:
   source_code_uri: https://github.com/mudge/argon2id
   rubygems_mfa_required: 'true'
 post_install_message: 
-rdoc_options: []
+rdoc_options:
+- "--main"
+- README.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement