rubysl-openssl 2.10 → 2.11

data/ext/rubysl/openssl/ossl_x509revoked.c

@@ -109,6 +109,25 @@ ossl_x509revoked_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+static VALUE
+ossl_x509revoked_initialize_copy(VALUE self, VALUE other)
+{
+    X509_REVOKED *rev, *rev_other, *rev_new;
+
+    rb_check_frozen(self);
+    GetX509Rev(self, rev);
+    SafeGetX509Rev(other, rev_other);
+
+    rev_new = X509_REVOKED_dup(rev_other);
+    if (!rev_new)
+	ossl_raise(eX509RevError, "X509_REVOKED_dup");
+
+    SetX509Rev(self, rev_new);
+    X509_REVOKED_free(rev);
+
+    return self;
+}
+
 static VALUE
 ossl_x509revoked_get_serial(VALUE self)
 {
@@ -116,16 +135,22 @@ ossl_x509revoked_get_serial(VALUE self)
 
     GetX509Rev(self, rev);
 
-    return asn1integer_to_num(rev->serialNumber);
+    return asn1integer_to_num(X509_REVOKED_get0_serialNumber(rev));
 }
 
 static VALUE
 ossl_x509revoked_set_serial(VALUE self, VALUE num)
 {
     X509_REVOKED *rev;
+    ASN1_INTEGER *asn1int;
 
     GetX509Rev(self, rev);
-    rev->serialNumber = num_to_asn1integer(num, rev->serialNumber);
+    asn1int = num_to_asn1integer(num, NULL);
+    if (!X509_REVOKED_set_serialNumber(rev, asn1int)) {
+	ASN1_INTEGER_free(asn1int);
+	ossl_raise(eX509RevError, "X509_REVOKED_set_serialNumber");
+    }
+    ASN1_INTEGER_free(asn1int);
 
     return num;
 }
@@ -137,20 +162,22 @@ ossl_x509revoked_get_time(VALUE self)
 
     GetX509Rev(self, rev);
 
-    return asn1time_to_time(rev->revocationDate);
+    return asn1time_to_time(X509_REVOKED_get0_revocationDate(rev));
 }
 
 static VALUE
 ossl_x509revoked_set_time(VALUE self, VALUE time)
 {
     X509_REVOKED *rev;
-    time_t sec;
+    ASN1_TIME *asn1time;
 
-    sec = time_to_time_t(time);
     GetX509Rev(self, rev);
-    if (!X509_time_adj(rev->revocationDate, 0, &sec)) {
-	ossl_raise(eX509RevError, NULL);
+    asn1time = ossl_x509_time_adjust(NULL, time);
+    if (!X509_REVOKED_set_revocationDate(rev, asn1time)) {
+	ASN1_TIME_free(asn1time);
+	ossl_raise(eX509RevError, "X509_REVOKED_set_revocationDate");
     }
+    ASN1_TIME_free(asn1time);
 
     return time;
 }
@@ -196,8 +223,8 @@ ossl_x509revoked_set_extensions(VALUE self, VALUE ary)
 	OSSL_Check_Kind(RARRAY_AREF(ary, i), cX509Ext);
     }
     GetX509Rev(self, rev);
