rubysl-openssl 1.0.2 → 2.0.0

data/ext/rubysl/openssl/ossl_ns_spki.h

@@ -1,5 +1,5 @@
 /*
- * $Id: ossl_ns_spki.h 11708 2007-02-12 23:01:19Z shyouhei $
+ * $Id$
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
  * All rights reserved.

data/ext/rubysl/openssl/ossl_ocsp.c

@@ -14,55 +14,55 @@
 #if defined(OSSL_OCSP_ENABLED)
 
 #define WrapOCSPReq(klass, obj, req) do { \
-    if(!req) ossl_raise(rb_eRuntimeError, "Request wasn't initialized!"); \
-    obj = Data_Wrap_Struct(klass, 0, OCSP_REQUEST_free, req); \
+    if(!(req)) ossl_raise(rb_eRuntimeError, "Request wasn't initialized!"); \
+    (obj) = Data_Wrap_Struct((klass), 0, OCSP_REQUEST_free, (req)); \
 } while (0)
 #define GetOCSPReq(obj, req) do { \
-    Data_Get_Struct(obj, OCSP_REQUEST, req); \
-    if(!req) ossl_raise(rb_eRuntimeError, "Request wasn't initialized!"); \
+    Data_Get_Struct((obj), OCSP_REQUEST, (req)); \
+    if(!(req)) ossl_raise(rb_eRuntimeError, "Request wasn't initialized!"); \
 } while (0)
 #define SafeGetOCSPReq(obj, req) do { \
-    OSSL_Check_Kind(obj, cOCSPReq); \
-    GetOCSPReq(obj, req); \
+    OSSL_Check_Kind((obj), cOCSPReq); \
+    GetOCSPReq((obj), (req)); \
 } while (0)
 
 #define WrapOCSPRes(klass, obj, res) do { \
-    if(!res) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
-    obj = Data_Wrap_Struct(klass, 0, OCSP_RESPONSE_free, res); \
+    if(!(res)) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
+    (obj) = Data_Wrap_Struct((klass), 0, OCSP_RESPONSE_free, (res)); \
 } while (0)
 #define GetOCSPRes(obj, res) do { \
-    Data_Get_Struct(obj, OCSP_RESPONSE, res); \
-    if(!res) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
+    Data_Get_Struct((obj), OCSP_RESPONSE, (res)); \
+    if(!(res)) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
 } while (0)
 #define SafeGetOCSPRes(obj, res) do { \
-    OSSL_Check_Kind(obj, cOCSPRes); \
-    GetOCSPRes(obj, res); \
+    OSSL_Check_Kind((obj), cOCSPRes); \
+    GetOCSPRes((obj), (res)); \
 } while (0)
 
 #define WrapOCSPBasicRes(klass, obj, res) do { \
-    if(!res) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
-    obj = Data_Wrap_Struct(klass, 0, OCSP_BASICRESP_free, res); \
+    if(!(res)) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
+    (obj) = Data_Wrap_Struct((klass), 0, OCSP_BASICRESP_free, (res)); \
 } while (0)
 #define GetOCSPBasicRes(obj, res) do { \
-    Data_Get_Struct(obj, OCSP_BASICRESP, res); \
-    if(!res) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
+    Data_Get_Struct((obj), OCSP_BASICRESP, (res)); \
+    if(!(res)) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
 } while (0)
 #define SafeGetOCSPBasicRes(obj, res) do { \
-    OSSL_Check_Kind(obj, cOCSPBasicRes); \
-    GetOCSPBasicRes(obj, res); \
+    OSSL_Check_Kind((obj), cOCSPBasicRes); \
+    GetOCSPBasicRes((obj), (res)); \
 } while (0)
 
 #define WrapOCSPCertId(klass, obj, cid) do { \
-    if(!cid) ossl_raise(rb_eRuntimeError, "Cert ID wasn't initialized!"); \
-    obj = Data_Wrap_Struct(klass, 0, OCSP_CERTID_free, cid); \
+    if(!(cid)) ossl_raise(rb_eRuntimeError, "Cert ID wasn't initialized!"); \
+    (obj) = Data_Wrap_Struct((klass), 0, OCSP_CERTID_free, (cid)); \
 } while (0)
 #define GetOCSPCertId(obj, cid) do { \
-    Data_Get_Struct(obj, OCSP_CERTID, cid); \
-    if(!cid) ossl_raise(rb_eRuntimeError, "Cert ID wasn't initialized!"); \
+    Data_Get_Struct((obj), OCSP_CERTID, (cid)); \
+    if(!(cid)) ossl_raise(rb_eRuntimeError, "Cert ID wasn't initialized!"); \
 } while (0)
 #define SafeGetOCSPCertId(obj, cid) do { \
-    OSSL_Check_Kind(obj, cOCSPCertId); \
-    GetOCSPCertId(obj, cid); \
+    OSSL_Check_Kind((obj), cOCSPCertId); \
+    GetOCSPCertId((obj), (cid)); \
 } while (0)
 
 VALUE mOCSP;
@@ -107,11 +107,13 @@ ossl_ocspreq_initialize(int argc, VALUE *argv, VALUE self)
 
     rb_scan_args(argc, argv, "01", &arg);
     if(!NIL_P(arg)){
+	OCSP_REQUEST *req = DATA_PTR(self), *x;
 	arg = ossl_to_der_if_possible(arg);
 	StringValue(arg);
-	p = (const unsigned char*)RSTRING_PTR(arg);
-	if(!d2i_OCSP_REQUEST((OCSP_REQUEST**)&DATA_PTR(self), &p,
-			     RSTRING_LEN(arg))){
+	p = (unsigned char*)RSTRING_PTR(arg);
+	x = d2i_OCSP_REQUEST(&req, &p, RSTRING_LEN(arg));
+	DATA_PTR(self) = req;
+	if(!x){
 	    ossl_raise(eOCSPError, "cannot load DER encoded request");
 	}
     }
@@ -134,7 +136,7 @@ ossl_ocspreq_add_nonce(int argc, VALUE *argv, VALUE self)
     else{
 	StringValue(val);
 	GetOCSPReq(self, req);
-	ret = OCSP_request_add1_nonce(req, RSTRING_PTR(val), RSTRING_LEN(val));
+	ret = OCSP_request_add1_nonce(req, (unsigned char *)RSTRING_PTR(val), RSTRING_LENINT(val));
     }
     if(!ret) ossl_raise(eOCSPError, NULL);
 
@@ -243,7 +245,7 @@ ossl_ocspreq_verify(int argc, VALUE *argv, VALUE self)
 
     rb_scan_args(argc, argv, "21", &certs, &store, &flags);
     x509st = GetX509StorePtr(store);
-    flg = NIL_P(flags) ? 0 : INT2NUM(flags);
+    flg = NIL_P(flags) ? 0 : NUM2INT(flags);
     x509s = ossl_x509_ary2sk(certs);
     GetOCSPReq(self, req);
     result = OCSP_request_verify(req, x509s, x509st, flg);
@@ -265,7 +267,7 @@ ossl_ocspreq_to_der(VALUE self)
     if((len = i2d_OCSP_REQUEST(req, NULL)) <= 0)
 	ossl_raise(eOCSPError, NULL);
     str = rb_str_new(0, len);
-    p = RSTRING_PTR(str);
+    p = (unsigned char *)RSTRING_PTR(str);
     if(i2d_OCSP_REQUEST(req, &p) <= 0)
 	ossl_raise(eOCSPError, NULL);
     ossl_str_adjust(str, p);
@@ -314,11 +316,13 @@ ossl_ocspres_initialize(int argc, VALUE *argv, VALUE self)
 
     rb_scan_args(argc, argv, "01", &arg);
     if(!NIL_P(arg)){
+	OCSP_RESPONSE *res = DATA_PTR(self), *x;
 	arg = ossl_to_der_if_possible(arg);
 	StringValue(arg);
-	p = (const unsigned char*) RSTRING_PTR(arg);
-	if(!d2i_OCSP_RESPONSE((OCSP_RESPONSE**)&DATA_PTR(self), &p,
-			      RSTRING_LEN(arg))){
+	p = (unsigned char *)RSTRING_PTR(arg);
+	x = d2i_OCSP_RESPONSE(&res, &p, RSTRING_LEN(arg));
+	DATA_PTR(self) = res;
+	if(!x){
 	    ossl_raise(eOCSPError, "cannot load DER encoded response");
 	}
     }
@@ -377,7 +381,7 @@ ossl_ocspres_to_der(VALUE self)
     if((len = i2d_OCSP_RESPONSE(res, NULL)) <= 0)
 	ossl_raise(eOCSPError, NULL);
     str = rb_str_new(0, len);
-    p = RSTRING_PTR(str);
+    p = (unsigned char *)RSTRING_PTR(str);
     if(i2d_OCSP_RESPONSE(res, &p) <= 0)
 	ossl_raise(eOCSPError, NULL);
     ossl_str_adjust(str, p);
@@ -436,7 +440,7 @@ ossl_ocspbres_add_nonce(int argc, VALUE *argv, VALUE self)
     else{
 	StringValue(val);
 	GetOCSPBasicRes(self, bs);
-	ret = OCSP_basic_add1_nonce(bs, RSTRING_PTR(val), RSTRING_LEN(val));
+	ret = OCSP_basic_add1_nonce(bs, (unsigned char *)RSTRING_PTR(val), RSTRING_LENINT(val));
     }
     if(!ret) ossl_raise(eOCSPError, NULL);
 
@@ -554,7 +558,7 @@ ossl_ocspbres_get_status(VALUE self)
     }
 
     return ret;
-} 
+}
 
 static VALUE
 ossl_ocspbres_sign(int argc, VALUE *argv, VALUE self)
@@ -597,7 +601,7 @@ ossl_ocspbres_verify(int argc, VALUE *argv, VALUE self)
 
     rb_scan_args(argc, argv, "21", &certs, &store, &flags);
     x509st = GetX509StorePtr(store);
-    flg = NIL_P(flags) ? 0 : INT2NUM(flags);
+    flg = NIL_P(flags) ? 0 : NUM2INT(flags);
     x509s = ossl_x509_ary2sk(certs);
     GetOCSPBasicRes(self, bs);
     result = OCSP_basic_verify(bs, x509s, x509st, flg) > 0 ? Qtrue : Qfalse;
@@ -624,14 +628,27 @@ ossl_ocspcid_alloc(VALUE klass)
 }
 
 static VALUE
-ossl_ocspcid_initialize(VALUE self, VALUE subject, VALUE issuer)
+ossl_ocspcid_initialize(int argc, VALUE *argv, VALUE self)
 {
     OCSP_CERTID *id, *newid;
     X509 *x509s, *x509i;
+    VALUE subject, issuer, digest;
+    const EVP_MD *md;
+
+    if (rb_scan_args(argc, argv, "21", &subject, &issuer, &digest) == 0) {
+	return self;
+    }
 
     x509s = GetX509CertPtr(subject); /* NO NEED TO DUP */
     x509i = GetX509CertPtr(issuer); /* NO NEED TO DUP */
