kdf: introduce OpenSSL::KDF module

Introduce a new OpenSSL::KDF module as a namespace for to-be-added
KDFs. This makes it easier to add new KDFs in future.

We already have a stand-alone KDF, OpenSSL::PKCS5.pbkdf2_hmac. This is
migrated to the new namespace. The backwards compatibility is retained
by the method defined in the newly added lib/openssl/pkcs5.rb.

6 files changed, 151 insertions, 180 deletions

diff --git a/ext/openssl/ossl.c b/ext/openssl/ossl.c
index bcadc3e1..793eb729 100644
--- a/ext/openssl/ossl.c
+++ b/ext/openssl/ossl.c
@@ -1169,7 +1169,6 @@ Init_openssl(void)
     Init_ossl_ns_spki();
     Init_ossl_pkcs12();
     Init_ossl_pkcs7();
-    Init_ossl_pkcs5();
     Init_ossl_pkey();
     Init_ossl_rand();
     Init_ossl_ssl();
@@ -1177,6 +1176,7 @@ Init_openssl(void)
     Init_ossl_ocsp();
     Init_ossl_engine();
     Init_ossl_asn1();
+    Init_ossl_kdf();
 
 #if defined(OSSL_DEBUG)
     /*
diff --git a/ext/openssl/ossl.h b/ext/openssl/ossl.h
index 78eddd09..999e8708 100644
--- a/ext/openssl/ossl.h
+++ b/ext/openssl/ossl.h
@@ -173,13 +173,13 @@ void ossl_debug(const char *, ...);
 #include "ossl_ocsp.h"
 #include "ossl_pkcs12.h"
 #include "ossl_pkcs7.h"
-#include "ossl_pkcs5.h"
 #include "ossl_pkey.h"
 #include "ossl_rand.h"
 #include "ossl_ssl.h"
 #include "ossl_version.h"
 #include "ossl_x509.h"
 #include "ossl_engine.h"
+#include "ossl_kdf.h"
 
 void Init_openssl(void);
 
diff --git a/ext/openssl/ossl_kdf.c b/ext/openssl/ossl_kdf.c
new file mode 100644
index 00000000..c785ee6d
--- /dev/null
+++ b/ext/openssl/ossl_kdf.c
@@ -0,0 +1,143 @@
+/*
+ * 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 = GetDigestPtr(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;
+}
+
+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
+     *
+     * == 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);
+}
diff --git a/ext/openssl/ossl_kdf.h b/ext/openssl/ossl_kdf.h
new file mode 100644
index 00000000..b6503f8d
--- /dev/null
+++ b/ext/openssl/ossl_kdf.h
@@ -0,0 +1,6 @@
+#if !defined(OSSL_KDF_H)
+#define OSSL_KDF_H
+
+void Init_ossl_kdf(void);
+
+#endif
diff --git a/ext/openssl/ossl_pkcs5.c b/ext/openssl/ossl_pkcs5.c
deleted file mode 100644
index 7811c5fe..00000000
--- a/ext/openssl/ossl_pkcs5.c
+++ /dev/null
@@ -1,172 +0,0 @@
-/*
- * Copyright (C) 2007 Technorama Ltd. <oss-ruby@technorama.net>
- */
-#include "ossl.h"
-
-VALUE mPKCS5;
-VALUE ePKCS5;
-
-/*
- * call-seq:
- *    PKCS5.pbkdf2_hmac(pass, salt, iter, keylen, digest) => string
- *
- * === Parameters
- * * +pass+ - string
- * * +salt+ - string - should be at least 8 bytes long.
- * * +iter+ - integer - should be greater than 1000.  20000 is better.
- * * +keylen+ - integer
- * * +digest+ - a string or OpenSSL::Digest object.
- *
- * Digests other than SHA1 may not be supported by other cryptography libraries.
- */
-static VALUE
-ossl_pkcs5_pbkdf2_hmac(VALUE self, VALUE pass, VALUE salt, VALUE iter, VALUE keylen, VALUE digest)
-{
-    VALUE str;
-    const EVP_MD *md;
-    int len = NUM2INT(keylen);
-
-    StringValue(pass);
-    StringValue(salt);
-    md = GetDigestPtr(digest);
-
-    str = rb_str_new(0, len);
-
-    if (PKCS5_PBKDF2_HMAC(RSTRING_PTR(pass), RSTRING_LENINT(pass),
-			  (unsigned char *)RSTRING_PTR(salt), RSTRING_LENINT(salt),
-			  NUM2INT(iter), md, len,
-			  (unsigned char *)RSTRING_PTR(str)) != 1)
-        ossl_raise(ePKCS5, "PKCS5_PBKDF2_HMAC");
-
-    return str;
-}
-
-/*
- * call-seq:
- *    PKCS5.pbkdf2_hmac_sha1(pass, salt, iter, keylen) => string
- *
- * === Parameters
- * * +pass+ - string
- * * +salt+ - string - should be at least 8 bytes long.
- * * +iter+ - integer - should be greater than 1000.  20000 is better.
- * * +keylen+ - integer
- *
- * This method is available in almost any version of OpenSSL.
- *
- * Conforms to RFC 2898.
- */
-static VALUE
-ossl_pkcs5_pbkdf2_hmac_sha1(VALUE self, VALUE pass, VALUE salt, VALUE iter, VALUE keylen)
-{
-    VALUE str;
-    int len = NUM2INT(keylen);
-
-    StringValue(pass);
-    StringValue(salt);
-
-    str = rb_str_new(0, len);
-
-    if (PKCS5_PBKDF2_HMAC_SHA1(RSTRING_PTR(pass), RSTRING_LENINT(pass),
-			       (const unsigned char *)RSTRING_PTR(salt), RSTRING_LENINT(salt), NUM2INT(iter),
-			       len, (unsigned char *)RSTRING_PTR(str)) != 1)
-        ossl_raise(ePKCS5, "PKCS5_PBKDF2_HMAC_SHA1");
-
-    return str;
-}
-
-void
-Init_ossl_pkcs5(void)
-{
-#if 0
-    mOSSL = rb_define_module("OpenSSL");
-    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
-#endif
-
-    /* Document-class: OpenSSL::PKCS5
-     *
-     * Provides password-based encryption functionality based on PKCS#5.
-     * 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.
-     *
-     * PKCS5 offers support for PBKDF2 with an OpenSSL::Digest::SHA1-based
-     * HMAC, or an arbitrary Digest.
-     *
-     * === Parameters
-     * ==== Password
-     * Typically an arbitrary String that represents the password to be used
-     * for deriving a key.
-     * ==== Salt
-     * Prevents attacks based on dictionaries of common passwords. It is a
-     * public value that can be safely stored along with the password (e.g.
-     * if PBKDF2 is used for password storage). For maximum security, a fresh,
-     * random salt should be generated for each stored password. According
-     * to PKCS#5, a salt should be at least 8 bytes long.
-     * ==== Iteration Count
-     * Allows to tweak the length that the actual computation will take. The
-     * larger the iteration count, the longer it will take.
-     * ==== Key Length
-     * Specifies the length in bytes of the output that will be generated.
-     * Typically, the key length should be larger than or equal to the output
-     * length of the underlying digest function, otherwise an attacker could
-     * simply try to brute-force the key. According to PKCS#5, security is
-     * limited by the output length of the underlying digest function, i.e.
-     * security is not improved if a key length strictly larger than the
-     * digest output length is chosen. Therefore, when using PKCS5 for
-     * password storage, it suffices to store values equal to the digest
-     * output length, nothing is gained by storing larger values.
-     *
-     * == Examples
-     * === Generating a 128 bit key for a Cipher (e.g. AES)
-     *   pass = "secret"
-     *   salt = OpenSSL::Random.random_bytes(16)
-     *   iter = 20000
-     *   key_len = 16
-     *   key = OpenSSL::PKCS5.pbkdf2_hmac_sha1(pass, salt, iter, key_len)
-     *
-     * === Storing Passwords
-     *   pass = "secret"
-     *   salt = OpenSSL::Random.random_bytes(16) #store this with the generated value
-     *   iter = 20000
-     *   digest = OpenSSL::Digest::SHA256.new
-     *   len = digest.digest_length
-     *   #the final value to be stored
-     *   value = OpenSSL::PKCS5.pbkdf2_hmac(pass, salt, iter, len, digest)
-     *
-     * === 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.to_a
-     *     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 PKCS#5, the
-     * length of the values to be compared is of fixed size.
-     */
-
-    mPKCS5 = rb_define_module_under(mOSSL, "PKCS5");
-    /* Document-class: OpenSSL::PKCS5::PKCS5Error
-     *
-     * Generic Exception class that is raised if an error occurs during a
-     * computation.
-     */
-    ePKCS5 = rb_define_class_under(mPKCS5, "PKCS5Error", eOSSLError);
-
-    rb_define_module_function(mPKCS5, "pbkdf2_hmac", ossl_pkcs5_pbkdf2_hmac, 5);
-    rb_define_module_function(mPKCS5, "pbkdf2_hmac_sha1", ossl_pkcs5_pbkdf2_hmac_sha1, 4);
-}
diff --git a/ext/openssl/ossl_pkcs5.h b/ext/openssl/ossl_pkcs5.h
deleted file mode 100644
index a3b132bc..00000000
--- a/ext/openssl/ossl_pkcs5.h
+++ /dev/null
@@ -1,6 +0,0 @@
-#if !defined(_OSSL_PKCS5_H_)
-#define _OSSL_PKCS5_H_
-
-void Init_ossl_pkcs5(void);
-
-#endif /* _OSSL_PKCS5_H_ */