-    sk_X509_EXTENSION_pop_free(rev->extensions, X509_EXTENSION_free);
-    rev->extensions = NULL;
+    while ((ext = X509_REVOKED_delete_ext(rev, 0)))
+	X509_EXTENSION_free(ext);
     for (i=0; i<RARRAY_LEN(ary); i++) {
 	item = RARRAY_AREF(ary, i);
 	ext = GetX509ExtPtr(item);
@@ -228,12 +255,19 @@ ossl_x509revoked_add_extension(VALUE self, VALUE ext)
 void
 Init_ossl_x509revoked(void)
 {
+#if 0
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
+    mX509 = rb_define_module_under(mOSSL, "X509");
+#endif
+
     eX509RevError = rb_define_class_under(mX509, "RevokedError", eOSSLError);
 
     cX509Rev = rb_define_class_under(mX509, "Revoked", rb_cObject);
 
     rb_define_alloc_func(cX509Rev, ossl_x509revoked_alloc);
     rb_define_method(cX509Rev, "initialize", ossl_x509revoked_initialize, -1);
+    rb_define_copy_func(cX509Rev, ossl_x509revoked_initialize_copy);
 
     rb_define_method(cX509Rev, "serial", ossl_x509revoked_get_serial, 0);
     rb_define_method(cX509Rev, "serial=", ossl_x509revoked_set_serial, 1);

data/ext/rubysl/openssl/ossl_x509store.c

@@ -47,6 +47,65 @@
     GetX509Store((obj), (ctx)); \
 } while (0)
 
+/*
+ * Verify callback stuff
+ */
+static int stctx_ex_verify_cb_idx, store_ex_verify_cb_idx;
+static VALUE ossl_x509stctx_new(X509_STORE_CTX *);
+
+struct ossl_verify_cb_args {
+    VALUE proc;
+    VALUE preverify_ok;
+    VALUE store_ctx;
+};
+
+static VALUE
+call_verify_cb_proc(struct ossl_verify_cb_args *args)
+{
+    return rb_funcall(args->proc, rb_intern("call"), 2,
+		      args->preverify_ok, args->store_ctx);
+}
+
+int
+ossl_verify_cb_call(VALUE proc, int ok, X509_STORE_CTX *ctx)
+{
+    VALUE rctx, ret;
+    struct ossl_verify_cb_args args;
+    int state;
+
+    if (NIL_P(proc))
+	return ok;
+
+    ret = Qfalse;
+    rctx = rb_protect((VALUE(*)(VALUE))ossl_x509stctx_new, (VALUE)ctx, &state);
+    if (state) {
+	rb_set_errinfo(Qnil);
+	rb_warn("StoreContext initialization failure");
+    }
+    else {
+	args.proc = proc;
+	args.preverify_ok = ok ? Qtrue : Qfalse;
+	args.store_ctx = rctx;
+	ret = rb_protect((VALUE(*)(VALUE))call_verify_cb_proc, (VALUE)&args, &state);
+	if (state) {
+	    rb_set_errinfo(Qnil);
+	    rb_warn("exception in verify_callback is ignored");
+	}
+	RTYPEDDATA_DATA(rctx) = NULL;
+    }
+    if (ret == Qtrue) {
+	X509_STORE_CTX_set_error(ctx, X509_V_OK);
+	ok = 1;
+    }
+    else {
+	if (X509_STORE_CTX_get_error(ctx) == X509_V_OK)
+	    X509_STORE_CTX_set_error(ctx, X509_V_ERR_CERT_REJECTED);
+	ok = 0;
+    }
+
+    return ok;
+}
+
 /*
  * Classes
  */
@@ -98,7 +157,7 @@ DupX509StorePtr(VALUE obj)
     X509_STORE *store;
 
     SafeGetX509Store(obj, store);
-    CRYPTO_add(&store->references, 1, CRYPTO_LOCK_X509_STORE);
+    X509_STORE_up_ref(store);
 
     return store;
 }
@@ -106,6 +165,21 @@ DupX509StorePtr(VALUE obj)
 /*
  * Private functions
  */
