openssl 2.0.9 → 2.1.0.beta1

data/ext/openssl/ossl_cipher.h

@@ -13,7 +13,7 @@
 extern VALUE cCipher;
 extern VALUE eCipherError;
 
-const EVP_CIPHER *GetCipherPtr(VALUE);
+const EVP_CIPHER *ossl_evp_get_cipherbyname(VALUE);
 VALUE ossl_cipher_new(const EVP_CIPHER *);
 void Init_ossl_cipher(void);
 

data/ext/openssl/ossl_digest.c

@@ -15,10 +15,6 @@
 	ossl_raise(rb_eRuntimeError, "Digest CTX wasn't initialized!"); \
     } \
 } while (0)
-#define SafeGetDigest(obj, ctx) do { \
-    OSSL_Check_Kind((obj), cDigest); \
-    GetDigest((obj), (ctx)); \
-} while (0)
 
 /*
  * Classes
@@ -46,7 +42,7 @@ static const rb_data_type_t ossl_digest_type = {
  * Public
  */
 const EVP_MD *
-GetDigestPtr(VALUE obj)
+ossl_evp_get_digestbyname(VALUE obj)
 {
     const EVP_MD *md;
     ASN1_OBJECT *oid = NULL;
@@ -65,7 +61,7 @@ GetDigestPtr(VALUE obj)
     } else {
         EVP_MD_CTX *ctx;
 
-        SafeGetDigest(obj, ctx);
+        GetDigest(obj, ctx);
 
         md = EVP_MD_CTX_md(ctx);
     }
@@ -106,15 +102,15 @@ VALUE ossl_digest_update(VALUE, VALUE);
  *  call-seq:
  *     Digest.new(string [, data]) -> Digest
  *
- * Creates a Digest instance based on +string+, which is either the ln
+ * Creates a Digest instance based on _string_, which is either the ln
  * (long name) or sn (short name) of a supported digest algorithm.
  *
- * If +data+ (a +String+) is given, it is used as the initial input to the
+ * If _data_ (a String) is given, it is used as the initial input to the
  * Digest instance, i.e.
  *
  *   digest = OpenSSL::Digest.new('sha256', 'digestdata')
  *
- * is equal to
+ * is equivalent to
  *
  *   digest = OpenSSL::Digest.new('sha256')
  *   digest.update('digestdata')
@@ -127,7 +123,7 @@ ossl_digest_initialize(int argc, VALUE *argv, VALUE self)
     VALUE type, data;
 
     rb_scan_args(argc, argv, "11", &type, &data);
-    md = GetDigestPtr(type);
+    md = ossl_evp_get_digestbyname(type);
     if (!NIL_P(data)) StringValue(data);
 
     TypedData_Get_Struct(self, EVP_MD_CTX, &ossl_digest_type, ctx);
@@ -158,7 +154,7 @@ ossl_digest_copy(VALUE self, VALUE other)
 	if (!ctx1)
 	    ossl_raise(eDigestError, "EVP_MD_CTX_new");
     }
-    SafeGetDigest(other, ctx2);
+    GetDigest(other, ctx2);
 
     if (!EVP_MD_CTX_copy(ctx1, ctx2)) {
 	ossl_raise(eDigestError, NULL);
@@ -448,7 +444,7 @@ Init_ossl_digest(void)
     rb_define_alloc_func(cDigest, ossl_digest_alloc);
 
     rb_define_method(cDigest, "initialize", ossl_digest_initialize, -1);
-    rb_define_copy_func(cDigest, ossl_digest_copy);
+    rb_define_method(cDigest, "initialize_copy", ossl_digest_copy, 1);
     rb_define_method(cDigest, "reset", ossl_digest_reset, 0);
     rb_define_method(cDigest, "update", ossl_digest_update, 1);
     rb_define_alias(cDigest, "<<", "update");

data/ext/openssl/ossl_digest.h

@@ -13,7 +13,7 @@
 extern VALUE cDigest;
 extern VALUE eDigestError;
 
-const EVP_MD *GetDigestPtr(VALUE);
+const EVP_MD *ossl_evp_get_digestbyname(VALUE);
 VALUE ossl_digest_new(const EVP_MD *);
 void Init_ossl_digest(void);
 

data/ext/openssl/ossl_engine.c

@@ -25,10 +25,6 @@
         ossl_raise(rb_eRuntimeError, "ENGINE wasn't initialized."); \
     } \
 } while (0)
