argon2id 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d82db47aaab5dae5c5123f1a7e333256d736be27a93ba3817b9b569501d5ef1
+  data.tar.gz: 0dad93f3f34a8c3bc592b5b839aeecdf4975cf42c93f6690cfdb5bbb033be2b4
+SHA512:
+  metadata.gz: 3fb64986c811e4fa6f510d73475184305f23a233e6f9486cbd10e1bdd8d8f24e59b755fb71cd67eb4edadb22122d0313c815f789e6d86cd14b5e99ab57e0ef6d
+  data.tar.gz: b0b406c29495e2c8f5b79bc6ffe30cfbae4fc4bb889005159b07f7e148d09f20d0ad88044e699f0b0553b40849d5abf702f576d2e496e856126ad461f306e0f9

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 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.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.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,248 @@
+# Argon2id - Ruby bindings to the award-winning 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  
+**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
+```
+
+## 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
+```
+
+### Errors
+
+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)
+```
+
+## Requirements
+
+This gem requires the following to run:
+
+* [Ruby](https://www.ruby-lang.org/en/) 2.6 to 3.3
+
+### Native 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.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
+```
+
+[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.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:                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.txt`.
+
+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,57 @@
+require "rake/extensiontask"
+require "rake_compiler_dock"
+require "rake/testtask"
+
+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")
+
+Gem::PackageTask.new(gemspec).define
+
+Rake::ExtensionTask.new("argon2id", gemspec) do |e|
+  e.cross_compile = true
+  e.cross_platform = cross_platforms
+end
+
+Rake::TestTask.new do |t|
+  t.warning = true
+end
+
+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
+end
+
+task default: [:compile, :test]

data/argon2id.gemspec

@@ -0,0 +1,58 @@
+# 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.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/ext/argon2id/argon2id.c

@@ -0,0 +1,69 @@
+#include <ruby.h>
+#include <stdint.h>
+
+#include "argon2.h"
+
+#define UNUSED(x) (void)(x)
+
+VALUE mArgon2id, cArgon2idError;
+
+static VALUE
+rb_argon2id_hash_encoded(VALUE module, VALUE iterations, VALUE memory, VALUE threads, VALUE pwd, VALUE salt, VALUE hashlen)
+{
+  uint32_t t_cost, m_cost, parallelism;
+  size_t encodedlen, outlen;
+  char * encoded;
+  int result;
+  VALUE hash;
+
+  UNUSED(module);
+
+  t_cost = FIX2INT(iterations);
+  m_cost = FIX2INT(memory);
+  parallelism = FIX2INT(threads);
+  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);
+  if (!encoded) {
+    rb_raise(rb_eNoMemError, "not enough memory to allocate for encoded password");
+  }
+
+  result = argon2id_hash_encoded(t_cost, m_cost, parallelism, StringValuePtr(pwd), RSTRING_LEN(pwd), StringValuePtr(salt), RSTRING_LEN(salt), outlen, encoded, encodedlen);
+
+  if (result != ARGON2_OK) {
+    free(encoded);
+    rb_raise(cArgon2idError, "%s", argon2_error_message(result));
+  }
+
+  hash = rb_str_new(encoded, strlen(encoded));
+  free(encoded);
+
+  return hash;
+}
+
+static VALUE
+rb_argon2id_verify(VALUE module, VALUE encoded, VALUE pwd) {
+  int result;
+
+  UNUSED(module);
+
+  result = argon2id_verify(StringValuePtr(encoded), StringValuePtr(pwd), RSTRING_LEN(pwd));
+  if (result == ARGON2_OK) {
+    return Qtrue;
+  }
+  if (result == ARGON2_VERIFY_MISMATCH) {
+    return Qfalse;
+  }
+
+  rb_raise(cArgon2idError, "%s", argon2_error_message(result));
+}
+
+void
+Init_argon2id(void)
+{
+  mArgon2id = rb_define_module("Argon2id");
+  cArgon2idError = rb_define_class_under(mArgon2id, "Error", rb_eStandardError);
+  rb_define_singleton_method(mArgon2id, "hash_encoded", rb_argon2id_hash_encoded, 6);
+  rb_define_singleton_method(mArgon2id, "verify", rb_argon2id_verify, 2);
+}

data/ext/argon2id/extconf.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+$CFLAGS << " -Wextra"
+
+$VPATH << "$(srcdir)/libargon2"
+$VPATH << "$(srcdir)/libargon2/blake2"
+
+$srcs = Dir.glob("#{$srcdir}/{,libargon2/,libargon2/blake2/}*.c").map { |n| File.basename(n) }.sort
+
+$CPPFLAGS << " " << "-I$(srcdir)/libargon2"
+
+have_header("stdint.h")
+have_header("argon2.h")
+
+create_makefile "argon2id"