ossl.c: improve docs for constants and methods under ::OpenSSL

Author: rhenium

ext/openssl/ossl.c

@@ -388,10 +388,14 @@ osslerror_detailed_message(int argc, VALUE *argv, VALUE self)
  * call-seq:
  *   OpenSSL.errors -> [String...]
  *
- * See any remaining errors held in queue.
+ * Returns any remaining errors held in the OpenSSL thread-local error queue
+ * and clears the queue. This should normally return an empty array.
  *
- * Any errors you see here are probably due to a bug in Ruby's OpenSSL
- * implementation.
+ * This is intended for debugging Ruby/OpenSSL. If you see any errors here,
+ * it likely indicates a bug in the extension. Please file an issue at
+ * https://github.com/ruby/openssl.
+ *
+ * For debugging your program, OpenSSL.debug= may be useful.
  */
 static VALUE
 ossl_get_errors(VALUE _)
@@ -415,6 +419,8 @@ VALUE dOSSL;
 /*
  * call-seq:
  *   OpenSSL.debug -> true | false
+ *
+ * Returns whether Ruby/OpenSSL's debug mode is currently enabled.
  */
 static VALUE
 ossl_debug_get(VALUE self)
@@ -424,7 +430,7 @@ ossl_debug_get(VALUE self)
 
 /*
  * call-seq:
- *   OpenSSL.debug = boolean -> boolean
+ *   OpenSSL.debug = boolean
  *
  * Turns on or off debug mode. With debug mode, all errors added to the OpenSSL
  * error queue will be printed to stderr.
@@ -440,6 +446,8 @@ ossl_debug_set(VALUE self, VALUE val)
 /*
  * call-seq:
  *   OpenSSL.fips_mode -> true | false
+ *
+ * Returns whether the FIPS mode is currently enabled.
  */
 static VALUE
 ossl_fips_mode_get(VALUE self)
@@ -460,7 +468,7 @@ ossl_fips_mode_get(VALUE self)
 
 /*
  * call-seq:
- *   OpenSSL.fips_mode = boolean -> boolean
+ *   OpenSSL.fips_mode = boolean
  *
  * Turns FIPS mode on or off. Turning on FIPS mode will obviously only have an
  * effect for FIPS-capable installations of the OpenSSL library. Trying to do
@@ -503,13 +511,13 @@ ossl_fips_mode_set(VALUE self, VALUE enabled)
 
 /*
  * call-seq:
- *   OpenSSL.fixed_length_secure_compare(string, string) -> boolean
+ *   OpenSSL.fixed_length_secure_compare(string, string) -> true or false
  *
  * Constant time memory comparison for fixed length strings, such as results
- * of HMAC calculations.
+ * of \HMAC calculations.
  *
  * Returns +true+ if the strings are identical, +false+ if they are of the same
- * length but not identical. If the length is different, +ArgumentError+ is
+ * length but not identical. If the length is different, ArgumentError is
  * raised.
  */
 static VALUE
