]>
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 | ||
023ec151 | 11 | void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *,void *), void *arg); |
c4068186 LJ |
12 | |
13 | =head1 DESCRIPTION | |
14 | ||
15 | SSL_CTX_set_cert_verify_callback() sets the verification callback function for | |
023ec151 | 16 | I<ctx>. SSL objects that are created from I<ctx> inherit the setting valid at |
9b86974e | 17 | the time when L<SSL_new(3)> is called. |
c4068186 LJ |
18 | |
19 | =head1 NOTES | |
20 | ||
21 | Whenever a certificate is verified during a SSL/TLS handshake, a verification | |
22 | function is called. If the application does not explicitly specify a | |
23 | verification callback function, the built-in verification function is used. | |
023ec151 | 24 | If a verification callback I<callback> is specified via |
c4068186 | 25 | SSL_CTX_set_cert_verify_callback(), the supplied callback function is called |
023ec151 | 26 | instead. By setting I<callback> to NULL, the default behaviour is restored. |
c4068186 | 27 | |
023ec151 BM |
28 | When the verification must be performed, I<callback> will be called with |
29 | the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The | |
30 | argument I<arg> is specified by the application when setting I<callback>. | |
c4068186 | 31 | |
023ec151 BM |
32 | I<callback> should return 1 to indicate verification success and 0 to |
33 | indicate verification failure. If SSL_VERIFY_PEER is set and I<callback> | |
c4068186 LJ |
34 | returns 0, the handshake will fail. As the verification procedure may |
35 | allow to continue the connection in case of failure (by always returning 1) | |
36 | the verification result must be set in any case using the B<error> | |
023ec151 | 37 | member of I<x509_store_ctx> so that the calling application will be informed |
c4068186 LJ |
38 | about the detailed result of the verification procedure! |
39 | ||
023ec151 | 40 | Within I<x509_store_ctx>, I<callback> has access to the I<verify_callback> |
9b86974e | 41 | function set using L<SSL_CTX_set_verify(3)>. |
c4068186 LJ |
42 | |
43 | =head1 WARNINGS | |
44 | ||
45 | Do not mix the verification callback described in this function with the | |
46 | B<verify_callback> function called during the verification process. The | |
9b86974e | 47 | latter is set using the L<SSL_CTX_set_verify(3)> |
c4068186 LJ |
48 | family of functions. |
49 | ||
50 | Providing a complete verification procedure including certificate purpose | |
51 | settings etc is a complex task. The built-in procedure is quite powerful | |
52 | and in most cases it should be sufficient to modify its behaviour using | |
53 | the B<verify_callback> function. | |
54 | ||
55 | =head1 BUGS | |
56 | ||
c4068186 LJ |
57 | =head1 RETURN VALUES |
58 | ||
59 | SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. | |
60 | ||
61 | =head1 SEE ALSO | |
62 | ||
9b86974e RS |
63 | L<ssl(3)>, L<SSL_CTX_set_verify(3)>, |
64 | L<SSL_get_verify_result(3)>, | |
65 | L<SSL_CTX_load_verify_locations(3)> | |
c4068186 | 66 | |
023ec151 BM |
67 | =head1 HISTORY |
68 | ||
69 | Previous to OpenSSL 0.9.7, the I<arg> argument to B<SSL_CTX_set_cert_verify_callback> | |
70 | was ignored, and I<callback> was called simply as | |
71 | int (*callback)(X509_STORE_CTX *) | |
72 | To compile software written for previous versions of OpenSSL, a dummy | |
73 | argument will have to be added to I<callback>. | |
74 | ||
c4068186 | 75 | =cut |