-#define SafeGetEngine(obj, engine) do { \
-    OSSL_Check_Kind((obj), cEngine); \
-    GetPKCS7((obj), (engine)); \
-} while (0)
 
 /*
  * Classes
@@ -72,14 +68,13 @@ static const rb_data_type_t ossl_engine_type = {
     0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
 };
 
-/* Document-method: OpenSSL::Engine.load
- *
+/*
  * call-seq:
- *   load(enginename = nil)
+ *    OpenSSL::Engine.load(name = nil)
  *
- * This method loads engines. If +name+ is nil, then all builtin engines are
- * loaded. Otherwise, the given +name+, as a string,  is loaded if available to
- * your runtime, and returns true. If +name+ is not found, then nil is
+ * This method loads engines. If _name_ is nil, then all builtin engines are
+ * loaded. Otherwise, the given _name_, as a String,  is loaded if available to
+ * your runtime, and returns true. If _name_ is not found, then nil is
  * returned.
  *
  */
@@ -153,9 +148,9 @@ ossl_engine_s_load(int argc, VALUE *argv, VALUE klass)
 #endif /* HAVE_ENGINE_LOAD_BUILTIN_ENGINES */
 }
 
-/* Document-method: OpenSSL::Engine.cleanup
+/*
  * call-seq:
- *  OpenSSL::Engine.cleanup
+ *    OpenSSL::Engine.cleanup
  *
  * It is only necessary to run cleanup when engines are loaded via
  * OpenSSL::Engine.load. However, running cleanup before exit is recommended.
@@ -169,7 +164,9 @@ ossl_engine_s_cleanup(VALUE self)
     return Qnil;
 }
 
-/* Document-method: OpenSSL::Engine.engines
+/*
+ * call-seq:
+ *    OpenSSL::Engine.engines -> [engine, ...]
  *
  * Returns an array of currently loaded engines.
  */
@@ -193,17 +190,16 @@ ossl_engine_s_engines(VALUE klass)
     return ary;
 }
 
-/* Document-method: OpenSSL::Engine.by_id
- *
+/*
  * call-seq:
- *   by_id(name) -> engine
+ *    OpenSSL::Engine.by_id(name) -> engine
  *
- * Fetch the engine as specified by the +id+ String
+ * Fetches the engine as specified by the _id_ String.
  *
  *   OpenSSL::Engine.by_id("openssl")
  *    => #<OpenSSL::Engine id="openssl" name="Software engine support">
  *
- * See OpenSSL::Engine.engines for the currently loaded engines
+ * See OpenSSL::Engine.engines for the currently loaded engines.
  */
 static VALUE
 ossl_engine_s_by_id(VALUE klass, VALUE id)
@@ -227,9 +223,11 @@ ossl_engine_s_by_id(VALUE klass, VALUE id)
     return obj;
 }
 