-    if(!(newid = OCSP_cert_to_id(NULL, x509s, x509i)))
+
+    if (!NIL_P(digest)) {
+	md = GetDigestPtr(digest);
+	newid = OCSP_cert_to_id(md, x509s, x509i);
+    } else {
+	newid = OCSP_cert_to_id(NULL, x509s, x509i);
+    }
+    if(!newid)
 	ossl_raise(eOCSPError, NULL);
     GetOCSPCertId(self, id);
     OCSP_CERTID_free(id);
@@ -715,7 +732,7 @@ Init_ossl_ocsp()
 
     cOCSPCertId = rb_define_class_under(mOCSP, "CertificateId", rb_cObject);
     rb_define_alloc_func(cOCSPCertId, ossl_ocspcid_alloc);
-    rb_define_method(cOCSPCertId, "initialize", ossl_ocspcid_initialize, 2);
+    rb_define_method(cOCSPCertId, "initialize", ossl_ocspcid_initialize, -1);
     rb_define_method(cOCSPCertId, "cmp", ossl_ocspcid_cmp, 1);
     rb_define_method(cOCSPCertId, "cmp_issuer", ossl_ocspcid_cmp_issuer, 1);
     rb_define_method(cOCSPCertId, "serial", ossl_ocspcid_get_serial, 0);