+static int
+x509store_verify_cb(int ok, X509_STORE_CTX *ctx)
+{
+    VALUE proc;
+
+    proc = (VALUE)X509_STORE_CTX_get_ex_data(ctx, stctx_ex_verify_cb_idx);
+    if (!proc)
+	proc = (VALUE)X509_STORE_get_ex_data(X509_STORE_CTX_get0_store(ctx),
+					     store_ex_verify_cb_idx);
+    if (!proc)
+	return ok;
+
+    return ossl_verify_cb_call(proc, ok, ctx);
+}
+
 static VALUE
 ossl_x509store_alloc(VALUE klass)
 {
@@ -130,7 +204,7 @@ ossl_x509store_set_vfy_cb(VALUE self, VALUE cb)
     X509_STORE *store;
 
     GetX509Store(self, store);
-    X509_STORE_set_ex_data(store, ossl_verify_cb_idx, (void*)cb);
+    X509_STORE_set_ex_data(store, store_ex_verify_cb_idx, (void *)cb);
     rb_iv_set(self, "@verify_callback", cb);
 
     return cb;
@@ -141,6 +215,7 @@ ossl_x509store_set_vfy_cb(VALUE self, VALUE cb)
  * call-seq:
  *    X509::Store.new => store
  *
+ * Creates a new X509::Store.
  */
 static VALUE
 ossl_x509store_initialize(int argc, VALUE *argv, VALUE self)
@@ -149,15 +224,12 @@ ossl_x509store_initialize(int argc, VALUE *argv, VALUE self)
 
 /* BUG: This method takes any number of arguments but appears to ignore them. */
     GetX509Store(self, store);
+#if !defined(HAVE_OPAQUE_OPENSSL)
+    /* [Bug #405] [Bug #1678] [Bug #3000]; already fixed? */
     store->ex_data.sk = NULL;
-    X509_STORE_set_verify_cb_func(store, ossl_verify_cb);
-    ossl_x509store_set_vfy_cb(self, Qnil);
-
-#if (OPENSSL_VERSION_NUMBER < 0x00907000L)
-    rb_iv_set(self, "@flags", INT2FIX(0));
-    rb_iv_set(self, "@purpose", INT2FIX(0));
-    rb_iv_set(self, "@trust", INT2FIX(0));
 #endif
+    X509_STORE_set_verify_cb(store, x509store_verify_cb);
+    ossl_x509store_set_vfy_cb(self, Qnil);
 
     /* last verification status */
     rb_iv_set(self, "@error", Qnil);
@@ -168,54 +240,77 @@ ossl_x509store_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   store.flags = flag
+ *
+ * Sets +flag+ to the Store. +flag+ consists of zero or more of the constants
+ * defined in with name V_FLAG_* or'ed together.
+ */
 static VALUE
 ossl_x509store_set_flags(VALUE self, VALUE flags)
 {
-#if (OPENSSL_VERSION_NUMBER >= 0x00907000L)
     X509_STORE *store;
     long f = NUM2LONG(flags);
 
     GetX509Store(self, store);
     X509_STORE_set_flags(store, f);
-#else
-    rb_iv_set(self, "@flags", flags);
-#endif
 
     return flags;
 }
 
+/*
+ * call-seq:
+ *   store.purpose = purpose
+ *
+ * Sets the store's purpose to +purpose+. If specified, the verifications on
+ * the store will check every untrusted certificate's extensions are consistent
+ * with the purpose. The purpose is specified by constants:
+ *
+ * * X509::PURPOSE_SSL_CLIENT
+ * * X509::PURPOSE_SSL_SERVER
+ * * X509::PURPOSE_NS_SSL_SERVER
+ * * X509::PURPOSE_SMIME_SIGN
+ * * X509::PURPOSE_SMIME_ENCRYPT
+ * * X509::PURPOSE_CRL_SIGN
+ * * X509::PURPOSE_ANY
+ * * X509::PURPOSE_OCSP_HELPER
+ * * X509::PURPOSE_TIMESTAMP_SIGN
+ */
 static VALUE
 ossl_x509store_set_purpose(VALUE self, VALUE purpose)
 {
-#if (OPENSSL_VERSION_NUMBER >= 0x00907000L)
     X509_STORE *store;
     int p = NUM2INT(purpose);
 
     GetX509Store(self, store);
     X509_STORE_set_purpose(store, p);
-#else
-    rb_iv_set(self, "@purpose", purpose);
-#endif
 
     return purpose;
 }
 
+/*
+ * call-seq:
+ *   store.trust = trust
+ */
 static VALUE
 ossl_x509store_set_trust(VALUE self, VALUE trust)
 {
-#if (OPENSSL_VERSION_NUMBER >= 0x00907000L)
     X509_STORE *store;
     int t = NUM2INT(trust);
 
     GetX509Store(self, store);
     X509_STORE_set_trust(store, t);
-#else
-    rb_iv_set(self, "@trust", trust);
-#endif
 
     return trust;
 }
 
+/*
+ * call-seq:
+ *   store.time = time
+ *
+ * Sets the time to be used in verifications.
+ */
 static VALUE
 ossl_x509store_set_time(VALUE self, VALUE time)
 {
@@ -225,13 +320,11 @@ ossl_x509store_set_time(VALUE self, VALUE time)
 
 /*
  * call-seq:
- *   store.add_file(file) -> store
- *
+ *   store.add_file(file) -> self
  *
  * Adds the certificates in +file+ to the certificate store.  The +file+ can
  * contain multiple PEM-encoded certificates.
  */
-
 static VALUE
 ossl_x509store_add_file(VALUE self, VALUE file)
 {
@@ -240,8 +333,8 @@ ossl_x509store_add_file(VALUE self, VALUE file)
     char *path = NULL;
 
     if(file != Qnil){
-        SafeStringValue(file);
-	path = RSTRING_PTR(file);
+	rb_check_safe_obj(file);
+	path = StringValueCStr(file);
     }
     GetX509Store(self, store);
     lookup = X509_STORE_add_lookup(store, X509_LOOKUP_file());
@@ -249,10 +342,25 @@ ossl_x509store_add_file(VALUE self, VALUE file)
     if(X509_LOOKUP_load_file(lookup, path, X509_FILETYPE_PEM) != 1){
         ossl_raise(eX509StoreError, NULL);
     }
+#if OPENSSL_VERSION_NUMBER < 0x10101000 || defined(LIBRESSL_VERSION_NUMBER)
+    /*
+     * X509_load_cert_crl_file() which is called from X509_LOOKUP_load_file()
+     * did not check the return value of X509_STORE_add_{cert,crl}(), leaking
+     * "cert already in hash table" errors on the error queue, if duplicate
+     * certificates are found. This will be fixed by OpenSSL 1.1.1.
+     */
+    ossl_clear_error();
+#endif
 
     return self;
 }
 
+/*
+ * call-seq:
+ *   store.add_path(path) -> self
+ *
+ * Adds +path+ as the hash dir to be looked up by the store.
+ */
 static VALUE
 ossl_x509store_add_path(VALUE self, VALUE dir)
 {
@@ -261,8 +369,8 @@ ossl_x509store_add_path(VALUE self, VALUE dir)
     char *path = NULL;
 
     if(dir != Qnil){
-        SafeStringValue(dir);
-	path = RSTRING_PTR(dir);
+	rb_check_safe_obj(dir);
+	path = StringValueCStr(dir);
     }
     GetX509Store(self, store);
     lookup = X509_STORE_add_lookup(store, X509_LOOKUP_hash_dir());
@@ -278,11 +386,12 @@ ossl_x509store_add_path(VALUE self, VALUE dir)
  * call-seq:
  *   store.set_default_paths
  *
- * Adds the default certificates to the certificate store.  These certificates
- * are loaded from the default configuration directory which can usually be
+ * Configures +store+ to look up CA certificates from the system default
+ * certificate store as needed basis. The location of the store can usually be
  * determined by:
  *
- *   File.dirname OpenSSL::Config::DEFAULT_CONFIG_FILE
+ * * OpenSSL::X509::DEFAULT_CERT_FILE
+ * * OpenSSL::X509::DEFAULT_CERT_DIR
  */
 static VALUE
 ossl_x509store_set_default_paths(VALUE self)
@@ -303,7 +412,6 @@ ossl_x509store_set_default_paths(VALUE self)
  *
  * Adds the OpenSSL::X509::Certificate +cert+ to the certificate store.
  */
-
 static VALUE
 ossl_x509store_add_cert(VALUE self, VALUE arg)
 {
@@ -319,6 +427,12 @@ ossl_x509store_add_cert(VALUE self, VALUE arg)
     return self;
 }
 
+/*
+ * call-seq:
+ *   store.add_crl(crl) -> self
+ *
+ * Adds the OpenSSL::X509::CRL +crl+ to the store.
+ */
 static VALUE
 ossl_x509store_add_crl(VALUE self, VALUE arg)
 {
@@ -338,6 +452,21 @@ static VALUE ossl_x509stctx_get_err(VALUE);
 static VALUE ossl_x509stctx_get_err_string(VALUE);
 static VALUE ossl_x509stctx_get_chain(VALUE);
 
+/*
+ * call-seq:
+ *   store.verify(cert, chain = nil) -> true | false
+ *
+ * Performs a certificate verification on the OpenSSL::X509::Certificate +cert+.
+ *
+ * +chain+ can be an array of OpenSSL::X509::Certificate that is used to
+ * construct the certificate chain.
+ *
+ * If a block is given, it overrides the callback set by #verify_callback=.
+ *
+ * After finishing the verification, the error information can be retrieved by
+ * #error, #error_string, and the resuting complete certificate chain can be
+ * retrieved by #chain.
+ */
 static VALUE
 ossl_x509store_verify(int argc, VALUE *argv, VALUE self)
 {
@@ -372,27 +501,6 @@ static const rb_data_type_t ossl_x509stctx_type = {
     0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
 };
 
-
-VALUE
-ossl_x509stctx_new(X509_STORE_CTX *ctx)
-{
-    VALUE obj;
-
-    obj = NewX509StCtx(cX509StoreContext);
-    SetX509StCtx(obj, ctx);
-
-    return obj;
-}
-
-VALUE
-ossl_x509stctx_clear_ptr(VALUE obj)
-{
-    OSSL_Check_Kind(obj, cX509StoreContext);
-    RDATA(obj)->data = NULL;
-
-    return obj;
-}
-
 /*
  * Private functions
  */
@@ -400,10 +508,10 @@ static void
 ossl_x509stctx_free(void *ptr)
 {
     X509_STORE_CTX *ctx = ptr;
-    if(ctx->untrusted)
-	sk_X509_pop_free(ctx->untrusted, X509_free);
-    if(ctx->cert)
-	X509_free(ctx->cert);
+    if (X509_STORE_CTX_get0_untrusted(ctx))
+	sk_X509_pop_free(X509_STORE_CTX_get0_untrusted(ctx), X509_free);
+    if (X509_STORE_CTX_get0_cert(ctx))
+	X509_free(X509_STORE_CTX_get0_cert(ctx));
     X509_STORE_CTX_free(ctx);
 }
 
@@ -422,11 +530,26 @@ ossl_x509stctx_alloc(VALUE klass)
     return obj;
 }
 
+static VALUE
+ossl_x509stctx_new(X509_STORE_CTX *ctx)
+{
+    VALUE obj;
+
+    obj = NewX509StCtx(cX509StoreContext);
+    SetX509StCtx(obj, ctx);
+
+    return obj;
+}
+
 static VALUE ossl_x509stctx_set_flags(VALUE, VALUE);
 static VALUE ossl_x509stctx_set_purpose(VALUE, VALUE);
 static VALUE ossl_x509stctx_set_trust(VALUE, VALUE);
 static VALUE ossl_x509stctx_set_time(VALUE, VALUE);
 
+/*
+ * call-seq:
+ *   StoreContext.new(store, cert = nil, chain = nil)
+ */
 static VALUE
 ossl_x509stctx_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -441,17 +564,10 @@ ossl_x509stctx_initialize(int argc, VALUE *argv, VALUE self)
     SafeGetX509Store(store, x509st);
     if(!NIL_P(cert)) x509 = DupX509CertPtr(cert); /* NEED TO DUP */
     if(!NIL_P(chain)) x509s = ossl_x509_ary2sk(chain);
-#if (OPENSSL_VERSION_NUMBER >= 0x00907000L)
     if(X509_STORE_CTX_init(ctx, x509st, x509, x509s) != 1){
         sk_X509_pop_free(x509s, X509_free);
         ossl_raise(eX509StoreError, NULL);
     }
-#else
-    X509_STORE_CTX_init(ctx, x509st, x509, x509s);
-    ossl_x509stctx_set_flags(self, rb_iv_get(store, "@flags"));
-    ossl_x509stctx_set_purpose(self, rb_iv_get(store, "@purpose"));
-    ossl_x509stctx_set_trust(self, rb_iv_get(store, "@trust"));
-#endif
     if (!NIL_P(t = rb_iv_get(store, "@time")))
 	ossl_x509stctx_set_time(self, t);
     rb_iv_set(self, "@verify_callback", rb_iv_get(store, "@verify_callback"));
@@ -460,20 +576,34 @@ ossl_x509stctx_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   stctx.verify -> true | false
+ */
 static VALUE
 ossl_x509stctx_verify(VALUE self)
 {
     X509_STORE_CTX *ctx;
-    int result;
 
     GetX509StCtx(self, ctx);
-    X509_STORE_CTX_set_ex_data(ctx, ossl_verify_cb_idx,
-                               (void*)rb_iv_get(self, "@verify_callback"));
-    result = X509_verify_cert(ctx);
-
-    return result ? Qtrue : Qfalse;
+    X509_STORE_CTX_set_ex_data(ctx, stctx_ex_verify_cb_idx,
+			       (void *)rb_iv_get(self, "@verify_callback"));
+
+    switch (X509_verify_cert(ctx)) {
+      case 1:
+	return Qtrue;
+      case 0:
+	ossl_clear_error();
+	return Qfalse;
+      default:
+	ossl_raise(eX509CertError, NULL);
+    }
 }
 
+/*
+ * call-seq:
+ *   stctx.chain -> Array of X509::Certificate
+ */
 static VALUE
 ossl_x509stctx_get_chain(VALUE self)
 {
@@ -484,7 +614,7 @@ ossl_x509stctx_get_chain(VALUE self)
     VALUE ary;
 
     GetX509StCtx(self, ctx);
-    if((chain = X509_STORE_CTX_get_chain(ctx)) == NULL){
+    if((chain = X509_STORE_CTX_get0_chain(ctx)) == NULL){
         return Qnil;
     }
     if((num = sk_X509_num(chain)) < 0){
@@ -500,6 +630,10 @@ ossl_x509stctx_get_chain(VALUE self)
     return ary;
 }
 
+/*
+ * call-seq:
+ *   stctx.error -> Integer
+ */
 static VALUE
 ossl_x509stctx_get_err(VALUE self)
 {
@@ -507,9 +641,13 @@ ossl_x509stctx_get_err(VALUE self)
 
     GetX509StCtx(self, ctx);
 
-    return INT2FIX(X509_STORE_CTX_get_error(ctx));
+    return INT2NUM(X509_STORE_CTX_get_error(ctx));
 }
 
+/*
+ * call-seq:
+ *   stctx.error = error_code
+ */
 static VALUE
 ossl_x509stctx_set_error(VALUE self, VALUE err)
 {
@@ -521,6 +659,12 @@ ossl_x509stctx_set_error(VALUE self, VALUE err)
     return err;
 }
 
+/*
+ * call-seq:
+ *   stctx.error_string -> String
+ *
+ * Returns the error string corresponding to the error code retrieved by #error.
+ */
 static VALUE
 ossl_x509stctx_get_err_string(VALUE self)
 {
@@ -533,6 +677,10 @@ ossl_x509stctx_get_err_string(VALUE self)
     return rb_str_new2(X509_verify_cert_error_string(err));
 }
 
+/*
+ * call-seq:
+ *   stctx.error_depth -> Integer
+ */
 static VALUE
 ossl_x509stctx_get_err_depth(VALUE self)
 {
@@ -540,9 +688,13 @@ ossl_x509stctx_get_err_depth(VALUE self)
 
     GetX509StCtx(self, ctx);
 
-    return INT2FIX(X509_STORE_CTX_get_error_depth(ctx));
+    return INT2NUM(X509_STORE_CTX_get_error_depth(ctx));
 }
 
+/*
+ * call-seq:
+ *   stctx.current_cert -> X509::Certificate
+ */
 static VALUE
 ossl_x509stctx_get_curr_cert(VALUE self)
 {
@@ -553,21 +705,30 @@ ossl_x509stctx_get_curr_cert(VALUE self)
     return ossl_x509_new(X509_STORE_CTX_get_current_cert(ctx));
 }
 
+/*
+ * call-seq:
+ *   stctx.current_crl -> X509::CRL
+ */
 static VALUE
 ossl_x509stctx_get_curr_crl(VALUE self)
 {
-#if (OPENSSL_VERSION_NUMBER >= 0x00907000L)
     X509_STORE_CTX *ctx;
+    X509_CRL *crl;
 
     GetX509StCtx(self, ctx);
-    if(!ctx->current_crl) return Qnil;
+    crl = X509_STORE_CTX_get0_current_crl(ctx);
+    if (!crl)
+	return Qnil;
 
-    return ossl_x509crl_new(ctx->current_crl);
-#else
-    return Qnil;
-#endif
+    return ossl_x509crl_new(crl);
 }
 
+/*
+ * call-seq:
+ *   stctx.flags = flags
+ *
+ * Sets the verification flags to the context. See Store#flags=.
+ */
 static VALUE
 ossl_x509stctx_set_flags(VALUE self, VALUE flags)
 {
@@ -580,6 +741,12 @@ ossl_x509stctx_set_flags(VALUE self, VALUE flags)
     return flags;
 }
 
+/*
+ * call-seq:
+ *   stctx.purpose = purpose
+ *
+ * Sets the purpose of the context. See Store#purpose=.
+ */
 static VALUE
 ossl_x509stctx_set_purpose(VALUE self, VALUE purpose)
 {
@@ -592,6 +759,10 @@ ossl_x509stctx_set_purpose(VALUE self, VALUE purpose)
     return purpose;
 }
 
+/*
+ * call-seq:
+ *   stctx.trust = trust
+ */
 static VALUE
 ossl_x509stctx_set_trust(VALUE self, VALUE trust)
 {
@@ -606,7 +777,9 @@ ossl_x509stctx_set_trust(VALUE self, VALUE trust)
 
 /*
  * call-seq:
- *    storectx.time = time => time
+ *   stctx.time = time
+ *
+ * Sets the time used in the verification. If not set, the current time is used.
  */
 static VALUE
 ossl_x509stctx_set_time(VALUE self, VALUE time)
@@ -627,13 +800,21 @@ ossl_x509stctx_set_time(VALUE self, VALUE time)
 void
 Init_ossl_x509store(void)
 {
-    VALUE x509stctx;
-
+#undef rb_intern
 #if 0
-    mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
+    mOSSL = rb_define_module("OpenSSL");
+    eOSSLError = rb_define_class_under(mOSSL, "OpenSSLError", rb_eStandardError);
     mX509 = rb_define_module_under(mOSSL, "X509");
 #endif
 
+    /* Register ext_data slot for verify callback Proc */
+    stctx_ex_verify_cb_idx = X509_STORE_CTX_get_ex_new_index(0, (void *)"stctx_ex_verify_cb_idx", 0, 0, 0);
+    if (stctx_ex_verify_cb_idx < 0)
+	ossl_raise(eOSSLError, "X509_STORE_CTX_get_ex_new_index");
+    store_ex_verify_cb_idx = X509_STORE_get_ex_new_index(0, (void *)"store_ex_verify_cb_idx", 0, 0, 0);
+    if (store_ex_verify_cb_idx < 0)
+	ossl_raise(eOSSLError, "X509_STORE_get_ex_new_index");
+
     eX509StoreError = rb_define_class_under(mX509, "StoreError", eOSSLError);
 
     /* Document-class: OpenSSL::X509::Store
@@ -648,11 +829,11 @@ Init_ossl_x509store(void)
      *
      * This will use your system's built-in certificates.
      *
-     * If your system does not have a default set of certificates you can
-     * obtain a set from Mozilla here: http://curl.haxx.se/docs/caextract.html
-     * (Note that this set does not have an HTTPS download option so you may
-     * wish to use the firefox-db2pem.sh script to extract the certificates
-     * from a local install to avoid man-in-the-middle attacks.)
+     * If your system does not have a default set of certificates you can obtain
+     * a set extracted from Mozilla CA certificate store by cURL maintainers
+     * here: https://curl.haxx.se/docs/caextract.html (You may wish to use the
+     * firefox-db2pem.sh script to extract the certificates from a local install
+     * to avoid man-in-the-middle attacks.)
      *
      * After downloading or generating a cacert.pem from the above link you
      * can create a certificate store from the pem file like this:
@@ -663,6 +844,7 @@ Init_ossl_x509store(void)
      * The certificate store can be used with an SSLSocket like this:
      *
      *   ssl_context = OpenSSL::SSL::SSLContext.new
+     *   ssl_context.verify_mode = OpenSSL::SSL::VERIFY_PEER
      *   ssl_context.cert_store = cert_store
      *
      *   tcp_socket = TCPSocket.open 'example.com', 443
@@ -671,12 +853,30 @@ Init_ossl_x509store(void)
      */
 
     cX509Store = rb_define_class_under(mX509, "Store", rb_cObject);
+    /*
+     * The callback for additional certificate verification. It is invoked for
+     * each untrusted certificate in the chain.
+     *
+     * The callback is invoked with two values, a boolean that indicates if the
+     * pre-verification by OpenSSL has succeeded or not, and the StoreContext in
+     * use. The callback must return either true or false.
+     */
     rb_attr(cX509Store, rb_intern("verify_callback"), 1, 0, Qfalse);
+    /*
+     * The error code set by the last call of #verify.
+     */
     rb_attr(cX509Store, rb_intern("error"), 1, 0, Qfalse);
+    /*
+     * The description for the error code set by the last call of #verify.
+     */
     rb_attr(cX509Store, rb_intern("error_string"), 1, 0, Qfalse);
+    /*
+     * The certificate chain constructed by the last call of #verify.
+     */
     rb_attr(cX509Store, rb_intern("chain"), 1, 0, Qfalse);
     rb_define_alloc_func(cX509Store, ossl_x509store_alloc);
     rb_define_method(cX509Store, "initialize",   ossl_x509store_initialize, -1);
+    rb_undef_method(cX509Store, "initialize_copy");
     rb_define_method(cX509Store, "verify_callback=", ossl_x509store_set_vfy_cb, 1);
     rb_define_method(cX509Store, "flags=",       ossl_x509store_set_flags, 1);
     rb_define_method(cX509Store, "purpose=",     ossl_x509store_set_purpose, 1);
@@ -689,21 +889,26 @@ Init_ossl_x509store(void)
     rb_define_method(cX509Store, "add_crl",      ossl_x509store_add_crl, 1);
     rb_define_method(cX509Store, "verify",       ossl_x509store_verify, -1);
 
-    cX509StoreContext = rb_define_class_under(mX509,"StoreContext",rb_cObject);
-    x509stctx = cX509StoreContext;
+    /*
+     * Document-class: OpenSSL::X509::StoreContext
+     *
+     * A StoreContext is used while validating a single certificate and holds
+     * the status involved.
+     */
+    cX509StoreContext = rb_define_class_under(mX509,"StoreContext", rb_cObject);
     rb_define_alloc_func(cX509StoreContext, ossl_x509stctx_alloc);
-    rb_define_method(x509stctx,"initialize",  ossl_x509stctx_initialize, -1);
-    rb_define_method(x509stctx,"verify",      ossl_x509stctx_verify, 0);
-    rb_define_method(x509stctx,"chain",       ossl_x509stctx_get_chain,0);
-    rb_define_method(x509stctx,"error",       ossl_x509stctx_get_err, 0);
-    rb_define_method(x509stctx,"error=",      ossl_x509stctx_set_error, 1);
-    rb_define_method(x509stctx,"error_string",ossl_x509stctx_get_err_string,0);
-    rb_define_method(x509stctx,"error_depth", ossl_x509stctx_get_err_depth, 0);
-    rb_define_method(x509stctx,"current_cert",ossl_x509stctx_get_curr_cert, 0);
-    rb_define_method(x509stctx,"current_crl", ossl_x509stctx_get_curr_crl, 0);
-    rb_define_method(x509stctx,"flags=",      ossl_x509stctx_set_flags, 1);
-    rb_define_method(x509stctx,"purpose=",    ossl_x509stctx_set_purpose, 1);
-    rb_define_method(x509stctx,"trust=",      ossl_x509stctx_set_trust, 1);
-    rb_define_method(x509stctx,"time=",       ossl_x509stctx_set_time, 1);
-
+    rb_define_method(cX509StoreContext, "initialize", ossl_x509stctx_initialize, -1);
+    rb_undef_method(cX509StoreContext, "initialize_copy");
+    rb_define_method(cX509StoreContext, "verify", ossl_x509stctx_verify, 0);
+    rb_define_method(cX509StoreContext, "chain", ossl_x509stctx_get_chain,0);
+    rb_define_method(cX509StoreContext, "error", ossl_x509stctx_get_err, 0);
+    rb_define_method(cX509StoreContext, "error=", ossl_x509stctx_set_error, 1);
+    rb_define_method(cX509StoreContext, "error_string", ossl_x509stctx_get_err_string,0);
+    rb_define_method(cX509StoreContext, "error_depth", ossl_x509stctx_get_err_depth, 0);
+    rb_define_method(cX509StoreContext, "current_cert", ossl_x509stctx_get_curr_cert, 0);
+    rb_define_method(cX509StoreContext, "current_crl", ossl_x509stctx_get_curr_crl, 0);
+    rb_define_method(cX509StoreContext, "flags=", ossl_x509stctx_set_flags, 1);
+    rb_define_method(cX509StoreContext, "purpose=", ossl_x509stctx_set_purpose, 1);
+    rb_define_method(cX509StoreContext, "trust=", ossl_x509stctx_set_trust, 1);
+    rb_define_method(cX509StoreContext, "time=", ossl_x509stctx_set_time, 1);
 }