]>
Commit | Line | Data |
---|---|---|
238d692c RP |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
9e183d22 | 5 | ssl_ct_validation_cb, |
9d8c2dfe | 6 | SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct, |
238d692c | 7 | SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, |
43341433 | 8 | SSL_ct_is_enabled, SSL_CTX_ct_is_enabled - |
238d692c RP |
9 | control Certificate Transparency policy |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/ssl.h> | |
14 | ||
9e183d22 RS |
15 | typedef int (*ssl_ct_validation_cb)(const CT_POLICY_EVAL_CTX *ctx, |
16 | const STACK_OF(SCT) *scts, void *arg); | |
17 | ||
b03fe231 EK |
18 | int SSL_enable_ct(SSL *s, int validation_mode); |
19 | int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode); | |
43341433 VD |
20 | int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback, |
21 | void *arg); | |
22 | int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, | |
23 | ssl_ct_validation_cb callback, | |
24 | void *arg); | |
b03fe231 EK |
25 | void SSL_disable_ct(SSL *s); |
26 | void SSL_CTX_disable_ct(SSL_CTX *ctx); | |
43341433 VD |
27 | int SSL_ct_is_enabled(const SSL *s); |
28 | int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx); | |
238d692c RP |
29 | |
30 | =head1 DESCRIPTION | |
31 | ||
b03fe231 | 32 | SSL_enable_ct() and SSL_CTX_enable_ct() enable the processing of signed |
43341433 VD |
33 | certificate timestamps (SCTs) either for a given SSL connection or for all |
34 | connections that share the given SSL context, respectively. | |
35 | This is accomplished by setting a built-in CT validation callback. | |
36 | The behaviour of the callback is determined by the B<validation_mode> argument, | |
37 | which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or | |
38 | B<SSL_CT_VALIDATION_STRICT> as described below. | |
39 | ||
f75b34c8 VD |
40 | If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full |
41 | TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer | |
42 | presents no valid SCTs the handshake will be aborted. | |
43 | If the verification mode is B<SSL_VERIFY_NONE>, the handshake will continue | |
44 | despite lack of valid SCTs. | |
45 | However, in that case if the verification status before the built-in callback | |
46 | was B<X509_V_OK> it will be set to B<X509_V_ERR_NO_VALID_SCTS> after the | |
47 | callback. | |
48 | Applications can call L<SSL_get_verify_result(3)> to check the status at | |
49 | handshake completion, even after session resumption since the verification | |
50 | status is part of the saved session state. | |
51 | See L<SSL_set_verify(3)>, <SSL_get_verify_result(3)>, L<SSL_session_reused(3)>. | |
52 | ||
43341433 | 53 | If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the |
f75b34c8 VD |
54 | handshake continues, and the verification status is not modified, regardless of |
55 | the validation status of any SCTs. | |
56 | The application can still inspect the validation status of the SCTs at | |
57 | handshake completion. | |
43341433 VD |
58 | Note that with session resumption there will not be any SCTs presented during |
59 | the handshake. | |
60 | Therefore, in applications that delay SCT policy enforcement until after | |
f75b34c8 VD |
61 | handshake completion, such delayed SCT checks should only be performed when the |
62 | session is not resumed. | |
43341433 VD |
63 | |
64 | SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() | |
65 | register a custom callback that may implement a different policy than either of | |
66 | the above. | |
67 | This callback can examine the peer's SCTs and determine whether they are | |
68 | sufficient to allow the connection to continue. | |
69 | The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE> | |
70 | and the callback returns a non-positive result. | |
71 | ||
30a9d5d1 | 72 | An arbitrary callback data argument, B<arg>, can be passed in when setting |
43341433 VD |
73 | the callback. |
74 | This will be passed to the callback whenever it is invoked. | |
75 | Ownership of this context remains with the caller. | |
238d692c RP |
76 | |
77 | If no callback is set, SCTs will not be requested and Certificate Transparency | |
78 | validation will not occur. | |
79 | ||
43341433 | 80 | No callback will be invoked when the peer presents no certificate, e.g. by |
c4de074e | 81 | employing an anonymous (aNULL) cipher suite. |
43341433 VD |
82 | In that case the handshake continues as it would had no callback been |
83 | requested. | |
84 | Callbacks are also not invoked when the peer certificate chain is invalid or | |
85 | validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509 | |
86 | PKI, or no X.509 PKI at all, respectively. | |
87 | Clients that require SCTs are expected to not have enabled any aNULL ciphers | |
88 | nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA | |
89 | records. | |
90 | ||
b03fe231 | 91 | SSL_disable_ct() and SSL_CTX_disable_ct() turn off CT processing, whether |
43341433 VD |
92 | enabled via the built-in or the custom callbacks, by setting a NULL callback. |
93 | These may be implemented as macros. | |
94 | ||
95 | SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is | |
b03fe231 | 96 | enabled via either SSL_enable_ct() or a non-null custom callback, and 0 |
43341433 VD |
97 | otherwise. |
98 | ||
238d692c RP |
99 | =head1 NOTES |
100 | ||
43341433 VD |
101 | When SCT processing is enabled, OCSP stapling will be enabled. This is because |
102 | one possible source of SCTs is the OCSP response from a server. | |
238d692c | 103 | |
1fa9ffd9 RP |
104 | The time returned by SSL_SESSION_get_time() will be used to evaluate whether any |
105 | presented SCTs have timestamps that are in the future (and therefore invalid). | |
106 | ||
238d692c RP |
107 | =head1 RESTRICTIONS |
108 | ||
109 | Certificate Transparency validation cannot be enabled and so a callback cannot | |
110 | be set if a custom client extension handler has been registered to handle SCT | |
111 | extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>). | |
112 | ||
113 | =head1 RETURN VALUES | |
114 | ||
b03fe231 | 115 | SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and |
43341433 VD |
116 | SSL_set_ct_validation_callback() return 1 if the B<callback> is successfully |
117 | set. | |
118 | They return 0 if an error occurs, e.g. a custom client extension handler has | |
119 | been setup to handle SCTs. | |
120 | ||
b03fe231 | 121 | SSL_disable_ct() and SSL_CTX_disable_ct() do not return a result. |
238d692c | 122 | |
43341433 VD |
123 | SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT |
124 | validation callback is set, or 0 if no callback (or equivalently a NULL | |
125 | callback) is set. | |
238d692c RP |
126 | |
127 | =head1 SEE ALSO | |
128 | ||
b97fdb57 | 129 | L<ssl(7)>, |
f75b34c8 | 130 | <SSL_get_verify_result(3)>, |
43341433 VD |
131 | L<SSL_session_reused(3)>, |
132 | L<SSL_set_verify(3)>, | |
133 | L<SSL_CTX_set_verify(3)>, | |
1fa9ffd9 | 134 | L<SSL_SESSION_get_time(3)> |
238d692c | 135 | |
e2f92610 RS |
136 | =head1 COPYRIGHT |
137 | ||
9e183d22 | 138 | Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 139 | |
4746f25a | 140 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
141 | this file except in compliance with the License. You can obtain a copy |
142 | in the file LICENSE in the source distribution or at | |
143 | L<https://www.openssl.org/source/license.html>. | |
144 | ||
145 | =cut |