data/ext/rubysl/openssl/ossl_ocsp.h

@@ -1,5 +1,5 @@
 /*
- * $Id: ossl_ocsp.h 11708 2007-02-12 23:01:19Z shyouhei $
+ * $Id$
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2003  Michal Rokos <m.rokos@sh.cvut.cz>
  * Copyright (C) 2003  GOTOU Yuuzou <gotoyuzo@notwork.org>

data/ext/rubysl/openssl/ossl_pkcs12.c

@@ -1,23 +1,23 @@
 /*
  * This program is licenced under the same licence as Ruby.
  * (See the file 'LICENCE'.)
- * $Id: ossl_pkcs12.c 12496 2007-06-08 15:02:04Z technorama $
+ * $Id$
  */
 #include "ossl.h"
 
 #define WrapPKCS12(klass, obj, p12) do { \
-    if(!p12) ossl_raise(rb_eRuntimeError, "PKCS12 wasn't initialized."); \
-    obj = Data_Wrap_Struct(klass, 0, PKCS12_free, p12); \
+    if(!(p12)) ossl_raise(rb_eRuntimeError, "PKCS12 wasn't initialized."); \
+    (obj) = Data_Wrap_Struct((klass), 0, PKCS12_free, (p12)); \
 } while (0)
 
 #define GetPKCS12(obj, p12) do { \
