Skip to content

Commit 02b6f82

Browse files
committed
x509store: update rdoc for X509::Store and X509::StoreContext
Add more details about each method, and add reference to OpenSSL man pages.
1 parent b31809b commit 02b6f82

File tree

1 file changed

+113
-13
lines changed

1 file changed

+113
-13
lines changed

ext/openssl/ossl_x509store.c

Lines changed: 113 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -214,8 +214,16 @@ ossl_x509store_initialize(int argc, VALUE *argv, VALUE self)
214214
* call-seq:
215215
* store.flags = flags
216216
*
217-
* Sets _flags_ to the Store. _flags_ consists of zero or more of the constants
218-
* defined in with name V_FLAG_* or'ed together.
217+
* Sets the default flags used by certificate chain verification performed with
218+
* the Store.
219+
*
220+
* _flags_ consists of zero or more of the constants defined in OpenSSL::X509
221+
* with name V_FLAG_* or'ed together.
222+
*
223+
* OpenSSL::X509::StoreContext#flags= can be used to change the flags for a
224+
* single verification operation.
225+
*
226+
* See also the man page X509_VERIFY_PARAM_set_flags(3).
219227
*/
220228
static VALUE
221229
ossl_x509store_set_flags(VALUE self, VALUE flags)
@@ -233,9 +241,9 @@ ossl_x509store_set_flags(VALUE self, VALUE flags)
233241
* call-seq:
234242
* store.purpose = purpose
235243
*
236-
* Sets the store's purpose to _purpose_. If specified, the verifications on
237-
* the store will check every untrusted certificate's extensions are consistent
238-
* with the purpose. The purpose is specified by constants:
244+
* Sets the store's default verification purpose. If specified,
245+
* the verifications on the store will check every certificate's extensions are
246+
* consistent with the purpose. The purpose is specified by constants:
239247
*
240248
* * X509::PURPOSE_SSL_CLIENT
241249
* * X509::PURPOSE_SSL_SERVER
@@ -246,6 +254,11 @@ ossl_x509store_set_flags(VALUE self, VALUE flags)
246254
* * X509::PURPOSE_ANY
247255
* * X509::PURPOSE_OCSP_HELPER
248256
* * X509::PURPOSE_TIMESTAMP_SIGN
257+
*
258+
* OpenSSL::X509::StoreContext#purpose= can be used to change the value for a
259+
* single verification operation.
260+
*
261+
* See also the man page X509_VERIFY_PARAM_set_purpose(3).
249262
*/
250263
static VALUE
251264
ossl_x509store_set_purpose(VALUE self, VALUE purpose)
@@ -262,6 +275,14 @@ ossl_x509store_set_purpose(VALUE self, VALUE purpose)
262275
/*
263276
* call-seq:
264277
* store.trust = trust
278+
*
279+
* Sets the default trust settings used by the certificate verification with
280+
* the store.
281+
*
282+
* OpenSSL::X509::StoreContext#trust= can be used to change the value for a
283+
* single verification operation.
284+
*
285+
* See also the man page X509_VERIFY_PARAM_set_trust(3).
265286
*/
266287
static VALUE
267288
ossl_x509store_set_trust(VALUE self, VALUE trust)
@@ -279,7 +300,13 @@ ossl_x509store_set_trust(VALUE self, VALUE trust)
279300
* call-seq:
280301
* store.time = time
281302
*
282-
* Sets the time to be used in verifications.
303+
* Sets the time to be used in the certificate verifications with the store.
304+
* By default, if not specified, the current system time is used.
305+
*
306+
* OpenSSL::X509::StoreContext#time= can be used to change the value for a
307+
* single verification operation.
308+
*
309+
* See also the man page X509_VERIFY_PARAM_set_time(3).
283310
*/
284311
static VALUE
285312
ossl_x509store_set_time(VALUE self, VALUE time)
@@ -295,6 +322,8 @@ ossl_x509store_set_time(VALUE self, VALUE time)
295322
* Adds the certificates in _file_ to the certificate store. _file_ is the path
296323
* to the file, and the file contains one or more certificates in PEM format
297324
* concatenated together.
325+
*
326+
* See also the man page X509_LOOKUP_file(3).
298327
*/
299328
static VALUE
300329
ossl_x509store_add_file(VALUE self, VALUE file)
@@ -328,6 +357,8 @@ ossl_x509store_add_file(VALUE self, VALUE file)
328357
* store.add_path(path) -> self
329358
*
330359
* Adds _path_ as the hash dir to be looked up by the store.
360+
*
361+
* See also the man page X509_LOOKUP_hash_dir(3).
331362
*/
332363
static VALUE
333364
ossl_x509store_add_path(VALUE self, VALUE dir)
@@ -357,6 +388,8 @@ ossl_x509store_add_path(VALUE self, VALUE dir)
357388
*
358389
* * OpenSSL::X509::DEFAULT_CERT_FILE
359390
* * OpenSSL::X509::DEFAULT_CERT_DIR
391+
*
392+
* See also the man page X509_STORE_set_default_paths(3).
360393
*/
361394
static VALUE
362395
ossl_x509store_set_default_paths(VALUE self)
@@ -372,9 +405,11 @@ ossl_x509store_set_default_paths(VALUE self)
372405

