rubysl-openssl 2.1.0 → 2.2.0

data/ext/rubysl/openssl/ossl_engine.c

@@ -32,7 +32,18 @@
 /*
  * Classes
  */
+/* Document-class: OpenSSL::Engine
+ *
+ * This class is the access to openssl's ENGINE cryptographic module
+ * implementation.
+ *
+ * See also, https://www.openssl.org/docs/crypto/engine.html
+ */
 VALUE cEngine;
+/* Document-class: OpenSSL::Engine::EngineError
+ *
+ * This is the generic exception for OpenSSL::Engine related errors
+ */
 VALUE eEngineError;
 
 /*
@@ -46,6 +57,17 @@ do{\
   }\
 }while(0)
 
+/* Document-method: OpenSSL::Engine.load
+ *
+ * call-seq:
+ *   load(enginename = nil)
+ *
+ * This method loads engines. If +name+ is nil, then all builtin engines are
+ * loaded. Otherwise, the given +name+, as a string,  is loaded if available to
+ * your runtime, and returns true. If +name+ is not found, then nil is
+ * returned.
+ *
+ */
 static VALUE
 ossl_engine_s_load(int argc, VALUE *argv, VALUE klass)
 {
@@ -116,6 +138,15 @@ ossl_engine_s_load(int argc, VALUE *argv, VALUE klass)
 #endif /* HAVE_ENGINE_LOAD_BUILTIN_ENGINES */
 }
 
+/* Document-method: OpenSSL::Engine.cleanup
+ * call-seq:
+ *  OpenSSL::Engine.cleanup
+ *
+ * It is only necessary to run cleanup when engines are loaded via
+ * OpenSSL::Engine.load. However, running cleanup before exit is recommended.
+ *
+ * See also, https://www.openssl.org/docs/crypto/engine.html
+ */
 static VALUE
 ossl_engine_s_cleanup(VALUE self)
 {
@@ -125,6 +156,10 @@ ossl_engine_s_cleanup(VALUE self)
     return Qnil;
 }
 
+/* Document-method: OpenSSL::Engine.engines
+ *
+ * Returns an array of currently loaded engines.
+ */
 static VALUE
 ossl_engine_s_engines(VALUE klass)
 {
@@ -144,6 +179,18 @@ ossl_engine_s_engines(VALUE klass)
     return ary;
 }
 
+/* Document-method: OpenSSL::Engine.by_id
+ *
+ * call-seq:
+ *   by_id(name) -> engine
+ *
+ * Fetch the engine as specified by the +id+ String
+ *
+ *   OpenSSL::Engine.by_id("openssl")
+ *    => #<OpenSSL::Engine id="openssl" name="Software engine support">
+ *
+ * See OpenSSL::Engine.engines for the currently loaded engines
+ */
 static VALUE
 ossl_engine_s_by_id(VALUE klass, VALUE id)
 {
@@ -179,6 +226,15 @@ ossl_engine_s_alloc(VALUE klass)
     return obj;
 }
 
+/* Document-method: OpenSSL::Engine#id
+ *
+ * Get the id for this engine
+ *
+ *    OpenSSL::Engine.load
+ *    OpenSSL::Engine.engines #=> [#<OpenSSL::Engine#>, ...]
+ *    OpenSSL::Engine.engines.first.id
+ *	#=> "rsax"
+ */
 static VALUE
 ossl_engine_get_id(VALUE self)
 {
@@ -187,6 +243,16 @@ ossl_engine_get_id(VALUE self)
     return rb_str_new2(ENGINE_get_id(e));
 }
 
+/* Document-method: OpenSSL::Engine#name
+ *
+ * Get the descriptive name for this engine
+ *
+ *    OpenSSL::Engine.load
+ *    OpenSSL::Engine.engines #=> [#<OpenSSL::Engine#>, ...]
+ *    OpenSSL::Engine.engines.first.name
+ *	#=> "RSAX engine support"
+ *
+ */
 static VALUE
 ossl_engine_get_name(VALUE self)
 {
@@ -195,6 +261,12 @@ ossl_engine_get_name(VALUE self)
     return rb_str_new2(ENGINE_get_name(e));
 }
 
+/* Document-method: OpenSSL::Engine#finish
+ *
+ * Releases all internal structural references for this engine.
+ *
+ * May raise an EngineError if the engine is unavailable
+ */
 static VALUE
 ossl_engine_finish(VALUE self)
 {
@@ -207,6 +279,22 @@ ossl_engine_finish(VALUE self)
 }
 
 #if defined(HAVE_ENGINE_GET_CIPHER)
