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