doc/ssl/SSL_CTX_dane_enable.pod

   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 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 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.
  48 Specifying a B<NULL> digest algorithm for a matching type disables
  49 support for that matching type.
  50 Matching type Full(0) cannot be 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() 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.
  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.
  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)>.
  66
  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.
  69 (This too must be done prior to the beginning of the SSL handshake).
  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.
  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)>.
  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.
  93 Applications that want to retain access to the certificate can call
  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.
 120
 121 =head1 RETURN VALUES
 122
 123 The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(),
 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.
 138
 139 =head1 EXAMPLE
 140
 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
 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);
 186     /* free data as appropriate */
 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
 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
 215   /* Perform SSL_connect() handshake and handle errors here */
 216
 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) {
 230     const char *peername = SSL_get0_peername(ssl);
 231     EVP_PKEY *mspki = NULL;
 232
 233     int depth = SSL_get0_dane_authority(ssl, NULL, &mspki);
 234     if (depth >= 0) {
 235         (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL);
 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
 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.
 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)>,
 284 L<SSL_get0_verified_chain(3)>,
 285 L<SSL_get_peer_cert_chain(3)>,
 286 L<SSL_get_verify_result(3)>,
 287 L<SSL_connect(3)>,
 288 L<SSL_get0_peername(3)>,
 289 L<X509_verify_cert(3)>,
 290 L<X509_up_ref(3)>,
 291 L<X509_free(3)>,
 292 L<EVP_get_digestbyname(3)>,
 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