373406
/*
374407
* call-seq:
375-
* store.add_cert(cert)
408+
* store.add_cert(cert) -> self
376409
*
377410
* Adds the OpenSSL::X509::Certificate _cert_ to the certificate store.
411+
*
412+
* See also the man page X509_STORE_add_cert(3).
378413
*/
379414
static VALUE
380415
ossl_x509store_add_cert(VALUE self, VALUE arg)
@@ -395,6 +430,8 @@ ossl_x509store_add_cert(VALUE self, VALUE arg)
395430
* store.add_crl(crl) -> self
396431
*
397432
* Adds the OpenSSL::X509::CRL _crl_ to the store.
433+
*
434+
* See also the man page X509_STORE_add_crl(3).
398435
*/
399436
static VALUE
400437
ossl_x509store_add_crl(VALUE self, VALUE arg)
@@ -510,6 +547,8 @@ static VALUE ossl_x509stctx_set_time(VALUE, VALUE);
510547
/*
511548
* call-seq:
512549
* StoreContext.new(store, cert = nil, chain = nil)
550+
*
551+
* Sets up a StoreContext for a verification of the X.509 certificate _cert_.
513552
*/
514553
static VALUE
515554
ossl_x509stctx_initialize(int argc, VALUE *argv, VALUE self)
@@ -540,6 +579,10 @@ ossl_x509stctx_initialize(int argc, VALUE *argv, VALUE self)
540579
/*
541580
* call-seq:
542581
* stctx.verify -> true | false
582+
*
583+
* Performs the certificate verification using the parameters set to _stctx_.
584+
*
585+
* See also the man page X509_verify_cert(3).
543586
*/
544587
static VALUE
545588
ossl_x509stctx_verify(VALUE self)
@@ -563,7 +606,11 @@ ossl_x509stctx_verify(VALUE self)
563606