-/* Document-method: OpenSSL::Engine#id
+/*
+ * call-seq:
+ *    engine.id -> string
  *
- * Get the id for this engine
+ * Gets the id for this engine.
  *
  *    OpenSSL::Engine.load
  *    OpenSSL::Engine.engines #=> [#<OpenSSL::Engine#>, ...]
@@ -244,9 +242,11 @@ ossl_engine_get_id(VALUE self)
     return rb_str_new2(ENGINE_get_id(e));
 }
 
-/* Document-method: OpenSSL::Engine#name
+/*
+ * call-seq:
+ *    engine.name -> string
  *
- * Get the descriptive name for this engine
+ * Get the descriptive name for this engine.
  *
  *    OpenSSL::Engine.load
  *    OpenSSL::Engine.engines #=> [#<OpenSSL::Engine#>, ...]
@@ -262,7 +262,9 @@ ossl_engine_get_name(VALUE self)
     return rb_str_new2(ENGINE_get_name(e));
 }
 
-/* Document-method: OpenSSL::Engine#finish
+/*
+ * call-seq:
+ *    engine.finish -> nil
  *
  * Releases all internal structural references for this engine.
  *
@@ -279,13 +281,12 @@ ossl_engine_finish(VALUE self)
     return Qnil;
 }
 
-/* Document-method: OpenSSL::Engine#cipher
- *
+/*
  * call-seq:
  *   engine.cipher(name) -> OpenSSL::Cipher
  *
- * This returns an OpenSSL::Cipher by +name+, if it is available in this
- * engine.
+ * Returns a new instance of OpenSSL::Cipher by _name_, if it is available in
+ * this engine.
  *
  * An EngineError will be raised if the cipher is unavailable.
  *
@@ -312,12 +313,11 @@ ossl_engine_get_cipher(VALUE self, VALUE name)
     return ossl_cipher_new(ciph);
 }
 
-/* Document-method: OpenSSL::Engine#digest
- *
+/*
  * call-seq:
  *   engine.digest(name) -> OpenSSL::Digest
  *
- * This returns an OpenSSL::Digest by +name+.
+ * Returns a new instance of OpenSSL::Digest by _name_.
  *
  * Will raise an EngineError if the digest is unavailable.
  *
@@ -345,12 +345,11 @@ ossl_engine_get_digest(VALUE self, VALUE name)
     return ossl_digest_new(md);
 }
 
-/* Document-method: OpenSSL::Engine#load_private_key
- *
+/*
  * call-seq:
  *    engine.load_private_key(id = nil, data = nil) -> OpenSSL::PKey
  *
- * Loads the given private key by +id+ and +data+.
+ * Loads the given private key identified by _id_ and _data_.
  *
  * An EngineError is raised of the OpenSSL::PKey is unavailable.
  *
@@ -375,12 +374,11 @@ ossl_engine_load_privkey(int argc, VALUE *argv, VALUE self)
     return obj;
 }
 
-/* Document-method: OpenSSL::Engine#load_public_key
- *
+/*
  * call-seq:
  *    engine.load_public_key(id = nil, data = nil) -> OpenSSL::PKey
  *
- * Loads the given private key by +id+ and +data+.
+ * Loads the given public key identified by _id_ and _data_.
  *
  * An EngineError is raised of the OpenSSL::PKey is unavailable.
  *
@@ -403,16 +401,15 @@ ossl_engine_load_pubkey(int argc, VALUE *argv, VALUE self)
     return ossl_pkey_new(pkey);
 }
 
-/* Document-method: OpenSSL::Engine#set_default
- *
+/*
  * call-seq:
  *    engine.set_default(flag)
  *
- * Set the defaults for this engine with the given +flag+.
+ * Set the defaults for this engine with the given _flag_.
  *
  * These flags are used to control combinations of algorithm methods.
  *
- * +flag+ can be one of the following, other flags are available depending on
+ * _flag_ can be one of the following, other flags are available depending on
  * your OS.
  *
  * [All flags]  0xFFFF
@@ -432,14 +429,13 @@ ossl_engine_set_default(VALUE self, VALUE flag)
     return Qtrue;
 }
 
-/* Document-method: OpenSSL::Engine#ctrl_cmd
- *
+/*
  * call-seq:
  *    engine.ctrl_cmd(command, value = nil) -> engine
  *
- * Send the given +command+ to this engine.
+ * Sends the given _command_ to this engine.
  *
- * Raises an EngineError if the +command+ fails.
+ * Raises an EngineError if the command fails.
  */
 static VALUE
 ossl_engine_ctrl_cmd(int argc, VALUE *argv, VALUE self)
