secure/lib/libcrypto/man/man3/SSL_CTX_dane_enable.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_DANE_ENABLE 3"
 136 .TH SSL_CTX_DANE_ENABLE 3 "2020-03-17" "1.1.1e" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable, SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa, SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags, SSL_dane_set_flags, SSL_dane_clear_flags \&\- enable DANE TLS authentication of the remote TLS server in the local TLS client
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& int SSL_CTX_dane_enable(SSL_CTX *ctx);
 149 \& int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md,
 150 \&                            uint8_t mtype, uint8_t ord);
 151 \& int SSL_dane_enable(SSL *s, const char *basedomain);
 152 \& int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector,
 153 \&                       uint8_t mtype, unsigned const char *data, size_t dlen);
 154 \& int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki);
 155 \& int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector,
 156 \&                        uint8_t *mtype, unsigned const char **data,
 157 \&                        size_t *dlen);
 158 \& unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags);
 159 \& unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags);
 160 \& unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags);
 161 \& unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags);
 162 .Ve
 163 .SH "DESCRIPTION"
 164 .IX Header "DESCRIPTION"
 165 These functions implement support for \s-1DANE TLSA\s0 (\s-1RFC6698\s0 and \s-1RFC7671\s0)
 166 peer authentication.
 167 .PP
 168 \&\fBSSL_CTX_dane_enable()\fR must be called first to initialize the shared state
 169 required for \s-1DANE\s0 support.
 170 Individual connections associated with the context can then enable
 171 per-connection \s-1DANE\s0 support as appropriate.
 172 \&\s-1DANE\s0 authentication is implemented in the \fBX509_verify_cert\fR\|(3) function, and
 173 applications that override \fBX509_verify_cert\fR\|(3) via
 174 \&\fBSSL_CTX_set_cert_verify_callback\fR\|(3) are responsible to authenticate the peer
 175 chain in whatever manner they see fit.
 176 .PP
 177 \&\fBSSL_CTX_dane_mtype_set()\fR may then be called zero or more times to adjust the
 178 supported digest algorithms.
 179 This must be done before any \s-1SSL\s0 handles are created for the context.
 180 .PP
 181 The \fBmtype\fR argument specifies a \s-1DANE TLSA\s0 matching type and the \fBmd\fR
 182 argument specifies the associated digest algorithm handle.
 183 The \fBord\fR argument specifies a strength ordinal.
 184 Algorithms with a larger strength ordinal are considered more secure.
 185 Strength ordinals are used to implement \s-1RFC7671\s0 digest algorithm agility.
 186 Specifying a \fB\s-1NULL\s0\fR digest algorithm for a matching type disables
 187 support for that matching type.
 188 Matching type \fBFull\fR\|(0) cannot be modified or disabled.
 189 .PP
 190 By default, matching type \f(CW\*(C`SHA2\-256(1)\*(C'\fR (see \s-1RFC7218\s0 for definitions
 191 of the \s-1DANE TLSA\s0 parameter acronyms) is mapped to \f(CW\*(C`EVP_sha256()\*(C'\fR
 192 with a strength ordinal of \f(CW1\fR and matching type \f(CW\*(C`SHA2\-512(2)\*(C'\fR
 193 is mapped to \f(CW\*(C`EVP_sha512()\*(C'\fR with a strength ordinal of \f(CW2\fR.
 194 .PP
 195 \&\fBSSL_dane_enable()\fR must be called before the \s-1SSL\s0 handshake is initiated with
 196 \&\fBSSL_connect\fR\|(3) if (and only if) you want to enable \s-1DANE\s0 for that connection.
 197 (The connection must be associated with a DANE-enabled \s-1SSL\s0 context).
 198 The \fBbasedomain\fR argument specifies the \s-1RFC7671 TLSA\s0 base domain,
 199 which will be the primary peer reference identifier for certificate
 200 name checks.
 201 Additional server names can be specified via \fBSSL_add1_host\fR\|(3).
 202 The \fBbasedomain\fR is used as the default \s-1SNI\s0 hint if none has yet been
 203 specified via \fBSSL_set_tlsext_host_name\fR\|(3).
 204 .PP
 205 \&\fBSSL_dane_tlsa_add()\fR may then be called one or more times, to load each of the
 206 \&\s-1TLSA\s0 records that apply to the remote \s-1TLS\s0 peer.
 207 (This too must be done prior to the beginning of the \s-1SSL\s0 handshake).
 208 The arguments specify the fields of the \s-1TLSA\s0 record.
 209 The \fBdata\fR field is provided in binary (wire \s-1RDATA\s0) form, not the hexadecimal
 210 \&\s-1ASCII\s0 presentation form, with an explicit length passed via \fBdlen\fR.
 211 The library takes a copy of the \fBdata\fR buffer contents and the caller may
 212 free the original \fBdata\fR buffer when convenient.
 213 A return value of 0 indicates that \*(L"unusable\*(R" \s-1TLSA\s0 records (with invalid or
 214 unsupported parameters) were provided.
 215 A negative return value indicates an internal error in processing the record.
 216 .PP
 217 The caller is expected to check the return value of each \fBSSL_dane_tlsa_add()\fR
 218 call and take appropriate action if none are usable or an internal error
 219 is encountered in processing some records.
 220 .PP
 221 If no \s-1TLSA\s0 records are added successfully, \s-1DANE\s0 authentication is not enabled,
 222 and authentication will be based on any configured traditional trust-anchors;
 223 authentication success in this case does not mean that the peer was
 224 DANE-authenticated.
 225 .PP
 226 \&\fBSSL_get0_dane_authority()\fR can be used to get more detailed information about
 227 the matched \s-1DANE\s0 trust-anchor after successful connection completion.
 228 The return value is negative if \s-1DANE\s0 verification failed (or was not enabled),
 229 0 if an \s-1EE TLSA\s0 record directly matched the leaf certificate, or a positive
 230 number indicating the depth at which a \s-1TA\s0 record matched an issuer certificate.
 231 The complete verified chain can be retrieved via \fBSSL_get0_verified_chain\fR\|(3).
 232 The return value is an index into this verified chain, rather than the list of
 233 certificates sent by the peer as returned by \fBSSL_get_peer_cert_chain\fR\|(3).
 234 .PP
 235 If the \fBmcert\fR argument is not \fB\s-1NULL\s0\fR and a \s-1TLSA\s0 record matched a chain
 236 certificate, a pointer to the matching certificate is returned via \fBmcert\fR.
 237 The returned address is a short-term internal reference to the certificate and
 238 must not be freed by the application.
 239 Applications that want to retain access to the certificate can call
 240 \&\fBX509_up_ref\fR\|(3) to obtain a long-term reference which must then be freed via
 241 \&\fBX509_free\fR\|(3) once no longer needed.
 242 .PP
 243 If no \s-1TLSA\s0 records directly matched any elements of the certificate chain, but
 244 a \s-1\fBDANE\-TA\s0\fR\|(2) \s-1\fBSPKI\s0\fR\|(1) \fBFull\fR\|(0) record provided the public key that signed an
 245 element of the chain, then that key is returned via \fBmspki\fR argument (if not
 246 \&\s-1NULL\s0).
 247 In this case the return value is the depth of the top-most element of the
 248 validated certificate chain.
 249 As with \fBmcert\fR this is a short-term internal reference, and
 250 \&\fBEVP_PKEY_up_ref\fR\|(3) and \fBEVP_PKEY_free\fR\|(3) can be used to acquire and
 251 release long-term references respectively.
 252 .PP
 253 \&\fBSSL_get0_dane_tlsa()\fR can be used to retrieve the fields of the \s-1TLSA\s0 record that
 254 matched the peer certificate chain.
 255 The return value indicates the match depth or failure to match just as with
 256 \&\fBSSL_get0_dane_authority()\fR.
 257 When the return value is non-negative, the storage pointed to by the \fBusage\fR,
 258 \&\fBselector\fR, \fBmtype\fR and \fBdata\fR parameters is updated to the corresponding
 259 \&\s-1TLSA\s0 record fields.
 260 The \fBdata\fR field is in binary wire form, and is therefore not NUL-terminated,
 261 its length is returned via the \fBdlen\fR parameter.
 262 If any of these parameters is \s-1NULL,\s0 the corresponding field is not returned.
 263 The \fBdata\fR parameter is set to a short-term internal-copy of the associated
 264 data field and must not be freed by the application.
 265 Applications that need long-term access to this field need to copy the content.
 266 .PP
 267 \&\fBSSL_CTX_dane_set_flags()\fR and \fBSSL_dane_set_flags()\fR can be used to enable
 268 optional \s-1DANE\s0 verification features.
 269 \&\fBSSL_CTX_dane_clear_flags()\fR and \fBSSL_dane_clear_flags()\fR can be used to disable
 270 the same features.
 271 The \fBflags\fR argument is a bitmask of the features to enable or disable.
 272 The \fBflags\fR set for an \fB\s-1SSL_CTX\s0\fR context are copied to each \fB\s-1SSL\s0\fR handle
 273 associated with that context at the time the handle is created.
 274 Subsequent changes in the context's \fBflags\fR have no effect on the \fBflags\fR set
 275 for the handle.
 276 .PP
 277 At present, the only available option is \fB\s-1DANE_FLAG_NO_DANE_EE_NAMECHECKS\s0\fR
 278 which can be used to disable server name checks when authenticating via
 279 \&\s-1\fBDANE\-EE\s0\fR\|(3) \s-1TLSA\s0 records.
 280 For some applications, primarily web browsers, it is not safe to disable name
 281 checks due to \*(L"unknown key share\*(R" attacks, in which a malicious server can
 282 convince a client that a connection to a victim server is instead a secure
 283 connection to the malicious server.
 284 The malicious server may then be able to violate cross-origin scripting
 285 restrictions.
 286 Thus, despite the text of \s-1RFC7671,\s0 name checks are by default enabled for
 287 \&\s-1\fBDANE\-EE\s0\fR\|(3) \s-1TLSA\s0 records, and can be disabled in applications where it is safe
 288 to do so.
 289 In particular, \s-1SMTP\s0 and \s-1XMPP\s0 clients should set this option as \s-1SRV\s0 and \s-1MX\s0
 290 records already make it possible for a remote domain to redirect client
 291 connections to any server of its choice, and in any case \s-1SMTP\s0 and \s-1XMPP\s0 clients
 292 do not execute scripts downloaded from remote servers.
 293 .SH "RETURN VALUES"
 294 .IX Header "RETURN VALUES"
 295 The functions \fBSSL_CTX_dane_enable()\fR, \fBSSL_CTX_dane_mtype_set()\fR,
 296 \&\fBSSL_dane_enable()\fR and \fBSSL_dane_tlsa_add()\fR return a positive value on success.
 297 Negative return values indicate resource problems (out of memory, etc.) in the
 298 \&\s-1SSL\s0 library, while a return value of \fB0\fR indicates incorrect usage or invalid
 299 input, such as an unsupported \s-1TLSA\s0 record certificate usage, selector or
 300 matching type.
 301 Invalid input also includes malformed data, either a digest length that does
 302 not match the digest algorithm, or a \f(CWFull(0)\fR (binary \s-1ASN.1 DER\s0 form)
 303 certificate or a public key that fails to parse.
 304 .PP
 305 The functions \fBSSL_get0_dane_authority()\fR and \fBSSL_get0_dane_tlsa()\fR return a
 306 negative value when \s-1DANE\s0 authentication failed or was not enabled, a
 307 non-negative value indicates the chain depth at which the \s-1TLSA\s0 record matched a
 308 chain certificate, or the depth of the top-most certificate, when the \s-1TLSA\s0
 309 record is a full public key that is its signer.
 310 .PP
 311 The functions \fBSSL_CTX_dane_set_flags()\fR, \fBSSL_CTX_dane_clear_flags()\fR,
 312 \&\fBSSL_dane_set_flags()\fR and \fBSSL_dane_clear_flags()\fR return the \fBflags\fR in effect
 313 before they were called.
 314 .SH "EXAMPLES"
 315 .IX Header "EXAMPLES"
 316 Suppose \*(L"smtp.example.com\*(R" is the \s-1MX\s0 host of the domain \*(L"example.com\*(R", and has
 317 DNSSEC-validated \s-1TLSA\s0 records.
 318 The calls below will perform \s-1DANE\s0 authentication and arrange to match either
 319 the \s-1MX\s0 hostname or the destination domain name in the \s-1SMTP\s0 server certificate.
 320 Wildcards are supported, but must match the entire label.
 321 The actual name matched in the certificate (which might be a wildcard) is
 322 retrieved, and must be copied by the application if it is to be retained beyond
 323 the lifetime of the \s-1SSL\s0 connection.
 324 .PP
 325 .Vb 7
 326 \& SSL_CTX *ctx;
 327 \& SSL *ssl;
 328 \& int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL;
 329 \& int num_usable = 0;
 330 \& const char *nexthop_domain = "example.com";
 331 \& const char *dane_tlsa_domain = "smtp.example.com";
 332 \& uint8_t usage, selector, mtype;
 333 \&
 334 \& if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL)
 335 \&     /* error */
 336 \& if (SSL_CTX_dane_enable(ctx) <= 0)
 337 \&     /* error */
 338 \& if ((ssl = SSL_new(ctx)) == NULL)
 339 \&     /* error */
 340 \& if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0)
 341 \&     /* error */
 342 \&
 343 \& /*
 344 \&  * For many applications it is safe to skip DANE\-EE(3) namechecks.  Do not
 345 \&  * disable the checks unless "unknown key share" attacks pose no risk for
 346 \&  * your application.
 347 \&  */
 348 \& SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS);
 349 \&
 350 \& if (!SSL_add1_host(ssl, nexthop_domain))
 351 \&     /* error */
 352 \& SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
 353 \&
 354 \& for (... each TLSA record ...) {
 355 \&     unsigned char *data;
 356 \&     size_t len;
 357 \&     int ret;
 358 \&
 359 \&     /* set usage, selector, mtype, data, len */
 360 \&
 361 \&     /*
 362 \&      * Opportunistic DANE TLS clients support only DANE\-TA(2) or DANE\-EE(3).
 363 \&      * They treat all other certificate usages, and in particular PKIX\-TA(0)
 364 \&      * and PKIX\-EE(1), as unusable.
 365 \&      */
 366 \&     switch (usage) {
 367 \&     default:
 368 \&     case 0:     /* PKIX\-TA(0) */
 369 \&     case 1:     /* PKIX\-EE(1) */
 370 \&         continue;
 371 \&     case 2:     /* DANE\-TA(2) */
 372 \&     case 3:     /* DANE\-EE(3) */
 373 \&         break;
 374 \&     }
 375 \&
 376 \&     ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len);
 377 \&     /* free data as appropriate */
 378 \&
 379 \&     if (ret < 0)
 380 \&         /* handle SSL library internal error */
 381 \&     else if (ret == 0)
 382 \&         /* handle unusable TLSA record */
 383 \&     else
 384 \&         ++num_usable;
 385 \& }
 386 \&
 387 \& /*
 388 \&  * At this point, the verification mode is still the default SSL_VERIFY_NONE.
 389 \&  * Opportunistic DANE clients use unauthenticated TLS when all TLSA records
 390 \&  * are unusable, so continue the handshake even if authentication fails.
 391 \&  */
 392 \& if (num_usable == 0) {
 393 \&     /* Log all records unusable? */
 394 \&
 395 \&     /* Optionally set verify_cb to a suitable non\-NULL callback. */
 396 \&     SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb);
 397 \& } else {
 398 \&     /* At least one usable record.  We expect to verify the peer */
 399 \&
 400 \&     /* Optionally set verify_cb to a suitable non\-NULL callback. */
 401 \&
 402 \&     /*
 403 \&      * Below we elect to fail the handshake when peer verification fails.
 404 \&      * Alternatively, use the permissive SSL_VERIFY_NONE verification mode,
 405 \&      * complete the handshake, check the verification status, and if not
 406 \&      * verified disconnect gracefully at the application layer, especially if
 407 \&      * application protocol supports informing the server that authentication
 408 \&      * failed.
 409 \&      */
 410 \&     SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb);
 411 \& }
 412 \&
 413 \& /*
 414 \&  * Load any saved session for resumption, making sure that the previous
 415 \&  * session applied the same security and authentication requirements that
 416 \&  * would be expected of a fresh connection.
 417 \&  */
 418 \&
 419 \& /* Perform SSL_connect() handshake and handle errors here */
 420 \&
 421 \& if (SSL_session_reused(ssl)) {
 422 \&     if (SSL_get_verify_result(ssl) == X509_V_OK) {
 423 \&         /*
 424 \&          * Resumed session was originally verified, this connection is
 425 \&          * authenticated.
 426 \&          */
 427 \&     } else {
 428 \&         /*
 429 \&          * Resumed session was not originally verified, this connection is not
 430 \&          * authenticated.
 431 \&          */
 432 \&     }
 433 \& } else if (SSL_get_verify_result(ssl) == X509_V_OK) {
 434 \&     const char *peername = SSL_get0_peername(ssl);
 435 \&     EVP_PKEY *mspki = NULL;
 436 \&
 437 \&     int depth = SSL_get0_dane_authority(ssl, NULL, &mspki);
 438 \&     if (depth >= 0) {
 439 \&         (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL);
 440 \&         printf("DANE TLSA %d %d %d %s at depth %d\en", usage, selector, mtype,
 441 \&                (mspki != NULL) ? "TA public key verified certificate" :
 442 \&                depth ? "matched TA certificate" : "matched EE certificate",
 443 \&                depth);
 444 \&     }
 445 \&     if (peername != NULL) {
 446 \&         /* Name checks were in scope and matched the peername */
 447 \&         printf("Verified peername: %s\en", peername);
 448 \&     }
 449 \& } else {
 450 \&     /*
 451 \&      * Not authenticated, presumably all TLSA rrs unusable, but possibly a
 452 \&      * callback suppressed connection termination despite the presence of
 453 \&      * usable TLSA RRs none of which matched.  Do whatever is appropriate for
 454 \&      * fresh unauthenticated connections.
 455 \&      */
 456 \& }
 457 .Ve
 458 .SH "NOTES"
 459 .IX Header "NOTES"
 460 It is expected that the majority of clients employing \s-1DANE TLS\s0 will be doing
 461 \&\*(L"opportunistic \s-1DANE TLS\*(R"\s0 in the sense of \s-1RFC7672\s0 and \s-1RFC7435.\s0
 462 That is, they will use \s-1DANE\s0 authentication when DNSSEC-validated \s-1TLSA\s0 records
 463 are published for a given peer, and otherwise will use unauthenticated \s-1TLS\s0 or
 464 even cleartext.
 465 .PP
 466 Such applications should generally treat any \s-1TLSA\s0 records published by the peer
 467 with usages \s-1\fBPKIX\-TA\s0\fR\|(0) and \s-1\fBPKIX\-EE\s0\fR\|(1) as \*(L"unusable\*(R", and should not include
 468 them among the \s-1TLSA\s0 records used to authenticate peer connections.
 469 In addition, some \s-1TLSA\s0 records with supported usages may be \*(L"unusable\*(R" as a
 470 result of invalid or unsupported parameters.
 471 .PP
 472 When a peer has \s-1TLSA\s0 records, but none are \*(L"usable\*(R", an opportunistic
 473 application must avoid cleartext, but cannot authenticate the peer,
 474 and so should generally proceed with an unauthenticated connection.
 475 Opportunistic applications need to note the return value of each
 476 call to \fBSSL_dane_tlsa_add()\fR, and if all return 0 (due to invalid
 477 or unsupported parameters) disable peer authentication by calling
 478 \&\fBSSL_set_verify\fR\|(3) with \fBmode\fR equal to \fB\s-1SSL_VERIFY_NONE\s0\fR.
 479 .SH "SEE ALSO"
 480 .IX Header "SEE ALSO"
 481 \&\fBSSL_new\fR\|(3),
 482 \&\fBSSL_add1_host\fR\|(3),
 483 \&\fBSSL_set_hostflags\fR\|(3),
 484 \&\fBSSL_set_tlsext_host_name\fR\|(3),
 485 \&\fBSSL_set_verify\fR\|(3),
 486 \&\fBSSL_CTX_set_cert_verify_callback\fR\|(3),
 487 \&\fBSSL_get0_verified_chain\fR\|(3),
 488 \&\fBSSL_get_peer_cert_chain\fR\|(3),
 489 \&\fBSSL_get_verify_result\fR\|(3),
 490 \&\fBSSL_connect\fR\|(3),
 491 \&\fBSSL_get0_peername\fR\|(3),
 492 \&\fBX509_verify_cert\fR\|(3),
 493 \&\fBX509_up_ref\fR\|(3),
 494 \&\fBX509_free\fR\|(3),
 495 \&\fBEVP_get_digestbyname\fR\|(3),
 496 \&\fBEVP_PKEY_up_ref\fR\|(3),
 497 \&\fBEVP_PKEY_free\fR\|(3)
 498 .SH "HISTORY"
 499 .IX Header "HISTORY"
 500 These functions were added in OpenSSL 1.1.0.
 501 .SH "COPYRIGHT"
 502 .IX Header "COPYRIGHT"
 503 Copyright 2016\-2019 The OpenSSL Project Authors. All Rights Reserved.
 504 .PP
 505 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 506 this file except in compliance with the License.  You can obtain a copy
 507 in the file \s-1LICENSE\s0 in the source distribution or at
 508 <https://www.openssl.org/source/license.html>.