]>
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 | ||
39 | SSL_CTX_dane_mtype_set() may then be called zero or more times to to adjust the | |
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 | |
74 | unsupported parameters) were provided, a negative return value indicates an | |
75 | internal error in processing the records. | |
76 | If DANE authentication is enabled, but no TLSA records are added successfully, | |
77 | authentication will fail, and the handshake may not complete, depending on the | |
78 | B<mode> argument of L<SSL_set_verify(3)> and any verification callback. | |
79 | ||
80 | SSL_get0_dane_authority() can be used to get more detailed information about | |
81 | the matched DANE trust-anchor after successful connection completion. | |
82 | The return value is negative if DANE verification failed (or was not enabled), | |
83 | 0 if an EE TLSA record directly matched the leaf certificate, or a positive | |
84 | number indicating the depth at which a TA record matched an issuer certificate. | |
c0a445a9 VD |
85 | The complete verified chain can be retrieved via L<SSL_get0_verified_chain(3)>. |
86 | The return value is an index into this verified chain, rather than the list of | |
87 | certificates sent by the peer as returned by L<SSL_get_peer_cert_chain(3)>. | |
ee84152f VD |
88 | |
89 | If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain | |
90 | certificate, a pointer to the matching certificate is returned via B<mcert>. | |
91 | The returned address is a short-term internal reference to the certificate and | |
92 | must not be freed by the application. | |
919ba009 | 93 | Applications that want to retain access to the certificate can call |
ee84152f VD |
94 | L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via |
95 | L<X509_free(3)> once no longer needed. | |
96 | ||
97 | If no TLSA records directly matched any elements of the certificate chain, but | |
98 | a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an | |
99 | element of the chain, then that key is returned via B<mspki> argument (if not | |
100 | NULL). | |
101 | In this case the return value is the depth of the top-most element of the | |
102 | validated certificate chain. | |
103 | As with B<mcert> this is a short-term internal reference, and | |
104 | L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and | |
105 | release long-term references respectively. | |
106 | ||
107 | SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that | |
108 | matched the peer certificate chain. | |
109 | The return value indicates the match depth or failure to match just as with | |
110 | SSL_get0_dane_authority(). | |
111 | When the return value is non-negative, the storage pointed to by the B<usage>, | |
112 | B<selector>, B<mtype> and B<data> parameters is updated to the corresponding | |
113 | TLSA record fields. | |
114 | The B<data> field is in binary wire form, and is therefore not NUL-terminated, | |
115 | its length is returned via the B<dlen> parameter. | |
116 | If any of these parameters is NULL, the corresponding field is not returned. | |
117 | The B<data> parameter is set to a short-term internal-copy of the associated | |
118 | data field and must not be freed by the application. | |
119 | Applications that need long-term access to this field need to copy the content. | |
919ba009 VD |
120 | |
121 | =head1 RETURN VALUES | |
122 | ||
123 | The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(), | |
ee84152f VD |
124 | SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success. |
125 | Negative return values indicate resource problems (out of memory, etc.) in the | |
126 | SSL library, while a return value of B<0> indicates incorrect usage or invalid | |
127 | input, such as an unsupported TLSA record certificate usage, selector or | |
128 | matching type. | |
129 | Invalid input also includes malformed data, either a digest length that does | |
130 | not match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form) | |
131 | certificate or a public key that fails to parse. | |
132 | ||
133 | The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a | |
134 | negative value when DANE authentication failed or was not enabled, a | |
135 | non-negative value indicates the chain depth at which the TLSA record matched a | |
136 | chain certificate, or the depth of the top-most certificate, when the TLSA | |
137 | record is a full public key that is its signer. | |
919ba009 VD |
138 | |
139 | =head1 EXAMPLE | |
140 | ||
ee84152f VD |
141 | Suppose "smtp.example.com" is the MX host of the domain "example.com", and has |
142 | DNSSEC-validated TLSA records. | |
143 | The calls below will perform DANE authentication and arrange to match either | |
144 | the MX hostname or the destination domain name in the SMTP server certificate. | |
145 | Wildcards are supported, but must match the entire label. | |
146 | The actual name matched in the certificate (which might be a wildcard) is | |
147 | retrieved, and must be copied by the application if it is to be retained beyond | |
919ba009 VD |
148 | the lifetime of the SSL connection. |
149 | ||
150 | SSL_CTX *ctx; | |
151 | SSL *ssl; | |
152 | int num_usable = 0; | |
153 | const char *nexthop_domain = "example.com"; | |
154 | const char *dane_tlsa_domain = "smtp.example.com"; | |
155 | uint8_t usage, selector, mtype; | |
156 | ||
157 | if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) | |
158 | /* handle error */ | |
159 | if (SSL_CTX_dane_enable(ctx) <= 0) | |
160 | /* handle error */ | |
161 | ||
162 | if ((ssl = SSL_new(ctx)) == NULL) | |
163 | /* handle error */ | |
164 | ||
165 | if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) | |
166 | /* handle error */ | |
167 | if (!SSL_add1_host(ssl, nexthop_domain)) | |
168 | /* handle error */ | |
169 | SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); | |
170 | ||
171 | for (... each TLSA record ...) { | |
172 | unsigned char *data; | |
173 | size_t len; | |
174 | int ret; | |
175 | ||
176 | /* set usage, selector, mtype, data, len */ | |
177 | ||
178 | /* Opportunistic DANE TLS clients treat usages 0, 1 as unusable. */ | |
179 | switch (usage) { | |
180 | case 0: /* PKIX-TA(0) */ | |
181 | case 1: /* PKIX-EE(1) */ | |
182 | continue; | |
183 | } | |
184 | ||
185 | ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len); | |
63b65834 | 186 | /* free data as appropriate */ |
919ba009 VD |
187 | |
188 | if (ret < 0) | |
189 | /* handle SSL library internal error */ | |
190 | else if (ret == 0) | |
191 | /* handle unusable TLSA record */ | |
192 | else | |
193 | ++num_usable; | |
194 | } | |
195 | ||
196 | /* | |
197 | * Opportunistic DANE clients use unauthenticated TLS when all TLSA records | |
198 | * are unusable, so continue the handshake even if authentication fails. | |
199 | */ | |
200 | if (num_usable == 0) { | |
201 | int (*cb)(int ok, X509_STORE_CTX *sctx) = NULL; | |
202 | ||
203 | /* Log all records unusable? */ | |
204 | /* Set cb to a non-NULL callback of your choice? */ | |
205 | ||
206 | SSL_set_verify(ssl, SSL_VERIFY_NONE, cb); | |
207 | } | |
208 | ||
c0a445a9 VD |
209 | /* |
210 | * Load any saved session for resumption, making sure that the previous | |
211 | * session applied the same security and authentication requirements that | |
212 | * would be expected of a fresh connection. | |
213 | */ | |
214 | ||
919ba009 VD |
215 | /* Perform SSL_connect() handshake and handle errors here */ |
216 | ||
c0a445a9 VD |
217 | if (SSL_session_resumed(ssl)) { |
218 | if (SSL_get_verify_result(ssl) == X509_V_OK) { | |
219 | /* | |
220 | * Resumed session was originally verified, this connection is | |
221 | * authenticated. | |
222 | */ | |
223 | } else { | |
224 | /* | |
225 | * Resumed session was not originally verified, this connection is not | |
226 | * authenticated. | |
227 | */ | |
228 | } | |
229 | } else if (SSL_get_verify_result(ssl) == X509_V_OK) { | |
919ba009 VD |
230 | const char *peername = SSL_get0_peername(ssl); |
231 | EVP_PKEY *mspki = NULL; | |
232 | ||
80f63d66 | 233 | int depth = SSL_get0_dane_authority(ssl, NULL, &mspki); |
919ba009 | 234 | if (depth >= 0) { |
80f63d66 | 235 | (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL); |
919ba009 VD |
236 | printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype, |
237 | (mspki != NULL) ? "TA public key verified certificate" : | |
238 | depth ? "matched TA certificate" : "matched EE certificate", | |
239 | depth); | |
240 | } | |
241 | if (peername != NULL) { | |
242 | /* Name checks were in scope and matched the peername */ | |
243 | printf(bio, "Verified peername: %s\n", peername); | |
244 | } | |
245 | } else { | |
246 | /* | |
247 | * Not authenticated, presumably all TLSA rrs unusable, but possibly a | |
248 | * callback suppressed connection termination despite presence of TLSA | |
249 | * usable RRs none of which matched. Do whatever is appropriate for | |
250 | * unauthenticated connections. | |
251 | */ | |
252 | } | |
253 | ||
254 | =head1 NOTES | |
255 | ||
ee84152f VD |
256 | It is expected that the majority of clients employing DANE TLS will be doing |
257 | "opportunistic DANE TLS" in the sense of RFC7672 and RFC7435. | |
258 | That is, they will use DANE authentication when DNSSEC-validated TLSA records | |
259 | are published for a given peer, and otherwise will use unauthenticated TLS or | |
260 | even cleartext. | |
261 | ||
262 | Such applications should generally treat any TLSA records published by the peer | |
263 | with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include | |
264 | them among the TLSA records used to authenticate peer connections. | |
265 | In addition, some TLSA records with supported usages may be "unusable" as a | |
266 | result of invalid or unsupported parameters. | |
919ba009 VD |
267 | |
268 | When a peer has TLSA records, but none are "usable", an opportunistic | |
269 | application must avoid cleartext, but cannot authenticate the peer, | |
270 | and so should generally proceed with an unauthenticated connection. | |
271 | Opportunistic applications need to note the return value of each | |
272 | call to SSL_dane_tlsa_add(), and if all return 0 (due to invalid | |
273 | or unsupported parameters) disable peer authentication by calling | |
274 | L<SSL_set_verify(3)> with B<mode> equal to B<SSL_VERIFY_NONE>. | |
275 | ||
276 | =head1 SEE ALSO | |
277 | ||
278 | L<SSL_new(3)>, | |
279 | L<SSL_add1_host(3)>, | |
280 | L<SSL_set_hostflags(3)>, | |
281 | L<SSL_set_tlsext_host_name(3)>, | |
282 | L<SSL_set_verify(3)>, | |
283 | L<SSL_CTX_set_cert_verify_callback(3)>, | |
c0a445a9 VD |
284 | L<SSL_get0_verified_chain(3)>, |
285 | L<SSL_get_peer_cert_chain(3)>, | |
286 | L<SSL_get_verify_result(3)>, | |
919ba009 VD |
287 | L<SSL_connect(3)>, |
288 | L<SSL_get0_peername(3)>, | |
c0a445a9 | 289 | L<X509_verify_cert(3)>, |
919ba009 VD |
290 | L<X509_up_ref(3)>, |
291 | L<X509_free(3)>, | |
c0a445a9 | 292 | L<EVP_get_digestbyname(3)>, |
919ba009 VD |
293 | L<EVP_PKEY_up_ref(3)>, |
294 | L<EVP_PKEY_free(3)> | |
295 | ||
296 | =head1 HISTORY | |
297 | ||
298 | These functions were first added to OpenSSL 1.1.0. | |
299 | ||
300 | =cut |