509 lines
22 KiB
Groff
509 lines
22 KiB
Groff
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
. ds C`
|
|
. ds C'
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is >0, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.\"
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
|
.de IX
|
|
..
|
|
.nr rF 0
|
|
.if \n(.g .if rF .nr rF 1
|
|
.if (\n(rF:(\n(.g==0)) \{\
|
|
. if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. if !\nF==2 \{\
|
|
. nr % 0
|
|
. nr F 2
|
|
. \}
|
|
. \}
|
|
.\}
|
|
.rr rF
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "SSL_CTX_DANE_ENABLE 3"
|
|
.TH SSL_CTX_DANE_ENABLE 3 "2020-12-08" "1.1.1i" "OpenSSL"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
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
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/ssl.h>
|
|
\&
|
|
\& int SSL_CTX_dane_enable(SSL_CTX *ctx);
|
|
\& int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md,
|
|
\& uint8_t mtype, uint8_t ord);
|
|
\& int SSL_dane_enable(SSL *s, const char *basedomain);
|
|
\& int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector,
|
|
\& uint8_t mtype, unsigned const char *data, size_t dlen);
|
|
\& int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki);
|
|
\& int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector,
|
|
\& uint8_t *mtype, unsigned const char **data,
|
|
\& size_t *dlen);
|
|
\& unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags);
|
|
\& unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags);
|
|
\& unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags);
|
|
\& unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
These functions implement support for \s-1DANE TLSA\s0 (\s-1RFC6698\s0 and \s-1RFC7671\s0)
|
|
peer authentication.
|
|
.PP
|
|
\&\fBSSL_CTX_dane_enable()\fR must be called first to initialize the shared state
|
|
required for \s-1DANE\s0 support.
|
|
Individual connections associated with the context can then enable
|
|
per-connection \s-1DANE\s0 support as appropriate.
|
|
\&\s-1DANE\s0 authentication is implemented in the \fBX509_verify_cert\fR\|(3) function, and
|
|
applications that override \fBX509_verify_cert\fR\|(3) via
|
|
\&\fBSSL_CTX_set_cert_verify_callback\fR\|(3) are responsible to authenticate the peer
|
|
chain in whatever manner they see fit.
|
|
.PP
|
|
\&\fBSSL_CTX_dane_mtype_set()\fR may then be called zero or more times to adjust the
|
|
supported digest algorithms.
|
|
This must be done before any \s-1SSL\s0 handles are created for the context.
|
|
.PP
|
|
The \fBmtype\fR argument specifies a \s-1DANE TLSA\s0 matching type and the \fBmd\fR
|
|
argument specifies the associated digest algorithm handle.
|
|
The \fBord\fR argument specifies a strength ordinal.
|
|
Algorithms with a larger strength ordinal are considered more secure.
|
|
Strength ordinals are used to implement \s-1RFC7671\s0 digest algorithm agility.
|
|
Specifying a \fB\s-1NULL\s0\fR digest algorithm for a matching type disables
|
|
support for that matching type.
|
|
Matching type \fBFull\fR\|(0) cannot be modified or disabled.
|
|
.PP
|
|
By default, matching type \f(CW\*(C`SHA2\-256(1)\*(C'\fR (see \s-1RFC7218\s0 for definitions
|
|
of the \s-1DANE TLSA\s0 parameter acronyms) is mapped to \f(CW\*(C`EVP_sha256()\*(C'\fR
|
|
with a strength ordinal of \f(CW1\fR and matching type \f(CW\*(C`SHA2\-512(2)\*(C'\fR
|
|
is mapped to \f(CW\*(C`EVP_sha512()\*(C'\fR with a strength ordinal of \f(CW2\fR.
|
|
.PP
|
|
\&\fBSSL_dane_enable()\fR must be called before the \s-1SSL\s0 handshake is initiated with
|
|
\&\fBSSL_connect\fR\|(3) if (and only if) you want to enable \s-1DANE\s0 for that connection.
|
|
(The connection must be associated with a DANE-enabled \s-1SSL\s0 context).
|
|
The \fBbasedomain\fR argument specifies the \s-1RFC7671 TLSA\s0 base domain,
|
|
which will be the primary peer reference identifier for certificate
|
|
name checks.
|
|
Additional server names can be specified via \fBSSL_add1_host\fR\|(3).
|
|
The \fBbasedomain\fR is used as the default \s-1SNI\s0 hint if none has yet been
|
|
specified via \fBSSL_set_tlsext_host_name\fR\|(3).
|
|
.PP
|
|
\&\fBSSL_dane_tlsa_add()\fR may then be called one or more times, to load each of the
|
|
\&\s-1TLSA\s0 records that apply to the remote \s-1TLS\s0 peer.
|
|
(This too must be done prior to the beginning of the \s-1SSL\s0 handshake).
|
|
The arguments specify the fields of the \s-1TLSA\s0 record.
|
|
The \fBdata\fR field is provided in binary (wire \s-1RDATA\s0) form, not the hexadecimal
|
|
\&\s-1ASCII\s0 presentation form, with an explicit length passed via \fBdlen\fR.
|
|
The library takes a copy of the \fBdata\fR buffer contents and the caller may
|
|
free the original \fBdata\fR buffer when convenient.
|
|
A return value of 0 indicates that \*(L"unusable\*(R" \s-1TLSA\s0 records (with invalid or
|
|
unsupported parameters) were provided.
|
|
A negative return value indicates an internal error in processing the record.
|
|
.PP
|
|
The caller is expected to check the return value of each \fBSSL_dane_tlsa_add()\fR
|
|
call and take appropriate action if none are usable or an internal error
|
|
is encountered in processing some records.
|
|
.PP
|
|
If no \s-1TLSA\s0 records are added successfully, \s-1DANE\s0 authentication is not enabled,
|
|
and authentication will be based on any configured traditional trust-anchors;
|
|
authentication success in this case does not mean that the peer was
|
|
DANE-authenticated.
|
|
.PP
|
|
\&\fBSSL_get0_dane_authority()\fR can be used to get more detailed information about
|
|
the matched \s-1DANE\s0 trust-anchor after successful connection completion.
|
|
The return value is negative if \s-1DANE\s0 verification failed (or was not enabled),
|
|
0 if an \s-1EE TLSA\s0 record directly matched the leaf certificate, or a positive
|
|
number indicating the depth at which a \s-1TA\s0 record matched an issuer certificate.
|
|
The complete verified chain can be retrieved via \fBSSL_get0_verified_chain\fR\|(3).
|
|
The return value is an index into this verified chain, rather than the list of
|
|
certificates sent by the peer as returned by \fBSSL_get_peer_cert_chain\fR\|(3).
|
|
.PP
|
|
If the \fBmcert\fR argument is not \fB\s-1NULL\s0\fR and a \s-1TLSA\s0 record matched a chain
|
|
certificate, a pointer to the matching certificate is returned via \fBmcert\fR.
|
|
The returned address is a short-term internal reference to the certificate and
|
|
must not be freed by the application.
|
|
Applications that want to retain access to the certificate can call
|
|
\&\fBX509_up_ref\fR\|(3) to obtain a long-term reference which must then be freed via
|
|
\&\fBX509_free\fR\|(3) once no longer needed.
|
|
.PP
|
|
If no \s-1TLSA\s0 records directly matched any elements of the certificate chain, but
|
|
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
|
|
element of the chain, then that key is returned via \fBmspki\fR argument (if not
|
|
\&\s-1NULL\s0).
|
|
In this case the return value is the depth of the top-most element of the
|
|
validated certificate chain.
|
|
As with \fBmcert\fR this is a short-term internal reference, and
|
|
\&\fBEVP_PKEY_up_ref\fR\|(3) and \fBEVP_PKEY_free\fR\|(3) can be used to acquire and
|
|
release long-term references respectively.
|
|
.PP
|
|
\&\fBSSL_get0_dane_tlsa()\fR can be used to retrieve the fields of the \s-1TLSA\s0 record that
|
|
matched the peer certificate chain.
|
|
The return value indicates the match depth or failure to match just as with
|
|
\&\fBSSL_get0_dane_authority()\fR.
|
|
When the return value is nonnegative, the storage pointed to by the \fBusage\fR,
|
|
\&\fBselector\fR, \fBmtype\fR and \fBdata\fR parameters is updated to the corresponding
|
|
\&\s-1TLSA\s0 record fields.
|
|
The \fBdata\fR field is in binary wire form, and is therefore not NUL-terminated,
|
|
its length is returned via the \fBdlen\fR parameter.
|
|
If any of these parameters is \s-1NULL,\s0 the corresponding field is not returned.
|
|
The \fBdata\fR parameter is set to a short-term internal-copy of the associated
|
|
data field and must not be freed by the application.
|
|
Applications that need long-term access to this field need to copy the content.
|
|
.PP
|
|
\&\fBSSL_CTX_dane_set_flags()\fR and \fBSSL_dane_set_flags()\fR can be used to enable
|
|
optional \s-1DANE\s0 verification features.
|
|
\&\fBSSL_CTX_dane_clear_flags()\fR and \fBSSL_dane_clear_flags()\fR can be used to disable
|
|
the same features.
|
|
The \fBflags\fR argument is a bit mask of the features to enable or disable.
|
|
The \fBflags\fR set for an \fB\s-1SSL_CTX\s0\fR context are copied to each \fB\s-1SSL\s0\fR handle
|
|
associated with that context at the time the handle is created.
|
|
Subsequent changes in the context's \fBflags\fR have no effect on the \fBflags\fR set
|
|
for the handle.
|
|
.PP
|
|
At present, the only available option is \fB\s-1DANE_FLAG_NO_DANE_EE_NAMECHECKS\s0\fR
|
|
which can be used to disable server name checks when authenticating via
|
|
\&\s-1\fBDANE\-EE\s0\fR\|(3) \s-1TLSA\s0 records.
|
|
For some applications, primarily web browsers, it is not safe to disable name
|
|
checks due to \*(L"unknown key share\*(R" attacks, in which a malicious server can
|
|
convince a client that a connection to a victim server is instead a secure
|
|
connection to the malicious server.
|
|
The malicious server may then be able to violate cross-origin scripting
|
|
restrictions.
|
|
Thus, despite the text of \s-1RFC7671,\s0 name checks are by default enabled for
|
|
\&\s-1\fBDANE\-EE\s0\fR\|(3) \s-1TLSA\s0 records, and can be disabled in applications where it is safe
|
|
to do so.
|
|
In particular, \s-1SMTP\s0 and \s-1XMPP\s0 clients should set this option as \s-1SRV\s0 and \s-1MX\s0
|
|
records already make it possible for a remote domain to redirect client
|
|
connections to any server of its choice, and in any case \s-1SMTP\s0 and \s-1XMPP\s0 clients
|
|
do not execute scripts downloaded from remote servers.
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
The functions \fBSSL_CTX_dane_enable()\fR, \fBSSL_CTX_dane_mtype_set()\fR,
|
|
\&\fBSSL_dane_enable()\fR and \fBSSL_dane_tlsa_add()\fR return a positive value on success.
|
|
Negative return values indicate resource problems (out of memory, etc.) in the
|
|
\&\s-1SSL\s0 library, while a return value of \fB0\fR indicates incorrect usage or invalid
|
|
input, such as an unsupported \s-1TLSA\s0 record certificate usage, selector or
|
|
matching type.
|
|
Invalid input also includes malformed data, either a digest length that does
|
|
not match the digest algorithm, or a \f(CWFull(0)\fR (binary \s-1ASN.1 DER\s0 form)
|
|
certificate or a public key that fails to parse.
|
|
.PP
|
|
The functions \fBSSL_get0_dane_authority()\fR and \fBSSL_get0_dane_tlsa()\fR return a
|
|
negative value when \s-1DANE\s0 authentication failed or was not enabled, a
|
|
nonnegative value indicates the chain depth at which the \s-1TLSA\s0 record matched a
|
|
chain certificate, or the depth of the top-most certificate, when the \s-1TLSA\s0
|
|
record is a full public key that is its signer.
|
|
.PP
|
|
The functions \fBSSL_CTX_dane_set_flags()\fR, \fBSSL_CTX_dane_clear_flags()\fR,
|
|
\&\fBSSL_dane_set_flags()\fR and \fBSSL_dane_clear_flags()\fR return the \fBflags\fR in effect
|
|
before they were called.
|
|
.SH "EXAMPLES"
|
|
.IX Header "EXAMPLES"
|
|
Suppose \*(L"smtp.example.com\*(R" is the \s-1MX\s0 host of the domain \*(L"example.com\*(R", and has
|
|
DNSSEC-validated \s-1TLSA\s0 records.
|
|
The calls below will perform \s-1DANE\s0 authentication and arrange to match either
|
|
the \s-1MX\s0 hostname or the destination domain name in the \s-1SMTP\s0 server certificate.
|
|
Wildcards are supported, but must match the entire label.
|
|
The actual name matched in the certificate (which might be a wildcard) is
|
|
retrieved, and must be copied by the application if it is to be retained beyond
|
|
the lifetime of the \s-1SSL\s0 connection.
|
|
.PP
|
|
.Vb 7
|
|
\& SSL_CTX *ctx;
|
|
\& SSL *ssl;
|
|
\& int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL;
|
|
\& int num_usable = 0;
|
|
\& const char *nexthop_domain = "example.com";
|
|
\& const char *dane_tlsa_domain = "smtp.example.com";
|
|
\& uint8_t usage, selector, mtype;
|
|
\&
|
|
\& if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL)
|
|
\& /* error */
|
|
\& if (SSL_CTX_dane_enable(ctx) <= 0)
|
|
\& /* error */
|
|
\& if ((ssl = SSL_new(ctx)) == NULL)
|
|
\& /* error */
|
|
\& if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0)
|
|
\& /* error */
|
|
\&
|
|
\& /*
|
|
\& * For many applications it is safe to skip DANE\-EE(3) namechecks. Do not
|
|
\& * disable the checks unless "unknown key share" attacks pose no risk for
|
|
\& * your application.
|
|
\& */
|
|
\& SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS);
|
|
\&
|
|
\& if (!SSL_add1_host(ssl, nexthop_domain))
|
|
\& /* error */
|
|
\& SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
|
|
\&
|
|
\& for (... each TLSA record ...) {
|
|
\& unsigned char *data;
|
|
\& size_t len;
|
|
\& int ret;
|
|
\&
|
|
\& /* set usage, selector, mtype, data, len */
|
|
\&
|
|
\& /*
|
|
\& * Opportunistic DANE TLS clients support only DANE\-TA(2) or DANE\-EE(3).
|
|
\& * They treat all other certificate usages, and in particular PKIX\-TA(0)
|
|
\& * and PKIX\-EE(1), as unusable.
|
|
\& */
|
|
\& switch (usage) {
|
|
\& default:
|
|
\& case 0: /* PKIX\-TA(0) */
|
|
\& case 1: /* PKIX\-EE(1) */
|
|
\& continue;
|
|
\& case 2: /* DANE\-TA(2) */
|
|
\& case 3: /* DANE\-EE(3) */
|
|
\& break;
|
|
\& }
|
|
\&
|
|
\& ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len);
|
|
\& /* free data as appropriate */
|
|
\&
|
|
\& if (ret < 0)
|
|
\& /* handle SSL library internal error */
|
|
\& else if (ret == 0)
|
|
\& /* handle unusable TLSA record */
|
|
\& else
|
|
\& ++num_usable;
|
|
\& }
|
|
\&
|
|
\& /*
|
|
\& * At this point, the verification mode is still the default SSL_VERIFY_NONE.
|
|
\& * Opportunistic DANE clients use unauthenticated TLS when all TLSA records
|
|
\& * are unusable, so continue the handshake even if authentication fails.
|
|
\& */
|
|
\& if (num_usable == 0) {
|
|
\& /* Log all records unusable? */
|
|
\&
|
|
\& /* Optionally set verify_cb to a suitable non\-NULL callback. */
|
|
\& SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb);
|
|
\& } else {
|
|
\& /* At least one usable record. We expect to verify the peer */
|
|
\&
|
|
\& /* Optionally set verify_cb to a suitable non\-NULL callback. */
|
|
\&
|
|
\& /*
|
|
\& * Below we elect to fail the handshake when peer verification fails.
|
|
\& * Alternatively, use the permissive SSL_VERIFY_NONE verification mode,
|
|
\& * complete the handshake, check the verification status, and if not
|
|
\& * verified disconnect gracefully at the application layer, especially if
|
|
\& * application protocol supports informing the server that authentication
|
|
\& * failed.
|
|
\& */
|
|
\& SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb);
|
|
\& }
|
|
\&
|
|
\& /*
|
|
\& * Load any saved session for resumption, making sure that the previous
|
|
\& * session applied the same security and authentication requirements that
|
|
\& * would be expected of a fresh connection.
|
|
\& */
|
|
\&
|
|
\& /* Perform SSL_connect() handshake and handle errors here */
|
|
\&
|
|
\& if (SSL_session_reused(ssl)) {
|
|
\& if (SSL_get_verify_result(ssl) == X509_V_OK) {
|
|
\& /*
|
|
\& * Resumed session was originally verified, this connection is
|
|
\& * authenticated.
|
|
\& */
|
|
\& } else {
|
|
\& /*
|
|
\& * Resumed session was not originally verified, this connection is not
|
|
\& * authenticated.
|
|
\& */
|
|
\& }
|
|
\& } else if (SSL_get_verify_result(ssl) == X509_V_OK) {
|
|
\& const char *peername = SSL_get0_peername(ssl);
|
|
\& EVP_PKEY *mspki = NULL;
|
|
\&
|
|
\& int depth = SSL_get0_dane_authority(ssl, NULL, &mspki);
|
|
\& if (depth >= 0) {
|
|
\& (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL);
|
|
\& printf("DANE TLSA %d %d %d %s at depth %d\en", usage, selector, mtype,
|
|
\& (mspki != NULL) ? "TA public key verified certificate" :
|
|
\& depth ? "matched TA certificate" : "matched EE certificate",
|
|
\& depth);
|
|
\& }
|
|
\& if (peername != NULL) {
|
|
\& /* Name checks were in scope and matched the peername */
|
|
\& printf("Verified peername: %s\en", peername);
|
|
\& }
|
|
\& } else {
|
|
\& /*
|
|
\& * Not authenticated, presumably all TLSA rrs unusable, but possibly a
|
|
\& * callback suppressed connection termination despite the presence of
|
|
\& * usable TLSA RRs none of which matched. Do whatever is appropriate for
|
|
\& * fresh unauthenticated connections.
|
|
\& */
|
|
\& }
|
|
.Ve
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
It is expected that the majority of clients employing \s-1DANE TLS\s0 will be doing
|
|
\&\*(L"opportunistic \s-1DANE TLS\*(R"\s0 in the sense of \s-1RFC7672\s0 and \s-1RFC7435.\s0
|
|
That is, they will use \s-1DANE\s0 authentication when DNSSEC-validated \s-1TLSA\s0 records
|
|
are published for a given peer, and otherwise will use unauthenticated \s-1TLS\s0 or
|
|
even cleartext.
|
|
.PP
|
|
Such applications should generally treat any \s-1TLSA\s0 records published by the peer
|
|
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
|
|
them among the \s-1TLSA\s0 records used to authenticate peer connections.
|
|
In addition, some \s-1TLSA\s0 records with supported usages may be \*(L"unusable\*(R" as a
|
|
result of invalid or unsupported parameters.
|
|
.PP
|
|
When a peer has \s-1TLSA\s0 records, but none are \*(L"usable\*(R", an opportunistic
|
|
application must avoid cleartext, but cannot authenticate the peer,
|
|
and so should generally proceed with an unauthenticated connection.
|
|
Opportunistic applications need to note the return value of each
|
|
call to \fBSSL_dane_tlsa_add()\fR, and if all return 0 (due to invalid
|
|
or unsupported parameters) disable peer authentication by calling
|
|
\&\fBSSL_set_verify\fR\|(3) with \fBmode\fR equal to \fB\s-1SSL_VERIFY_NONE\s0\fR.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fBSSL_new\fR\|(3),
|
|
\&\fBSSL_add1_host\fR\|(3),
|
|
\&\fBSSL_set_hostflags\fR\|(3),
|
|
\&\fBSSL_set_tlsext_host_name\fR\|(3),
|
|
\&\fBSSL_set_verify\fR\|(3),
|
|
\&\fBSSL_CTX_set_cert_verify_callback\fR\|(3),
|
|
\&\fBSSL_get0_verified_chain\fR\|(3),
|
|
\&\fBSSL_get_peer_cert_chain\fR\|(3),
|
|
\&\fBSSL_get_verify_result\fR\|(3),
|
|
\&\fBSSL_connect\fR\|(3),
|
|
\&\fBSSL_get0_peername\fR\|(3),
|
|
\&\fBX509_verify_cert\fR\|(3),
|
|
\&\fBX509_up_ref\fR\|(3),
|
|
\&\fBX509_free\fR\|(3),
|
|
\&\fBEVP_get_digestbyname\fR\|(3),
|
|
\&\fBEVP_PKEY_up_ref\fR\|(3),
|
|
\&\fBEVP_PKEY_free\fR\|(3)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
These functions were added in OpenSSL 1.1.0.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2016\-2020 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
|
<https://www.openssl.org/source/license.html>.
|