-    Data_Get_Struct(obj, PKCS12, p12); \
-    if(!p12) ossl_raise(rb_eRuntimeError, "PKCS12 wasn't initialized."); \
+    Data_Get_Struct((obj), PKCS12, (p12)); \
+    if(!(p12)) ossl_raise(rb_eRuntimeError, "PKCS12 wasn't initialized."); \
 } while (0)
 
 #define SafeGetPKCS12(obj, p12) do { \
-    OSSL_Check_Kind(obj, cPKCS12); \
-    GetPKCS12(obj, p12); \
+    OSSL_Check_Kind((obj), cPKCS12); \
+    GetPKCS12((obj), (p12)); \
 } while (0)
 
 #define ossl_pkcs12_set_key(o,v)      rb_iv_set((o), "@key", (v))
@@ -81,7 +81,7 @@ ossl_pkcs12_s_create(int argc, VALUE *argv, VALUE self)
     STACK_OF(X509) *x509s;
     int nkey = 0, ncert = 0, kiter = 0, miter = 0, ktype = 0;
     PKCS12 *p12;
-    
+
     rb_scan_args(argc, argv, "46", &pass, &name, &pkey, &cert, &ca, &key_nid, &cert_nid, &key_iter, &mac_iter, &keytype);
     passphrase = NIL_P(pass) ? NULL : StringValuePtr(pass);
     friendlyname = NIL_P(name) ? NULL : StringValuePtr(name);
@@ -91,11 +91,11 @@ ossl_pkcs12_s_create(int argc, VALUE *argv, VALUE self)
 /* TODO: make a VALUE to nid function */
     if (!NIL_P(key_nid)) {
         if ((nkey = OBJ_txt2nid(StringValuePtr(key_nid))) == NID_undef)
-            rb_raise(rb_eArgError, "Unknown PBE algorithm %s", StringValuePtr(key_nid));
+            ossl_raise(rb_eArgError, "Unknown PBE algorithm %s", StringValuePtr(key_nid));
     }
     if (!NIL_P(cert_nid)) {
         if ((ncert = OBJ_txt2nid(StringValuePtr(cert_nid))) == NID_undef)
-            rb_raise(rb_eArgError, "Unknown PBE algorithm %s", StringValuePtr(cert_nid));
+            ossl_raise(rb_eArgError, "Unknown PBE algorithm %s", StringValuePtr(cert_nid));
     }
     if (!NIL_P(key_iter))
         kiter = NUM2INT(key_iter);
@@ -137,15 +137,17 @@ ossl_pkcs12_initialize(int argc, VALUE *argv, VALUE self)
     X509 *x509;
     STACK_OF(X509) *x509s = NULL;
     int st = 0;
+    PKCS12 *pkcs = DATA_PTR(self);
 
     if(rb_scan_args(argc, argv, "02", &arg, &pass) == 0) return self;
     passphrase = NIL_P(pass) ? NULL : StringValuePtr(pass);
     in = ossl_obj2bio(arg);
-    d2i_PKCS12_bio(in, (PKCS12 **)&DATA_PTR(self));
+    d2i_PKCS12_bio(in, &pkcs);
+    DATA_PTR(self) = pkcs;
     BIO_free(in);
 
     pkey = cert = ca = Qnil;
-    if(!PKCS12_parse((PKCS12*)DATA_PTR(self), passphrase, &key, &x509, &x509s))
+    if(!PKCS12_parse(pkcs, passphrase, &key, &x509, &x509s))
 	ossl_raise(ePKCS12Error, "PKCS12_parse");
     pkey = rb_protect((VALUE(*)_((VALUE)))ossl_pkey_new, (VALUE)key,
 		      &st); /* NO DUP */
