@@ -214,8 +214,16 @@ ossl_x509store_initialize(int argc, VALUE *argv, VALUE self)
214
214
* call-seq:
215
215
* store.flags = flags
216
216
*
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).
219
227
*/
220
228
static VALUE
221
229
ossl_x509store_set_flags (VALUE self , VALUE flags )
@@ -233,9 +241,9 @@ ossl_x509store_set_flags(VALUE self, VALUE flags)
233
241
* call-seq:
234
242
* store.purpose = purpose
235
243
*
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:
239
247
*
240
248
* * X509::PURPOSE_SSL_CLIENT
241
249
* * X509::PURPOSE_SSL_SERVER
@@ -246,6 +254,11 @@ ossl_x509store_set_flags(VALUE self, VALUE flags)
246
254
* * X509::PURPOSE_ANY
247
255
* * X509::PURPOSE_OCSP_HELPER
248
256
* * 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).
249
262
*/
250
263
static VALUE
251
264
ossl_x509store_set_purpose (VALUE self , VALUE purpose )
@@ -262,6 +275,14 @@ ossl_x509store_set_purpose(VALUE self, VALUE purpose)
262
275
/*
263
276
* call-seq:
264
277
* 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).
265
286
*/
266
287
static VALUE
267
288
ossl_x509store_set_trust (VALUE self , VALUE trust )
@@ -279,7 +300,13 @@ ossl_x509store_set_trust(VALUE self, VALUE trust)
279
300
* call-seq:
280
301
* store.time = time
281
302
*
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).
283
310
*/
284
311
static VALUE
285
312
ossl_x509store_set_time (VALUE self , VALUE time )
@@ -295,6 +322,8 @@ ossl_x509store_set_time(VALUE self, VALUE time)
295
322
* Adds the certificates in _file_ to the certificate store. _file_ is the path
296
323
* to the file, and the file contains one or more certificates in PEM format
297
324
* concatenated together.
325
+ *
326
+ * See also the man page X509_LOOKUP_file(3).
298
327
*/
299
328
static VALUE
300
329
ossl_x509store_add_file (VALUE self , VALUE file )
@@ -328,6 +357,8 @@ ossl_x509store_add_file(VALUE self, VALUE file)
328
357
* store.add_path(path) -> self
329
358
*
330
359
* 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).
331
362
*/
332
363
static VALUE
333
364
ossl_x509store_add_path (VALUE self , VALUE dir )
@@ -357,6 +388,8 @@ ossl_x509store_add_path(VALUE self, VALUE dir)
357
388
*
358
389
* * OpenSSL::X509::DEFAULT_CERT_FILE
359
390
* * OpenSSL::X509::DEFAULT_CERT_DIR
391
+ *
392
+ * See also the man page X509_STORE_set_default_paths(3).
360
393
*/
361
394
static VALUE
362
395
ossl_x509store_set_default_paths (VALUE self )
@@ -372,9 +405,11 @@ ossl_x509store_set_default_paths(VALUE self)
372
405
373
406
/*
374
407
* call-seq:
375
- * store.add_cert(cert)
408
+ * store.add_cert(cert) -> self
376
409
*
377
410
* Adds the OpenSSL::X509::Certificate _cert_ to the certificate store.
411
+ *
412
+ * See also the man page X509_STORE_add_cert(3).
378
413
*/
379
414
static VALUE
380
415
ossl_x509store_add_cert (VALUE self , VALUE arg )
@@ -395,6 +430,8 @@ ossl_x509store_add_cert(VALUE self, VALUE arg)
395
430
* store.add_crl(crl) -> self
396
431
*
397
432
* Adds the OpenSSL::X509::CRL _crl_ to the store.
433
+ *
434
+ * See also the man page X509_STORE_add_crl(3).
398
435
*/
399
436
static VALUE
400
437
ossl_x509store_add_crl (VALUE self , VALUE arg )
@@ -510,6 +547,8 @@ static VALUE ossl_x509stctx_set_time(VALUE, VALUE);
510
547
/*
511
548
* call-seq:
512
549
* StoreContext.new(store, cert = nil, chain = nil)
550
+ *
551
+ * Sets up a StoreContext for a verification of the X.509 certificate _cert_.
513
552
*/
514
553
static VALUE
515
554
ossl_x509stctx_initialize (int argc , VALUE * argv , VALUE self )
@@ -540,6 +579,10 @@ ossl_x509stctx_initialize(int argc, VALUE *argv, VALUE self)
540
579
/*
541
580
* call-seq:
542
581
* 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).
543
586
*/
544
587
static VALUE
545
588
ossl_x509stctx_verify (VALUE self )
@@ -563,7 +606,11 @@ ossl_x509stctx_verify(VALUE self)
563
606
564
607
/*
565
608
* 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).
567
614
*/
568
615
static VALUE
569
616
ossl_x509stctx_get_chain (VALUE self )
@@ -581,6 +628,12 @@ ossl_x509stctx_get_chain(VALUE self)
581
628
/*
582
629
* call-seq:
583
630
* 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).
584
637
*/
585
638
static VALUE
586
639
ossl_x509stctx_get_err (VALUE self )
@@ -595,6 +648,11 @@ ossl_x509stctx_get_err(VALUE self)
595
648
/*
596
649
* call-seq:
597
650
* 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).
598
656
*/
599
657
static VALUE
600
658
ossl_x509stctx_set_error (VALUE self , VALUE err )
@@ -611,7 +669,10 @@ ossl_x509stctx_set_error(VALUE self, VALUE err)
611
669
* call-seq:
612
670
* stctx.error_string -> String
613
671
*
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).
615
676
*/
616
677
static VALUE
617
678
ossl_x509stctx_get_err_string (VALUE self )
@@ -628,6 +689,10 @@ ossl_x509stctx_get_err_string(VALUE self)
628
689
/*
629
690
* call-seq:
630
691
* 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).
631
696
*/
632
697
static VALUE
633
698
ossl_x509stctx_get_err_depth (VALUE self )
@@ -642,6 +707,10 @@ ossl_x509stctx_get_err_depth(VALUE self)
642
707
/*
643
708
* call-seq:
644
709
* 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).
645
714
*/
646
715
static VALUE
647
716
ossl_x509stctx_get_curr_cert (VALUE self )
@@ -656,6 +725,10 @@ ossl_x509stctx_get_curr_cert(VALUE self)
656
725
/*
657
726
* call-seq:
658
727
* 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).
659
732
*/
660
733
static VALUE
661
734
ossl_x509stctx_get_curr_crl (VALUE self )
@@ -675,7 +748,10 @@ ossl_x509stctx_get_curr_crl(VALUE self)
675
748
* call-seq:
676
749
* stctx.flags = flags
677
750
*
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).
679
755
*/
680
756
static VALUE
681
757
ossl_x509stctx_set_flags (VALUE self , VALUE flags )
@@ -693,7 +769,10 @@ ossl_x509stctx_set_flags(VALUE self, VALUE flags)
693
769
* call-seq:
694
770
* stctx.purpose = purpose
695
771
*
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).
697
776
*/
698
777
static VALUE
699
778
ossl_x509stctx_set_purpose (VALUE self , VALUE purpose )
@@ -710,6 +789,11 @@ ossl_x509stctx_set_purpose(VALUE self, VALUE purpose)
710
789
/*
711
790
* call-seq:
712
791
* 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).
713
797
*/
714
798
static VALUE
715
799
ossl_x509stctx_set_trust (VALUE self , VALUE trust )
@@ -728,6 +812,8 @@ ossl_x509stctx_set_trust(VALUE self, VALUE trust)
728
812
* stctx.time = time
729
813
*
730
814
* 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).
731
817
*/
732
818
static VALUE
733
819
ossl_x509stctx_set_time (VALUE self , VALUE time )
@@ -803,23 +889,37 @@ Init_ossl_x509store(void)
803
889
cX509Store = rb_define_class_under (mX509 , "Store" , rb_cObject );
804
890
/*
805
891
* 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.
807
894
*
808
895
* The callback is invoked with two values, a boolean that indicates if the
809
896
* 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).
811
905
*/
812
906
rb_attr (cX509Store , rb_intern ("verify_callback" ), 1 , 0 , Qfalse );
813
907
/*
814
908
* The error code set by the last call of #verify.
909
+ *
910
+ * See also StoreContext#error.
815
911
*/
816
912
rb_attr (cX509Store , rb_intern ("error" ), 1 , 0 , Qfalse );
817
913
/*
818
914
* The description for the error code set by the last call of #verify.
915
+ *
916
+ * See also StoreContext#error_string.
819
917
*/
820
918
rb_attr (cX509Store , rb_intern ("error_string" ), 1 , 0 , Qfalse );
821
919
/*
822
920
* The certificate chain constructed by the last call of #verify.
921
+ *
922
+ * See also StoreContext#chain.
823
923
*/
824
924
rb_attr (cX509Store , rb_intern ("chain" ), 1 , 0 , Qfalse );
825
925
rb_define_alloc_func (cX509Store , ossl_x509store_alloc );
0 commit comments