argon2id 0.4.0-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ecd94924e9be36c2d5cc914996688424ed5ac72b6a42e9f3c11062d4a95f5a57
+  data.tar.gz: fba3c84cb52265555796ab00e50578fb2711e080fca794e865743f4290c1d43c
+SHA512:
+  metadata.gz: a83e14f427cf90a788535a08c992e699501d15678825a1efbef93966859a309d73dfabde9d33aa4e0bde37ac2f97abb0fd911d2faee028eaab55f972583dc2a4
+  data.tar.gz: 9d2d6186851a7ce7ca5ab3a05889ee540820169632d7c98dcf921a61de2731592f6038457f1ad506b858db216710ad6ca1597a4cd56408c1647c297f66a63697

data/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+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.4.0] - 2024-11-02
+
+### Added
+
+- Added support for JRuby 9.4 by adding an implementation of Argon2id hashing
+  and verification using JRuby-OpenSSL's Bouncy Castle internals.
+- Added `output` to `Argon2id::Password` instances so the actual "output" part
+  of a password hash can be retrieved (and compared)
+
+### Changed
+
+- Verifying a password will now consistently raise an `ArgumentError` when
+  given an invalid encoded hash rather than an `Argon2id::Error`
+
+## [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
+
+- Anything that can be coerced to a String can now be passed to
+  `Argon2id::Password.new`
+
+## [0.2.0] - 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
+
+- 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
+
+- The initial version of the Argon2id gem, providing Ruby bindings to the
+  reference C implementation of Argon2, the password-hashing function that won
+  the Password Hashing Competition.
+
+[0.4.0]: https://github.com/mudge/argon2id/releases/tag/v0.4.0
+[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
+[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/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :memcheck, optional: true do
+  gem "ruby_memcheck"
+end

data/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2024 Paul Mucur.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,285 @@
+# 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.4.0  
+**Bundled Argon2 version:** libargon2.1 (20190702)
+
+```ruby
+Argon2id::Password.create("password").to_s
+#=> "$argon2id$v=19$m=19456,t=2,p=1$agNV6OfDL1OwE44WdrFCJw$ITrBwvCsW4b5GjgZuL67RCcvVMEWBWXtASc9TVyI3rY"
+
+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
+
+password.m_cost #=> 19456
+password.salt   #=> "e-\xA7\x04U\x81\xA6{v\xF0x\xED\xCC\xD3\x96\xE3"
+```
+
+## Table of contents
+
+* [Why Argon2id?](#why-argon2id)
+* [Usage](#usage)
+    * [Hashing passwords](#hashing-passwords)
+    * [Verifying passwords](#verifying-passwords)
+    * [Errors](#errors)
+* [Requirements](#requirements)
+    * [Native gems](#native-gems)
+    * [Verifying the gems](#verifying-the-gems)
+    * [Installing the `ruby` platform gem](#installing-the-ruby-platform-gem)
+* [Thanks](#thanks)
+* [Contact](#contact)
+* [License](#license)
+    * [Dependencies](#dependencies)
+
+## Why Argon2id?
+
+> Argon2 is a password-hashing function that summarizes the state of the art in
+> the design of memory-hard functions and can be used to hash passwords for
+> credential storage, key derivation, or other applications.
+>
+> It has a simple design aimed at the highest memory filling rate and effective
+> use of multiple computing units, while still providing defense against
+> tradeoff attacks (by exploiting the cache and memory organization of the
+> recent processors).
+
+— [Argon2][]
+
+> Argon2 was the winner of the 2015 Password Hashing Competition. Out of the
+> three Argon2 versions, use the Argon2id variant since it provides a balanced
+> approach to resisting both side-channel and GPU-based attacks.
+
+— [OWASP Password Storage Cheat Sheet][]
+
+## Usage
+
+Install argon2id as a dependency:
+
+```ruby
+# In your Gemfile
+gem "argon2id"
+
+# Or without Bundler
+gem install argon2id
+```
+
+Include in your code:
+
+```ruby
+require "argon2id"
+```
+
+### Hashing passwords
+
+Hash a plain text password (e.g. from user input) with
+`Argon2id::Password.create`:
+
+```ruby
+password = Argon2id::Password.create("opensesame")
+```
+
+The encoded value of the resulting hash is available via
+`Argon2id::Password#to_s` (ideal for persisting somewhere):
+
+```ruby
+password.to_s
+#=> "$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU"
+```
+
+By default, `Argon2id::Password.create` will use the second set of parameters
+recommended by [OWASP][OWASP Password Storage Cheat Sheet] but these can be
+overridden by passing keyword arguments to `Argon2id::Password.create`:
+
+* `t_cost`: the "time cost" given as a number of iterations (defaults to 2)
+* `m_cost`: the "memory cost" given in kibibytes (defaults to 19 mebibytes)
+* `parallelism`: the number of threads and compute lanes to use (defaults to 1)
+* `salt_len`: the salt size in bytes (defaults to 16)
+* `output_len`: the desired length of the hash in bytes (defaults to 32)
+
+```ruby
+password = Argon2id::Password.create("opensesame", t_cost: 3, m_cost: 12288)
+password.to_s
+#=> "$argon2id$v=19$m=12288,t=3,p=1$uukIsLS6y6etvsgoN20kVg$exMvDX/P9exvEPmnZL2gZClRyMdrnqjqyysLMP/VUWA"
+```
+
+If you want to override the parameters for all calls to
+`Argon2id::Password.create`, you can set them on `Argon2id` directly:
+
+```ruby
+Argon2id.t_cost = 3
+Argon2id.m_cost = 12288
+Argon2id.parallelism = 1
+Argon2id.salt_len = 16
+Argon2id.output_len = 32
+```
+
+### Verifying passwords
+
+To verify a password against a hash, use `Argon2id::Password#==`:
+
+```ruby
+password = Argon2id::Password.create("opensesame")
+password == "opensesame"    #=> true
+password == "notopensesame" #=> false
+```
+
+Or, if you only have the hash (e.g. retrieved from storage):
+
+```ruby
+password = Argon2id::Password.new("$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU")
+password == "opensesame"    #=> true
+password == "notopensesame" #=> false
+```
+
+For compatibility with [bcrypt-ruby][], `Argon2id::Password#==` is aliased to `Argon2id::Password.is_password?`:
+
+```ruby
+password = Argon2id::Password.new("$argon2id$v=19$m=19456,t=2,p=1$ZS2nBFWBpnt28HjtzNOW4w$SQ+p+dIcWbpzWpZQ/ZZFj8IQkyhYZf127U4QdkRmKFU")
+password.is_password?("opensesame")    #=> true
+password.is_password?("notopensesame") #=> false
+```
+
+The various parts of the encoded password can be retrieved:
+
+```ruby
+password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+password.type        #=> "argon2id"
+password.version     #=> 19
+password.m_cost      #=> 256
+password.t_cost      #=> 2
+password.parallelism #=> 1
+password.salt        #=> "somesalt"
+password.output
+#=> "\x9D\xFE\xB9\x10\xE8\v\xAD\x03\x11\xFE\xE2\x0F\x9C\x0E+\x12\xC1y\x87\xB4\xCA\xC9\f.\xF5M[0!\xC6\x8B\xFE"
+```
+
+### Errors
+
+Any errors returned from Argon2 will be raised as `Argon2id::Error`, e.g.
+
+```ruby
+Argon2id::Password.create("password", salt_len: 0)
+# Salt is too short (Argon2id::Error)
+```
+
+## Requirements
+
+This gem requires any of the following to run:
+
+* [Ruby](https://www.ruby-lang.org/en/) 2.6 to 3.3
+* [JRuby](https://www.jruby.org) 9.4
+* [TruffleRuby](https://www.graalvm.org/ruby/) 24.1
+
+> [!NOTE]
+> The JRuby version of the gem uses
+> [JRuby-OpenSSL](https://github.com/jruby/jruby-openssl)'s implementation of
+> Argon2 instead of the reference C implementation.
+
+### 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`
+* Java: any platform running JRuby 9.4 or higher
+
+### 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.
+
+```console
+$ gem fetch argon2id -v 0.3.0
+Fetching argon2id-0.3.0-arm64-darwin.gem
+Downloaded argon2id-0.3.0-arm64-darwin
+$ sha256sum argon2id-0.3.0-arm64-darwin.gem
+9d49de6840942b48d020dddd422a1577fde7289ccb08a637bdb29f4a09b4e181  argon2id-0.3.0-arm64-darwin.gem
+```
+
+[GPG](https://www.gnupg.org/) signatures are attached to each release (the
+assets ending in `.sig`) and can be verified if you import [our signing key
+`0x39AC3530070E0F75`](https://mudge.name/39AC3530070E0F75.asc) (or fetch it
+from a public keyserver, e.g. `gpg --keyserver keyserver.ubuntu.com --recv-key
+0x39AC3530070E0F75`):
+
+```console
+$ gpg --verify argon2id-0.3.0-arm64-darwin.gem.sig argon2id-0.3.0-arm64-darwin.gem
+gpg: Signature made Fri  1 Nov 18:15:47 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]
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg:          There is no indication that the signature belongs to the owner.
+Primary key fingerprint: 7026 09D9 C790 F45B 577D  7BEC 39AC 3530 070E 0F75
+```
+
+The fingerprint should be as shown above or you can independently verify it
+with the ones shown in the footer of https://mudge.name.
+
+### Installing the `ruby` platform gem
+
+> [!WARNING]
+> We strongly recommend using the native gems where possible to avoid the need
+> for compiling the C extension and its dependencies which will take longer and
+> be less reliable.
+
+If you wish to compile the gem, you will need to explicitly install the `ruby` platform gem:
+
+```ruby
+# In your Gemfile with Bundler 2.3.18+
+gem "argon2id", force_ruby_platform: true
+
+# With Bundler 2.1+
+bundle config set force_ruby_platform true
+
+# With older versions of Bundler
+bundle config force_ruby_platform true
+
+# Without Bundler
+gem install argon2id --platform=ruby
+```
+
+You will need a full compiler toolchain for compiling Ruby C extensions (see
+[Nokogiri's "The Compiler
+Toolchain"](https://nokogiri.org/tutorials/installing_nokogiri.html#appendix-a-the-compiler-toolchain))
+plus the toolchain required for compiling the vendored version of Argon2.
+
+## Thanks
+
+* Thanks to [Mike Dalessio](https://github.com/flavorjones) for his advice and
+ [Ruby C Extensions Explained](https://github.com/flavorjones/ruby-c-extensions-explained)
+ project
+
+## Contact
+
+All issues and suggestions should go to [GitHub
+Issues](https://github.com/mudge/argon2id/issues).
+
+## License
+
+This library is licensed under the BSD 3-Clause License, see `LICENSE`.
+
+Copyright © 2024, Paul Mucur.
+
+### Dependencies
+
+The source code of [Argon2][] is distributed in the gem. This code is copyright
+© 2015 Daniel Dinu, Dmitry Khovratovich (main authors), Jean-Philippe Aumasson
+and Samuel Neves, and dual licensed under the [CC0 License][] and the [Apache
+2.0 License][].
+
+  [Argon2]: https://github.com/P-H-C/phc-winner-argon2/
+  [OWASP Password Storage Cheat Sheet]: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#argon2id
+  [bcrypt-ruby]: https://github.com/bcrypt-ruby/bcrypt-ruby
+  [CC0 License]: https://creativecommons.org/about/cc0
+  [Apache 2.0 License]: https://www.apache.org/licenses/LICENSE-2.0
+  [Password Hashing Competition]: https://www.password-hashing.net

data/Rakefile

@@ -0,0 +1,71 @@
+require "rake/extensiontask"
+require "rake_compiler_dock"
+require "minitest/test_task"
+
+CLEAN.add("lib/**/*.{o,so,bundle}", "pkg")
+
+cross_platforms = %w[
+  aarch64-linux
+  arm-linux
+  arm64-darwin
+  x64-mingw-ucrt
+  x64-mingw32
+  x86-linux
+  x86-mingw32
+  x86_64-darwin
+  x86_64-linux
+].freeze
+
+ENV["RUBY_CC_VERSION"] = %w[3.3.0 3.2.0 3.1.0 3.0.0 2.7.0 2.6.0].join(":")
+
+gemspec = Gem::Specification.load("argon2id.gemspec")
+
+if RUBY_PLATFORM == "java"
+  gemspec.files.reject! { |path| File.fnmatch?("ext/*", path) }
+  gemspec.extensions.clear
+  gemspec.platform = Gem::Platform.new("java")
+  gemspec.required_ruby_version = ">= 3.1.0"
+end
+
+Gem::PackageTask.new(gemspec).define
+
+Rake::ExtensionTask.new("argon2id", gemspec) do |e|
+  e.cross_compile = true
+  e.cross_platform = cross_platforms
+end
+
+Minitest::TestTask.create
+
+begin
+  require "ruby_memcheck"
+
+  namespace :test do
+    RubyMemcheck::TestTask.new(valgrind: :compile)
+  end
+rescue LoadError
+  # Only define the test:valgrind task if ruby_memcheck is installed
+end
+
+namespace :gem do
+  cross_platforms.each do |platform|
+    desc "Compile and build native gem for #{platform}"
+    task platform do
+      RakeCompilerDock.sh <<~SCRIPT, platform: platform, verbose: true
+        gem install bundler --no-document &&
+        bundle &&
+        bundle exec rake native:#{platform} pkg/#{gemspec.full_name}-#{Gem::Platform.new(platform)}.gem PATH="/usr/local/bin:$PATH"
+      SCRIPT
+    end
+  end
+
+  desc "Compile gem for JRuby"
+  task :jruby do
+    RakeCompilerDock.sh <<~SCRIPT, rubyvm: "jruby", platform: "jruby", verbose: true
+      gem install bundler --no-document &&
+      bundle &&
+      bundle exec rake gem
+    SCRIPT
+  end
+end
+
+task default: [:compile, :test]

data/argon2id.gemspec

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "lib/argon2id/version"
+
+Gem::Specification.new do |s|
+  s.name = "argon2id"
+  s.version = Argon2id::VERSION
+  s.summary = "Ruby bindings to Argon2"
+  s.description = "Ruby bindings to the reference C implementation of Argon2, the password-hashing function that won the 2015 Password Hashing Competition."
+  s.license = "BSD-3-Clause"
+  s.authors = ["Paul Mucur"]
+  s.homepage = "https://github.com/mudge/argon2id"
+  s.metadata = {
+    "bug_tracker_uri" => "https://github.com/mudge/argon2id/issues",
+    "changelog_uri" => "https://github.com/mudge/argon2id/blob/main/CHANGELOG.md",
+    "funding_uri" => "https://github.com/sponsors/mudge",
+    "homepage_uri" => "https://github.com/mudge/argon2id",
+    "source_code_uri" => "https://github.com/mudge/argon2id",
+    "rubygems_mfa_required" => "true"
+  }
+  s.required_ruby_version = ">= 2.6.0"
+  s.extensions = ["ext/argon2id/extconf.rb"]
+  s.files = [
+    "CHANGELOG.md",
+    "Gemfile",
+    "LICENSE",
+    "README.md",
+    "Rakefile",
+    "argon2id.gemspec",
+    "ext/argon2id/argon2id.c",
+    "ext/argon2id/extconf.rb",
+    "ext/argon2id/libargon2/LICENSE",
+    "ext/argon2id/libargon2/argon2.c",
+    "ext/argon2id/libargon2/argon2.h",
+    "ext/argon2id/libargon2/blake2/blake2-impl.h",
+    "ext/argon2id/libargon2/blake2/blake2.h",
+    "ext/argon2id/libargon2/blake2/blake2b.c",
+    "ext/argon2id/libargon2/blake2/blamka-round-opt.h",
+    "ext/argon2id/libargon2/blake2/blamka-round-ref.h",
+    "ext/argon2id/libargon2/core.c",
+    "ext/argon2id/libargon2/core.h",
+    "ext/argon2id/libargon2/encoding.c",
+    "ext/argon2id/libargon2/encoding.h",
+    "ext/argon2id/libargon2/ref.c",
+    "ext/argon2id/libargon2/thread.c",
+    "ext/argon2id/libargon2/thread.h",
+    "lib/argon2id.rb",
+    "lib/argon2id/password.rb",
+    "lib/argon2id/version.rb",
+    "test/test_hash_encoded.rb",
+    "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")
+  s.add_development_dependency("minitest", "~> 5.25")
+end

data/lib/argon2id/password.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+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 wrap an encoded Argon2id password hash, use Argon2id::Password.new:
+  #
+  #   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+)
+      \$
+      ([a-zA-Z0-9+/]+)
+      \$
+      ([a-zA-Z0-9+/]+)
+      \z
+    }x.freeze
+
+    # 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
+
+    # The hash output.
+    attr_reader :output
+
+    # 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(
+          Integer(t_cost),
+          Integer(m_cost),
+          Integer(parallelism),
+          String(pwd),
+          OpenSSL::Random.random_bytes(Integer(salt_len)),
+          Integer(output_len)
+        )
+      )
+    end
+
+    # 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 =~ String(encoded)
+
+      @encoded = $&
+      @type = $1
+      @version = Integer($2 || 0x10)
+      @m_cost = Integer($3)
+      @t_cost = Integer($4)
+      @parallelism = Integer($5)
+      @salt = $6.unpack1("m")
+      @output = $7.unpack1("m")
+    end
+
+    # Return the encoded password hash.
+    alias_method :to_s, :encoded
+
+    # 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
+    #   password == "notpassword" #=> false
+    def ==(other)
+      Argon2id.verify(encoded, String(other))
+    end
+
+    alias_method :is_password?, :==
+  end
+end

data/lib/argon2id/version.rb

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

data/lib/argon2id.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+if RUBY_PLATFORM == "java"
+  require "openssl"
+else
+  begin
+    ::RUBY_VERSION =~ /(\d+\.\d+)/
+    require_relative "#{Regexp.last_match(1)}/argon2id.so"
+  rescue LoadError
+    require "argon2id.so"
+  end
+end
+
+require "argon2id/version"
+require "argon2id/password"
+
+module Argon2id
+  # The default "time cost" of 2 iterations recommended by OWASP.
+  DEFAULT_T_COST = 2
+
+  # 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
+  @m_cost = DEFAULT_M_COST
+  @parallelism = DEFAULT_PARALLELISM
+  @salt_len = DEFAULT_SALT_LEN
+  @output_len = DEFAULT_OUTPUT_LEN
+
+  class << self
+    # 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
+
+  if RUBY_PLATFORM == "java"
+    Error = Class.new(StandardError)
+
+    def self.hash_encoded(t_cost, m_cost, parallelism, pwd, salt, hashlen)
+      raise Error, "Salt is too short" unless String(salt).bytesize.positive?
+
+      hash = Java::byte[Integer(hashlen)].new
+      params = Java::OrgBouncycastleCryptoParams::Argon2Parameters::Builder
+        .new(Java::OrgBouncycastleCryptoParams::Argon2Parameters::ARGON2_id)
+        .with_salt(String(salt).to_java_bytes)
+        .with_parallelism(Integer(parallelism))
+        .with_memory_as_kb(Integer(m_cost))
+        .with_iterations(Integer(t_cost))
+        .build
+      generator = Java::OrgBouncycastleCryptoGenerators::Argon2BytesGenerator.new
+      encoder = Java::JavaUtil::Base64.get_encoder.without_padding
+
+      generator.init(params)
+      generator.generate_bytes(String(pwd).to_java_bytes, hash)
+
+      encoded_salt = encoder.encode_to_string(params.get_salt)
+      encoded_output = encoder.encode_to_string(hash)
+
+      "$argon2id$v=#{params.get_version}$m=#{params.get_memory}," \
+        "t=#{params.get_iterations},p=#{params.get_lanes}" \
+        "$#{encoded_salt}$#{encoded_output}"
+    rescue => e
+      raise Error, e.message
+    end
+
+    def self.verify(encoded, pwd)
+      password = Password.new(encoded)
+      other_password = Password.new(
+        hash_encoded(
+          password.t_cost,
+          password.m_cost,
+          password.parallelism,
+          String(pwd),
+          password.salt,
+          password.output.bytesize
+        )
+      )
+
+      Java::OrgBouncycastleUtil::Arrays.constant_time_are_equal(
+        password.output.to_java_bytes,
+        other_password.output.to_java_bytes
+      )
+    end
+  end
+end

data/test/test_hash_encoded.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "argon2id"
+
+class TestHashEncoded < Minitest::Test
+  def test_valid_password_and_salt_encodes_successfully
+    encoded = Argon2id.hash_encoded(2, 256, 1, "password", "somesalt", 32)
+
+    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, 256, 1, "password", "somesalt", 32)
+
+    refute encoded.end_with?("\x00")
+  end
+
+  def test_raises_with_too_short_output
+    assert_raises(Argon2id::Error) do
+      Argon2id.hash_encoded(2, 256, 1, "password", "somesalt", 1)
+    end
+  end
+
+  def test_raises_with_too_few_lanes
+    assert_raises(Argon2id::Error) do
+      Argon2id.hash_encoded(2, 256, 0, "password", "somesalt", 32)
+    end
+  end
+
+  def test_raises_with_too_small_memory_cost
+    assert_raises(Argon2id::Error) do
+      Argon2id.hash_encoded(2, 0, 1, "password", "somesalt", 32)
+    end
+  end
+
+  def test_raises_with_too_small_time_cost
+    assert_raises(Argon2id::Error) do
+      Argon2id.hash_encoded(0, 256, 1, "password", "somesalt", 32)
+    end
+  end
+
+  def test_raises_with_too_short_salt
+    assert_raises(Argon2id::Error) do
+      Argon2id.hash_encoded(2, 256, 1, "password", "", 32)
+    end
+  end
+end

data/test/test_password.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "argon2id"
+
+class TestPassword < Minitest::Test
+  def test_create_returns_encoded_password_with_defaults
+    password = Argon2id::Password.create("opensesame")
+
+    assert password.to_s.start_with?("$argon2id$")
+    assert password.to_s.include?("t=2")
+    assert password.to_s.include?("m=19456")
+  end
+
+  def test_create_options_can_override_parameters
+    password = Argon2id::Password.create("opensesame", t_cost: 2, m_cost: 256)
+
+    assert password.to_s.include?("t=2")
+    assert password.to_s.include?("m=256")
+  end
+
+  def test_create_uses_argon2id_configuration
+    Argon2id.t_cost = 2
+    Argon2id.m_cost = 256
+
+    password = Argon2id::Password.create("opensesame")
+
+    assert password.to_s.include?("t=2")
+    assert password.to_s.include?("m=256")
+  ensure
+    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, 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: "2", m_cost: "256", parallelism: "1", salt_len: "8", output_len: "32")
+
+    assert password.to_s.start_with?("$argon2id$")
+  end
+
+  def test_create_raises_if_given_non_integer_costs
+    assert_raises(ArgumentError) do
+      Argon2id::Password.create("opensesame", t_cost: "not an integer")
+    end
+  end
+
+  def test_equals_correct_password
+    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", t_cost: 2, m_cost: 256)
+
+    refute password == "notopensesame"
+  end
+
+  def test_is_password_returns_true_with_correct_password
+    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", t_cost: 2, m_cost: 256)
+
+    refute password.is_password?("notopensesame")
+  end
+
+  def test_salt_returns_the_original_salt
+    password = Argon2id::Password.new("$argon2id$v=19$m=256,t=2,p=1$c29tZXNhbHQ$nf65EOgLrQMR/uIPnA4rEsF5h7TKyQwu9U1bMCHGi/4")
+
+    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 "somesalt", password.salt
+  end
+
+  def test_coerces_given_hash_to_string
+    password = Argon2id::Password.create("password")
+
+    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

data/test/test_verify.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "argon2id"
+
+class TestVerify < Minitest::Test
+  def test_returns_true_with_correct_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
+    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
+    assert_raises(ArgumentError) do
+      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

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: argon2id
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: java
+authors:
+- Paul Mucur
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  name: rake-compiler
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  name: rake-compiler-dock
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  name: minitest
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+description: Ruby bindings to the reference C implementation of Argon2, the password-hashing
+  function that won the 2015 Password Hashing Competition.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- argon2id.gemspec
+- lib/argon2id.rb
+- lib/argon2id/password.rb
+- lib/argon2id/version.rb
+- test/test_hash_encoded.rb
+- test/test_password.rb
+- test/test_verify.rb
+homepage: https://github.com/mudge/argon2id
+licenses:
+- BSD-3-Clause
+metadata:
+  bug_tracker_uri: https://github.com/mudge/argon2id/issues
+  changelog_uri: https://github.com/mudge/argon2id/blob/main/CHANGELOG.md
+  funding_uri: https://github.com/sponsors/mudge
+  homepage_uri: https://github.com/mudge/argon2id
+  source_code_uri: https://github.com/mudge/argon2id
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.25
+signing_key:
+specification_version: 4
+summary: Ruby bindings to Argon2
+test_files: []