secure/lib/libcrypto/man/SSL_CTX_dane_enable.3

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