564607
/*
565608
* call-seq:
566-
* stctx.chain -> Array of X509::Certificate
609+
* stctx.chain -> nil | Array of X509::Certificate
610+
*
611+
* Returns the verified chain.
612+
*
613+
* See also the man page X509_STORE_CTX_set0_verified_chain(3).
567614
*/
568615
static VALUE
569616
ossl_x509stctx_get_chain(VALUE self)
@@ -581,6 +628,12 @@ ossl_x509stctx_get_chain(VALUE self)
581628
/*
582629
* call-seq:
583630
* stctx.error -> Integer
631+
*
632+
* Returns the error code of _stctx_. This is typically called after #verify
633+
* is done, or from the verification callback set to
634+
* OpenSSL::X509::Store#verify_callback=.
635+
*
636+
* See also the man page X509_STORE_CTX_get_error(3).
584637
*/
585638
static VALUE
586639
ossl_x509stctx_get_err(VALUE self)
@@ -595,6 +648,11 @@ ossl_x509stctx_get_err(VALUE self)
595648
/*
596649
* call-seq:
597650
* stctx.error = error_code
651+
*
652+
* Sets the error code of _stctx_. This is used by the verification callback
653+
* set to OpenSSL::X509::Store#verify_callback=.
654+
*
655+
* See also the man page X509_STORE_CTX_set_error(3).
598656
*/
599657
static VALUE
600658
ossl_x509stctx_set_error(VALUE self, VALUE err)
@@ -611,7 +669,10 @@ ossl_x509stctx_set_error(VALUE self, VALUE err)
611669
* call-seq:
612670
* stctx.error_string -> String
613671
*
614-
* Returns the error string corresponding to the error code retrieved by #error.
672+
* Returns the human readable error string corresponding to the error code
673+
* retrieved by #error.
674+
*
675+
* See also the man page X509_verify_cert_error_string(3).
615676
*/
616677
static VALUE
617678
ossl_x509stctx_get_err_string(VALUE self)
@@ -628,6 +689,10 @@ ossl_x509stctx_get_err_string(VALUE self)
628689
/*
629690
* call-seq:
630691
* stctx.error_depth -> Integer
692+
*
693+
* Returns the depth of the chain. This is used in combination with #error.
694+
*
695+
* See also the man page X509_STORE_CTX_get_error_depth(3).
631696
*/
632697
static VALUE
633698
ossl_x509stctx_get_err_depth(VALUE self)
@@ -642,6 +707,10 @@ ossl_x509stctx_get_err_depth(VALUE self)
642707
/*
643708
* call-seq:
644709
* stctx.current_cert -> X509::Certificate
710+
*
711+
* Returns the certificate which caused the error.
712+
*
713+
* See also the man page X509_STORE_CTX_get_current_cert(3).
645714
*/
646715
static VALUE
647716
ossl_x509stctx_get_curr_cert(VALUE self)
@@ -656,6 +725,10 @@ ossl_x509stctx_get_curr_cert(VALUE self)
656725
/*
657726
* call-seq:
658727
* stctx.current_crl -> X509::CRL
728+
*
729+
* Returns the CRL which caused the error.
730+
*
731+
* See also the man page X509_STORE_CTX_get_current_crl(3).
659732
*/
660733
static VALUE
661734
ossl_x509stctx_get_curr_crl(VALUE self)
@@ -675,7 +748,10 @@ ossl_x509stctx_get_curr_crl(VALUE self)
675748
* call-seq:
676749
* stctx.flags = flags
677750
*
678-
* Sets the verification flags to the context. See Store#flags=.
751+
* Sets the verification flags to the context. This overrides the default value
752+
* set by Store#flags=.
753+
*
754+
* See also the man page X509_VERIFY_PARAM_set_flags(3).
679755
*/
680756
static VALUE
681757
ossl_x509stctx_set_flags(VALUE self, VALUE flags)
@@ -693,7 +769,10 @@ ossl_x509stctx_set_flags(VALUE self, VALUE flags)
693769
* call-seq:
694770
* stctx.purpose = purpose
695771
*
696-
* Sets the purpose of the context. See Store#purpose=.
772+
* Sets the purpose of the context. This overrides the default value set by
773+
* Store#purpose=.
774+
*
775+
* See also the man page X509_VERIFY_PARAM_set_purpose(3).
697776
*/
698777
static VALUE
699778
ossl_x509stctx_set_purpose(VALUE self, VALUE purpose)
@@ -710,6 +789,11 @@ ossl_x509stctx_set_purpose(VALUE self, VALUE purpose)
710789
/*
711790
* call-seq:
712791
* stctx.trust = trust
792+
*
793+
* Sets the trust settings of the context. This overrides the default value set
794+
* by Store#trust=.
795+
*
796+
* See also the man page X509_VERIFY_PARAM_set_trust(3).
713797
*/
714798
static VALUE
715799
ossl_x509stctx_set_trust(VALUE self, VALUE trust)
@@ -728,6 +812,8 @@ ossl_x509stctx_set_trust(VALUE self, VALUE trust)
728812
* stctx.time = time
729813
*
730814
* Sets the time used in the verification. If not set, the current time is used.
815+
*
816+
* See also the man page X509_VERIFY_PARAM_set_time(3).
731817
*/
732818
static VALUE
733819
ossl_x509stctx_set_time(VALUE self, VALUE time)
@@ -803,23 +889,37 @@ Init_ossl_x509store(void)
803889
cX509Store = rb_define_class_under(mX509, "Store", rb_cObject);
804890
/*
805891
* The callback for additional certificate verification. It is invoked for
806-
* each untrusted certificate in the chain.
892+
* each certificate in the chain and can be used to implement custom
893+
* certificate verification conditions.
807894
*
808895
* The callback is invoked with two values, a boolean that indicates if the
809896
* pre-verification by OpenSSL has succeeded or not, and the StoreContext in
810-
* use. The callback must return either true or false.
897+
* use.
898+
*
899+
* The callback can use StoreContext#error= to change the error code as
900+
* needed. The callback must return either true or false.
901+
*
902+
* NOTE: any exception raised within the callback will be ignored.
903+
*
904+
* See also the man page X509_STORE_CTX_set_verify_cb(3).
811905
*/
812906
rb_attr(cX509Store, rb_intern("verify_callback"), 1, 0, Qfalse);
813907
/*
814908
* The error code set by the last call of #verify.
909+
*
910+
* See also StoreContext#error.
815911
*/
816912
rb_attr(cX509Store, rb_intern("error"), 1, 0, Qfalse);
817913
/*
818914
* The description for the error code set by the last call of #verify.
915+
*
916+
* See also StoreContext#error_string.
819917
*/
820918
rb_attr(cX509Store, rb_intern("error_string"), 1, 0, Qfalse);
821919
/*
822920
* The certificate chain constructed by the last call of #verify.
921+
*
922+
* See also StoreContext#chain.
823923
*/
824924
rb_attr(cX509Store, rb_intern("chain"), 1, 0, Qfalse);
825925
rb_define_alloc_func(cX509Store, ossl_x509store_alloc);

0 commit comments

Comments
 (0)