]>
Commit | Line | Data |
---|---|---|
238d692c RP |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
43341433 | 5 | SSL_ct_enable, SSL_CTX_ct_enable, SSL_ct_disable, SSL_CTX_ct_disable, |
238d692c | 6 | SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, |
43341433 | 7 | SSL_ct_is_enabled, SSL_CTX_ct_is_enabled - |
238d692c RP |
8 | control Certificate Transparency policy |
9 | ||
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/ssl.h> | |
13 | ||
43341433 VD |
14 | int SSL_ct_enable(SSL *s, int validation_mode); |
15 | int SSL_CTX_ct_enable(SSL_CTX *ctx, int validation_mode); | |
16 | int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback, | |
17 | void *arg); | |
18 | int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, | |
19 | ssl_ct_validation_cb callback, | |
20 | void *arg); | |
21 | void SSL_ct_disable(SSL *s); | |
22 | void SSL_CTX_ct_disable(SSL_CTX *ctx); | |
23 | int SSL_ct_is_enabled(const SSL *s); | |
24 | int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx); | |
238d692c RP |
25 | |
26 | =head1 DESCRIPTION | |
27 | ||
43341433 VD |
28 | SSL_ct_enable() and SSL_CTX_ct_enable() enable the processing of signed |
29 | certificate timestamps (SCTs) either for a given SSL connection or for all | |
30 | connections that share the given SSL context, respectively. | |
31 | This is accomplished by setting a built-in CT validation callback. | |
32 | The behaviour of the callback is determined by the B<validation_mode> argument, | |
33 | which can be either of B<SSL_CT_VALIDATION_PERMISSIVE> or | |
34 | B<SSL_CT_VALIDATION_STRICT> as described below. | |
35 | ||
36 | If B<validation_mode> is equal to B<SSL_CT_VALIDATION_PERMISSIVE>, then the | |
37 | handshake continues regardless of the validation status of any SCTs. | |
38 | The application can inspect the validation status of the SCTs at handshake | |
39 | completion. | |
40 | Note that with session resumption there will not be any SCTs presented during | |
41 | the handshake. | |
42 | Therefore, in applications that delay SCT policy enforcement until after | |
43 | handshake completion, SCT checks should only be performed when the session is | |
44 | not reused. | |
45 | See L<SSL_session_reused(3)>. | |
46 | ||
47 | If B<validation_mode> is equal to B<SSL_CT_VALIDATION_STRICT>, then in a full | |
48 | TLS handshake with the verification mode set to B<SSL_VERIFY_PEER>, if the peer | |
49 | presents no valid SCTs the handshake will be aborted. | |
50 | See L<SSL_set_verify(3)>. | |
51 | ||
52 | SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() | |
53 | register a custom callback that may implement a different policy than either of | |
54 | the above. | |
55 | This callback can examine the peer's SCTs and determine whether they are | |
56 | sufficient to allow the connection to continue. | |
57 | The TLS handshake is aborted if the verification mode is not B<SSL_VERIFY_NONE> | |
58 | and the callback returns a non-positive result. | |
59 | ||
60 | An arbitrary callback context argument, B<arg>, can be passed in when setting | |
61 | the callback. | |
62 | This will be passed to the callback whenever it is invoked. | |
63 | Ownership of this context remains with the caller. | |
238d692c RP |
64 | |
65 | If no callback is set, SCTs will not be requested and Certificate Transparency | |
66 | validation will not occur. | |
67 | ||
43341433 VD |
68 | No callback will be invoked when the peer presents no certificate, e.g. by |
69 | employing an anonymous (aNULL) ciphersuite. | |
70 | In that case the handshake continues as it would had no callback been | |
71 | requested. | |
72 | Callbacks are also not invoked when the peer certificate chain is invalid or | |
73 | validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509 | |
74 | PKI, or no X.509 PKI at all, respectively. | |
75 | Clients that require SCTs are expected to not have enabled any aNULL ciphers | |
76 | nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA | |
77 | records. | |
78 | ||
79 | SSL_ct_disable() and SSL_CTX_ct_disable() turn off CT processing, whether | |
80 | enabled via the built-in or the custom callbacks, by setting a NULL callback. | |
81 | These may be implemented as macros. | |
82 | ||
83 | SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is | |
84 | enabled via either SSL_ct_enable() or a non-null custom callback, and 0 | |
85 | otherwise. | |
86 | ||
238d692c RP |
87 | =head1 NOTES |
88 | ||
43341433 VD |
89 | When SCT processing is enabled, OCSP stapling will be enabled. This is because |
90 | one possible source of SCTs is the OCSP response from a server. | |
238d692c RP |
91 | |
92 | =head1 RESTRICTIONS | |
93 | ||
94 | Certificate Transparency validation cannot be enabled and so a callback cannot | |
95 | be set if a custom client extension handler has been registered to handle SCT | |
96 | extensions (B<TLSEXT_TYPE_signed_certificate_timestamp>). | |
97 | ||
98 | =head1 RETURN VALUES | |
99 | ||
43341433 VD |
100 | SSL_ct_enable(), SSL_CTX_ct_enable(), SSL_CTX_set_ct_validation_callback() and |
101 | SSL_set_ct_validation_callback() return 1 if the B<callback> is successfully | |
102 | set. | |
103 | They return 0 if an error occurs, e.g. a custom client extension handler has | |
104 | been setup to handle SCTs. | |
105 | ||
106 | SSL_ct_disable() and SSL_CTX_ct_disable() do not return a result. | |
238d692c | 107 | |
43341433 VD |
108 | SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT |
109 | validation callback is set, or 0 if no callback (or equivalently a NULL | |
110 | callback) is set. | |
238d692c RP |
111 | |
112 | =head1 SEE ALSO | |
113 | ||
114 | L<ssl(3)>, | |
43341433 VD |
115 | L<SSL_session_reused(3)>, |
116 | L<SSL_set_verify(3)>, | |
117 | L<SSL_CTX_set_verify(3)>, | |
118 | L<ssl_ct_validation_cb(3)> | |
238d692c RP |
119 | |
120 | =cut |