https://git.ruby-lang.org/ruby.git/commit/?id=c46b1f0bec

From c46b1f0bec3af8c51a9eebc6408a2895eccdff91 Mon Sep 17 00:00:00 2001
From: Kazuki Yamaguchi <k@r...>
Date: Wed, 12 Aug 2020 17:45:36 +0900
Subject: [ruby/openssl] x509store: update rdoc for X509::Store and
 X509::StoreContext

Add more details about each method, and add reference to OpenSSL man
pages.

https://github.com/ruby/openssl/commit/02b6f82c73
---
 ext/openssl/ossl_x509store.c | 124 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 111 insertions(+), 13 deletions(-)

diff --git a/ext/openssl/ossl_x509store.c b/ext/openssl/ossl_x509store.c
index aba68ab..5e0ab8d 100644
--- a/ext/openssl/ossl_x509store.c
+++ b/ext/openssl/ossl_x509store.c
@@ -214,8 +214,16 @@ ossl_x509store_initialize(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L214
  * call-seq:
  *   store.flags = flags
  *
- * Sets _flags_ to the Store. _flags_ consists of zero or more of the constants
- * defined in with name V_FLAG_* or'ed together.
+ * Sets the default flags used by certificate chain verification performed with
+ * the Store.
+ *
+ * _flags_ consists of zero or more of the constants defined in OpenSSL::X509
+ * with name V_FLAG_* or'ed together.
+ *
+ * OpenSSL::X509::StoreContext#flags= can be used to change the flags for a
+ * single verification operation.
+ *
+ * See also the man page X509_VERIFY_PARAM_set_flags(3).
  */
 static VALUE
 ossl_x509store_set_flags(VALUE self, VALUE flags)
@@ -233,9 +241,9 @@ ossl_x509store_set_flags(VALUE self, VALUE flags) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L241
  * 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:
+ * Sets the store's default verification purpose. If specified,
+ * the verifications on the store will check every certificate's extensions are
+ * consistent with the purpose. The purpose is specified by constants:
  *
  * * X509::PURPOSE_SSL_CLIENT
  * * X509::PURPOSE_SSL_SERVER
@@ -246,6 +254,11 @@ ossl_x509store_set_flags(VALUE self, VALUE flags) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L254
  * * X509::PURPOSE_ANY
  * * X509::PURPOSE_OCSP_HELPER
  * * X509::PURPOSE_TIMESTAMP_SIGN
+ *
+ * OpenSSL::X509::StoreContext#purpose= can be used to change the value for a
+ * single verification operation.
+ *
+ * See also the man page X509_VERIFY_PARAM_set_purpose(3).
  */
 static VALUE
 ossl_x509store_set_purpose(VALUE self, VALUE purpose)
@@ -262,6 +275,14 @@ ossl_x509store_set_purpose(VALUE self, VALUE purpose) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L275
 /*
  * call-seq:
  *   store.trust = trust
+ *
+ * Sets the default trust settings used by the certificate verification with
+ * the store.
+ *
+ * OpenSSL::X509::StoreContext#trust= can be used to change the value for a
+ * single verification operation.
+ *
+ * See also the man page X509_VERIFY_PARAM_set_trust(3).
  */
 static VALUE
 ossl_x509store_set_trust(VALUE self, VALUE trust)
@@ -279,7 +300,13 @@ ossl_x509store_set_trust(VALUE self, VALUE trust) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L300
  * call-seq:
  *   store.time = time
  *
- * Sets the time to be used in verifications.
+ * Sets the time to be used in the certificate verifications with the store.
+ * By default, if not specified, the current system time is used.
+ *
+ * OpenSSL::X509::StoreContext#time= can be used to change the value for a
+ * single verification operation.
+ *
+ * See also the man page X509_VERIFY_PARAM_set_time(3).
  */
 static VALUE
 ossl_x509store_set_time(VALUE self, VALUE time)
@@ -295,6 +322,8 @@ ossl_x509store_set_time(VALUE self, VALUE time) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L322
  * Adds the certificates in _file_ to the certificate store. _file_ is the path
  * to the file, and the file contains one or more certificates in PEM format
  * concatenated together.
+ *
+ * See also the man page X509_LOOKUP_file(3).
  */
 static VALUE
 ossl_x509store_add_file(VALUE self, VALUE file)
@@ -328,6 +357,8 @@ ossl_x509store_add_file(VALUE self, VALUE file) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L357
  *   store.add_path(path) -> self
  *
  * Adds _path_ as the hash dir to be looked up by the store.
+ *
+ * See also the man page X509_LOOKUP_hash_dir(3).
  */
 static VALUE
 ossl_x509store_add_path(VALUE self, VALUE dir)
@@ -357,6 +388,8 @@ ossl_x509store_add_path(VALUE self, VALUE dir) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L388
  *
  * * OpenSSL::X509::DEFAULT_CERT_FILE
  * * OpenSSL::X509::DEFAULT_CERT_DIR
+ *
+ * See also the man page X509_STORE_set_default_paths(3).
  */
 static VALUE
 ossl_x509store_set_default_paths(VALUE self)
@@ -372,9 +405,11 @@ ossl_x509store_set_default_paths(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L405
 
 /*
  * call-seq:
- *   store.add_cert(cert)
+ *   store.add_cert(cert) -> self
  *
  * Adds the OpenSSL::X509::Certificate _cert_ to the certificate store.
+ *
+ * See also the man page X509_STORE_add_cert(3).
  */
 static VALUE
 ossl_x509store_add_cert(VALUE self, VALUE arg)
@@ -395,6 +430,8 @@ ossl_x509store_add_cert(VALUE self, VALUE arg) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L430
  *   store.add_crl(crl) -> self
  *
  * Adds the OpenSSL::X509::CRL _crl_ to the store.
+ *
+ * See also the man page X509_STORE_add_crl(3).
  */
 static VALUE
 ossl_x509store_add_crl(VALUE self, VALUE arg)
@@ -551,6 +588,10 @@ ossl_x509stctx_initialize(int argc, VALUE *argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L588
 /*
  * call-seq:
  *   stctx.verify -> true | false
+ *
+ * Performs the certificate verification using the parameters set to _stctx_.
+ *
+ * See also the man page X509_verify_cert(3).
  */
 static VALUE
 ossl_x509stctx_verify(VALUE self)
@@ -574,7 +615,11 @@ ossl_x509stctx_verify(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L615
 
 /*
  * call-seq:
- *   stctx.chain -> Array of X509::Certificate
+ *   stctx.chain -> nil | Array of X509::Certificate
+ *
+ * Returns the verified chain.
+ *
+ * See also the man page X509_STORE_CTX_set0_verified_chain(3).
  */
 static VALUE
 ossl_x509stctx_get_chain(VALUE self)
@@ -592,6 +637,12 @@ ossl_x509stctx_get_chain(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L637
 /*
  * call-seq:
  *   stctx.error -> Integer
+ *
+ * Returns the error code of _stctx_. This is typically called after #verify
+ * is done, or from the verification callback set to
+ * OpenSSL::X509::Store#verify_callback=.
+ *
+ * See also the man page X509_STORE_CTX_get_error(3).
  */
 static VALUE
 ossl_x509stctx_get_err(VALUE self)
@@ -606,6 +657,11 @@ ossl_x509stctx_get_err(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L657
 /*
  * call-seq:
  *   stctx.error = error_code
+ *
+ * Sets the error code of _stctx_. This is used by the verification callback
+ * set to OpenSSL::X509::Store#verify_callback=.
+ *
+ * See also the man page X509_STORE_CTX_set_error(3).
  */
 static VALUE
 ossl_x509stctx_set_error(VALUE self, VALUE err)
@@ -622,7 +678,10 @@ ossl_x509stctx_set_error(VALUE self, VALUE err) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L678
  * call-seq:
  *   stctx.error_string -> String
  *
- * Returns the error string corresponding to the error code retrieved by #error.
+ * Returns the human readable error string corresponding to the error code
+ * retrieved by #error.
+ *
+ * See also the man page X509_verify_cert_error_string(3).
  */
 static VALUE
 ossl_x509stctx_get_err_string(VALUE self)
@@ -639,6 +698,10 @@ ossl_x509stctx_get_err_string(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L698
 /*
  * call-seq:
  *   stctx.error_depth -> Integer
+ *
+ * Returns the depth of the chain. This is used in combination with #error.
+ *
+ * See also the man page X509_STORE_CTX_get_error_depth(3).
  */
 static VALUE
 ossl_x509stctx_get_err_depth(VALUE self)
@@ -653,6 +716,10 @@ ossl_x509stctx_get_err_depth(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L716
 /*
  * call-seq:
  *   stctx.current_cert -> X509::Certificate
+ *
+ * Returns the certificate which caused the error.
+ *
+ * See also the man page X509_STORE_CTX_get_current_cert(3).
  */
 static VALUE
 ossl_x509stctx_get_curr_cert(VALUE self)
@@ -667,6 +734,10 @@ ossl_x509stctx_get_curr_cert(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L734
 /*
  * call-seq:
  *   stctx.current_crl -> X509::CRL
+ *
+ * Returns the CRL which caused the error.
+ *
+ * See also the man page X509_STORE_CTX_get_current_crl(3).
  */
 static VALUE
 ossl_x509stctx_get_curr_crl(VALUE self)
@@ -686,7 +757,10 @@ ossl_x509stctx_get_curr_crl(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L757
  * call-seq:
  *   stctx.flags = flags
  *
- * Sets the verification flags to the context. See Store#flags=.
+ * Sets the verification flags to the context. This overrides the default value
+ * set by Store#flags=.
+ *
+ * See also the man page X509_VERIFY_PARAM_set_flags(3).
  */
 static VALUE
 ossl_x509stctx_set_flags(VALUE self, VALUE flags)
@@ -704,7 +778,10 @@ ossl_x509stctx_set_flags(VALUE self, VALUE flags) https://github.com/ruby/ruby/blob/trunk/ext/openssl/ossl_x509store.c#L778
  * call-seq:
  *   stctx.purpose = purpose
  *
- * Sets the purpose of the context. See Store#purpose=.
+ * Sets the purpose of the context. This overrides the default value set by
+ * Store#purpose=.
+ *
+ * See also the man page X509_VERIFY_PARAM_set_purp (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/