+/* Document-method: OpenSSL::Engine#cipher
+ *
+ * call-seq:
+ *   engine.cipher(name) -> OpenSSL::Cipher
+ *
+ * This returns an OpenSSL::Cipher by +name+, if it is available in this
+ * engine.
+ *
+ * A EngineError will be raised if the cipher is unavailable.
+ *
+ *    e = OpenSSL::Engine.by_id("openssl")
+ *     => #<OpenSSL::Engine id="openssl" name="Software engine support">
+ *    e.cipher("RC4")
+ *     => #<OpenSSL::Cipher:0x007fc5cacc3048>
+ *
+ */
 static VALUE
 ossl_engine_get_cipher(VALUE self, VALUE name)
 {
@@ -230,6 +318,22 @@ ossl_engine_get_cipher(VALUE self, VALUE name)
 #endif
 
 #if defined(HAVE_ENGINE_GET_DIGEST)
+/* Document-method: OpenSSL::Engine#digest
+ *
+ * call-seq:
+ *   engine.digest(name) -> OpenSSL::Digest
+ *
+ * This returns an OpenSSL::Digest by +name+.
+ *
+ * Will raise an EngineError if the digest is unavailable.
+ *
+ *    e = OpenSSL::Engine.by_id("openssl")
+ *	#=> #<OpenSSL::Engine id="openssl" name="Software engine support">
+ *    e.digest("SHA1")
+ *	#=> #<OpenSSL::Digest: da39a3ee5e6b4b0d3255bfef95601890afd80709>
+ *    e.digest("zomg")
+ *	#=> OpenSSL::Engine::EngineError: no such digest `zomg'
+ */
 static VALUE
 ossl_engine_get_digest(VALUE self, VALUE name)
 {
@@ -252,6 +356,16 @@ ossl_engine_get_digest(VALUE self, VALUE name)
 #define ossl_engine_get_digest rb_f_notimplement
 #endif
 
+/* Document-method: OpenSSL::Engine#load_private_key
+ *
+ * call-seq:
+ *    engine.load_private_key(id = nil, data = nil) -> OpenSSL::PKey
+ *
+ * Loads the given private key by +id+ and +data+.
+ *
+ * An EngineError is raised of the OpenSSL::PKey is unavailable.
+ *
+ */
 static VALUE
 ossl_engine_load_privkey(int argc, VALUE *argv, VALUE self)
 {
@@ -276,6 +390,16 @@ ossl_engine_load_privkey(int argc, VALUE *argv, VALUE self)
     return obj;
 }
 
+/* Document-method: OpenSSL::Engine#load_public_key
+ *
+ * call-seq:
+ *    engine.load_public_key(id = nil, data = nil) -> OpenSSL::PKey
+ *
+ * Loads the given private key by +id+ and +data+.
+ *
+ * An EngineError is raised of the OpenSSL::PKey is unavailable.
+ *
+ */
 static VALUE
 ossl_engine_load_pubkey(int argc, VALUE *argv, VALUE self)
 {
@@ -298,6 +422,23 @@ ossl_engine_load_pubkey(int argc, VALUE *argv, VALUE self)
     return ossl_pkey_new(pkey);
 }
 
+/* Document-method: OpenSSL::Engine#set_default
+ *
+ * call-seq:
+ *    engine.set_default(flag)
+ *
+ * Set the defaults for this engine with the given +flag+.
+ *
+ * These flags are used to control combinations of algorithm methods.
+ *
+ * +flag+ can be one of the following, other flags are available depending on
+ * your OS.
+ *
+ * [All flags]  0xFFFF
+ * [No flags]	0x0000
+ *
+ * See also <openssl/engine.h>
+ */
 static VALUE
 ossl_engine_set_default(VALUE self, VALUE flag)
 {
@@ -310,6 +451,15 @@ ossl_engine_set_default(VALUE self, VALUE flag)
     return Qtrue;
 }
 
+/* Document-method: OpenSSL::Engine#ctrl_cmd
+ *
+ * call-seq:
+ *    engine.ctrl_cmd(command, value = nil) -> engine
+ *
+ * Send the given +command+ to this engine.
+ *
+ * Raises an EngineError if the +command+ fails.
+ */
 static VALUE
 ossl_engine_ctrl_cmd(int argc, VALUE *argv, VALUE self)
 {
@@ -340,6 +490,10 @@ ossl_engine_cmd_flag_to_name(int flag)
     }
 }
 
+/* Document-method: OpenSSL::Engine#cmds
+ *
+ * Returns an array of command definitions for the current engine
+ */
 static VALUE
 ossl_engine_get_cmds(VALUE self)
 {
@@ -362,6 +516,10 @@ ossl_engine_get_cmds(VALUE self)
     return ary;
 }
 
+/* Document-method: OpenSSL::Engine#inspect
+ *
+ * Pretty print this engine
+ */
 static VALUE
 ossl_engine_inspect(VALUE self)
 {

data/ext/rubysl/openssl/ossl_hmac.c

@@ -62,6 +62,36 @@ ossl_hmac_alloc(VALUE klass)
  *  call-seq:
  *     HMAC.new(key, digest) -> hmac
  *
+ * Returns an instance of OpenSSL::HMAC set with the key and digest
+ * algorithm to be used. The instance represents the initial state of
+ * the message authentication code before any data has been processed.
+ * To process data with it, use the instance method #update with your
+ * data as an argument.
+ *
+ * === Example
+ *
+ *	key = 'key'
+ * 	digest = OpenSSL::Digest.new('sha1')
+ * 	instance = OpenSSL::HMAC.new(key, digest)
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ * 	instance.class
+ * 	#=> OpenSSL::HMAC
+ *
+ * === A note about comparisons
+ *
+ * Two instances won't be equal when they're compared, even if they have the
+ * same value. Use #to_s or #hexdigest to return the authentication code that
+ * the instance represents. For example:
+ *
+ *	other_instance = OpenSSL::HMAC.new('key', OpenSSL::Digest.new('sha1'))
+ *  	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *  	instance
+ *  	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *  	instance == other_instance
+ *  	#=> false
+ *  	instance.to_s == other_instance.to_s
+ *  	#=> true
+ *
  */
 static VALUE
 ossl_hmac_initialize(VALUE self, VALUE key, VALUE digest)
@@ -95,6 +125,19 @@ ossl_hmac_copy(VALUE self, VALUE other)
  *  call-seq:
  *     hmac.update(string) -> self
  *
+ * Returns +self+ updated with the message to be authenticated.
+ * Can be called repeatedly with chunks of the message.
+ *
+ * === Example
+ *
+ *	first_chunk = 'The quick brown fox jumps '
+ * 	second_chunk = 'over the lazy dog'
+ *
+ * 	instance.update(first_chunk)
+ * 	#=> 5b9a8038a65d571076d97fe783989e52278a492a
+ * 	instance.update(second_chunk)
+ * 	#=> de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9
+ *
  */
 static VALUE
 ossl_hmac_update(VALUE self, VALUE data)
@@ -125,7 +168,16 @@ hmac_final(HMAC_CTX *ctx, unsigned char **buf, unsigned int *buf_len)
 
 /*
  *  call-seq:
- *     hmac.digest -> aString
+ *     hmac.digest -> string
+ *
+ * Returns the authentication code an instance represents as a binary string.
+ *
+ * === Example
+ *
+ *	instance = OpenSSL::HMAC.new('key', OpenSSL::Digest.new('sha1'))
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ * 	instance.digest
+ * 	#=> "\xF4+\xB0\xEE\xB0\x18\xEB\xBDE\x97\xAEr\x13q\x1E\xC6\a`\x84?"
  *
  */
 static VALUE
@@ -145,7 +197,10 @@ ossl_hmac_digest(VALUE self)
 
 /*
  *  call-seq:
- *     hmac.hexdigest -> aString
+ *     hmac.hexdigest -> string
+ *
+ * Returns the authentication code an instance represents as a hex-encoded
+ * string.
  *
  */
 static VALUE
@@ -173,6 +228,20 @@ ossl_hmac_hexdigest(VALUE self)
  *  call-seq:
  *     hmac.reset -> self
  *
+ * Returns +self+ as it was when it was first initialized, with all processed
+ * data cleared from it.
+ *
+ * === Example
+ *
+ *	data = "The quick brown fox jumps over the lazy dog"
+ * 	instance = OpenSSL::HMAC.new('key', OpenSSL::Digest.new('sha1'))
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *
+ * 	instance.update(data)
+ * 	#=> de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9
+ * 	instance.reset
+ * 	#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
+ *
  */
 static VALUE
 ossl_hmac_reset(VALUE self)
@@ -189,6 +258,18 @@ ossl_hmac_reset(VALUE self)
  *  call-seq:
  *     HMAC.digest(digest, key, data) -> aString
  *
+ * Returns the authentication code as a binary string. The +digest+ parameter
+ * must be an instance of OpenSSL::Digest.
+ *
+ * === Example
+ *
+ *	key = 'key'
+ * 	data = 'The quick brown fox jumps over the lazy dog'
+ * 	digest = OpenSSL::Digest.new('sha1')
+ *
+ * 	hmac = OpenSSL::HMAC.digest(digest, key, data)
+ * 	#=> "\xDE|\x9B\x85\xB8\xB7\x8A\xA6\xBC\x8Az6\xF7\n\x90p\x1C\x9D\xB4\xD9"
+ *
  */
 static VALUE
 ossl_hmac_s_digest(VALUE klass, VALUE digest, VALUE key, VALUE data)
@@ -206,7 +287,19 @@ ossl_hmac_s_digest(VALUE klass, VALUE digest, VALUE key, VALUE data)
 
 /*
  *  call-seq:
- *     HMAC.digest(digest, key, data) -> aString
+ *     HMAC.hexdigest(digest, key, data) -> aString
+ *
+ * Returns the authentication code as a hex-encoded string. The +digest+
+ * parameter must be an instance of OpenSSL::Digest.
+ *
+ * === Example
+ *
+ *	key = 'key'
+ * 	data = 'The quick brown fox jumps over the lazy dog'
+ * 	digest = OpenSSL::Digest.new('sha1')
+ *
+ * 	hmac = OpenSSL::HMAC.hexdigest(digest, key, data)
+ * 	#=> "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9"
  *
  */
 static VALUE
@@ -237,6 +330,7 @@ void
 Init_ossl_hmac()
 {
 #if 0
+    /* :nodoc: */
     mOSSL = rb_define_module("OpenSSL"); /* let rdoc know about mOSSL */
 #endif
 

data/ext/rubysl/openssl/ossl_ocsp.c

@@ -149,7 +149,7 @@ ossl_ocspreq_add_nonce(int argc, VALUE *argv, VALUE self)
  *  2: nonces both absent.
  *  3: nonce present in response only.
  *  0: nonces both present and not equal.
- * -1: nonce in request only.
+ *  -1: nonce in request only.
  *
  *  For most responders clients can check return > 0.
  *  If responder doesn't handle nonces return != 0 may be
@@ -466,7 +466,7 @@ ossl_ocspbres_add_status(VALUE self, VALUE cid, VALUE status,
 	/* All ary's members should be X509Extension */
 	Check_Type(ext, T_ARRAY);
 	for (i = 0; i < RARRAY_LEN(ext); i++)
-	    OSSL_Check_Kind(rb_ary_entry(ext, i), cX509Ext);
+	    OSSL_Check_Kind(RARRAY_PTR(ext)[i], cX509Ext);
     }
 
     error = 0;
@@ -495,7 +495,7 @@ ossl_ocspbres_add_status(VALUE self, VALUE cid, VALUE status,
 	sk_X509_EXTENSION_pop_free(single->singleExtensions, X509_EXTENSION_free);
 	single->singleExtensions = NULL;
 	for(i = 0; i < RARRAY_LEN(ext); i++){
-	    x509ext = DupX509ExtPtr(rb_ary_entry(ext, i));
+	    x509ext = DupX509ExtPtr(RARRAY_PTR(ext)[i]);
 	    if(!OCSP_SINGLERESP_add_ext(single, x509ext, -1)){
 		X509_EXTENSION_free(x509ext);
 		error = 1;

data/ext/rubysl/openssl/ossl_pkcs7.c

@@ -624,7 +624,7 @@ pkcs7_get_crls(VALUE self)
 }
 
 static VALUE
-ossl_pkcs7_set_certs_i(VALUE i, VALUE arg)
+ossl_pkcs7_set_certs_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, arg))
 {
     return ossl_pkcs7_add_certificate(arg, i);
 }
@@ -664,7 +664,7 @@ ossl_pkcs7_add_crl(VALUE self, VALUE crl)
 }
 
 static VALUE
-ossl_pkcs7_set_crls_i(VALUE i, VALUE arg)
+ossl_pkcs7_set_crls_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, arg))
 {
     return ossl_pkcs7_add_crl(arg, i);
 }

