]>
Commit | Line | Data |
---|---|---|
919ba009 VD |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable, | |
6061f80b | 6 | SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa, |
5ae4ceb9 | 7 | SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags, |
2bcb232e RS |
8 | SSL_dane_set_flags, SSL_dane_clear_flags |
9 | - enable DANE TLS authentication of the remote TLS server in the local | |
919ba009 VD |
10 | TLS client |
11 | ||
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/ssl.h> | |
15 | ||
16 | int SSL_CTX_dane_enable(SSL_CTX *ctx); | |
17 | int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md, | |
18 | uint8_t mtype, uint8_t ord); | |
19 | int SSL_dane_enable(SSL *s, const char *basedomain); | |
20 | int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector, | |
6d4313f0 | 21 | uint8_t mtype, const unsigned char *data, size_t dlen); |
919ba009 VD |
22 | int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki); |
23 | int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector, | |
6d4313f0 | 24 | uint8_t *mtype, const unsigned char **data, |
919ba009 | 25 | size_t *dlen); |
5ae4ceb9 VD |
26 | unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags); |
27 | unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags); | |
28 | unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags); | |
29 | unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags); | |
919ba009 VD |
30 | |
31 | =head1 DESCRIPTION | |
32 | ||
33 | These functions implement support for DANE TLSA (RFC6698 and RFC7671) | |
34 | peer authentication. | |
35 | ||
ee84152f VD |
36 | SSL_CTX_dane_enable() must be called first to initialize the shared state |
37 | required for DANE support. | |
38 | Individual connections associated with the context can then enable | |
39 | per-connection DANE support as appropriate. | |
40 | DANE authentication is implemented in the L<X509_verify_cert(3)> function, and | |
41 | applications that override L<X509_verify_cert(3)> via | |
42 | L<SSL_CTX_set_cert_verify_callback(3)> are responsible to authenticate the peer | |
43 | chain in whatever manner they see fit. | |
44 | ||
b9b6a7e5 | 45 | SSL_CTX_dane_mtype_set() may then be called zero or more times to adjust the |
ee84152f VD |
46 | supported digest algorithms. |
47 | This must be done before any SSL handles are created for the context. | |
48 | ||
49 | The B<mtype> argument specifies a DANE TLSA matching type and the B<md> | |
50 | argument specifies the associated digest algorithm handle. | |
51 | The B<ord> argument specifies a strength ordinal. | |
52 | Algorithms with a larger strength ordinal are considered more secure. | |
53 | Strength ordinals are used to implement RFC7671 digest algorithm agility. | |
919ba009 | 54 | Specifying a B<NULL> digest algorithm for a matching type disables |
ee84152f VD |
55 | support for that matching type. |
56 | Matching type Full(0) cannot be modified or disabled. | |
919ba009 VD |
57 | |
58 | By default, matching type C<SHA2-256(1)> (see RFC7218 for definitions | |
59 | of the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()> | |
60 | with a strength ordinal of C<1> and matching type C<SHA2-512(2)> | |
61 | is mapped to C<EVP_sha512()> with a strength ordinal of C<2>. | |
62 | ||
80f63d66 VD |
63 | SSL_dane_enable() must be called before the SSL handshake is initiated with |
64 | L<SSL_connect(3)> if (and only if) you want to enable DANE for that connection. | |
919ba009 VD |
65 | (The connection must be associated with a DANE-enabled SSL context). |
66 | The B<basedomain> argument specifies the RFC7671 TLSA base domain, | |
67 | which will be the primary peer reference identifier for certificate | |
ee84152f VD |
68 | name checks. |
69 | Additional server names can be specified via L<SSL_add1_host(3)>. | |
70 | The B<basedomain> is used as the default SNI hint if none has yet been | |
71 | specified via L<SSL_set_tlsext_host_name(3)>. | |
919ba009 | 72 | |
ee84152f VD |
73 | SSL_dane_tlsa_add() may then be called one or more times, to load each of the |
74 | TLSA records that apply to the remote TLS peer. | |
919ba009 | 75 | (This too must be done prior to the beginning of the SSL handshake). |
ee84152f VD |
76 | The arguments specify the fields of the TLSA record. |
77 | The B<data> field is provided in binary (wire RDATA) form, not the hexadecimal | |
78 | ASCII presentation form, with an explicit length passed via B<dlen>. | |
a41a6120 PS |
79 | The library takes a copy of the B<data> buffer contents and the caller may |
80 | free the original B<data> buffer when convenient. | |
ee84152f | 81 | A return value of 0 indicates that "unusable" TLSA records (with invalid or |
9f6b22b8 VD |
82 | unsupported parameters) were provided. |
83 | A negative return value indicates an internal error in processing the record. | |
84 | ||
85 | The caller is expected to check the return value of each SSL_dane_tlsa_add() | |
86 | call and take appropriate action if none are usable or an internal error | |
87 | is encountered in processing some records. | |
88 | ||
89 | If no TLSA records are added successfully, DANE authentication is not enabled, | |
90 | and authentication will be based on any configured traditional trust-anchors; | |
91 | authentication success in this case does not mean that the peer was | |
92 | DANE-authenticated. | |
ee84152f VD |
93 | |
94 | SSL_get0_dane_authority() can be used to get more detailed information about | |
95 | the matched DANE trust-anchor after successful connection completion. | |
96 | The return value is negative if DANE verification failed (or was not enabled), | |
97 | 0 if an EE TLSA record directly matched the leaf certificate, or a positive | |
98 | number indicating the depth at which a TA record matched an issuer certificate. | |
c0a445a9 VD |
99 | The complete verified chain can be retrieved via L<SSL_get0_verified_chain(3)>. |
100 | The return value is an index into this verified chain, rather than the list of | |
101 | certificates sent by the peer as returned by L<SSL_get_peer_cert_chain(3)>. | |
ee84152f VD |
102 | |
103 | If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain | |
104 | certificate, a pointer to the matching certificate is returned via B<mcert>. | |
105 | The returned address is a short-term internal reference to the certificate and | |
106 | must not be freed by the application. | |
919ba009 | 107 | Applications that want to retain access to the certificate can call |
ee84152f VD |
108 | L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via |
109 | L<X509_free(3)> once no longer needed. | |
110 | ||
111 | If no TLSA records directly matched any elements of the certificate chain, but | |
112 | a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an | |
113 | element of the chain, then that key is returned via B<mspki> argument (if not | |
114 | NULL). | |
115 | In this case the return value is the depth of the top-most element of the | |
116 | validated certificate chain. | |
117 | As with B<mcert> this is a short-term internal reference, and | |
118 | L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and | |
119 | release long-term references respectively. | |
120 | ||
121 | SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that | |
122 | matched the peer certificate chain. | |
123 | The return value indicates the match depth or failure to match just as with | |
124 | SSL_get0_dane_authority(). | |
490c8711 | 125 | When the return value is nonnegative, the storage pointed to by the B<usage>, |
ee84152f VD |
126 | B<selector>, B<mtype> and B<data> parameters is updated to the corresponding |
127 | TLSA record fields. | |
128 | The B<data> field is in binary wire form, and is therefore not NUL-terminated, | |
129 | its length is returned via the B<dlen> parameter. | |
130 | If any of these parameters is NULL, the corresponding field is not returned. | |
131 | The B<data> parameter is set to a short-term internal-copy of the associated | |
132 | data field and must not be freed by the application. | |
133 | Applications that need long-term access to this field need to copy the content. | |
919ba009 | 134 | |
5ae4ceb9 VD |
135 | SSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable |
136 | optional DANE verification features. | |
137 | SSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable | |
138 | the same features. | |
9c0586d5 | 139 | The B<flags> argument is a bit-mask of the features to enable or disable. |
5ae4ceb9 VD |
140 | The B<flags> set for an B<SSL_CTX> context are copied to each B<SSL> handle |
141 | associated with that context at the time the handle is created. | |
142 | Subsequent changes in the context's B<flags> have no effect on the B<flags> set | |
143 | for the handle. | |
144 | ||
145 | At present, the only available option is B<DANE_FLAG_NO_DANE_EE_NAMECHECKS> | |
146 | which can be used to disable server name checks when authenticating via | |
147 | DANE-EE(3) TLSA records. | |
148 | For some applications, primarily web browsers, it is not safe to disable name | |
149 | checks due to "unknown key share" attacks, in which a malicious server can | |
150 | convince a client that a connection to a victim server is instead a secure | |
151 | connection to the malicious server. | |
152 | The malicious server may then be able to violate cross-origin scripting | |
153 | restrictions. | |
154 | Thus, despite the text of RFC7671, name checks are by default enabled for | |
155 | DANE-EE(3) TLSA records, and can be disabled in applications where it is safe | |
156 | to do so. | |
157 | In particular, SMTP and XMPP clients should set this option as SRV and MX | |
158 | records already make it possible for a remote domain to redirect client | |
159 | connections to any server of its choice, and in any case SMTP and XMPP clients | |
160 | do not execute scripts downloaded from remote servers. | |
161 | ||
919ba009 VD |
162 | =head1 RETURN VALUES |
163 | ||
164 | The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(), | |
ee84152f VD |
165 | SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success. |
166 | Negative return values indicate resource problems (out of memory, etc.) in the | |
167 | SSL library, while a return value of B<0> indicates incorrect usage or invalid | |
168 | input, such as an unsupported TLSA record certificate usage, selector or | |
169 | matching type. | |
170 | Invalid input also includes malformed data, either a digest length that does | |
171 | not match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form) | |
172 | certificate or a public key that fails to parse. | |
173 | ||
174 | The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a | |
175 | negative value when DANE authentication failed or was not enabled, a | |
490c8711 | 176 | nonnegative value indicates the chain depth at which the TLSA record matched a |
ee84152f VD |
177 | chain certificate, or the depth of the top-most certificate, when the TLSA |
178 | record is a full public key that is its signer. | |
919ba009 | 179 | |
5ae4ceb9 VD |
180 | The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(), |
181 | SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect | |
182 | before they were called. | |
183 | ||
cda77422 | 184 | =head1 EXAMPLES |
919ba009 | 185 | |
ee84152f VD |
186 | Suppose "smtp.example.com" is the MX host of the domain "example.com", and has |
187 | DNSSEC-validated TLSA records. | |
188 | The calls below will perform DANE authentication and arrange to match either | |
189 | the MX hostname or the destination domain name in the SMTP server certificate. | |
190 | Wildcards are supported, but must match the entire label. | |
191 | The actual name matched in the certificate (which might be a wildcard) is | |
192 | retrieved, and must be copied by the application if it is to be retained beyond | |
919ba009 VD |
193 | the lifetime of the SSL connection. |
194 | ||
2947af32 BB |
195 | SSL_CTX *ctx; |
196 | SSL *ssl; | |
197 | int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL; | |
198 | int num_usable = 0; | |
199 | const char *nexthop_domain = "example.com"; | |
200 | const char *dane_tlsa_domain = "smtp.example.com"; | |
201 | uint8_t usage, selector, mtype; | |
202 | ||
203 | if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) | |
204 | /* error */ | |
205 | if (SSL_CTX_dane_enable(ctx) <= 0) | |
206 | /* error */ | |
207 | if ((ssl = SSL_new(ctx)) == NULL) | |
208 | /* error */ | |
209 | if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) | |
210 | /* error */ | |
211 | ||
212 | /* | |
213 | * For many applications it is safe to skip DANE-EE(3) namechecks. Do not | |
214 | * disable the checks unless "unknown key share" attacks pose no risk for | |
215 | * your application. | |
216 | */ | |
217 | SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS); | |
218 | ||
219 | if (!SSL_add1_host(ssl, nexthop_domain)) | |
220 | /* error */ | |
221 | SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); | |
222 | ||
223 | for (... each TLSA record ...) { | |
224 | unsigned char *data; | |
225 | size_t len; | |
226 | int ret; | |
227 | ||
228 | /* set usage, selector, mtype, data, len */ | |
229 | ||
230 | /* | |
231 | * Opportunistic DANE TLS clients support only DANE-TA(2) or DANE-EE(3). | |
232 | * They treat all other certificate usages, and in particular PKIX-TA(0) | |
233 | * and PKIX-EE(1), as unusable. | |
234 | */ | |
235 | switch (usage) { | |
236 | default: | |
237 | case 0: /* PKIX-TA(0) */ | |
238 | case 1: /* PKIX-EE(1) */ | |
239 | continue; | |
240 | case 2: /* DANE-TA(2) */ | |
241 | case 3: /* DANE-EE(3) */ | |
242 | break; | |
243 | } | |
244 | ||
245 | ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len); | |
246 | /* free data as appropriate */ | |
247 | ||
248 | if (ret < 0) | |
249 | /* handle SSL library internal error */ | |
250 | else if (ret == 0) | |
251 | /* handle unusable TLSA record */ | |
252 | else | |
253 | ++num_usable; | |
254 | } | |
255 | ||
256 | /* | |
257 | * At this point, the verification mode is still the default SSL_VERIFY_NONE. | |
258 | * Opportunistic DANE clients use unauthenticated TLS when all TLSA records | |
259 | * are unusable, so continue the handshake even if authentication fails. | |
260 | */ | |
261 | if (num_usable == 0) { | |
262 | /* Log all records unusable? */ | |
263 | ||
264 | /* Optionally set verify_cb to a suitable non-NULL callback. */ | |
265 | SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb); | |
266 | } else { | |
267 | /* At least one usable record. We expect to verify the peer */ | |
268 | ||
269 | /* Optionally set verify_cb to a suitable non-NULL callback. */ | |
270 | ||
271 | /* | |
272 | * Below we elect to fail the handshake when peer verification fails. | |
273 | * Alternatively, use the permissive SSL_VERIFY_NONE verification mode, | |
274 | * complete the handshake, check the verification status, and if not | |
275 | * verified disconnect gracefully at the application layer, especially if | |
276 | * application protocol supports informing the server that authentication | |
277 | * failed. | |
278 | */ | |
279 | SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb); | |
280 | } | |
281 | ||
282 | /* | |
283 | * Load any saved session for resumption, making sure that the previous | |
284 | * session applied the same security and authentication requirements that | |
285 | * would be expected of a fresh connection. | |
286 | */ | |
287 | ||
288 | /* Perform SSL_connect() handshake and handle errors here */ | |
289 | ||
290 | if (SSL_session_reused(ssl)) { | |
291 | if (SSL_get_verify_result(ssl) == X509_V_OK) { | |
292 | /* | |
293 | * Resumed session was originally verified, this connection is | |
294 | * authenticated. | |
295 | */ | |
296 | } else { | |
297 | /* | |
298 | * Resumed session was not originally verified, this connection is not | |
299 | * authenticated. | |
300 | */ | |
301 | } | |
302 | } else if (SSL_get_verify_result(ssl) == X509_V_OK) { | |
303 | const char *peername = SSL_get0_peername(ssl); | |
304 | EVP_PKEY *mspki = NULL; | |
305 | ||
306 | int depth = SSL_get0_dane_authority(ssl, NULL, &mspki); | |
307 | if (depth >= 0) { | |
308 | (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL); | |
309 | printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype, | |
310 | (mspki != NULL) ? "TA public key verified certificate" : | |
311 | depth ? "matched TA certificate" : "matched EE certificate", | |
312 | depth); | |
313 | } | |
314 | if (peername != NULL) { | |
315 | /* Name checks were in scope and matched the peername */ | |
316 | printf("Verified peername: %s\n", peername); | |
317 | } | |
318 | } else { | |
319 | /* | |
320 | * Not authenticated, presumably all TLSA rrs unusable, but possibly a | |
321 | * callback suppressed connection termination despite the presence of | |
322 | * usable TLSA RRs none of which matched. Do whatever is appropriate for | |
323 | * fresh unauthenticated connections. | |
324 | */ | |
325 | } | |
919ba009 VD |
326 | |
327 | =head1 NOTES | |
328 | ||
ee84152f VD |
329 | It is expected that the majority of clients employing DANE TLS will be doing |
330 | "opportunistic DANE TLS" in the sense of RFC7672 and RFC7435. | |
331 | That is, they will use DANE authentication when DNSSEC-validated TLSA records | |
332 | are published for a given peer, and otherwise will use unauthenticated TLS or | |
333 | even cleartext. | |
334 | ||
335 | Such applications should generally treat any TLSA records published by the peer | |
336 | with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include | |
337 | them among the TLSA records used to authenticate peer connections. | |
338 | In addition, some TLSA records with supported usages may be "unusable" as a | |
339 | result of invalid or unsupported parameters. | |
919ba009 | 340 | |
0517ffc4 | 341 | When a peer has TLSA records, but none are "usable", an opportunistic |
919ba009 VD |
342 | application must avoid cleartext, but cannot authenticate the peer, |
343 | and so should generally proceed with an unauthenticated connection. | |
344 | Opportunistic applications need to note the return value of each | |
345 | call to SSL_dane_tlsa_add(), and if all return 0 (due to invalid | |
346 | or unsupported parameters) disable peer authentication by calling | |
347 | L<SSL_set_verify(3)> with B<mode> equal to B<SSL_VERIFY_NONE>. | |
348 | ||
349 | =head1 SEE ALSO | |
350 | ||
98ca37e4 | 351 | L<ssl(7)>, |
919ba009 VD |
352 | L<SSL_new(3)>, |
353 | L<SSL_add1_host(3)>, | |
354 | L<SSL_set_hostflags(3)>, | |
355 | L<SSL_set_tlsext_host_name(3)>, | |
356 | L<SSL_set_verify(3)>, | |
357 | L<SSL_CTX_set_cert_verify_callback(3)>, | |
c0a445a9 VD |
358 | L<SSL_get0_verified_chain(3)>, |
359 | L<SSL_get_peer_cert_chain(3)>, | |
360 | L<SSL_get_verify_result(3)>, | |
919ba009 VD |
361 | L<SSL_connect(3)>, |
362 | L<SSL_get0_peername(3)>, | |
c0a445a9 | 363 | L<X509_verify_cert(3)>, |
919ba009 VD |
364 | L<X509_up_ref(3)>, |
365 | L<X509_free(3)>, | |
c0a445a9 | 366 | L<EVP_get_digestbyname(3)>, |
919ba009 VD |
367 | L<EVP_PKEY_up_ref(3)>, |
368 | L<EVP_PKEY_free(3)> | |
369 | ||
370 | =head1 HISTORY | |
371 | ||
fc5ecadd | 372 | These functions were added in OpenSSL 1.1.0. |
919ba009 | 373 | |
e2f92610 RS |
374 | =head1 COPYRIGHT |
375 | ||
4333b89f | 376 | Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 377 | |
4746f25a | 378 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
379 | this file except in compliance with the License. You can obtain a copy |
380 | in the file LICENSE in the source distribution or at | |
381 | L<https://www.openssl.org/source/license.html>. | |
382 | ||
383 | =cut |