1*1dcdf01fSchristos=pod 2*1dcdf01fSchristos 3*1dcdf01fSchristos=head1 NAME 4*1dcdf01fSchristos 5*1dcdf01fSchristosSSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable, 6*1dcdf01fSchristosSSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa, 7*1dcdf01fSchristosSSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags, 8*1dcdf01fSchristosSSL_dane_set_flags, SSL_dane_clear_flags 9*1dcdf01fSchristos- enable DANE TLS authentication of the remote TLS server in the local 10*1dcdf01fSchristosTLS client 11*1dcdf01fSchristos 12*1dcdf01fSchristos=head1 SYNOPSIS 13*1dcdf01fSchristos 14*1dcdf01fSchristos #include <openssl/ssl.h> 15*1dcdf01fSchristos 16*1dcdf01fSchristos int SSL_CTX_dane_enable(SSL_CTX *ctx); 17*1dcdf01fSchristos int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md, 18*1dcdf01fSchristos uint8_t mtype, uint8_t ord); 19*1dcdf01fSchristos int SSL_dane_enable(SSL *s, const char *basedomain); 20*1dcdf01fSchristos int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector, 21*1dcdf01fSchristos uint8_t mtype, unsigned const char *data, size_t dlen); 22*1dcdf01fSchristos int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki); 23*1dcdf01fSchristos int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector, 24*1dcdf01fSchristos uint8_t *mtype, unsigned const char **data, 25*1dcdf01fSchristos size_t *dlen); 26*1dcdf01fSchristos unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags); 27*1dcdf01fSchristos unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags); 28*1dcdf01fSchristos unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags); 29*1dcdf01fSchristos unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags); 30*1dcdf01fSchristos 31*1dcdf01fSchristos=head1 DESCRIPTION 32*1dcdf01fSchristos 33*1dcdf01fSchristosThese functions implement support for DANE TLSA (RFC6698 and RFC7671) 34*1dcdf01fSchristospeer authentication. 35*1dcdf01fSchristos 36*1dcdf01fSchristosSSL_CTX_dane_enable() must be called first to initialize the shared state 37*1dcdf01fSchristosrequired for DANE support. 38*1dcdf01fSchristosIndividual connections associated with the context can then enable 39*1dcdf01fSchristosper-connection DANE support as appropriate. 40*1dcdf01fSchristosDANE authentication is implemented in the L<X509_verify_cert(3)> function, and 41*1dcdf01fSchristosapplications that override L<X509_verify_cert(3)> via 42*1dcdf01fSchristosL<SSL_CTX_set_cert_verify_callback(3)> are responsible to authenticate the peer 43*1dcdf01fSchristoschain in whatever manner they see fit. 44*1dcdf01fSchristos 45*1dcdf01fSchristosSSL_CTX_dane_mtype_set() may then be called zero or more times to adjust the 46*1dcdf01fSchristossupported digest algorithms. 47*1dcdf01fSchristosThis must be done before any SSL handles are created for the context. 48*1dcdf01fSchristos 49*1dcdf01fSchristosThe B<mtype> argument specifies a DANE TLSA matching type and the B<md> 50*1dcdf01fSchristosargument specifies the associated digest algorithm handle. 51*1dcdf01fSchristosThe B<ord> argument specifies a strength ordinal. 52*1dcdf01fSchristosAlgorithms with a larger strength ordinal are considered more secure. 53*1dcdf01fSchristosStrength ordinals are used to implement RFC7671 digest algorithm agility. 54*1dcdf01fSchristosSpecifying a B<NULL> digest algorithm for a matching type disables 55*1dcdf01fSchristossupport for that matching type. 56*1dcdf01fSchristosMatching type Full(0) cannot be modified or disabled. 57*1dcdf01fSchristos 58*1dcdf01fSchristosBy default, matching type C<SHA2-256(1)> (see RFC7218 for definitions 59*1dcdf01fSchristosof the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()> 60*1dcdf01fSchristoswith a strength ordinal of C<1> and matching type C<SHA2-512(2)> 61*1dcdf01fSchristosis mapped to C<EVP_sha512()> with a strength ordinal of C<2>. 62*1dcdf01fSchristos 63*1dcdf01fSchristosSSL_dane_enable() must be called before the SSL handshake is initiated with 64*1dcdf01fSchristosL<SSL_connect(3)> if (and only if) you want to enable DANE for that connection. 65*1dcdf01fSchristos(The connection must be associated with a DANE-enabled SSL context). 66*1dcdf01fSchristosThe B<basedomain> argument specifies the RFC7671 TLSA base domain, 67*1dcdf01fSchristoswhich will be the primary peer reference identifier for certificate 68*1dcdf01fSchristosname checks. 69*1dcdf01fSchristosAdditional server names can be specified via L<SSL_add1_host(3)>. 70*1dcdf01fSchristosThe B<basedomain> is used as the default SNI hint if none has yet been 71*1dcdf01fSchristosspecified via L<SSL_set_tlsext_host_name(3)>. 72*1dcdf01fSchristos 73*1dcdf01fSchristosSSL_dane_tlsa_add() may then be called one or more times, to load each of the 74*1dcdf01fSchristosTLSA records that apply to the remote TLS peer. 75*1dcdf01fSchristos(This too must be done prior to the beginning of the SSL handshake). 76*1dcdf01fSchristosThe arguments specify the fields of the TLSA record. 77*1dcdf01fSchristosThe B<data> field is provided in binary (wire RDATA) form, not the hexadecimal 78*1dcdf01fSchristosASCII presentation form, with an explicit length passed via B<dlen>. 79*1dcdf01fSchristosThe library takes a copy of the B<data> buffer contents and the caller may 80*1dcdf01fSchristosfree the original B<data> buffer when convenient. 81*1dcdf01fSchristosA return value of 0 indicates that "unusable" TLSA records (with invalid or 82*1dcdf01fSchristosunsupported parameters) were provided. 83*1dcdf01fSchristosA negative return value indicates an internal error in processing the record. 84*1dcdf01fSchristos 85*1dcdf01fSchristosThe caller is expected to check the return value of each SSL_dane_tlsa_add() 86*1dcdf01fSchristoscall and take appropriate action if none are usable or an internal error 87*1dcdf01fSchristosis encountered in processing some records. 88*1dcdf01fSchristos 89*1dcdf01fSchristosIf no TLSA records are added successfully, DANE authentication is not enabled, 90*1dcdf01fSchristosand authentication will be based on any configured traditional trust-anchors; 91*1dcdf01fSchristosauthentication success in this case does not mean that the peer was 92*1dcdf01fSchristosDANE-authenticated. 93*1dcdf01fSchristos 94*1dcdf01fSchristosSSL_get0_dane_authority() can be used to get more detailed information about 95*1dcdf01fSchristosthe matched DANE trust-anchor after successful connection completion. 96*1dcdf01fSchristosThe return value is negative if DANE verification failed (or was not enabled), 97*1dcdf01fSchristos0 if an EE TLSA record directly matched the leaf certificate, or a positive 98*1dcdf01fSchristosnumber indicating the depth at which a TA record matched an issuer certificate. 99*1dcdf01fSchristosThe complete verified chain can be retrieved via L<SSL_get0_verified_chain(3)>. 100*1dcdf01fSchristosThe return value is an index into this verified chain, rather than the list of 101*1dcdf01fSchristoscertificates sent by the peer as returned by L<SSL_get_peer_cert_chain(3)>. 102*1dcdf01fSchristos 103*1dcdf01fSchristosIf the B<mcert> argument is not B<NULL> and a TLSA record matched a chain 104*1dcdf01fSchristoscertificate, a pointer to the matching certificate is returned via B<mcert>. 105*1dcdf01fSchristosThe returned address is a short-term internal reference to the certificate and 106*1dcdf01fSchristosmust not be freed by the application. 107*1dcdf01fSchristosApplications that want to retain access to the certificate can call 108*1dcdf01fSchristosL<X509_up_ref(3)> to obtain a long-term reference which must then be freed via 109*1dcdf01fSchristosL<X509_free(3)> once no longer needed. 110*1dcdf01fSchristos 111*1dcdf01fSchristosIf no TLSA records directly matched any elements of the certificate chain, but 112*1dcdf01fSchristosa DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an 113*1dcdf01fSchristoselement of the chain, then that key is returned via B<mspki> argument (if not 114*1dcdf01fSchristosNULL). 115*1dcdf01fSchristosIn this case the return value is the depth of the top-most element of the 116*1dcdf01fSchristosvalidated certificate chain. 117*1dcdf01fSchristosAs with B<mcert> this is a short-term internal reference, and 118*1dcdf01fSchristosL<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and 119*1dcdf01fSchristosrelease long-term references respectively. 120*1dcdf01fSchristos 121*1dcdf01fSchristosSSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that 122*1dcdf01fSchristosmatched the peer certificate chain. 123*1dcdf01fSchristosThe return value indicates the match depth or failure to match just as with 124*1dcdf01fSchristosSSL_get0_dane_authority(). 125*1dcdf01fSchristosWhen the return value is nonnegative, the storage pointed to by the B<usage>, 126*1dcdf01fSchristosB<selector>, B<mtype> and B<data> parameters is updated to the corresponding 127*1dcdf01fSchristosTLSA record fields. 128*1dcdf01fSchristosThe B<data> field is in binary wire form, and is therefore not NUL-terminated, 129*1dcdf01fSchristosits length is returned via the B<dlen> parameter. 130*1dcdf01fSchristosIf any of these parameters is NULL, the corresponding field is not returned. 131*1dcdf01fSchristosThe B<data> parameter is set to a short-term internal-copy of the associated 132*1dcdf01fSchristosdata field and must not be freed by the application. 133*1dcdf01fSchristosApplications that need long-term access to this field need to copy the content. 134*1dcdf01fSchristos 135*1dcdf01fSchristosSSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable 136*1dcdf01fSchristosoptional DANE verification features. 137*1dcdf01fSchristosSSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable 138*1dcdf01fSchristosthe same features. 139*1dcdf01fSchristosThe B<flags> argument is a bit mask of the features to enable or disable. 140*1dcdf01fSchristosThe B<flags> set for an B<SSL_CTX> context are copied to each B<SSL> handle 141*1dcdf01fSchristosassociated with that context at the time the handle is created. 142*1dcdf01fSchristosSubsequent changes in the context's B<flags> have no effect on the B<flags> set 143*1dcdf01fSchristosfor the handle. 144*1dcdf01fSchristos 145*1dcdf01fSchristosAt present, the only available option is B<DANE_FLAG_NO_DANE_EE_NAMECHECKS> 146*1dcdf01fSchristoswhich can be used to disable server name checks when authenticating via 147*1dcdf01fSchristosDANE-EE(3) TLSA records. 148*1dcdf01fSchristosFor some applications, primarily web browsers, it is not safe to disable name 149*1dcdf01fSchristoschecks due to "unknown key share" attacks, in which a malicious server can 150*1dcdf01fSchristosconvince a client that a connection to a victim server is instead a secure 151*1dcdf01fSchristosconnection to the malicious server. 152*1dcdf01fSchristosThe malicious server may then be able to violate cross-origin scripting 153*1dcdf01fSchristosrestrictions. 154*1dcdf01fSchristosThus, despite the text of RFC7671, name checks are by default enabled for 155*1dcdf01fSchristosDANE-EE(3) TLSA records, and can be disabled in applications where it is safe 156*1dcdf01fSchristosto do so. 157*1dcdf01fSchristosIn particular, SMTP and XMPP clients should set this option as SRV and MX 158*1dcdf01fSchristosrecords already make it possible for a remote domain to redirect client 159*1dcdf01fSchristosconnections to any server of its choice, and in any case SMTP and XMPP clients 160*1dcdf01fSchristosdo not execute scripts downloaded from remote servers. 161*1dcdf01fSchristos 162*1dcdf01fSchristos=head1 RETURN VALUES 163*1dcdf01fSchristos 164*1dcdf01fSchristosThe functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(), 165*1dcdf01fSchristosSSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success. 166*1dcdf01fSchristosNegative return values indicate resource problems (out of memory, etc.) in the 167*1dcdf01fSchristosSSL library, while a return value of B<0> indicates incorrect usage or invalid 168*1dcdf01fSchristosinput, such as an unsupported TLSA record certificate usage, selector or 169*1dcdf01fSchristosmatching type. 170*1dcdf01fSchristosInvalid input also includes malformed data, either a digest length that does 171*1dcdf01fSchristosnot match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form) 172*1dcdf01fSchristoscertificate or a public key that fails to parse. 173*1dcdf01fSchristos 174*1dcdf01fSchristosThe functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a 175*1dcdf01fSchristosnegative value when DANE authentication failed or was not enabled, a 176*1dcdf01fSchristosnonnegative value indicates the chain depth at which the TLSA record matched a 177*1dcdf01fSchristoschain certificate, or the depth of the top-most certificate, when the TLSA 178*1dcdf01fSchristosrecord is a full public key that is its signer. 179*1dcdf01fSchristos 180*1dcdf01fSchristosThe functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(), 181*1dcdf01fSchristosSSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect 182*1dcdf01fSchristosbefore they were called. 183*1dcdf01fSchristos 184*1dcdf01fSchristos=head1 EXAMPLES 185*1dcdf01fSchristos 186*1dcdf01fSchristosSuppose "smtp.example.com" is the MX host of the domain "example.com", and has 187*1dcdf01fSchristosDNSSEC-validated TLSA records. 188*1dcdf01fSchristosThe calls below will perform DANE authentication and arrange to match either 189*1dcdf01fSchristosthe MX hostname or the destination domain name in the SMTP server certificate. 190*1dcdf01fSchristosWildcards are supported, but must match the entire label. 191*1dcdf01fSchristosThe actual name matched in the certificate (which might be a wildcard) is 192*1dcdf01fSchristosretrieved, and must be copied by the application if it is to be retained beyond 193*1dcdf01fSchristosthe lifetime of the SSL connection. 194*1dcdf01fSchristos 195*1dcdf01fSchristos SSL_CTX *ctx; 196*1dcdf01fSchristos SSL *ssl; 197*1dcdf01fSchristos int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL; 198*1dcdf01fSchristos int num_usable = 0; 199*1dcdf01fSchristos const char *nexthop_domain = "example.com"; 200*1dcdf01fSchristos const char *dane_tlsa_domain = "smtp.example.com"; 201*1dcdf01fSchristos uint8_t usage, selector, mtype; 202*1dcdf01fSchristos 203*1dcdf01fSchristos if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) 204*1dcdf01fSchristos /* error */ 205*1dcdf01fSchristos if (SSL_CTX_dane_enable(ctx) <= 0) 206*1dcdf01fSchristos /* error */ 207*1dcdf01fSchristos if ((ssl = SSL_new(ctx)) == NULL) 208*1dcdf01fSchristos /* error */ 209*1dcdf01fSchristos if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) 210*1dcdf01fSchristos /* error */ 211*1dcdf01fSchristos 212*1dcdf01fSchristos /* 213*1dcdf01fSchristos * For many applications it is safe to skip DANE-EE(3) namechecks. Do not 214*1dcdf01fSchristos * disable the checks unless "unknown key share" attacks pose no risk for 215*1dcdf01fSchristos * your application. 216*1dcdf01fSchristos */ 217*1dcdf01fSchristos SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS); 218*1dcdf01fSchristos 219*1dcdf01fSchristos if (!SSL_add1_host(ssl, nexthop_domain)) 220*1dcdf01fSchristos /* error */ 221*1dcdf01fSchristos SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); 222*1dcdf01fSchristos 223*1dcdf01fSchristos for (... each TLSA record ...) { 224*1dcdf01fSchristos unsigned char *data; 225*1dcdf01fSchristos size_t len; 226*1dcdf01fSchristos int ret; 227*1dcdf01fSchristos 228*1dcdf01fSchristos /* set usage, selector, mtype, data, len */ 229*1dcdf01fSchristos 230*1dcdf01fSchristos /* 231*1dcdf01fSchristos * Opportunistic DANE TLS clients support only DANE-TA(2) or DANE-EE(3). 232*1dcdf01fSchristos * They treat all other certificate usages, and in particular PKIX-TA(0) 233*1dcdf01fSchristos * and PKIX-EE(1), as unusable. 234*1dcdf01fSchristos */ 235*1dcdf01fSchristos switch (usage) { 236*1dcdf01fSchristos default: 237*1dcdf01fSchristos case 0: /* PKIX-TA(0) */ 238*1dcdf01fSchristos case 1: /* PKIX-EE(1) */ 239*1dcdf01fSchristos continue; 240*1dcdf01fSchristos case 2: /* DANE-TA(2) */ 241*1dcdf01fSchristos case 3: /* DANE-EE(3) */ 242*1dcdf01fSchristos break; 243*1dcdf01fSchristos } 244*1dcdf01fSchristos 245*1dcdf01fSchristos ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len); 246*1dcdf01fSchristos /* free data as appropriate */ 247*1dcdf01fSchristos 248*1dcdf01fSchristos if (ret < 0) 249*1dcdf01fSchristos /* handle SSL library internal error */ 250*1dcdf01fSchristos else if (ret == 0) 251*1dcdf01fSchristos /* handle unusable TLSA record */ 252*1dcdf01fSchristos else 253*1dcdf01fSchristos ++num_usable; 254*1dcdf01fSchristos } 255*1dcdf01fSchristos 256*1dcdf01fSchristos /* 257*1dcdf01fSchristos * At this point, the verification mode is still the default SSL_VERIFY_NONE. 258*1dcdf01fSchristos * Opportunistic DANE clients use unauthenticated TLS when all TLSA records 259*1dcdf01fSchristos * are unusable, so continue the handshake even if authentication fails. 260*1dcdf01fSchristos */ 261*1dcdf01fSchristos if (num_usable == 0) { 262*1dcdf01fSchristos /* Log all records unusable? */ 263*1dcdf01fSchristos 264*1dcdf01fSchristos /* Optionally set verify_cb to a suitable non-NULL callback. */ 265*1dcdf01fSchristos SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb); 266*1dcdf01fSchristos } else { 267*1dcdf01fSchristos /* At least one usable record. We expect to verify the peer */ 268*1dcdf01fSchristos 269*1dcdf01fSchristos /* Optionally set verify_cb to a suitable non-NULL callback. */ 270*1dcdf01fSchristos 271*1dcdf01fSchristos /* 272*1dcdf01fSchristos * Below we elect to fail the handshake when peer verification fails. 273*1dcdf01fSchristos * Alternatively, use the permissive SSL_VERIFY_NONE verification mode, 274*1dcdf01fSchristos * complete the handshake, check the verification status, and if not 275*1dcdf01fSchristos * verified disconnect gracefully at the application layer, especially if 276*1dcdf01fSchristos * application protocol supports informing the server that authentication 277*1dcdf01fSchristos * failed. 278*1dcdf01fSchristos */ 279*1dcdf01fSchristos SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb); 280*1dcdf01fSchristos } 281*1dcdf01fSchristos 282*1dcdf01fSchristos /* 283*1dcdf01fSchristos * Load any saved session for resumption, making sure that the previous 284*1dcdf01fSchristos * session applied the same security and authentication requirements that 285*1dcdf01fSchristos * would be expected of a fresh connection. 286*1dcdf01fSchristos */ 287*1dcdf01fSchristos 288*1dcdf01fSchristos /* Perform SSL_connect() handshake and handle errors here */ 289*1dcdf01fSchristos 290*1dcdf01fSchristos if (SSL_session_reused(ssl)) { 291*1dcdf01fSchristos if (SSL_get_verify_result(ssl) == X509_V_OK) { 292*1dcdf01fSchristos /* 293*1dcdf01fSchristos * Resumed session was originally verified, this connection is 294*1dcdf01fSchristos * authenticated. 295*1dcdf01fSchristos */ 296*1dcdf01fSchristos } else { 297*1dcdf01fSchristos /* 298*1dcdf01fSchristos * Resumed session was not originally verified, this connection is not 299*1dcdf01fSchristos * authenticated. 300*1dcdf01fSchristos */ 301*1dcdf01fSchristos } 302*1dcdf01fSchristos } else if (SSL_get_verify_result(ssl) == X509_V_OK) { 303*1dcdf01fSchristos const char *peername = SSL_get0_peername(ssl); 304*1dcdf01fSchristos EVP_PKEY *mspki = NULL; 305*1dcdf01fSchristos 306*1dcdf01fSchristos int depth = SSL_get0_dane_authority(ssl, NULL, &mspki); 307*1dcdf01fSchristos if (depth >= 0) { 308*1dcdf01fSchristos (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL); 309*1dcdf01fSchristos printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype, 310*1dcdf01fSchristos (mspki != NULL) ? "TA public key verified certificate" : 311*1dcdf01fSchristos depth ? "matched TA certificate" : "matched EE certificate", 312*1dcdf01fSchristos depth); 313*1dcdf01fSchristos } 314*1dcdf01fSchristos if (peername != NULL) { 315*1dcdf01fSchristos /* Name checks were in scope and matched the peername */ 316*1dcdf01fSchristos printf("Verified peername: %s\n", peername); 317*1dcdf01fSchristos } 318*1dcdf01fSchristos } else { 319*1dcdf01fSchristos /* 320*1dcdf01fSchristos * Not authenticated, presumably all TLSA rrs unusable, but possibly a 321*1dcdf01fSchristos * callback suppressed connection termination despite the presence of 322*1dcdf01fSchristos * usable TLSA RRs none of which matched. Do whatever is appropriate for 323*1dcdf01fSchristos * fresh unauthenticated connections. 324*1dcdf01fSchristos */ 325*1dcdf01fSchristos } 326*1dcdf01fSchristos 327*1dcdf01fSchristos=head1 NOTES 328*1dcdf01fSchristos 329*1dcdf01fSchristosIt is expected that the majority of clients employing DANE TLS will be doing 330*1dcdf01fSchristos"opportunistic DANE TLS" in the sense of RFC7672 and RFC7435. 331*1dcdf01fSchristosThat is, they will use DANE authentication when DNSSEC-validated TLSA records 332*1dcdf01fSchristosare published for a given peer, and otherwise will use unauthenticated TLS or 333*1dcdf01fSchristoseven cleartext. 334*1dcdf01fSchristos 335*1dcdf01fSchristosSuch applications should generally treat any TLSA records published by the peer 336*1dcdf01fSchristoswith usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include 337*1dcdf01fSchristosthem among the TLSA records used to authenticate peer connections. 338*1dcdf01fSchristosIn addition, some TLSA records with supported usages may be "unusable" as a 339*1dcdf01fSchristosresult of invalid or unsupported parameters. 340*1dcdf01fSchristos 341*1dcdf01fSchristosWhen a peer has TLSA records, but none are "usable", an opportunistic 342*1dcdf01fSchristosapplication must avoid cleartext, but cannot authenticate the peer, 343*1dcdf01fSchristosand so should generally proceed with an unauthenticated connection. 344*1dcdf01fSchristosOpportunistic applications need to note the return value of each 345*1dcdf01fSchristoscall to SSL_dane_tlsa_add(), and if all return 0 (due to invalid 346*1dcdf01fSchristosor unsupported parameters) disable peer authentication by calling 347*1dcdf01fSchristosL<SSL_set_verify(3)> with B<mode> equal to B<SSL_VERIFY_NONE>. 348*1dcdf01fSchristos 349*1dcdf01fSchristos=head1 SEE ALSO 350*1dcdf01fSchristos 351*1dcdf01fSchristosL<SSL_new(3)>, 352*1dcdf01fSchristosL<SSL_add1_host(3)>, 353*1dcdf01fSchristosL<SSL_set_hostflags(3)>, 354*1dcdf01fSchristosL<SSL_set_tlsext_host_name(3)>, 355*1dcdf01fSchristosL<SSL_set_verify(3)>, 356*1dcdf01fSchristosL<SSL_CTX_set_cert_verify_callback(3)>, 357*1dcdf01fSchristosL<SSL_get0_verified_chain(3)>, 358*1dcdf01fSchristosL<SSL_get_peer_cert_chain(3)>, 359*1dcdf01fSchristosL<SSL_get_verify_result(3)>, 360*1dcdf01fSchristosL<SSL_connect(3)>, 361*1dcdf01fSchristosL<SSL_get0_peername(3)>, 362*1dcdf01fSchristosL<X509_verify_cert(3)>, 363*1dcdf01fSchristosL<X509_up_ref(3)>, 364*1dcdf01fSchristosL<X509_free(3)>, 365*1dcdf01fSchristosL<EVP_get_digestbyname(3)>, 366*1dcdf01fSchristosL<EVP_PKEY_up_ref(3)>, 367*1dcdf01fSchristosL<EVP_PKEY_free(3)> 368*1dcdf01fSchristos 369*1dcdf01fSchristos=head1 HISTORY 370*1dcdf01fSchristos 371*1dcdf01fSchristosThese functions were added in OpenSSL 1.1.0. 372*1dcdf01fSchristos 373*1dcdf01fSchristos=head1 COPYRIGHT 374*1dcdf01fSchristos 375*1dcdf01fSchristosCopyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. 376*1dcdf01fSchristos 377*1dcdf01fSchristosLicensed under the OpenSSL license (the "License"). You may not use 378*1dcdf01fSchristosthis file except in compliance with the License. You can obtain a copy 379*1dcdf01fSchristosin the file LICENSE in the source distribution or at 380*1dcdf01fSchristosL<https://www.openssl.org/source/license.html>. 381*1dcdf01fSchristos 382*1dcdf01fSchristos=cut 383