@@ -469,7 +465,9 @@ ossl_engine_cmd_flag_to_name(int flag)
     }
 }
 
-/* Document-method: OpenSSL::Engine#cmds
+/*
+ * call-seq:
+ *    engine.cmds -> [["name", "description", "flags"], ...]
  *
  * Returns an array of command definitions for the current engine
  */
@@ -495,9 +493,11 @@ ossl_engine_get_cmds(VALUE self)
     return ary;
 }
 
-/* Document-method: OpenSSL::Engine#inspect
+/*
+ * call-seq:
+ *    engine.inspect -> string
  *
- * Pretty print this engine
+ * Pretty prints this engine.
  */
 static VALUE
 ossl_engine_inspect(VALUE self)

data/ext/openssl/ossl_hmac.c

@@ -19,10 +19,6 @@
 	ossl_raise(rb_eRuntimeError, "HMAC wasn't initialized"); \
     } \
 } while (0)
-#define SafeGetHMAC(obj, ctx) do { \
-    OSSL_Check_Kind((obj), cHMAC); \
-    GetHMAC((obj), (ctx)); \
-} while (0)
 
 /*
  * Classes
@@ -110,7 +106,7 @@ ossl_hmac_initialize(VALUE self, VALUE key, VALUE digest)
     StringValue(key);
     GetHMAC(self, ctx);
     HMAC_Init_ex(ctx, RSTRING_PTR(key), RSTRING_LENINT(key),
-		 GetDigestPtr(digest), NULL);
+		 ossl_evp_get_digestbyname(digest), NULL);
 
     return self;
 }
@@ -124,7 +120,7 @@ ossl_hmac_copy(VALUE self, VALUE other)
     if (self == other) return self;
 
     GetHMAC(self, ctx1);
-    SafeGetHMAC(other, ctx2);
+    GetHMAC(other, ctx2);
 
     if (!HMAC_CTX_copy(ctx1, ctx2))
 	ossl_raise(eHMACError, "HMAC_CTX_copy");
@@ -135,7 +131,7 @@ ossl_hmac_copy(VALUE self, VALUE other)
  *  call-seq:
  *     hmac.update(string) -> self
  *
- * Returns +self+ updated with the message to be authenticated.
+ * Returns _hmac_ updated with the message to be authenticated.
  * Can be called repeatedly with chunks of the message.
  *
  * === Example
@@ -234,7 +230,7 @@ ossl_hmac_hexdigest(VALUE self)
  *  call-seq:
  *     hmac.reset -> self
  *
- * Returns +self+ as it was when it was first initialized, with all processed
+ * Returns _hmac_ as it was when it was first initialized, with all processed
  * data cleared from it.
  *
  * === Example
@@ -264,16 +260,16 @@ ossl_hmac_reset(VALUE self)
  *  call-seq:
  *     HMAC.digest(digest, key, data) -> aString
  *
- * Returns the authentication code as a binary string. The +digest+ parameter
- * must be an instance of OpenSSL::Digest.
+ * Returns the authentication code as a binary string. The _digest_ parameter
+ * specifies the digest algorithm to use. This may be a String representing
+ * the algorithm name or an instance of OpenSSL::Digest.
  *
  * === Example
  *
  *	key = 'key'
  * 	data = 'The quick brown fox jumps over the lazy dog'
- * 	digest = OpenSSL::Digest.new('sha1')
  *
- * 	hmac = OpenSSL::HMAC.digest(digest, key, data)
+ * 	hmac = OpenSSL::HMAC.digest('sha1', key, data)
  * 	#=> "\xDE|\x9B\x85\xB8\xB7\x8A\xA6\xBC\x8Az6\xF7\n\x90p\x1C\x9D\xB4\xD9"
  *
  */
