]>
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, | |
5ae4ceb9 VD |
6 | SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa |
7 | SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags, | |
8 | SSL_dane_set_flags, SSL_dane_clear_flags - | |
919ba009 VD |
9 | enable DANE TLS authentication of the remote TLS server in the local |
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, | |
21 | uint8_t mtype, unsigned char *data, size_t dlen); | |
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, | |
24 | uint8_t *mtype, unsigned const char **data, | |
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>. | |
79 | A return value of 0 indicates that "unusable" TLSA records (with invalid or | |
9f6b22b8 VD |
80 | unsupported parameters) were provided. |
81 | A negative return value indicates an internal error in processing the record. | |
82 | ||
83 | The caller is expected to check the return value of each SSL_dane_tlsa_add() | |
84 | call and take appropriate action if none are usable or an internal error | |
85 | is encountered in processing some records. | |
86 | ||
87 | If no TLSA records are added successfully, DANE authentication is not enabled, | |
88 | and authentication will be based on any configured traditional trust-anchors; | |
89 | authentication success in this case does not mean that the peer was | |
90 | DANE-authenticated. | |
ee84152f VD |
91 | |
92 | SSL_get0_dane_authority() can be used to get more detailed information about | |
93 | the matched DANE trust-anchor after successful connection completion. | |
94 | The return value is negative if DANE verification failed (or was not enabled), | |
95 | 0 if an EE TLSA record directly matched the leaf certificate, or a positive | |
96 | number indicating the depth at which a TA record matched an issuer certificate. | |
c0a445a9 VD |
97 | The complete verified chain can be retrieved via L<SSL_get0_verified_chain(3)>. |
98 | The return value is an index into this verified chain, rather than the list of | |
99 | certificates sent by the peer as returned by L<SSL_get_peer_cert_chain(3)>. | |
ee84152f VD |
100 | |
101 | If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain | |
102 | certificate, a pointer to the matching certificate is returned via B<mcert>. | |
103 | The returned address is a short-term internal reference to the certificate and | |
104 | must not be freed by the application. | |
919ba009 | 105 | Applications that want to retain access to the certificate can call |
ee84152f VD |
106 | L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via |
107 | L<X509_free(3)> once no longer needed. | |
108 | ||
109 | If no TLSA records directly matched any elements of the certificate chain, but | |
110 | a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an | |
111 | element of the chain, then that key is returned via B<mspki> argument (if not | |
112 | NULL). | |
113 | In this case the return value is the depth of the top-most element of the | |
114 | validated certificate chain. | |
115 | As with B<mcert> this is a short-term internal reference, and | |
116 | L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and | |
117 | release long-term references respectively. | |
118 | ||
119 | SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that | |
120 | matched the peer certificate chain. | |
121 | The return value indicates the match depth or failure to match just as with | |
122 | SSL_get0_dane_authority(). | |
123 | When the return value is non-negative, the storage pointed to by the B<usage>, | |
124 | B<selector>, B<mtype> and B<data> parameters is updated to the corresponding | |
125 | TLSA record fields. | |
126 | The B<data> field is in binary wire form, and is therefore not NUL-terminated, | |
127 | its length is returned via the B<dlen> parameter. | |
128 | If any of these parameters is NULL, the corresponding field is not returned. | |
129 | The B<data> parameter is set to a short-term internal-copy of the associated | |
130 | data field and must not be freed by the application. | |
131 | Applications that need long-term access to this field need to copy the content. | |
919ba009 | 132 | |
5ae4ceb9 VD |
133 | SSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable |
134 | optional DANE verification features. | |
135 | SSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable | |
136 | the same features. | |
137 | The B<flags> argument is a bitmask of the features to enable or disable. | |
138 | The B<flags> set for an B<SSL_CTX> context are copied to each B<SSL> handle | |
139 | associated with that context at the time the handle is created. | |
140 | Subsequent changes in the context's B<flags> have no effect on the B<flags> set | |
141 | for the handle. | |
142 | ||
143 | At present, the only available option is B<DANE_FLAG_NO_DANE_EE_NAMECHECKS> | |
144 | which can be used to disable server name checks when authenticating via | |
145 | DANE-EE(3) TLSA records. | |
146 | For some applications, primarily web browsers, it is not safe to disable name | |
147 | checks due to "unknown key share" attacks, in which a malicious server can | |
148 | convince a client that a connection to a victim server is instead a secure | |
149 | connection to the malicious server. | |
150 | The malicious server may then be able to violate cross-origin scripting | |
151 | restrictions. | |
152 | Thus, despite the text of RFC7671, name checks are by default enabled for | |
153 | DANE-EE(3) TLSA records, and can be disabled in applications where it is safe | |
154 | to do so. | |
155 | In particular, SMTP and XMPP clients should set this option as SRV and MX | |
156 | records already make it possible for a remote domain to redirect client | |
157 | connections to any server of its choice, and in any case SMTP and XMPP clients | |
158 | do not execute scripts downloaded from remote servers. | |
159 | ||
919ba009 VD |
160 | =head1 RETURN VALUES |
161 | ||
162 | The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(), | |
ee84152f VD |
163 | SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success. |
164 | Negative return values indicate resource problems (out of memory, etc.) in the | |
165 | SSL library, while a return value of B<0> indicates incorrect usage or invalid | |
166 | input, such as an unsupported TLSA record certificate usage, selector or | |
167 | matching type. | |
168 | Invalid input also includes malformed data, either a digest length that does | |
169 | not match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form) | |
170 | certificate or a public key that fails to parse. | |
171 | ||
172 | The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a | |
173 | negative value when DANE authentication failed or was not enabled, a | |
174 | non-negative value indicates the chain depth at which the TLSA record matched a | |
175 | chain certificate, or the depth of the top-most certificate, when the TLSA | |
176 | record is a full public key that is its signer. | |
919ba009 | 177 | |
5ae4ceb9 VD |
178 | The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(), |
179 | SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect | |
180 | before they were called. | |
181 | ||
919ba009 VD |
182 | =head1 EXAMPLE |
183 | ||
ee84152f VD |
184 | Suppose "smtp.example.com" is the MX host of the domain "example.com", and has |
185 | DNSSEC-validated TLSA records. | |
186 | The calls below will perform DANE authentication and arrange to match either | |
187 | the MX hostname or the destination domain name in the SMTP server certificate. | |
188 | Wildcards are supported, but must match the entire label. | |
189 | The actual name matched in the certificate (which might be a wildcard) is | |
190 | retrieved, and must be copied by the application if it is to be retained beyond | |
919ba009 VD |
191 | the lifetime of the SSL connection. |
192 | ||
193 | SSL_CTX *ctx; | |
194 | SSL *ssl; | |
9f6b22b8 | 195 | int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL; |
919ba009 VD |
196 | int num_usable = 0; |
197 | const char *nexthop_domain = "example.com"; | |
198 | const char *dane_tlsa_domain = "smtp.example.com"; | |
199 | uint8_t usage, selector, mtype; | |
200 | ||
201 | if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) | |
202 | /* handle error */ | |
203 | if (SSL_CTX_dane_enable(ctx) <= 0) | |
204 | /* handle error */ | |
205 | ||
206 | if ((ssl = SSL_new(ctx)) == NULL) | |
207 | /* handle error */ | |
208 | ||
209 | if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) | |
210 | /* handle error */ | |
5ae4ceb9 VD |
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 | ||
919ba009 VD |
219 | if (!SSL_add1_host(ssl, nexthop_domain)) |
220 | /* handle 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 | ||
9f6b22b8 VD |
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 | */ | |
919ba009 | 235 | switch (usage) { |
9f6b22b8 | 236 | default: |
919ba009 VD |
237 | case 0: /* PKIX-TA(0) */ |
238 | case 1: /* PKIX-EE(1) */ | |
239 | continue; | |
9f6b22b8 VD |
240 | case 2: /* DANE-TA(2) */ |
241 | case 3: /* DANE-EE(3) */ | |
242 | break; | |
919ba009 VD |
243 | } |
244 | ||
245 | ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len); | |
63b65834 | 246 | /* free data as appropriate */ |
919ba009 VD |
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 | /* | |
9f6b22b8 | 257 | * At this point, the verification mode is still the default SSL_VERIFY_NONE. |
919ba009 VD |
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) { | |
919ba009 | 262 | /* Log all records unusable? */ |
919ba009 | 263 | |
9f6b22b8 VD |
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); | |
919ba009 VD |
280 | } |
281 | ||
c0a445a9 VD |
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 | ||
919ba009 VD |
288 | /* Perform SSL_connect() handshake and handle errors here */ |
289 | ||
71ccf961 | 290 | if (SSL_session_reused(ssl)) { |
c0a445a9 VD |
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) { | |
919ba009 VD |
303 | const char *peername = SSL_get0_peername(ssl); |
304 | EVP_PKEY *mspki = NULL; | |
305 | ||
80f63d66 | 306 | int depth = SSL_get0_dane_authority(ssl, NULL, &mspki); |
919ba009 | 307 | if (depth >= 0) { |
80f63d66 | 308 | (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL); |
919ba009 VD |
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 */ | |
9f6b22b8 | 316 | printf("Verified peername: %s\n", peername); |
919ba009 VD |
317 | } |
318 | } else { | |
319 | /* | |
320 | * Not authenticated, presumably all TLSA rrs unusable, but possibly a | |
9f6b22b8 VD |
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. | |
919ba009 VD |
324 | */ |
325 | } | |
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 | ||
351 | L<SSL_new(3)>, | |
352 | L<SSL_add1_host(3)>, | |
353 | L<SSL_set_hostflags(3)>, | |
354 | L<SSL_set_tlsext_host_name(3)>, | |
355 | L<SSL_set_verify(3)>, | |
356 | L<SSL_CTX_set_cert_verify_callback(3)>, | |
c0a445a9 VD |
357 | L<SSL_get0_verified_chain(3)>, |
358 | L<SSL_get_peer_cert_chain(3)>, | |
359 | L<SSL_get_verify_result(3)>, | |
919ba009 VD |
360 | L<SSL_connect(3)>, |
361 | L<SSL_get0_peername(3)>, | |
c0a445a9 | 362 | L<X509_verify_cert(3)>, |
919ba009 VD |
363 | L<X509_up_ref(3)>, |
364 | L<X509_free(3)>, | |
c0a445a9 | 365 | L<EVP_get_digestbyname(3)>, |
919ba009 VD |
366 | L<EVP_PKEY_up_ref(3)>, |
367 | L<EVP_PKEY_free(3)> | |
368 | ||
369 | =head1 HISTORY | |
370 | ||
371 | These functions were first added to OpenSSL 1.1.0. | |
372 | ||
e2f92610 RS |
373 | =head1 COPYRIGHT |
374 | ||
375 | Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. | |
376 | ||
377 | Licensed under the OpenSSL license (the "License"). You may not use | |
378 | this file except in compliance with the License. You can obtain a copy | |
379 | in the file LICENSE in the source distribution or at | |
380 | L<https://www.openssl.org/source/license.html>. | |
381 | ||
382 | =cut |