rubysl-openssl 2.2.1 → 2.3.0

data/ext/rubysl/openssl/ossl_cipher.h

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_cipher.h 25189 2009-10-02 12:04:37Z akr $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
  * All rights reserved.

data/ext/rubysl/openssl/ossl_config.c

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_config.c 47744 2014-09-30 05:25:32Z nobu $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
  * All rights reserved.
@@ -17,7 +17,7 @@
 VALUE cConfig;
 /* Document-class: OpenSSL::ConfigError
  *
- * General error for openssl library configuration files. Including formating,
+ * General error for openssl library configuration files. Including formatting,
  * parsing errors, etc.
  */
 VALUE eConfigError;
@@ -69,7 +69,7 @@ GetConfigPtr(VALUE obj)
  * INIT
  */
 void
-Init_ossl_config()
+Init_ossl_config(void)
 {
     char *default_config_file;
     eConfigError = rb_define_class_under(mOSSL, "ConfigError", eOSSLError);

data/ext/rubysl/openssl/ossl_config.h

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_config.h 25189 2009-10-02 12:04:37Z akr $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
  * All rights reserved.

data/ext/rubysl/openssl/ossl_digest.c

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_digest.c 48791 2014-12-12 21:57:44Z nobu $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
  * All rights reserved.
@@ -11,7 +11,7 @@
 #include "ossl.h"
 
 #define GetDigest(obj, ctx) do { \
-    Data_Get_Struct((obj), EVP_MD_CTX, (ctx)); \
+    TypedData_Get_Struct((obj), EVP_MD_CTX, &ossl_digest_type, (ctx)); \
     if (!(ctx)) { \
 	ossl_raise(rb_eRuntimeError, "Digest CTX wasn't initialized!"); \
     } \
@@ -29,6 +29,20 @@ VALUE eDigestError;
 
 static VALUE ossl_digest_alloc(VALUE klass);
 
+static void
+ossl_digest_free(void *ctx)
+{
+    EVP_MD_CTX_destroy(ctx);
+}
+
+static const rb_data_type_t ossl_digest_type = {
+    "OpenSSL/Digest",
+    {
+	0, ossl_digest_free,
+    },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
 /*
  * Public
  */
@@ -38,7 +52,7 @@ GetDigestPtr(VALUE obj)
     const EVP_MD *md;
     ASN1_OBJECT *oid = NULL;
 
-    if (TYPE(obj) == T_STRING) {
+    if (RB_TYPE_P(obj, T_STRING)) {
     	const char *name = StringValueCStr(obj);
 
 	md = EVP_get_digestbyname(name);
@@ -87,7 +101,7 @@ ossl_digest_alloc(VALUE klass)
     ctx = EVP_MD_CTX_create();
     if (ctx == NULL)
 	ossl_raise(rb_eRuntimeError, "EVP_MD_CTX_create() failed");
-    obj = Data_Wrap_Struct(klass, 0, EVP_MD_CTX_destroy, ctx);
+    obj = TypedData_Wrap_Struct(klass, &ossl_digest_type, ctx);
 
     return obj;
 }
@@ -294,10 +308,8 @@ ossl_digest_block_length(VALUE self)
  * INIT
  */
 void
-Init_ossl_digest()
+Init_ossl_digest(void)
 {
-    rb_require("digest");
-
 #if 0
     mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
 #endif

data/ext/rubysl/openssl/ossl_digest.h

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_digest.h 25189 2009-10-02 12:04:37Z akr $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
  * All rights reserved.

data/ext/rubysl/openssl/ossl_engine.c

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_engine.c 48792 2014-12-12 21:57:49Z nobu $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2003  GOTOU Yuuzou <gotoyuzo@notwork.org>
  * All rights reserved.
@@ -16,10 +16,10 @@
     if (!(engine)) { \
 	ossl_raise(rb_eRuntimeError, "ENGINE wasn't initialized."); \
     } \
-    (obj) = Data_Wrap_Struct((klass), 0, ENGINE_free, (engine)); \
+    (obj) = TypedData_Wrap_Struct((klass), &ossl_engine_type, (engine)); \
 } while(0)
 #define GetEngine(obj, engine) do { \
-    Data_Get_Struct((obj), ENGINE, (engine)); \
+    TypedData_Get_Struct((obj), ENGINE, &ossl_engine_type, (engine)); \
     if (!(engine)) { \
         ossl_raise(rb_eRuntimeError, "ENGINE wasn't initialized."); \
     } \
@@ -57,6 +57,20 @@ do{\
   }\
 }while(0)
 
+static void
+ossl_engine_free(void *engine)
+{
+    ENGINE_free(engine);
+}
+
+static const rb_data_type_t ossl_engine_type = {
+    "OpenSSL/Engine",
+    {
+	0, ossl_engine_free,
+    },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
 /* Document-method: OpenSSL::Engine.load
  *
  * call-seq:
@@ -523,24 +537,17 @@ ossl_engine_get_cmds(VALUE self)
 static VALUE
 ossl_engine_inspect(VALUE self)
 {
-    VALUE str;
-    const char *cname = rb_class2name(rb_obj_class(self));
-
-    str = rb_str_new2("#<");
-    rb_str_cat2(str, cname);
-    rb_str_cat2(str, " id=\"");
-    rb_str_append(str, ossl_engine_get_id(self));
-    rb_str_cat2(str, "\" name=\"");
-    rb_str_append(str, ossl_engine_get_name(self));
-    rb_str_cat2(str, "\">");
-
-    return str;
+    ENGINE *e;
+
+    GetEngine(self, e);
+    return rb_sprintf("#<%"PRIsVALUE" id=\"%s\" name=\"%s\">",
+		      rb_obj_class(self), ENGINE_get_id(e), ENGINE_get_name(e));
 }
 
 #define DefEngineConst(x) rb_define_const(cEngine, #x, INT2NUM(ENGINE_##x))
 
 void
-Init_ossl_engine()
+Init_ossl_engine(void)
 {
     cEngine = rb_define_class_under(mOSSL, "Engine", rb_cObject);
     eEngineError = rb_define_class_under(cEngine, "EngineError", eOSSLError);
@@ -585,7 +592,7 @@ Init_ossl_engine()
 }
 #else
 void
-Init_ossl_engine()
+Init_ossl_engine(void)
 {
 }
 #endif

data/ext/rubysl/openssl/ossl_engine.h

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_engine.h 25189 2009-10-02 12:04:37Z akr $
  * '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_hmac.c

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_hmac.c 48793 2014-12-12 21:57:56Z nobu $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
  * All rights reserved.
@@ -13,9 +13,9 @@
 #include "ossl.h"
 
 #define MakeHMAC(obj, klass, ctx) \
-    (obj) = Data_Make_Struct((klass), HMAC_CTX, 0, ossl_hmac_free, (ctx))
+    (obj) = TypedData_Make_Struct((klass), HMAC_CTX, &ossl_hmac_type, (ctx))
 #define GetHMAC(obj, ctx) do { \
-    Data_Get_Struct((obj), HMAC_CTX, (ctx)); \
+    TypedData_Get_Struct((obj), HMAC_CTX, &ossl_hmac_type, (ctx)); \
     if (!(ctx)) { \
 	ossl_raise(rb_eRuntimeError, "HMAC wasn't initialized"); \
     } \
@@ -39,12 +39,20 @@ VALUE eHMACError;
  * Private
  */
 static void
-ossl_hmac_free(HMAC_CTX *ctx)
+ossl_hmac_free(void *ctx)
 {
     HMAC_CTX_cleanup(ctx);
     ruby_xfree(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)
 {
@@ -327,7 +335,7 @@ ossl_hmac_s_hexdigest(VALUE klass, VALUE digest, VALUE key, VALUE data)
  * INIT
  */
 void
-Init_ossl_hmac()
+Init_ossl_hmac(void)
 {
 #if 0
     /* :nodoc: */
@@ -357,8 +365,8 @@ Init_ossl_hmac()
 #else /* NO_HMAC */
 #  warning >>> OpenSSL is compiled without HMAC support <<<
 void
-Init_ossl_hmac()
+Init_ossl_hmac(void)
 {
-    rb_warning("HMAC will NOT be avaible: OpenSSL is compiled without HMAC.");
+    rb_warning("HMAC is not available: OpenSSL is compiled without HMAC.");
 }
 #endif /* NO_HMAC */

data/ext/rubysl/openssl/ossl_hmac.h

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_hmac.h 25189 2009-10-02 12:04:37Z akr $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
  * All rights reserved.

data/ext/rubysl/openssl/ossl_ns_spki.c

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_ns_spki.c 48794 2014-12-12 21:58:03Z nobu $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2001-2002  Michal Rokos <m.rokos@sh.cvut.cz>
  * All rights reserved.
@@ -14,10 +14,10 @@
     if (!(spki)) { \
 	ossl_raise(rb_eRuntimeError, "SPKI wasn't initialized!"); \
     } \
-    (obj) = Data_Wrap_Struct((klass), 0, NETSCAPE_SPKI_free, (spki)); \
+    (obj) = TypedData_Wrap_Struct((klass), &ossl_netscape_spki_type, (spki)); \
 } while (0)
 #define GetSPKI(obj, spki) do { \
-    Data_Get_Struct((obj), NETSCAPE_SPKI, (spki)); \
+    TypedData_Get_Struct((obj), NETSCAPE_SPKI, &ossl_netscape_spki_type, (spki)); \
     if (!(spki)) { \
 	ossl_raise(rb_eRuntimeError, "SPKI wasn't initialized!"); \
     } \
@@ -37,6 +37,21 @@ VALUE eSPKIError;
 /*
  * Private functions
  */
+
+static void
+ossl_netscape_spki_free(void *spki)
+{
+    NETSCAPE_SPKI_free(spki);
+}
+
+static const rb_data_type_t ossl_netscape_spki_type = {
+    "OpenSSL/NETSCAPE_SPKI",
+    {
+	0, ossl_netscape_spki_free,
+    },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
 static VALUE
 ossl_spki_alloc(VALUE klass)
 {
@@ -360,7 +375,7 @@ ossl_spki_verify(VALUE self, VALUE key)
  */
 
 void
-Init_ossl_ns_spki()
+Init_ossl_ns_spki(void)
 {
 #if 0
     mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */

data/ext/rubysl/openssl/ossl_ns_spki.h

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_ns_spki.h 25189 2009-10-02 12:04:37Z akr $
  * '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

@@ -1,5 +1,5 @@
 /*
- * $Id$
+ * $Id: ossl_ocsp.c 48798 2014-12-12 21:58:22Z nobu $
  * 'OpenSSL for Ruby' project
  * Copyright (C) 2003  Michal Rokos <m.rokos@sh.cvut.cz>
  * Copyright (C) 2003  GOTOU Yuuzou <gotoyuzo@notwork.org>
@@ -15,10 +15,10 @@
 
 #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)); \
+    (obj) = TypedData_Wrap_Struct((klass), &ossl_ocsp_request_type, (req)); \
 } while (0)
 #define GetOCSPReq(obj, req) do { \
-    Data_Get_Struct((obj), OCSP_REQUEST, (req)); \
+    TypedData_Get_Struct((obj), OCSP_REQUEST, &ossl_ocsp_request_type, (req)); \
     if(!(req)) ossl_raise(rb_eRuntimeError, "Request wasn't initialized!"); \
 } while (0)
 #define SafeGetOCSPReq(obj, req) do { \
@@ -28,10 +28,10 @@
 
 #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)); \
+    (obj) = TypedData_Wrap_Struct((klass), &ossl_ocsp_response_type, (res)); \
 } while (0)
 #define GetOCSPRes(obj, res) do { \
-    Data_Get_Struct((obj), OCSP_RESPONSE, (res)); \
+    TypedData_Get_Struct((obj), OCSP_RESPONSE, &ossl_ocsp_response_type, (res)); \
     if(!(res)) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
 } while (0)
 #define SafeGetOCSPRes(obj, res) do { \
@@ -41,10 +41,10 @@
 
 #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)); \
+    (obj) = TypedData_Wrap_Struct((klass), &ossl_ocsp_basicresp_type, (res)); \
 } while (0)
 #define GetOCSPBasicRes(obj, res) do { \
-    Data_Get_Struct((obj), OCSP_BASICRESP, (res)); \
+    TypedData_Get_Struct((obj), OCSP_BASICRESP, &ossl_ocsp_basicresp_type, (res)); \
     if(!(res)) ossl_raise(rb_eRuntimeError, "Response wasn't initialized!"); \
 } while (0)
 #define SafeGetOCSPBasicRes(obj, res) do { \
@@ -54,10 +54,10 @@
 
 #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)); \
+    (obj) = TypedData_Wrap_Struct((klass), &ossl_ocsp_certid_type, (cid)); \
 } while (0)
 #define GetOCSPCertId(obj, cid) do { \
-    Data_Get_Struct((obj), OCSP_CERTID, (cid)); \
+    TypedData_Get_Struct((obj), OCSP_CERTID, &ossl_ocsp_certid_type, (cid)); \
     if(!(cid)) ossl_raise(rb_eRuntimeError, "Cert ID wasn't initialized!"); \
 } while (0)
 #define SafeGetOCSPCertId(obj, cid) do { \
@@ -72,6 +72,62 @@ VALUE cOCSPRes;
 VALUE cOCSPBasicRes;
 VALUE cOCSPCertId;
 
+static void
+ossl_ocsp_request_free(void *ptr)
+{
+    OCSP_REQUEST_free(ptr);
+}
+
+static const rb_data_type_t ossl_ocsp_request_type = {
+    "OpenSSL/OCSP/REQUEST",
+    {
+	0, ossl_ocsp_request_free,
+    },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static void
+ossl_ocsp_response_free(void *ptr)
+{
+    OCSP_RESPONSE_free(ptr);
+}
+
+static const rb_data_type_t ossl_ocsp_response_type = {
+    "OpenSSL/OCSP/RESPONSE",
+    {
+	0, ossl_ocsp_response_free,
+    },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static void
+ossl_ocsp_basicresp_free(void *ptr)
+{
+    OCSP_BASICRESP_free(ptr);
+}
+
+static const rb_data_type_t ossl_ocsp_basicresp_type = {
+    "OpenSSL/OCSP/BASICRESP",
+    {
+	0, ossl_ocsp_basicresp_free,
+    },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static void
+ossl_ocsp_certid_free(void *ptr)
+{
+    OCSP_CERTID_free(ptr);
+}
+
+static const rb_data_type_t ossl_ocsp_certid_type = {
+    "OpenSSL/OCSP/CERTID",
+    {
+	0, ossl_ocsp_certid_free,
+    },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
 /*
  * Public
  */
@@ -99,6 +155,15 @@ ossl_ocspreq_alloc(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq:
+ *   OpenSSL::OCSP::Request.new              -> request
+ *   OpenSSL::OCSP::Request.new(request_der) -> request
+ *
+ * Creates a new OpenSSL::OCSP::Request.  The request may be created empty or
+ * from a +request_der+ string.
+ */
+
 static VALUE
 ossl_ocspreq_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -121,6 +186,17 @@ ossl_ocspreq_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   request.add_nonce(nonce = nil) -> request
+ *
+ * Adds a +nonce+ to the OCSP request.  If no nonce is given a random one will
+ * be generated.
+ *
+ * The nonce is used to prevent replay attacks but some servers do not support
+ * it.
+ */
+
 static VALUE
 ossl_ocspreq_add_nonce(int argc, VALUE *argv, VALUE self)
 {
@@ -143,18 +219,25 @@ ossl_ocspreq_add_nonce(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
-/* Check nonce validity in a request and response.
- * Return value reflects result:
- *  1: nonces present and equal.
- *  2: nonces both absent.
- *  3: nonce present in response only.
- *  0: nonces both present and not equal.
- *  -1: nonce in request only.
+/*
+ * call-seq:
+ *   request.check_nonce(response) -> result
+ *
+ * Checks the nonce validity for this request and +response+.
+ *
+ * The return value is one of the following:
  *
- *  For most responders clients can check return > 0.
- *  If responder doesn't handle nonces return != 0 may be
- *  necessary. return == 0 is always an error.
+ * -1 :: nonce in request only.
+ *  0 :: nonces both present and not equal.
+ *  1 :: nonces present and equal.
+ *  2 :: nonces both absent.
+ *  3 :: nonce present in response only.
+ *
+ * For most responses, clients can check +result+ > 0.  If a responder doesn't
+ * handle nonces <code>result.nonzero?</code> may be necessary.  A result of
+ * <code>0</code> is always an error.
  */
+
 static VALUE
 ossl_ocspreq_check_nonce(VALUE self, VALUE basic_resp)
 {
@@ -169,6 +252,13 @@ ossl_ocspreq_check_nonce(VALUE self, VALUE basic_resp)
     return INT2NUM(res);
 }
 
+/*
+ * call-seq:
+ *   request.add_certid(certificate_id) -> request
+ *
+ * Adds +certificate_id+ to the request.
+ */
+
 static VALUE
 ossl_ocspreq_add_certid(VALUE self, VALUE certid)
 {
@@ -183,6 +273,13 @@ ossl_ocspreq_add_certid(VALUE self, VALUE certid)
     return self;
 }
 
+/*
+ * call-seq:
+ *   request.certid -> [certificate_id, ...]
+ *
+ * Returns all certificate IDs in this request.
+ */
+
 static VALUE
 ossl_ocspreq_get_certid(VALUE self)
 {
@@ -206,6 +303,17 @@ ossl_ocspreq_get_certid(VALUE self)
     return ary;
 }
 
+/*
+ * call-seq:
+ *   request.sign(signer_cert, signer_key)                      -> self
+ *   request.sign(signer_cert, signer_key, certificates)        -> self
+ *   request.sign(signer_cert, signer_key, certificates, flags) -> self
+ *
+ * Signs this OCSP request using +signer_cert+ and +signer_key+.
+ * +certificates+ is an optional Array of certificates that may be included in
+ * the request.
+ */
+
 static VALUE
 ossl_ocspreq_sign(int argc, VALUE *argv, VALUE self)
 {
@@ -234,6 +342,14 @@ ossl_ocspreq_sign(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   request.verify(certificates, store)        -> true or false
+ *   request.verify(certificates, store, flags) -> true or false
+ *
+ * Verifies this request using the given +certificates+ and X509 +store+.
+ */
+
 static VALUE
 ossl_ocspreq_verify(int argc, VALUE *argv, VALUE self)
 {
@@ -255,6 +371,10 @@ ossl_ocspreq_verify(int argc, VALUE *argv, VALUE self)
     return result ? Qtrue : Qfalse;
 }
 
+/*
+ * Returns this request as a DER-encoded string
+ */
+
 static VALUE
 ossl_ocspreq_to_der(VALUE self)
 {
@@ -278,6 +398,13 @@ ossl_ocspreq_to_der(VALUE self)
 /*
  * OCSP::Response
  */
+
+/* call-seq:
+ *   OpenSSL::OCSP::Response.create(status, basic_response = nil) -> response
+ *
+ * Creates an OpenSSL::OCSP::Response from +status+ and +basic_response+.
+ */
+
 static VALUE
 ossl_ocspres_s_create(VALUE klass, VALUE status, VALUE basic_resp)
 {
@@ -308,6 +435,15 @@ ossl_ocspres_alloc(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq:
+ *   OpenSSL::OCSP::Response.new               -> response
+ *   OpenSSL::OCSP::Response.new(response_der) -> response
+ *
+ * Creates a new OpenSSL::OCSP::Response.  The response may be created empty or
+ * from a +response_der+ string.
+ */
+
 static VALUE
 ossl_ocspres_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -330,6 +466,13 @@ ossl_ocspres_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   response.status -> Integer
+ *
+ * Returns the status of the response.
+ */
+
 static VALUE
 ossl_ocspres_status(VALUE self)
 {
@@ -342,6 +485,13 @@ ossl_ocspres_status(VALUE self)
     return INT2NUM(st);
 }
 
+/*
+ * call-seq:
+ *   response.status_string -> String
+ *
+ * Returns a status string for the response.
+ */
+
 static VALUE
 ossl_ocspres_status_string(VALUE self)
 {
@@ -354,6 +504,13 @@ ossl_ocspres_status_string(VALUE self)
     return rb_str_new2(OCSP_response_status_str(st));
 }
 
+/*
+ * call-seq:
+ *   response.basic
+ *
+ * Returns a BasicResponse for this response
+ */
+
 static VALUE
 ossl_ocspres_get_basic(VALUE self)
 {
@@ -369,6 +526,13 @@ ossl_ocspres_get_basic(VALUE self)
     return ret;
 }
 
+/*
+ * call-seq:
+ *   response.to_der -> String
+ *
+ * Returns this response as a DER-encoded string.
+ */
+
 static VALUE
 ossl_ocspres_to_der(VALUE self)
 {
@@ -405,12 +569,27 @@ ossl_ocspbres_alloc(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq:
+ *   OpenSSL::OCSP::BasicResponse.new(*) -> basic_response
+ *
+ * Creates a new BasicResponse and ignores all arguments.
+ */
+
 static VALUE
 ossl_ocspbres_initialize(int argc, VALUE *argv, VALUE self)
 {
     return self;
 }
 
+/*
+ * call-seq:
+ *   basic_response.copy_nonce(request) -> Integer
+ *
+ * Copies the nonce from +request+ into this response.  Returns 1 on success
+ * and 0 on failure.
+ */
+
 static VALUE
 ossl_ocspbres_copy_nonce(VALUE self, VALUE request)
 {
@@ -425,6 +604,14 @@ ossl_ocspbres_copy_nonce(VALUE self, VALUE request)
     return INT2NUM(ret);
 }
 
+/*
+ * call-seq:
+ *   basic_response.add_nonce(nonce = nil)
+ *
+ * Adds +nonce+ to this response.  If no nonce was provided a random nonce
+ * will be added.
+ */
+
 static VALUE
 ossl_ocspbres_add_nonce(int argc, VALUE *argv, VALUE self)
 {
@@ -447,6 +634,22 @@ ossl_ocspbres_add_nonce(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   basic_response.add_status(certificate_id, status, reason, revocation_time, this_update, next_update, extensions) -> basic_response
+ *
+ * Adds a validation +status+ (0 for revoked, 1 for success) to this
+ * response for +certificate_id+.  +reason+ describes the reason for the
+ * revocation, if any.
+ *
+ * The +revocation_time+, +this_update+ and +next_update+ are times for the
+ * certificate's revocation time, the time of this status and the next update
+ * time for a new status, respectively.
+ *
+ * +extensions+ may be an Array of OpenSSL::X509::Extension that will
+ * be added to this response or nil.
+ */
+
 static VALUE
 ossl_ocspbres_add_status(VALUE self, VALUE cid, VALUE status,
 			 VALUE reason, VALUE revtime,
@@ -515,6 +718,16 @@ ossl_ocspbres_add_status(VALUE self, VALUE cid, VALUE status,
     return self;
 }
 
+/*
+ * call-seq:
+ *   basic_response.status -> statuses
+ *
+ * Returns an Array of statuses for this response.  Each status contains a
+ * CertificateId, the status (0 for success, 1 for revoked), the reason for
+ * the status, the revocation time, the time of this update, the time for the
+ * next update and a list of OpenSSL::X509::Extensions.
+ */
+
 static VALUE
 ossl_ocspbres_get_status(VALUE self)
 {
@@ -560,6 +773,16 @@ ossl_ocspbres_get_status(VALUE self)
     return ret;
 }
 
+/*
+ * call-seq:
+ *   basic_response.sign(signer_cert, signer_key) -> self
+ *   basic_response.sign(signer_cert, signer_key, certificates) -> self
+ *   basic_response.sign(signer_cert, signer_key, certificates, flags) -> self
+ *
+ * Signs this response using the +signer_cert+ and +signer_key+.  Additional
+ * +certificates+ may be added to the signature along with a set of +flags+.
+ */
+
 static VALUE
 ossl_ocspbres_sign(int argc, VALUE *argv, VALUE self)
 {
@@ -590,6 +813,14 @@ ossl_ocspbres_sign(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   basic_response.verify(certificates, store) -> true or false
+ *   basic_response.verify(certificates, store, flags) -> true or false
+ *
+ * Verifies the signature of the response using the given +certificates+,
+ * +store+ and +flags+.
+ */
 static VALUE
 ossl_ocspbres_verify(int argc, VALUE *argv, VALUE self)
 {
@@ -627,6 +858,15 @@ ossl_ocspcid_alloc(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq:
+ *   OpenSSL::OCSP::CertificateId.new(subject, issuer, digest = nil) -> certificate_id
+ *
+ * Creates a new OpenSSL::OCSP::CertificateId for the given +subject+ and
+ * +issuer+ X509 certificates.  The +digest+ is used to compute the
+ * certificate ID and must be an OpenSSL::Digest instance.
+ */
+
 static VALUE
 ossl_ocspcid_initialize(int argc, VALUE *argv, VALUE self)
 {
@@ -657,6 +897,13 @@ ossl_ocspcid_initialize(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ * call-seq:
+ *   certificate_id.cmp(other) -> true or false
+ *
+ * Compares this certificate id with +other+ and returns true if they are the
+ * same.
+ */
 static VALUE
 ossl_ocspcid_cmp(VALUE self, VALUE other)
 {
@@ -670,6 +917,14 @@ ossl_ocspcid_cmp(VALUE self, VALUE other)
     return (result == 0) ? Qtrue : Qfalse;
 }
 
+/*
+ * call-seq:
+ *   certificate_id.cmp_issuer(other) -> true or false
+ *
+ * Compares this certificate id's issuer with +other+ and returns true if
+ * they are the same.
+ */
+
 static VALUE
 ossl_ocspcid_cmp_issuer(VALUE self, VALUE other)
 {
@@ -683,6 +938,13 @@ ossl_ocspcid_cmp_issuer(VALUE self, VALUE other)
     return (result == 0) ? Qtrue : Qfalse;
 }
 
+/*
+ * call-seq:
+ *   certificate_id.get_serial -> Integer
+ *
+ * Returns the serial number of the issuing certificate.
+ */
+
 static VALUE
 ossl_ocspcid_get_serial(VALUE self)
 {
@@ -694,12 +956,132 @@ ossl_ocspcid_get_serial(VALUE self)
 }
 
 void
-Init_ossl_ocsp()
+Init_ossl_ocsp(void)
 {
+    /*
+     * OpenSSL::OCSP implements Online Certificate Status Protocol requests
+     * and responses.
+     *
+     * Creating and sending an OCSP request requires a subject certificate
+     * that contains an OCSP URL in an authorityInfoAccess extension and the
+     * issuer certificate for the subject certificate.  First, load the issuer
+     * and subject certificates:
+     *
+     *   subject = OpenSSL::X509::Certificate.new subject_pem
+     *   issuer  = OpenSSL::X509::Certificate.new issuer_pem
+     *
+     * To create the request we need to create a certificate ID for the
+     * subject certificate so the CA knows which certificate we are asking
+     * about:
+     *
+     *   digest = OpenSSL::Digest::SHA1.new
+     *   certificate_id =
+     *     OpenSSL::OCSP::CertificateId.new subject, issuer, digest
+     *
+     * Then create a request and add the certificate ID to it:
+     *
+     *   request = OpenSSL::OCSP::Request.new
+     *   request.add_certid certificate_id
+     *
+     * Adding a nonce to the request protects against replay attacks but not
+     * all CA process the nonce.
+     *
+     *   request.add_nonce
+     *
+     * To submit the request to the CA for verification we need to extract the
+     * OCSP URI from the subject certificate:
+     *
+     *   authority_info_access = subject.extensions.find do |extension|
+     *     extension.oid == 'authorityInfoAccess'
+     *   end
+     *
+     *   descriptions = authority_info_access.value.split "\n"
+     *   ocsp = descriptions.find do |description|
+     *     description.start_with? 'OCSP'
+     *   end
+     *
+     *   require 'uri'
+     *
+     *   ocsp_uri = URI ocsp[/URI:(.*)/, 1]
+     *
+     * To submit the request we'll POST the request to the OCSP URI (per RFC
+     * 2560).  Note that we only handle HTTP requests and don't handle any
+     * redirects in this example, so this is insufficient for serious use.
+     *
+     *   require 'net/http'
+     *
+     *   http_response =
+     *     Net::HTTP.start ocsp_uri.hostname, ocsp.port do |http|
+     *       http.post ocsp_uri.path, request.to_der,
+     *                 'content-type' => 'application/ocsp-request'
+     *   end
+     *
+     *   response = OpenSSL::OCSP::Response.new http_response.body
+     *   response_basic = response.basic
+     *
+     * First we check if the response has a valid signature.  Without a valid
+     * signature we cannot trust it.  If you get a failure here you may be
+     * missing a system certificate store or may be missing the intermediate
+     * certificates.
+     *
+     *   store = OpenSSL::X509::Store.new
+     *   store.set_default_paths
+     *
+     *   unless response.verify [], store then
+     *     raise 'response is not signed by a trusted certificate'
+     *   end
+     *
+     * The response contains the status information (success/fail).  We can
+     * display the status as a string:
+     *
+     *   puts response.status_string #=> successful
+     *
+     * Next we need to know the response details to determine if the response
+     * matches our request.  First we check the nonce.  Again, not all CAs
+     * support a nonce.  See Request#check_nonce for the meanings of the
+     * return values.
+     *
+     *   p request.check_nonce basic_response #=> value from -1 to 3
+     *
+     * Then extract the status information from the basic response.  (You can
+     * check multiple certificates in a request, but for this example we only
+     * submitted one.)
+     *
+     *   response_certificate_id, status, reason, revocation_time,
+     *     this_update, next_update, extensions = basic_response.status
+     *
+     * Then check the various fields.
+     *
+     *   unless response_certificate_id == certificate_id then
+     *     raise 'certificate id mismatch'
+     *   end
+     *
+     *   now = Time.now
+     *
+     *   if this_update > now then
+     *     raise 'update date is in the future'
+     *   end
+     *
+     *   if now > next_update then
+     *     raise 'next update time has passed'
+     *   end
+     */
+
     mOCSP = rb_define_module_under(mOSSL, "OCSP");
 
+    /*
+     * OCSP error class.
+     */
+
     eOCSPError = rb_define_class_under(mOCSP, "OCSPError", eOSSLError);
 
+    /*
+     * An OpenSSL::OCSP::Request contains the certificate information for
+     * determining if a certificate has been revoked or not.  A Request can be
+     * created for a certificate or from a DER-encoded request created
+     * elsewhere.
+     */
+
     cOCSPReq = rb_define_class_under(mOCSP, "Request", rb_cObject);
     rb_define_alloc_func(cOCSPReq, ossl_ocspreq_alloc);
     rb_define_method(cOCSPReq, "initialize", ossl_ocspreq_initialize, -1);
@@ -711,6 +1093,11 @@ Init_ossl_ocsp()
     rb_define_method(cOCSPReq, "verify", ossl_ocspreq_verify, -1);
     rb_define_method(cOCSPReq, "to_der", ossl_ocspreq_to_der, 0);
 
+    /*
+     * An OpenSSL::OCSP::Response contains the status of a certificate check
+     * which is created from an OpenSSL::OCSP::Request.
+     */
+
     cOCSPRes = rb_define_class_under(mOCSP, "Response", rb_cObject);
     rb_define_singleton_method(cOCSPRes, "create", ossl_ocspres_s_create, 2);
     rb_define_alloc_func(cOCSPRes, ossl_ocspres_alloc);
@@ -720,6 +1107,12 @@ Init_ossl_ocsp()
     rb_define_method(cOCSPRes, "basic", ossl_ocspres_get_basic, 0);
     rb_define_method(cOCSPRes, "to_der", ossl_ocspres_to_der, 0);
 
+    /*
+     * An OpenSSL::OCSP::BasicResponse contains the status of a certificate
+     * check which is created from an OpenSSL::OCSP::Request.  A
+     * BasicResponse is more detailed than a Response.
+     */
+
     cOCSPBasicRes = rb_define_class_under(mOCSP, "BasicResponse", rb_cObject);
     rb_define_alloc_func(cOCSPBasicRes, ossl_ocspbres_alloc);
     rb_define_method(cOCSPBasicRes, "initialize", ossl_ocspbres_initialize, -1);
@@ -730,6 +1123,11 @@ Init_ossl_ocsp()
     rb_define_method(cOCSPBasicRes, "sign", ossl_ocspbres_sign, -1);
     rb_define_method(cOCSPBasicRes, "verify", ossl_ocspbres_verify, -1);
 
+    /*
+     * An OpenSSL::OCSP::CertificateId identifies a certificate to the CA so
+     * that a status check can be performed.
+     */
+
     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, -1);
@@ -737,50 +1135,110 @@ Init_ossl_ocsp()
     rb_define_method(cOCSPCertId, "cmp_issuer", ossl_ocspcid_cmp_issuer, 1);
     rb_define_method(cOCSPCertId, "serial", ossl_ocspcid_get_serial, 0);
 
-#define DefOCSPConst(x) rb_define_const(mOCSP, #x, INT2NUM(OCSP_##x))
-
-    DefOCSPConst(RESPONSE_STATUS_SUCCESSFUL);
-    DefOCSPConst(RESPONSE_STATUS_MALFORMEDREQUEST);
-    DefOCSPConst(RESPONSE_STATUS_INTERNALERROR);
-    DefOCSPConst(RESPONSE_STATUS_TRYLATER);
-    DefOCSPConst(RESPONSE_STATUS_SIGREQUIRED);
-    DefOCSPConst(RESPONSE_STATUS_UNAUTHORIZED);
-
-    DefOCSPConst(REVOKED_STATUS_NOSTATUS);
-    DefOCSPConst(REVOKED_STATUS_UNSPECIFIED);
-    DefOCSPConst(REVOKED_STATUS_KEYCOMPROMISE);
-    DefOCSPConst(REVOKED_STATUS_CACOMPROMISE);
-    DefOCSPConst(REVOKED_STATUS_AFFILIATIONCHANGED);
-    DefOCSPConst(REVOKED_STATUS_SUPERSEDED);
-    DefOCSPConst(REVOKED_STATUS_CESSATIONOFOPERATION);
-    DefOCSPConst(REVOKED_STATUS_CERTIFICATEHOLD);
-    DefOCSPConst(REVOKED_STATUS_REMOVEFROMCRL);
-
-    DefOCSPConst(NOCERTS);
-    DefOCSPConst(NOINTERN);
-    DefOCSPConst(NOSIGS);
-    DefOCSPConst(NOCHAIN);
-    DefOCSPConst(NOVERIFY);
-    DefOCSPConst(NOEXPLICIT);
-    DefOCSPConst(NOCASIGN);
-    DefOCSPConst(NODELEGATED);
-    DefOCSPConst(NOCHECKS);
-    DefOCSPConst(TRUSTOTHER);
-    DefOCSPConst(RESPID_KEY);
-    DefOCSPConst(NOTIME);
-
-#define DefOCSPVConst(x) rb_define_const(mOCSP, "V_" #x, INT2NUM(V_OCSP_##x))
-
-    DefOCSPVConst(CERTSTATUS_GOOD);
-    DefOCSPVConst(CERTSTATUS_REVOKED);
-    DefOCSPVConst(CERTSTATUS_UNKNOWN);
-    DefOCSPVConst(RESPID_NAME);
-    DefOCSPVConst(RESPID_KEY);
+    /* Internal error in issuer */
+    rb_define_const(mOCSP, "RESPONSE_STATUS_INTERNALERROR", INT2NUM(OCSP_RESPONSE_STATUS_INTERNALERROR));
+
+    /* Illegal confirmation request */
+    rb_define_const(mOCSP, "RESPONSE_STATUS_MALFORMEDREQUEST", INT2NUM(OCSP_RESPONSE_STATUS_MALFORMEDREQUEST));
+
+    /* The certificate was revoked for an unknown reason */
+    rb_define_const(mOCSP, "REVOKED_STATUS_NOSTATUS", INT2NUM(OCSP_REVOKED_STATUS_NOSTATUS));
+
+    /* You must sign the request and resubmit */
+    rb_define_const(mOCSP, "RESPONSE_STATUS_SIGREQUIRED", INT2NUM(OCSP_RESPONSE_STATUS_SIGREQUIRED));
+
+    /* Response has valid confirmations */
+    rb_define_const(mOCSP, "RESPONSE_STATUS_SUCCESSFUL", INT2NUM(OCSP_RESPONSE_STATUS_SUCCESSFUL));
+
+    /* Try again later */
+    rb_define_const(mOCSP, "RESPONSE_STATUS_TRYLATER", INT2NUM(OCSP_RESPONSE_STATUS_TRYLATER));
+
+    /* The certificate subject's name or other information changed */
+    rb_define_const(mOCSP, "REVOKED_STATUS_AFFILIATIONCHANGED", INT2NUM(OCSP_REVOKED_STATUS_AFFILIATIONCHANGED));
+
+    /* This CA certificate was revoked due to a key compromise */
+    rb_define_const(mOCSP, "REVOKED_STATUS_CACOMPROMISE", INT2NUM(OCSP_REVOKED_STATUS_CACOMPROMISE));
+
+    /* The certificate is on hold */
+    rb_define_const(mOCSP, "REVOKED_STATUS_CERTIFICATEHOLD", INT2NUM(OCSP_REVOKED_STATUS_CERTIFICATEHOLD));
+
+    /* The certificate is no longer needed */
+    rb_define_const(mOCSP, "REVOKED_STATUS_CESSATIONOFOPERATION", INT2NUM(OCSP_REVOKED_STATUS_CESSATIONOFOPERATION));
+
+    /* The certificate was revoked due to a key compromise */
+    rb_define_const(mOCSP, "REVOKED_STATUS_KEYCOMPROMISE", INT2NUM(OCSP_REVOKED_STATUS_KEYCOMPROMISE));
+
+    /* The certificate was previously on hold and should now be removed from
+     * the CRL */
+    rb_define_const(mOCSP, "REVOKED_STATUS_REMOVEFROMCRL", INT2NUM(OCSP_REVOKED_STATUS_REMOVEFROMCRL));
+
+    /* The certificate was superseded by a new certificate */
+    rb_define_const(mOCSP, "REVOKED_STATUS_SUPERSEDED", INT2NUM(OCSP_REVOKED_STATUS_SUPERSEDED));
+
+    /* Your request is unauthorized. */
+    rb_define_const(mOCSP, "RESPONSE_STATUS_UNAUTHORIZED", INT2NUM(OCSP_RESPONSE_STATUS_UNAUTHORIZED));
+
+    /* The certificate was revoked for an unspecified reason */
+    rb_define_const(mOCSP, "REVOKED_STATUS_UNSPECIFIED", INT2NUM(OCSP_REVOKED_STATUS_UNSPECIFIED));
+
+    /* Do not include certificates in the response */
+    rb_define_const(mOCSP, "NOCERTS", INT2NUM(OCSP_NOCERTS));
+
+    /* Do not search certificates contained in the response for a signer */
+    rb_define_const(mOCSP, "NOINTERN", INT2NUM(OCSP_NOINTERN));
+
+    /* Do not check the signature on the response */
+    rb_define_const(mOCSP, "NOSIGS", INT2NUM(OCSP_NOSIGS));
+
+    /* Do not verify the certificate chain on the response */
+    rb_define_const(mOCSP, "NOCHAIN", INT2NUM(OCSP_NOCHAIN));
+
+    /* Do not verify the response at all */
+    rb_define_const(mOCSP, "NOVERIFY", INT2NUM(OCSP_NOVERIFY));
+
+    /* Do not check trust */
+    rb_define_const(mOCSP, "NOEXPLICIT", INT2NUM(OCSP_NOEXPLICIT));
+
+    /* (This flag is not used by OpenSSL 1.0.1g) */
+    rb_define_const(mOCSP, "NOCASIGN", INT2NUM(OCSP_NOCASIGN));
+
+    /* (This flag is not used by OpenSSL 1.0.1g) */
+    rb_define_const(mOCSP, "NODELEGATED", INT2NUM(OCSP_NODELEGATED));
+
+    /* Do not make additional signing certificate checks */
+    rb_define_const(mOCSP, "NOCHECKS", INT2NUM(OCSP_NOCHECKS));
+
+    /* Do not verify additional certificates */
+    rb_define_const(mOCSP, "TRUSTOTHER", INT2NUM(OCSP_TRUSTOTHER));
+
+    /* Identify the response by signing the certificate key ID */
+    rb_define_const(mOCSP, "RESPID_KEY", INT2NUM(OCSP_RESPID_KEY));
+
+    /* Do not include producedAt time in response */
+    rb_define_const(mOCSP, "NOTIME", INT2NUM(OCSP_NOTIME));
+
+    /* Indicates the certificate is not revoked but does not necessarily mean
+     * the certificate was issued or that this response is within the
+     * certificate's validity interval */
+    rb_define_const(mOCSP, "V_CERTSTATUS_GOOD", INT2NUM(V_OCSP_CERTSTATUS_GOOD));
+    /* Indicates the certificate has been revoked either permanently or
+     * temporarily (on hold). */
+    rb_define_const(mOCSP, "V_CERTSTATUS_REVOKED", INT2NUM(V_OCSP_CERTSTATUS_REVOKED));
+
+    /* Indicates the responder does not know about the certificate being
+     * requested. */
+    rb_define_const(mOCSP, "V_CERTSTATUS_UNKNOWN", INT2NUM(V_OCSP_CERTSTATUS_UNKNOWN));
+
+    /* The responder ID is based on the key name. */
+    rb_define_const(mOCSP, "V_RESPID_NAME", INT2NUM(V_OCSP_RESPID_NAME));
+
+    /* The responder ID is based on the public key. */
+    rb_define_const(mOCSP, "V_RESPID_KEY", INT2NUM(V_OCSP_RESPID_KEY));
 }
 
 #else /* ! OSSL_OCSP_ENABLED */
 void
-Init_ossl_ocsp()
+Init_ossl_ocsp(void)
 {
 }
 #endif