]>
Commit | Line | Data |
---|---|---|
c4068186 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
e9b77246 BB |
11 | void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, |
12 | int (*callback)(X509_STORE_CTX *, void *), | |
13 | void *arg); | |
c4068186 LJ |
14 | |
15 | =head1 DESCRIPTION | |
16 | ||
17 | SSL_CTX_set_cert_verify_callback() sets the verification callback function for | |
023ec151 | 18 | I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at |
9b86974e | 19 | the time when L<SSL_new(3)> is called. |
c4068186 LJ |
20 | |
21 | =head1 NOTES | |
22 | ||
23 | Whenever a certificate is verified during a SSL/TLS handshake, a verification | |
24 | function is called. If the application does not explicitly specify a | |
25 | verification callback function, the built-in verification function is used. | |
023ec151 | 26 | If a verification callback I<callback> is specified via |
c4068186 | 27 | SSL_CTX_set_cert_verify_callback(), the supplied callback function is called |
023ec151 | 28 | instead. By setting I<callback> to NULL, the default behaviour is restored. |
c4068186 | 29 | |
023ec151 | 30 | When the verification must be performed, I<callback> will be called with |
1bc74519 | 31 | the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The |
023ec151 | 32 | argument I<arg> is specified by the application when setting I<callback>. |
c4068186 | 33 | |
023ec151 BM |
34 | I<callback> should return 1 to indicate verification success and 0 to |
35 | indicate verification failure. If SSL_VERIFY_PEER is set and I<callback> | |
c4068186 | 36 | returns 0, the handshake will fail. As the verification procedure may |
6e501c47 P |
37 | allow the connection to continue in the case of failure (by always |
38 | returning 1) the verification result must be set in any case using the | |
39 | B<error> member of I<x509_store_ctx> so that the calling application | |
40 | will be informed about the detailed result of the verification procedure! | |
c4068186 | 41 | |
023ec151 | 42 | Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback> |
9b86974e | 43 | function set using L<SSL_CTX_set_verify(3)>. |
c4068186 | 44 | |
1f13ad31 PY |
45 | =head1 RETURN VALUES |
46 | ||
47 | SSL_CTX_set_cert_verify_callback() does not return a value. | |
48 | ||
c4068186 LJ |
49 | =head1 WARNINGS |
50 | ||
51 | Do not mix the verification callback described in this function with the | |
52 | B<verify_callback> function called during the verification process. The | |
9b86974e | 53 | latter is set using the L<SSL_CTX_set_verify(3)> |
c4068186 LJ |
54 | family of functions. |
55 | ||
56 | Providing a complete verification procedure including certificate purpose | |
57 | settings etc is a complex task. The built-in procedure is quite powerful | |
58 | and in most cases it should be sufficient to modify its behaviour using | |
59 | the B<verify_callback> function. | |
60 | ||
61 | =head1 BUGS | |
62 | ||
c4068186 LJ |
63 | SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. |
64 | ||
65 | =head1 SEE ALSO | |
66 | ||
b97fdb57 | 67 | L<ssl(7)>, L<SSL_CTX_set_verify(3)>, |
9b86974e RS |
68 | L<SSL_get_verify_result(3)>, |
69 | L<SSL_CTX_load_verify_locations(3)> | |
c4068186 | 70 | |
e2f92610 RS |
71 | =head1 COPYRIGHT |
72 | ||
61f805c1 | 73 | Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 74 | |
4746f25a | 75 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
76 | this file except in compliance with the License. You can obtain a copy |
77 | in the file LICENSE in the source distribution or at | |
78 | L<https://www.openssl.org/source/license.html>. | |
79 | ||
80 | =cut |