zig_example 0.3.0 → 0.3.1

data/ext/openssl/ossl_hmac.c

@@ -0,0 +1,310 @@
+/*
+ * 'OpenSSL for Ruby' project
+ * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
+ * All rights reserved.
+ */
+/*
+ * This program is licensed under the same licence as Ruby.
+ * (See the file 'LICENCE'.)
+ */
+#include "ossl.h"
+
+#define NewHMAC(klass) \
+    TypedData_Wrap_Struct((klass), &ossl_hmac_type, 0)
+#define GetHMAC(obj, ctx) do { \
+    TypedData_Get_Struct((obj), EVP_MD_CTX, &ossl_hmac_type, (ctx)); \
+    if (!(ctx)) { \
+	ossl_raise(rb_eRuntimeError, "HMAC wasn't initialized"); \
+    } \
+} while (0)
+
+/*
+ * Classes
+ */
+VALUE cHMAC;
+VALUE eHMACError;
+
+/*
+ * Public
+ */
+
+/*
+ * Private
+ */
+static void
+ossl_hmac_free(void *ctx)
+{
+    EVP_MD_CTX_free(ctx);
+}
+
+static const rb_data_type_t ossl_hmac_type = {
+    "OpenSSL/HMAC",
+    {
+	0, ossl_hmac_free,
+    },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+ossl_hmac_alloc(VALUE klass)
+{
+    VALUE obj;
+    EVP_MD_CTX *ctx;
+
+    obj = NewHMAC(klass);
+    ctx = EVP_MD_CTX_new();
+    if (!ctx)
+        ossl_raise(eHMACError, "EVP_MD_CTX");
+    RTYPEDDATA_DATA(obj) = ctx;
+
+    return obj;
+}
+
+
+/*
+ *  call-seq:
+ *     HMAC.new(key, digest) -> hmac
+ *
+ * Returns an instance of OpenSSL::HMAC set with the key and digest
+ * algorithm to be used. The instance represents the initial state of
+ * the message authentication code before any data has been processed.
+ * To process data with it, use the instance method #update with your
+ * data as an argument.
+ *
+ * === Example
+ *
+ *	key = 'key'
+ * 	instance = OpenSSL::HMAC.new(key, 'SHA1')
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ * 	instance.class
+ * 	#=> OpenSSL::HMAC
+ *
+ * === A note about comparisons
+ *
+ * Two instances can be securely compared with #== in constant time:
+ *
+ *	other_instance = OpenSSL::HMAC.new('key', 'SHA1')
+ *  #=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *  instance == other_instance
+ *  #=> true
+ *
+ */
+static VALUE
+ossl_hmac_initialize(VALUE self, VALUE key, VALUE digest)
+{
+    EVP_MD_CTX *ctx;
+    EVP_PKEY *pkey;
+
+    GetHMAC(self, ctx);
+    StringValue(key);
+#ifdef HAVE_EVP_PKEY_NEW_RAW_PRIVATE_KEY
+    pkey = EVP_PKEY_new_raw_private_key(EVP_PKEY_HMAC, NULL,
+                                        (unsigned char *)RSTRING_PTR(key),
+                                        RSTRING_LENINT(key));
+    if (!pkey)
+        ossl_raise(eHMACError, "EVP_PKEY_new_raw_private_key");
+#else
+    pkey = EVP_PKEY_new_mac_key(EVP_PKEY_HMAC, NULL,
+                                (unsigned char *)RSTRING_PTR(key),
+                                RSTRING_LENINT(key));
+    if (!pkey)
+        ossl_raise(eHMACError, "EVP_PKEY_new_mac_key");
+#endif
+    if (EVP_DigestSignInit(ctx, NULL, ossl_evp_get_digestbyname(digest),
+                           NULL, pkey) != 1) {
+        EVP_PKEY_free(pkey);
+        ossl_raise(eHMACError, "EVP_DigestSignInit");
+    }
+    /* Decrement reference counter; EVP_MD_CTX still keeps it */
+    EVP_PKEY_free(pkey);
+
+    return self;
+}
+
+static VALUE
+ossl_hmac_copy(VALUE self, VALUE other)
+{
+    EVP_MD_CTX *ctx1, *ctx2;
+
+    rb_check_frozen(self);
+    if (self == other) return self;
+
+    GetHMAC(self, ctx1);
+    GetHMAC(other, ctx2);
+    if (EVP_MD_CTX_copy(ctx1, ctx2) != 1)
+        ossl_raise(eHMACError, "EVP_MD_CTX_copy");
+    return self;
+}
+
+/*
+ *  call-seq:
+ *     hmac.update(string) -> self
+ *
+ * Returns _hmac_ updated with the message to be authenticated.
+ * Can be called repeatedly with chunks of the message.
+ *
+ * === Example
+ *
+ *	first_chunk = 'The quick brown fox jumps '
+ * 	second_chunk = 'over the lazy dog'
+ *
+ * 	instance.update(first_chunk)
+ * 	#=> 5b9a8038a65d571076d97fe783989e52278a492a
+ * 	instance.update(second_chunk)
+ * 	#=> de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9
+ *
+ */
+static VALUE
+ossl_hmac_update(VALUE self, VALUE data)
+{
+    EVP_MD_CTX *ctx;
+
+    StringValue(data);
+    GetHMAC(self, ctx);
+    if (EVP_DigestSignUpdate(ctx, RSTRING_PTR(data), RSTRING_LEN(data)) != 1)
+        ossl_raise(eHMACError, "EVP_DigestSignUpdate");
+
+    return self;
+}
+
+/*
+ *  call-seq:
+ *     hmac.digest -> string
+ *
+ * Returns the authentication code an instance represents as a binary string.
+ *
+ * === Example
+ *  instance = OpenSSL::HMAC.new('key', 'SHA1')
+ *  #=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *  instance.digest
+ *  #=> "\xF4+\xB0\xEE\xB0\x18\xEB\xBDE\x97\xAEr\x13q\x1E\xC6\a`\x84?"
+ */
+static VALUE
+ossl_hmac_digest(VALUE self)
+{
+    EVP_MD_CTX *ctx;
+    size_t buf_len = EVP_MAX_MD_SIZE;
+    VALUE ret;
+
+    GetHMAC(self, ctx);
+    ret = rb_str_new(NULL, EVP_MAX_MD_SIZE);
+    if (EVP_DigestSignFinal(ctx, (unsigned char *)RSTRING_PTR(ret),
+                            &buf_len) != 1)
+        ossl_raise(eHMACError, "EVP_DigestSignFinal");
+    rb_str_set_len(ret, (long)buf_len);
+
+    return ret;
+}
+
+/*
+ *  call-seq:
+ *     hmac.hexdigest -> string
+ *
+ * Returns the authentication code an instance represents as a hex-encoded
+ * string.
+ */
+static VALUE
+ossl_hmac_hexdigest(VALUE self)
+{
+    EVP_MD_CTX *ctx;
+    unsigned char buf[EVP_MAX_MD_SIZE];
+    size_t buf_len = EVP_MAX_MD_SIZE;
+    VALUE ret;
+
+    GetHMAC(self, ctx);
+    if (EVP_DigestSignFinal(ctx, buf, &buf_len) != 1)
+        ossl_raise(eHMACError, "EVP_DigestSignFinal");
+    ret = rb_str_new(NULL, buf_len * 2);
+    ossl_bin2hex(buf, RSTRING_PTR(ret), buf_len);
+
+    return ret;
+}
+
+/*
+ *  call-seq:
+ *     hmac.reset -> self
+ *
+ * Returns _hmac_ as it was when it was first initialized, with all processed
+ * data cleared from it.
+ *
+ * === Example
+ *
+ *	data = "The quick brown fox jumps over the lazy dog"
+ * 	instance = OpenSSL::HMAC.new('key', 'SHA1')
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *
+ * 	instance.update(data)
+ * 	#=> de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9
+ * 	instance.reset
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *
+ */
+static VALUE
+ossl_hmac_reset(VALUE self)
+{
+    EVP_MD_CTX *ctx;
+    EVP_PKEY *pkey;
+
+    GetHMAC(self, ctx);
+    pkey = EVP_PKEY_CTX_get0_pkey(EVP_MD_CTX_get_pkey_ctx(ctx));
+    if (EVP_DigestSignInit(ctx, NULL, EVP_MD_CTX_get0_md(ctx), NULL, pkey) != 1)
+        ossl_raise(eHMACError, "EVP_DigestSignInit");
+
+    return self;
+}
+
+/*
+ * INIT
+ */
+void
+Init_ossl_hmac(void)
+{
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+#endif
+
+    /*
+     * Document-class: OpenSSL::HMAC
+     *
+     * OpenSSL::HMAC allows computing Hash-based Message Authentication Code
+     * (HMAC). It is a type of message authentication code (MAC) involving a
+     * hash function in combination with a key. HMAC can be used to verify the
+     * integrity of a message as well as the authenticity.
+     *
+     * OpenSSL::HMAC has a similar interface to OpenSSL::Digest.
+     *
+     * === HMAC-SHA256 using one-shot interface
+     *
+     *   key = "key"
+     *   data = "message-to-be-authenticated"
+     *   mac = OpenSSL::HMAC.hexdigest("SHA256", key, data)
+     *   #=> "cddb0db23f469c8bf072b21fd837149bd6ace9ab771cceef14c9e517cc93282e"
+     *
+     * === HMAC-SHA256 using incremental interface
+     *
+     *   data1 = File.binread("file1")
+     *   data2 = File.binread("file2")
+     *   key = "key"
+     *   hmac = OpenSSL::HMAC.new(key, 'SHA256')
+     *   hmac << data1
+     *   hmac << data2
+     *   mac = hmac.digest
+     */
+    eHMACError = rb_define_class_under(mOSSL, "HMACError", eOSSLError);
+
+    cHMAC = rb_define_class_under(mOSSL, "HMAC", rb_cObject);
+
+    rb_define_alloc_func(cHMAC, ossl_hmac_alloc);
+
+    rb_define_method(cHMAC, "initialize", ossl_hmac_initialize, 2);
+    rb_define_method(cHMAC, "initialize_copy", ossl_hmac_copy, 1);
+
+    rb_define_method(cHMAC, "reset", ossl_hmac_reset, 0);
+    rb_define_method(cHMAC, "update", ossl_hmac_update, 1);
+    rb_define_alias(cHMAC, "<<", "update");
+    rb_define_method(cHMAC, "digest", ossl_hmac_digest, 0);
+    rb_define_method(cHMAC, "hexdigest", ossl_hmac_hexdigest, 0);
+    rb_define_alias(cHMAC, "inspect", "hexdigest");
+    rb_define_alias(cHMAC, "to_s", "hexdigest");
+}

data/ext/openssl/ossl_hmac.h

@@ -0,0 +1,18 @@
+/*
+ * 'OpenSSL for Ruby' project
+ * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
+ * All rights reserved.
+ */
+/*
+ * This program is licensed under the same licence as Ruby.
+ * (See the file 'LICENCE'.)
+ */
+#if !defined(_OSSL_HMAC_H_)
+#define _OSSL_HMAC_H_
+
+extern VALUE cHMAC;
+extern VALUE eHMACError;
+
+void Init_ossl_hmac(void);
+
+#endif /* _OSSL_HMAC_H_ */

data/ext/openssl/ossl_kdf.c

@@ -0,0 +1,311 @@
+/*
+ * Ruby/OpenSSL Project
+ * Copyright (C) 2007, 2017 Ruby/OpenSSL Project Authors
+ */
+#include "ossl.h"
+#if OSSL_OPENSSL_PREREQ(1, 1, 0) || OSSL_LIBRESSL_PREREQ(3, 6, 0)
+# include <openssl/kdf.h>
+#endif
+
+static VALUE mKDF, eKDF;
+
+/*
+ * call-seq:
+ *   KDF.pbkdf2_hmac(pass, salt:, iterations:, length:, hash:) -> aString
+ *
+ * PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in combination
+ * with HMAC. Takes _pass_, _salt_ and _iterations_, and then derives a key
+ * of _length_ bytes.
+ *
+ * For more information about PBKDF2, see RFC 2898 Section 5.2
+ * (https://tools.ietf.org/html/rfc2898#section-5.2).
+ *
+ * === Parameters
+ * pass       :: The passphrase.
+ * salt       :: The salt. Salts prevent attacks based on dictionaries of common
+ *               passwords and attacks based on rainbow tables. It is a public
+ *               value that can be safely stored along with the password (e.g.
+ *               if the derived value is used for password storage).
+ * iterations :: The iteration count. This provides the ability to tune the
+ *               algorithm. It is better to use the highest count possible for
+ *               the maximum resistance to brute-force attacks.
+ * length     :: The desired length of the derived key in octets.
+ * hash       :: The hash algorithm used with HMAC for the PRF. May be a String
+ *               representing the algorithm name, or an instance of
+ *               OpenSSL::Digest.
+ */
+static VALUE
+kdf_pbkdf2_hmac(int argc, VALUE *argv, VALUE self)
+{
+    VALUE pass, salt, opts, kwargs[4], str;
+    static ID kwargs_ids[4];
+    int iters, len;
+    const EVP_MD *md;
+
+    if (!kwargs_ids[0]) {
+	kwargs_ids[0] = rb_intern_const("salt");
+	kwargs_ids[1] = rb_intern_const("iterations");
+	kwargs_ids[2] = rb_intern_const("length");
+	kwargs_ids[3] = rb_intern_const("hash");
+    }
+    rb_scan_args(argc, argv, "1:", &pass, &opts);
+    rb_get_kwargs(opts, kwargs_ids, 4, 0, kwargs);
+
+    StringValue(pass);
+    salt = StringValue(kwargs[0]);
+    iters = NUM2INT(kwargs[1]);
+    len = NUM2INT(kwargs[2]);
+    md = ossl_evp_get_digestbyname(kwargs[3]);
+
+    str = rb_str_new(0, len);
+    if (!PKCS5_PBKDF2_HMAC(RSTRING_PTR(pass), RSTRING_LENINT(pass),
+			   (unsigned char *)RSTRING_PTR(salt),
+			   RSTRING_LENINT(salt), iters, md, len,
+			   (unsigned char *)RSTRING_PTR(str)))
+	ossl_raise(eKDF, "PKCS5_PBKDF2_HMAC");
+
+    return str;
+}
+
+#if defined(HAVE_EVP_PBE_SCRYPT)
+/*
+ * call-seq:
+ *   KDF.scrypt(pass, salt:, N:, r:, p:, length:) -> aString
+ *
+ * Derives a key from _pass_ using given parameters with the scrypt
+ * password-based key derivation function. The result can be used for password
+ * storage.
+ *
+ * scrypt is designed to be memory-hard and more secure against brute-force
+ * attacks using custom hardwares than alternative KDFs such as PBKDF2 or
+ * bcrypt.
+ *
+ * The keyword arguments _N_, _r_ and _p_ can be used to tune scrypt. RFC 7914
+ * (published on 2016-08, https://tools.ietf.org/html/rfc7914#section-2) states
+ * that using values r=8 and p=1 appears to yield good results.
+ *
+ * See RFC 7914 (https://tools.ietf.org/html/rfc7914) for more information.
+ *
+ * === Parameters
+ * pass   :: Passphrase.
+ * salt   :: Salt.
+ * N      :: CPU/memory cost parameter. This must be a power of 2.
+ * r      :: Block size parameter.
+ * p      :: Parallelization parameter.
+ * length :: Length in octets of the derived key.
+ *
+ * === Example
+ *   pass = "password"
+ *   salt = SecureRandom.random_bytes(16)
+ *   dk = OpenSSL::KDF.scrypt(pass, salt: salt, N: 2**14, r: 8, p: 1, length: 32)
+ *   p dk #=> "\xDA\xE4\xE2...\x7F\xA1\x01T"
+ */
+static VALUE
+kdf_scrypt(int argc, VALUE *argv, VALUE self)
+{
+    VALUE pass, salt, opts, kwargs[5], str;
+    static ID kwargs_ids[5];
+    size_t len;
+    uint64_t N, r, p, maxmem;
+
+    if (!kwargs_ids[0]) {
+	kwargs_ids[0] = rb_intern_const("salt");
+	kwargs_ids[1] = rb_intern_const("N");
+	kwargs_ids[2] = rb_intern_const("r");
+	kwargs_ids[3] = rb_intern_const("p");
+	kwargs_ids[4] = rb_intern_const("length");
+    }
+    rb_scan_args(argc, argv, "1:", &pass, &opts);
+    rb_get_kwargs(opts, kwargs_ids, 5, 0, kwargs);
+
+    StringValue(pass);
+    salt = StringValue(kwargs[0]);
+    N = NUM2UINT64T(kwargs[1]);
+    r = NUM2UINT64T(kwargs[2]);
+    p = NUM2UINT64T(kwargs[3]);
+    len = NUM2LONG(kwargs[4]);
+    /*
+     * OpenSSL uses 32MB by default (if zero is specified), which is too small.
+     * Let's not limit memory consumption but just let malloc() fail inside
+     * OpenSSL. The amount is controllable by other parameters.
+     */
+    maxmem = SIZE_MAX;
+
+    str = rb_str_new(0, len);
+    if (!EVP_PBE_scrypt(RSTRING_PTR(pass), RSTRING_LEN(pass),
+			(unsigned char *)RSTRING_PTR(salt), RSTRING_LEN(salt),
+			N, r, p, maxmem, (unsigned char *)RSTRING_PTR(str), len))
+	ossl_raise(eKDF, "EVP_PBE_scrypt");
+
+    return str;
+}
+#endif
+
+#if OSSL_OPENSSL_PREREQ(1, 1, 0) || OSSL_LIBRESSL_PREREQ(3, 6, 0)
+/*
+ * call-seq:
+ *    KDF.hkdf(ikm, salt:, info:, length:, hash:) -> String
+ *
+ * HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as specified in
+ * {RFC 5869}[https://tools.ietf.org/html/rfc5869].
+ *
+ * New in OpenSSL 1.1.0.
+ *
+ * === Parameters
+ * _ikm_::
+ *   The input keying material.
+ * _salt_::
+ *   The salt.
+ * _info_::
+ *   The context and application specific information.
+ * _length_::
+ *   The output length in octets. Must be <= <tt>255 * HashLen</tt>, where
+ *   HashLen is the length of the hash function output in octets.
+ * _hash_::
+ *   The hash function.
+ *
+ * === Example
+ *   # The values from https://datatracker.ietf.org/doc/html/rfc5869#appendix-A.1
+ *   ikm = ["0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b"].pack("H*")
+ *   salt = ["000102030405060708090a0b0c"].pack("H*")
+ *   info = ["f0f1f2f3f4f5f6f7f8f9"].pack("H*")
+ *   p OpenSSL::KDF.hkdf(ikm, salt: salt, info: info, length: 42, hash: "SHA256").unpack1("H*")
+ *   # => "3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865"
+ */
+static VALUE
+kdf_hkdf(int argc, VALUE *argv, VALUE self)
+{
+    VALUE ikm, salt, info, opts, kwargs[4], str;
+    static ID kwargs_ids[4];
+    int saltlen, ikmlen, infolen;
+    size_t len;
+    const EVP_MD *md;
+    EVP_PKEY_CTX *pctx;
+
+    if (!kwargs_ids[0]) {
+	kwargs_ids[0] = rb_intern_const("salt");
+	kwargs_ids[1] = rb_intern_const("info");
+	kwargs_ids[2] = rb_intern_const("length");
+	kwargs_ids[3] = rb_intern_const("hash");
+    }
+    rb_scan_args(argc, argv, "1:", &ikm, &opts);
+    rb_get_kwargs(opts, kwargs_ids, 4, 0, kwargs);
+
+    StringValue(ikm);
+    ikmlen = RSTRING_LENINT(ikm);
+    salt = StringValue(kwargs[0]);
+    saltlen = RSTRING_LENINT(salt);
+    info = StringValue(kwargs[1]);
+    infolen = RSTRING_LENINT(info);
+    len = (size_t)NUM2LONG(kwargs[2]);
+    if (len > LONG_MAX)
+	rb_raise(rb_eArgError, "length must be non-negative");
+    md = ossl_evp_get_digestbyname(kwargs[3]);
+
+    str = rb_str_new(NULL, (long)len);
+    pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);
+    if (!pctx)
+	ossl_raise(eKDF, "EVP_PKEY_CTX_new_id");
+    if (EVP_PKEY_derive_init(pctx) <= 0) {
+	EVP_PKEY_CTX_free(pctx);
+	ossl_raise(eKDF, "EVP_PKEY_derive_init");
+    }
+    if (EVP_PKEY_CTX_set_hkdf_md(pctx, md) <= 0) {
+	EVP_PKEY_CTX_free(pctx);
+	ossl_raise(eKDF, "EVP_PKEY_CTX_set_hkdf_md");
+    }
+    if (EVP_PKEY_CTX_set1_hkdf_salt(pctx, (unsigned char *)RSTRING_PTR(salt),
+				    saltlen) <= 0) {
+	EVP_PKEY_CTX_free(pctx);
+	ossl_raise(eKDF, "EVP_PKEY_CTX_set_hkdf_salt");
+    }
+    if (EVP_PKEY_CTX_set1_hkdf_key(pctx, (unsigned char *)RSTRING_PTR(ikm),
+				   ikmlen) <= 0) {
+	EVP_PKEY_CTX_free(pctx);
+	ossl_raise(eKDF, "EVP_PKEY_CTX_set_hkdf_key");
+    }
+    if (EVP_PKEY_CTX_add1_hkdf_info(pctx, (unsigned char *)RSTRING_PTR(info),
+				    infolen) <= 0) {
+	EVP_PKEY_CTX_free(pctx);
+	ossl_raise(eKDF, "EVP_PKEY_CTX_set_hkdf_info");
+    }
+    if (EVP_PKEY_derive(pctx, (unsigned char *)RSTRING_PTR(str), &len) <= 0) {
+	EVP_PKEY_CTX_free(pctx);
+	ossl_raise(eKDF, "EVP_PKEY_derive");
+    }
+    rb_str_set_len(str, (long)len);
+    EVP_PKEY_CTX_free(pctx);
+
+    return str;
+}
+#endif
+
+void
+Init_ossl_kdf(void)
+{
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+#endif
+
+    /*
+     * Document-module: OpenSSL::KDF
+     *
+     * Provides functionality of various KDFs (key derivation function).
+     *
+     * KDF is typically used for securely deriving arbitrary length symmetric
+     * keys to be used with an OpenSSL::Cipher from passwords. Another use case
+     * is for storing passwords: Due to the ability to tweak the effort of
+     * computation by increasing the iteration count, computation can be slowed
+     * down artificially in order to render possible attacks infeasible.
+     *
+     * Currently, OpenSSL::KDF provides implementations for the following KDF:
+     *
+     * * PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in
+     *   combination with HMAC
+     * * scrypt
+     * * HKDF
+     *
+     * == Examples
+     * === Generating a 128 bit key for a Cipher (e.g. AES)
+     *   pass = "secret"
+     *   salt = OpenSSL::Random.random_bytes(16)
+     *   iter = 20_000
+     *   key_len = 16
+     *   key = OpenSSL::KDF.pbkdf2_hmac(pass, salt: salt, iterations: iter,
+     *                                  length: key_len, hash: "sha1")
+     *
+     * === Storing Passwords
+     *   pass = "secret"
+     *   # store this with the generated value
+     *   salt = OpenSSL::Random.random_bytes(16)
+     *   iter = 20_000
+     *   hash = OpenSSL::Digest.new('SHA256')
+     *   len = hash.digest_length
+     *   # the final value to be stored
+     *   value = OpenSSL::KDF.pbkdf2_hmac(pass, salt: salt, iterations: iter,
+     *                                    length: len, hash: hash)
+     *
+     * == Important Note on Checking Passwords
+     * When comparing passwords provided by the user with previously stored
+     * values, a common mistake made is comparing the two values using "==".
+     * Typically, "==" short-circuits on evaluation, and is therefore
+     * vulnerable to timing attacks. The proper way is to use a method that
+     * always takes the same amount of time when comparing two values, thus
+     * not leaking any information to potential attackers. To do this, use
+     * +OpenSSL.fixed_length_secure_compare+.
+     */
+    mKDF = rb_define_module_under(mOSSL, "KDF");
+    /*
+     * Generic exception class raised if an error occurs in OpenSSL::KDF module.
+     */
+    eKDF = rb_define_class_under(mKDF, "KDFError", eOSSLError);
+
+    rb_define_module_function(mKDF, "pbkdf2_hmac", kdf_pbkdf2_hmac, -1);
+#if defined(HAVE_EVP_PBE_SCRYPT)
+    rb_define_module_function(mKDF, "scrypt", kdf_scrypt, -1);
+#endif
+#if OSSL_OPENSSL_PREREQ(1, 1, 0) || OSSL_LIBRESSL_PREREQ(3, 6, 0)
+    rb_define_module_function(mKDF, "hkdf", kdf_hkdf, -1);
+#endif
+}

data/ext/openssl/ossl_kdf.h

@@ -0,0 +1,6 @@
+#if !defined(OSSL_KDF_H)
+#define OSSL_KDF_H
+
+void Init_ossl_kdf(void);
+
+#endif