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