@@ -181,7 +183,7 @@ ossl_pkcs12_to_der(VALUE self)
     if((len = i2d_PKCS12(p12, NULL)) <= 0)
 	ossl_raise(ePKCS12Error, NULL);
     str = rb_str_new(0, len);
-    p = RSTRING_PTR(str);
+    p = (unsigned char *)RSTRING_PTR(str);
     if(i2d_PKCS12(p12, &p) <= 0)
 	ossl_raise(ePKCS12Error, NULL);
     ossl_str_adjust(str, p);

data/ext/rubysl/openssl/ossl_pkcs12.h

@@ -1,7 +1,7 @@
 /*
  * This program is licenced under the same licence as Ruby.
  * (See the file 'LICENCE'.)
- * $Id: ossl_pkcs12.h 12496 2007-06-08 15:02:04Z technorama $
+ * $Id$
  */
 #if !defined(_OSSL_PKCS12_H_)
 #define _OSSL_PKCS12_H_

data/ext/rubysl/openssl/ossl_pkcs5.c

@@ -7,66 +7,66 @@
 VALUE mPKCS5;
 VALUE ePKCS5;
 
+#ifdef HAVE_PKCS5_PBKDF2_HMAC
 /*
  * call-seq:
  *    PKCS5.pbkdf2_hmac(pass, salt, iter, keylen, digest) => string
  *
  * === Parameters
  * * +pass+ - string
- * * +salt+ - string
- * * +iter+ - integer - should be greater than 1000.  2000 is better.
+ * * +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.
  *
- * Available in OpenSSL 0.9.9?.
+ * Available in OpenSSL 0.9.4.
  *
  * 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)
 {
-#ifdef HAVE_PKCS5_PBKDF2_HMAC
     VALUE str;
     const EVP_MD *md;
     int len = NUM2INT(keylen);
-    unsigned char* salt_p;
-    unsigned char* str_p;
 
     StringValue(pass);
     StringValue(salt);
     md = GetDigestPtr(digest);
+
     str = rb_str_new(0, len);
-    salt_p = (unsigned char*)RSTRING_PTR(salt);
-    str_p = (unsigned char*)RSTRING_PTR(str);
 
-    if (PKCS5_PBKDF2_HMAC(RSTRING_PTR(pass), RSTRING_LEN(pass), salt_p, RSTRING_LEN(salt), NUM2INT(iter), md, len, str_p) != 1)
+    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;
+}
 #else
-    rb_notimplement();
+#define ossl_pkcs5_pbkdf2_hmac rb_f_notimplement
 #endif
-}
 
 
+#ifdef HAVE_PKCS5_PBKDF2_HMAC_SHA1
 /*
  * call-seq:
  *    PKCS5.pbkdf2_hmac_sha1(pass, salt, iter, keylen) => string
  *
  * === Parameters
  * * +pass+ - string
- * * +salt+ - string
- * * +iter+ - integer - should be greater than 1000.  2000 is better.
+ * * +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 almost any version OpenSSL.
+ * This method is available in almost any version of OpenSSL.
  *
  * Conforms to rfc2898.
  */
 static VALUE
 ossl_pkcs5_pbkdf2_hmac_sha1(VALUE self, VALUE pass, VALUE salt, VALUE iter, VALUE keylen)
 {
-#ifdef HAVE_PKCS5_PBKDF2_HMAC_SHA1
     VALUE str;
     int len = NUM2INT(keylen);
 
@@ -75,14 +75,16 @@ ossl_pkcs5_pbkdf2_hmac_sha1(VALUE self, VALUE pass, VALUE salt, VALUE iter, VALU
 
     str = rb_str_new(0, len);
 
-    if (PKCS5_PBKDF2_HMAC_SHA1(RSTRING_PTR(pass), RSTRING_LEN(pass), RSTRING_PTR(salt), RSTRING_LEN(salt), NUM2INT(iter), len, RSTRING_PTR(str)) != 1)
+    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;
+}
 #else
-    rb_notimplement();
+#define ossl_pkcs5_pbkdf2_hmac_sha1 rb_f_notimplement
 #endif
-}
 
 void
 Init_ossl_pkcs5()
@@ -91,7 +93,95 @@ Init_ossl_pkcs5()
      * Password-based Encryption
      *
      */
+
+    #if 0
+	mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    #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 if the underlying version of OpenSSL
+     * already supports it (>= 0.9.4).
+     *
+     * === 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);