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
162