@@ -285,8 +281,9 @@ ossl_hmac_s_digest(VALUE klass, VALUE digest, VALUE key, VALUE data)
 
     StringValue(key);
     StringValue(data);
-    buf = HMAC(GetDigestPtr(digest), RSTRING_PTR(key), RSTRING_LENINT(key),
-	       (unsigned char *)RSTRING_PTR(data), RSTRING_LEN(data), NULL, &buf_len);
+    buf = HMAC(ossl_evp_get_digestbyname(digest), RSTRING_PTR(key),
+	       RSTRING_LENINT(key), (unsigned char *)RSTRING_PTR(data),
+	       RSTRING_LEN(data), NULL, &buf_len);
 
     return rb_str_new((const char *)buf, buf_len);
 }
@@ -295,16 +292,16 @@ ossl_hmac_s_digest(VALUE klass, VALUE digest, VALUE key, VALUE data)
  *  call-seq:
  *     HMAC.hexdigest(digest, key, data) -> aString
  *
- * Returns the authentication code as a hex-encoded string. The +digest+
- * parameter must be an instance of OpenSSL::Digest.
+ * Returns the authentication code as a hex-encoded string. The _digest_
+ * parameter specifies the digest algorithm to use. This may be a String
+ * representing the algorithm name or an instance of OpenSSL::Digest.
  *
  * === Example
  *
  *	key = 'key'
  * 	data = 'The quick brown fox jumps over the lazy dog'
- * 	digest = OpenSSL::Digest.new('sha1')
  *
- * 	hmac = OpenSSL::HMAC.hexdigest(digest, key, data)
+ * 	hmac = OpenSSL::HMAC.hexdigest('sha1', key, data)
  * 	#=> "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9"
  *
  */
@@ -318,9 +315,9 @@ ossl_hmac_s_hexdigest(VALUE klass, VALUE digest, VALUE key, VALUE data)
     StringValue(key);
     StringValue(data);
 
-    if (!HMAC(GetDigestPtr(digest), RSTRING_PTR(key), RSTRING_LENINT(key),
-	      (unsigned char *)RSTRING_PTR(data), RSTRING_LEN(data),
-	      buf, &buf_len))
+    if (!HMAC(ossl_evp_get_digestbyname(digest), RSTRING_PTR(key),
+	      RSTRING_LENINT(key), (unsigned char *)RSTRING_PTR(data),
+	      RSTRING_LEN(data), buf, &buf_len))
 	ossl_raise(eHMACError, "HMAC");
 
     ret = rb_str_new(NULL, buf_len * 2);
@@ -377,7 +374,7 @@ Init_ossl_hmac(void)
     rb_define_singleton_method(cHMAC, "hexdigest", ossl_hmac_s_hexdigest, 3);
 
     rb_define_method(cHMAC, "initialize", ossl_hmac_initialize, 2);
-    rb_define_copy_func(cHMAC, ossl_hmac_copy);
+    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);

data/ext/openssl/ossl_kdf.c

@@ -0,0 +1,221 @@
+/*
+ * Ruby/OpenSSL Project
+ * Copyright (C) 2007, 2017 Ruby/OpenSSL Project Authors
+ */
+#include "ossl.h"
+
+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
+
+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
+     *
+     * == 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::SHA256.new
+     *   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 compare two
+     * values, the following could be used:
+     *
+     *   def eql_time_cmp(a, b)
+     *     unless a.length == b.length
+     *       return false
+     *     end
+     *     cmp = b.bytes
+     *     result = 0
+     *     a.bytes.each_with_index {|c,i|
+     *       result |= c ^ cmp[i]
+     *     }
+     *     result == 0
+     *   end
+     *
+     * Please note that the premature return in case of differing lengths
+     * typically does not leak valuable information - when using PBKDF2, the
+     * length of the values to be compared is of fixed size.
+     */
+    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
+}