summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod')
-rw-r--r--src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod161
1 files changed, 0 insertions, 161 deletions
diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod
deleted file mode 100644
index b9787a6ca6..0000000000
--- a/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod
+++ /dev/null
@@ -1,161 +0,0 @@
1=pod
2
3=head1 NAME
4
5X509_STORE_CTX_set_verify_cb - set verification callback
6
7=head1 SYNOPSIS
8
9 #include <openssl/x509_vfy.h>
10
11 void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx,
12 int (*verify_cb)(int ok, X509_STORE_CTX *ctx));
13
14=head1 DESCRIPTION
15
16X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to
17B<verify_cb> overwriting any existing callback.
18
19The verification callback can be used to customise the operation of certificate
20verification, either by overriding error conditions or logging errors for
21debugging purposes.
22
23However a verification callback is B<not> essential and the default operation
24is often sufficient.
25
26The B<ok> parameter to the callback indicates the value the callback should
27return to retain the default behaviour. If it is zero then and error condition
28is indicated. If it is 1 then no error occurred. If the flag
29B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the
30policy checking is complete.
31
32The B<ctx> parameter to the callback is the B<X509_STORE_CTX> structure that
33is performing the verification operation. A callback can examine this
34structure and receive additional information about the error, for example
35by calling X509_STORE_CTX_get_current_cert(). Additional application data can
36be passed to the callback via the B<ex_data> mechanism.
37
38=head1 WARNING
39
40In general a verification callback should B<NOT> unconditionally return 1 in
41all circumstances because this will allow verification to succeed no matter
42what the error. This effectively removes all security from the application
43because B<any> certificate (including untrusted generated ones) will be
44accepted.
45
46=head1 NOTES
47
48The verification callback can be set and inherited from the parent structure
49performing the operation. In some cases (such as S/MIME verification) the
50B<X509_STORE_CTX> structure is created and destroyed internally and the
51only way to set a custom verification callback is by inheriting it from the
52associated B<X509_STORE>.
53
54=head1 RETURN VALUES
55
56X509_STORE_CTX_set_verify_cb() does not return a value.
57
58=head1 EXAMPLES
59
60Default callback operation:
61
62 int verify_callback(int ok, X509_STORE_CTX *ctx)
63 {
64 return ok;
65 }
66
67Simple example, suppose a certificate in the chain is expired and we wish
68to continue after this error:
69
70 int verify_callback(int ok, X509_STORE_CTX *ctx)
71 {
72 /* Tolerate certificate expiration */
73 if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED)
74 return 1;
75 /* Otherwise don't override */
76 return ok;
77 }
78
79More complex example, we don't wish to continue after B<any> certificate has
80expired just one specific case:
81
82 int verify_callback(int ok, X509_STORE_CTX *ctx)
83 {
84 int err = X509_STORE_CTX_get_error(ctx);
85 X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx);
86 if (err == X509_V_ERR_CERT_HAS_EXPIRED)
87 {
88 if (check_is_acceptable_expired_cert(err_cert)
89 return 1;
90 }
91 return ok;
92 }
93
94Full featured logging callback. In this case the B<bio_err> is assumed to be
95a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using
96B<ex_data>.
97
98 int verify_callback(int ok, X509_STORE_CTX *ctx)
99 {
100 X509 *err_cert;
101 int err,depth;
102
103 err_cert = X509_STORE_CTX_get_current_cert(ctx);
104 err = X509_STORE_CTX_get_error(ctx);
105 depth = X509_STORE_CTX_get_error_depth(ctx);
106
107 BIO_printf(bio_err,"depth=%d ",depth);
108 if (err_cert)
109 {
110 X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert),
111 0, XN_FLAG_ONELINE);
112 BIO_puts(bio_err, "\n");
113 }
114 else
115 BIO_puts(bio_err, "<no cert>\n");
116 if (!ok)
117 BIO_printf(bio_err,"verify error:num=%d:%s\n",err,
118 X509_verify_cert_error_string(err));
119 switch (err)
120 {
121 case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT:
122 BIO_puts(bio_err,"issuer= ");
123 X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert),
124 0, XN_FLAG_ONELINE);
125 BIO_puts(bio_err, "\n");
126 break;
127 case X509_V_ERR_CERT_NOT_YET_VALID:
128 case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD:
129 BIO_printf(bio_err,"notBefore=");
130 ASN1_TIME_print(bio_err,X509_get_notBefore(err_cert));
131 BIO_printf(bio_err,"\n");
132 break;
133 case X509_V_ERR_CERT_HAS_EXPIRED:
134 case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD:
135 BIO_printf(bio_err,"notAfter=");
136 ASN1_TIME_print(bio_err,X509_get_notAfter(err_cert));
137 BIO_printf(bio_err,"\n");
138 break;
139 case X509_V_ERR_NO_EXPLICIT_POLICY:
140 policies_print(bio_err, ctx);
141 break;
142 }
143 if (err == X509_V_OK && ok == 2)
144 /* print out policies */
145
146 BIO_printf(bio_err,"verify return:%d\n",ok);
147 return(ok);
148 }
149
150=head1 SEE ALSO
151
152L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)>
153L<X509_STORE_set_verify_cb_func(3)|X509_STORE_set_verify_cb_func(3)>
154L<X509_STORE_CTX_get_ex_new_index(3)|X509_STORE_CTX_get_ex_new_index(3)>
155
156=head1 HISTORY
157
158X509_STORE_CTX_set_verify_cb() is available in all versions of SSLeay and
159OpenSSL.
160
161=cut
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-04 00:42:25 +0000