@@ -531,7 +539,7 @@ ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
 }
 
 /*
- * OpenSSL provides SSL, TLS and general purpose cryptography.  It wraps the
+ * OpenSSL provides \SSL, TLS and general purpose cryptography.  It wraps the
  * OpenSSL[https://www.openssl.org/] library.
  *
  * = Examples
@@ -899,23 +907,23 @@ ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
  *     io.write csr_cert.to_pem
  *   end
  *
- * == SSL and TLS Connections
+ * == \SSL and TLS Connections
  *
- * Using our created key and certificate we can create an SSL or TLS connection.
- * An SSLContext is used to set up an SSL session.
+ * Using our created key and certificate we can create an \SSL or TLS
+ * connection. An OpenSSL::SSL::SSLContext is used to set up an \SSL session.
  *
  *   context = OpenSSL::SSL::SSLContext.new
  *
- * === SSL Server
+ * === \SSL Server
  *
- * An SSL server requires the certificate and private key to communicate
+ * An \SSL server requires the certificate and private key to communicate
  * securely with its clients:
  *
  *   context.cert = cert
  *   context.key = key
  *
- * Then create an SSLServer with a TCP server socket and the context.  Use the
- * SSLServer like an ordinary TCP server.
+ * Then create an OpenSSL::SSL::SSLServer with a TCP server socket and the
+ * context.  Use the SSLServer like an ordinary TCP server.
  *
  *   require 'socket'
  *
@@ -934,14 +942,15 @@ ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
  *     ssl_connection.close
  *   end
  *
- * === SSL client
+ * === \SSL client
  *
- * An SSL client is created with a TCP socket and the context.
- * SSLSocket#connect must be called to initiate the SSL handshake and start
- * encryption.  A key and certificate are not required for the client socket.
+ * An \SSL client is created with a TCP socket and the context.
+ * OpenSSL::SSL::SSLSocket#connect must be called to initiate the \SSL handshake
+ * and start encryption.  A key and certificate are not required for the client
+ * socket.
  *
- * Note that SSLSocket#close doesn't close the underlying socket by default. Set
- * SSLSocket#sync_close to true if you want.
+ * Note that OpenSSL::SSL::SSLSocket#close doesn't close the underlying socket
+ * by default. Set OpenSSL::SSL::SSLSocket#sync_close to true if you want.
  *
  *   require 'socket'
  *
@@ -957,7 +966,7 @@ ossl_crypto_fixed_length_secure_compare(VALUE dummy, VALUE str1, VALUE str2)
  *
  * === Peer Verification
  *
- * An unverified SSL connection does not provide much security.  For enhanced
+ * An unverified \SSL connection does not provide much security.  For enhanced
  * security the client or server can verify the certificate of its peer.
  *
  * The client can be modified to verify the server's certificate against the
@@ -1008,13 +1017,14 @@ Init_openssl(void)
     rb_define_singleton_method(mOSSL, "fixed_length_secure_compare", ossl_crypto_fixed_length_secure_compare, 2);
 
     /*
-     * Version of OpenSSL the ruby OpenSSL extension was built with
+     * OpenSSL library version string used to compile the Ruby OpenSSL
+     * extension. This may differ from the version used at runtime.
      */
     rb_define_const(mOSSL, "OPENSSL_VERSION",
                     rb_obj_freeze(rb_str_new_cstr(OPENSSL_VERSION_TEXT)));
 
     /*
-     * Version of OpenSSL the ruby OpenSSL extension is running with
+     * OpenSSL library version string currently used at runtime.
      */
     rb_define_const(
         mOSSL,
@@ -1023,30 +1033,40 @@ Init_openssl(void)
     );
 
     /*
-     * Version number of OpenSSL the ruby OpenSSL extension was built with
-     * (base 16). The formats are below.
+     * OpenSSL library version number used to compile the Ruby OpenSSL
+     * extension. This may differ from the version used at runtime.
      *
-     * [OpenSSL 3] <tt>0xMNN00PP0 (major minor 00 patch 0)</tt>
-     * [OpenSSL before 3] <tt>0xMNNFFPPS (major minor fix patch status)</tt>
-     * [LibreSSL] <tt>0x20000000 (fixed value)</tt>
+     * The version number is encoded into a single integer value. The number
+     * follows the format:
+     *
+     * [OpenSSL 3.0.0 or later] <tt>0xMNN00PP0</tt> (major minor 00 patch 0)
+     * [OpenSSL 1.1.1 or earlier] <tt>0xMNNFFPPS</tt> (major minor fix patch status)
+     * [LibreSSL] <tt>0x20000000</tt> (a fixed value)
      *
      * See also the man page OPENSSL_VERSION_NUMBER(3).
      */
     rb_define_const(mOSSL, "OPENSSL_VERSION_NUMBER", INT2NUM(OPENSSL_VERSION_NUMBER));
 
 #if defined(LIBRESSL_VERSION_NUMBER)
     /*
-     * Version number of LibreSSL the ruby OpenSSL extension was built with
-     * (base 16). The format is <tt>0xMNNFF00f (major minor fix 00
-     * status)</tt>. This constant is only defined in LibreSSL cases.
+     * LibreSSL library version number used to compile the Ruby OpenSSL
+     * extension. This may differ from the version used at runtime.
+     *
+     * This constant is only defined if the extension was compiled against
+     * LibreSSL. The number follows the format:
+     * <tt>0xMNNFF00f</tt> (major minor fix 00 status).
      *
      * See also the man page LIBRESSL_VERSION_NUMBER(3).
      */
     rb_define_const(mOSSL, "LIBRESSL_VERSION_NUMBER", INT2NUM(LIBRESSL_VERSION_NUMBER));
 #endif
 
     /*
-     * Boolean indicating whether OpenSSL is FIPS-capable or not
+     * Boolean indicating whether the OpenSSL library is FIPS-capable or not.
+     * Always <tt>true</tt> for OpenSSL 3.0 or later.
+     *
+     * This is obsolete and will be removed in the future.
+     * See also OpenSSL.fips_mode.
      */
     rb_define_const(mOSSL, "OPENSSL_FIPS",
 /* OpenSSL 3 is FIPS-capable even when it is installed without fips option */

lib/openssl.rb

@@ -23,12 +23,16 @@
 require_relative 'openssl/x509'
 
 module OpenSSL
-  # call-seq:
-  #   OpenSSL.secure_compare(string, string) -> boolean
+  # :call-seq:
+  #    OpenSSL.secure_compare(string, string) -> true or false
   #
   # Constant time memory comparison. Inputs are hashed using SHA-256 to mask
   # the length of the secret. Returns +true+ if the strings are identical,
   # +false+ otherwise.
+  #
+  # This method is expensive due to the SHA-256 hashing. In most cases, where
+  # the input lengths are known to be equal or are not sensitive, use
+  # OpenSSL.fixed_length_secure_compare instead.
   def self.secure_compare(a, b)
     hashed_a = OpenSSL::Digest.digest('SHA256', a)
     hashed_b = OpenSSL::Digest.digest('SHA256', b)

lib/openssl/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module OpenSSL
+  # The version string of Ruby/OpenSSL.
   VERSION = "4.0.0.pre"
 end