kdf: add a shorthand method for Argon2id

Author: rhenium

lib/openssl.rb

@@ -17,6 +17,7 @@
 require_relative 'openssl/cipher'
 require_relative 'openssl/digest'
 require_relative 'openssl/hmac'
+require_relative 'openssl/kdf'
 require_relative 'openssl/pkcs5'
 require_relative 'openssl/pkey'
 require_relative 'openssl/ssl'

lib/openssl/kdf.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module OpenSSL
+  module KDF
+    if respond_to?(:derive)
+      # Argon2id, a variant of Argon2, is a password hashing function
+      # described in {RFC 9106}[https://www.rfc-editor.org/rfc/rfc9106].
+      #
+      # This methods requires \OpenSSL 3.2 or later.
+      #
+      # === Parameters
+      # pass::    Passowrd to be hashed. Message string +P+ in RFC 9106.
+      # salt::    Salt. Nonce +S+ in RFC 9106.
+      # lanes::   Degree of parallelism. +p+ in RFC 9106.
+      # length::  Desired output length in bytes. Tag length +T+ in RFC 9106.
+      # memcost:: Memory size in the number of kibibytes. +m+ in RFC 9106.
+      # iter::    Number of passes. +t+ in RFC 9106.
+      # secret::  Secret value. Optional. +K+ in RFC 9106.
+      # ad::      Associated data. Optional. +X+ in RFC 9106.
+      #
+      # === Example
+      #   password = "\x01" * 32
+      #   salt = "\x02" * 16
+      #   secret = "\x03" * 8
+      #   ad = "\x04" * 12
+      #   ret = OpenSSL::KDF.argon2id(
+      #     password, salt: salt, lanes: 4, length: 32,
+      #     memcost: 32, iter: 3, secret: secret, ad: ad,
+      #   )
+      #   p ret.unpack1("H*")
+      #   #=> "0d640df58d78766c08c037a34a8b53c9d01ef0452d75b65eb52520e96b01e659"
+      def self.argon2id(pass, salt:, lanes:, length:, memcost:, iter:,
+                        secret: "", ad: "")
+        params = {
+          pass: pass, salt: salt, lanes: lanes, memcost: memcost, iter: iter,
+          secret: secret, ad: ad,
+        }
+        derive("ARGON2ID", length, params)
+      end
+    end
+  end
+end

test/openssl/test_kdf.rb

@@ -201,6 +201,20 @@ def test_derive
     }
   end if openssl?(3, 0, 0) || OpenSSL::KDF.respond_to?(:derive)
 
+  def test_argon2id_rfc9106
+    # https://www.rfc-editor.org/rfc/rfc9106.html#section-5.3
+    # 5.3. Argon2id Test Vectors
+    password = B("01" * 32)
+    salt = B("02" * 16)
+    secret = B("03" * 8)
+    ad = B("04" * 12)
+    tag = B("0d640df58d78766c08c037a34a8b53c9d0" \
+            "1ef0452d75b65eb52520e96b01e659")
+    ret = OpenSSL::KDF.argon2id(password, salt: salt, lanes: 4, length: 32,
+                                memcost: 32, iter: 3, secret: secret, ad: ad)
+    assert_equal(tag, ret)
+  end if openssl?(3, 2, 0)
+
   private
 
   def B(ary)