data/ext/rubysl/openssl/ossl_pkey.c

@@ -112,7 +112,7 @@ ossl_pkey_new_from_file(VALUE filename)
     if (!(fp = fopen(RSTRING_PTR(filename), "r"))) {
 	ossl_raise(ePKeyError, "%s", strerror(errno));
     }
-    rb_update_max_fd(fileno(fp));
+    rb_fd_fix_cloexec(fileno(fp));
 
     pkey = PEM_read_PrivateKey(fp, NULL, ossl_pem_passwd_cb, NULL);
     fclose(fp);
@@ -318,13 +318,16 @@ ossl_pkey_verify(VALUE self, VALUE digest, VALUE sig, VALUE data)
 {
     EVP_PKEY *pkey;
     EVP_MD_CTX ctx;
+    int result;
 
     GetPKey(self, pkey);
-    EVP_VerifyInit(&ctx, GetDigestPtr(digest));
     StringValue(sig);
     StringValue(data);
+    EVP_VerifyInit(&ctx, GetDigestPtr(digest));
     EVP_VerifyUpdate(&ctx, RSTRING_PTR(data), RSTRING_LEN(data));
-    switch (EVP_VerifyFinal(&ctx, (unsigned char *)RSTRING_PTR(sig), RSTRING_LENINT(sig), pkey)) {
+    result = EVP_VerifyFinal(&ctx, (unsigned char *)RSTRING_PTR(sig), RSTRING_LENINT(sig), pkey);
+    EVP_MD_CTX_cleanup(&ctx);
+    switch (result) {
     case 0:
 	return Qfalse;
     case 1:

data/ext/rubysl/openssl/ossl_pkey_dh.c

@@ -278,7 +278,9 @@ ossl_dh_is_private(VALUE self)
 
 /*
  *  call-seq:
+ *     dh.export -> aString
  *     dh.to_pem -> aString
+ *     dh.to_s -> aString
  *
  * Encodes this DH to its PEM encoding. Note that any existing per-session
  * public/private keys will *not* get encoded, just the Diffie-Hellman
@@ -428,7 +430,7 @@ ossl_dh_to_public_key(VALUE self)
 
 /*
  *  call-seq:
- *     dh.check_params -> true | false
+ *     dh.params_ok? -> true | false
  *
  * Validates the Diffie-Hellman parameters associated with this instance.
  * It checks whether a safe prime and a suitable generator are used. If this
@@ -619,7 +621,7 @@ Init_ossl_dh()
      *
      * === Example of a key exchange
      *  dh1 = OpenSSL::PKey::DH.new(2048)
-     *  params = dh1.public_key.to_der #you may send this publicly to the participating party
+     *  der = dh1.public_key.to_der #you may send this publicly to the participating party
      *  dh2 = OpenSSL::PKey::DH.new(der)
      *  dh2.generate_key! #generate the per-session key pair
      *  symm_key1 = dh1.compute_key(dh2.pub_key)
@@ -662,4 +664,3 @@ Init_ossl_dh()
 {
 }
 #endif /* NO_DH */
-

data/ext/rubysl/openssl/ossl_pkey_dsa.c

@@ -291,7 +291,9 @@ ossl_dsa_is_private(VALUE self)
 
 /*
  *  call-seq:
+ *    dsa.export([cipher, password]) -> aString
  *    dsa.to_pem([cipher, password]) -> aString
+ *    dsa.to_s([cipher, password]) -> aString
  *
  * Encodes this DSA to its PEM encoding.
  *

data/ext/rubysl/openssl/ossl_pkey_ec.c

@@ -533,8 +533,8 @@ static VALUE ossl_ec_key_to_string(VALUE self, VALUE ciph, VALUE pass, int forma
 
 /*
  *  call-seq:
- *     key.export   => String
- *     key.export(cipher, pass_phrase) => String
+ *     key.export([cipher, pass_phrase]) => String
+ *     key.to_pem([cipher, pass_phrase]) => String
  *
  * Outputs the EC key in PEM encoding.  If +cipher+ and +pass_phrase+ are
  * given they will be used to encrypt the key.  +cipher+ must be an
@@ -847,6 +847,7 @@ static VALUE ossl_ec_group_initialize(int argc, VALUE *argv, VALUE self)
 }
 
 /*  call-seq:
+ *     group1.eql?(group2)   => true | false
  *     group1 == group2   => true | false
  *
  */
@@ -1316,6 +1317,7 @@ static VALUE ossl_ec_point_initialize(int argc, VALUE *argv, VALUE self)
 
 /*
  *  call-seq:
+ *     point1.eql?(point2) => true | false
  *     point1 == point2 => true | false
  *
  */

data/ext/rubysl/openssl/ossl_pkey_rsa.c

@@ -291,8 +291,9 @@ ossl_rsa_is_private(VALUE self)
 
 /*
  * call-seq:
- *   rsa.to_pem                      => PEM-format String
- *   rsa.to_pem(cipher, pass_phrase) => PEM-format String
+ *   rsa.export([cipher, pass_phrase]) => PEM-format String
+ *   rsa.to_pem([cipher, pass_phrase]) => PEM-format String
+ *   rsa.to_s([cipher, pass_phrase]) => PEM-format String
  *
  * Outputs this keypair in PEM encoding.  If +cipher+ and +pass_phrase+ are
  * given they will be used to encrypt the key.  +cipher+ must be an