generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Start a new line after each sentence-ending period.

Browse Source 
This avoids explicit double spaces between sentences.

Reviewed-by: Rich Salz <rsalz@openssl.org>
This commit is contained in:
Viktor Dukhovni 2016-01-16 15:43:14 -05:00
parent 80f63d6678
commit ee84152fae
1 changed files with 96 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

194
doc/ssl/SSL_CTX_dane_enable.pod
View File

@ -27,27 +27,27 @@ TLS client
These functions implement support for DANE TLSA (RFC6698 and RFC7671) These functions implement support for DANE TLSA (RFC6698 and RFC7671)
peer authentication. peer authentication.
SSL_CTX_dane_enable() must be called first to initialize the SSL_CTX_dane_enable() must be called first to initialize the shared state
shared state required for DANE support. Individual connections required for DANE support.
associated with the context can then enable per-connection DANE Individual connections associated with the context can then enable
support as appropriate. DANE authentication is implemented in the per-connection DANE support as appropriate.
L<X509_verify_cert(3)> function, and applications that override DANE authentication is implemented in the L<X509_verify_cert(3)> function, and
L<X509_verify_cert(3)> via L<SSL_CTX_set_cert_verify_callback(3)> applications that override L<X509_verify_cert(3)> via
are responsible to authenticate the peer chain in whatever manner L<SSL_CTX_set_cert_verify_callback(3)> are responsible to authenticate the peer
they see fit. chain in whatever manner they see fit.
SSL_CTX_dane_mtype_set() may then be called zero or more times to SSL_CTX_dane_mtype_set() may then be called zero or more times to to adjust the
to adjust the supported digest algorithms. This must be done before supported digest algorithms.
any SSL handles are created for the context. This must be done before any SSL handles are created for the context.
The B<mtype> argument specifies a DANE TLSA matching type and the The B<mtype> argument specifies a DANE TLSA matching type and the B<md>
B<md> argument specifies the associated digest algorithm handle. argument specifies the associated digest algorithm handle.
The B<ord> argument specifies a strength ordinal. Algorithms with The B<ord> argument specifies a strength ordinal.
a larger strength ordinal are considered more secure. Strength Algorithms with a larger strength ordinal are considered more secure.
ordinals are used to implement RFC7671 digest algorithm agility. Strength ordinals are used to implement RFC7671 digest algorithm agility.
Specifying a B<NULL> digest algorithm for a matching type disables Specifying a B<NULL> digest algorithm for a matching type disables
support for that matching type. Matching type Full(0) cannot be support for that matching type.
modified or disabled. Matching type Full(0) cannot be modified or disabled.
By default, matching type C<SHA2-256(1)> (see RFC7218 for definitions By default, matching type C<SHA2-256(1)> (see RFC7218 for definitions
of the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()> of the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()>
@ -59,90 +59,89 @@ L<SSL_connect(3)> if (and only if) you want to enable DANE for that connection.
(The connection must be associated with a DANE-enabled SSL context). (The connection must be associated with a DANE-enabled SSL context).
The B<basedomain> argument specifies the RFC7671 TLSA base domain, The B<basedomain> argument specifies the RFC7671 TLSA base domain,
which will be the primary peer reference identifier for certificate which will be the primary peer reference identifier for certificate
name checks. Additional server names can be specified via name checks.
L<SSL_add1_host(3)>. The B<basedomain> is used as the default SNI Additional server names can be specified via L<SSL_add1_host(3)>.
hint if none has yet been specified via L<SSL_set_tlsext_host_name(3)>. The B<basedomain> is used as the default SNI hint if none has yet been
specified via L<SSL_set_tlsext_host_name(3)>.
SSL_dane_tlsa_add() may then be called one or more times, to SSL_dane_tlsa_add() may then be called one or more times, to load each of the
load each of the TLSA records that apply to the remote TLS peer. TLSA records that apply to the remote TLS peer.
(This too must be done prior to the beginning of the SSL handshake). (This too must be done prior to the beginning of the SSL handshake).
The arguments specify the fields of the TLSA record. The B<data> The arguments specify the fields of the TLSA record.
field is provided in binary (wire RDATA) form, not the hexadecimal ASCII The B<data> field is provided in binary (wire RDATA) form, not the hexadecimal
presentation form, with an explicit length passed via B<dlen>. ASCII presentation form, with an explicit length passed via B<dlen>.
A return value of 0 indicates that "unusable" TLSA records A return value of 0 indicates that "unusable" TLSA records (with invalid or
(with invalid or unsupported parameters) were provided, a negative unsupported parameters) were provided, a negative return value indicates an
return value indicates an internal error in processing the records. internal error in processing the records.
If DANE authentication is enabled, but no TLSA records are added If DANE authentication is enabled, but no TLSA records are added successfully,
successfully, authentication will fail, and the handshake may not authentication will fail, and the handshake may not complete, depending on the
complete, depending on the B<mode> argument of L<SSL_set_verify(3)> B<mode> argument of L<SSL_set_verify(3)> and any verification callback.
and any verification callback.
SSL_get0_dane_authority() can be used to get more detailed information SSL_get0_dane_authority() can be used to get more detailed information about
about the matched DANE trust-anchor after successful connection the matched DANE trust-anchor after successful connection completion.
completion. The return value is negative if DANE verification The return value is negative if DANE verification failed (or was not enabled),
failed (or was not enabled), 0 if an EE TLSA record directly matched 0 if an EE TLSA record directly matched the leaf certificate, or a positive
the leaf certificate, or a positive number indicating the depth at number indicating the depth at which a TA record matched an issuer certificate.
which a TA record matched an issuer certificate.
If the B<mcert> argument is not B<NULL> and a TLSA record matched If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain
a chain certificate, a pointer to the matching certificate is certificate, a pointer to the matching certificate is returned via B<mcert>.
returned via B<mcert>. The returned address is a short-term internal The returned address is a short-term internal reference to the certificate and
reference to the certificate and must not be freed by the application. must not be freed by the application.
Applications that want to retain access to the certificate can call Applications that want to retain access to the certificate can call
L<X509_up_ref(3)> to obtain a long-term reference which must then L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via
be freed via L<X509_free(3)> once no longer needed. L<X509_free(3)> once no longer needed.
If no TLSA records directly matched any elements of the certificate If no TLSA records directly matched any elements of the certificate chain, but
chain, but a DANE-TA(2) SPKI(1) Full(0) record provided the public a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an
key that signed an element of the chain, then that key is returned element of the chain, then that key is returned via B<mspki> argument (if not
via B<mspki> argument (if not NULL). In this case the return value NULL).
is the depth of the top-most element of the validated certificate In this case the return value is the depth of the top-most element of the
chain. As with B<mcert> this is a short-term internal reference, validated certificate chain.
and L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to As with B<mcert> this is a short-term internal reference, and
acquire and release long-term references respectively. L<EVP_PKEY_up_ref(3)> and L<EVP_PKEY_free(3)> can be used to acquire and
release long-term references respectively.
SSL_get0_dane_tlsa() can be used to retrieve the fields of the SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that
TLSA record that matched the peer certificate chain. The return matched the peer certificate chain.
value indicates the match depth or failure to match just as with The return value indicates the match depth or failure to match just as with
SSL_get0_dane_authority(). When the return value is non-negative, SSL_get0_dane_authority().
the storage pointed to by the B<usage>, B<selector>, B<mtype> and When the return value is non-negative, the storage pointed to by the B<usage>,
B<data> parameters is updated to the corresponding TLSA record B<selector>, B<mtype> and B<data> parameters is updated to the corresponding
fields. The B<data> field is in binary wire form, and is therefore TLSA record fields.
not NUL-terminated, its length is returned via the B<dlen> parameter. The B<data> field is in binary wire form, and is therefore not NUL-terminated,
If any of these parameters is NULL, the corresponding field its length is returned via the B<dlen> parameter.
is not returned. The B<data> parameter is set to a short-term If any of these parameters is NULL, the corresponding field is not returned.
internal-copy of the associated data field and must not be freed The B<data> parameter is set to a short-term internal-copy of the associated
by the application. Applications that need long-term access to data field and must not be freed by the application.
this field need to copy the content. Applications that need long-term access to this field need to copy the content.
=head1 RETURN VALUES =head1 RETURN VALUES
The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(), The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(),
SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success.
on success. Negative return values indicate resource problems (out Negative return values indicate resource problems (out of memory, etc.) in the
of memory, etc.) in the SSL library, while a return value of B<0> SSL library, while a return value of B<0> indicates incorrect usage or invalid
indicates incorrect usage or invalid input, such as an unsupported input, such as an unsupported TLSA record certificate usage, selector or
TLSA record certificate usage, selector or matching type. Invalid matching type.
input also includes malformed data, either a digest length that Invalid input also includes malformed data, either a digest length that does
does not match the digest algorithm, or a C<Full(0)> (binary ASN.1 not match the digest algorithm, or a C<Full(0)> (binary ASN.1 DER form)
DER form) certificate or a public key that fails to parse. certificate or a public key that fails to parse.
The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a
return a negative value when DANE authentication failed or was not negative value when DANE authentication failed or was not enabled, a
enabled, a non-negative value indicates the chain depth at which non-negative value indicates the chain depth at which the TLSA record matched a
the TLSA record matched a chain certificate, or the depth of the chain certificate, or the depth of the top-most certificate, when the TLSA
top-most certificate, when the TLSA record is a full public key record is a full public key that is its signer.
that is its signer.
=head1 EXAMPLE =head1 EXAMPLE
Suppose "smtp.example.com" is the MX host of the domain "example.com", Suppose "smtp.example.com" is the MX host of the domain "example.com", and has
and has DNSSEC-validated TLSA records. The calls below will perform DNSSEC-validated TLSA records.
DANE authentication and arrange to match either the MX hostname or The calls below will perform DANE authentication and arrange to match either
the destination domain name in the SMTP server certificate. Wildcards the MX hostname or the destination domain name in the SMTP server certificate.
are supported, but must match the entire label. The actual name Wildcards are supported, but must match the entire label.
matched in the certificate (which might be a wildcard) is retrieved, The actual name matched in the certificate (which might be a wildcard) is
and must be copied by the application if it is to be retained beyond retrieved, and must be copied by the application if it is to be retained beyond
the lifetime of the SSL connection. the lifetime of the SSL connection.
SSL_CTX *ctx; SSL_CTX *ctx;
@ -233,18 +232,17 @@ the lifetime of the SSL connection.
=head1 NOTES =head1 NOTES
It is expected that the majority of clients employing DANE TLS will It is expected that the majority of clients employing DANE TLS will be doing
be doing "opportunistic DANE TLS" in the sense of RFC7672 and "opportunistic DANE TLS" in the sense of RFC7672 and RFC7435.
RFC7435. That is, they will use DANE authentication when That is, they will use DANE authentication when DNSSEC-validated TLSA records
DNSSEC-validated TLSA records are published for a given peer, and are published for a given peer, and otherwise will use unauthenticated TLS or
otherwise will use unauthenticated TLS or even cleartext. even cleartext.
Such applications should generally treat any TLSA records published Such applications should generally treat any TLSA records published by the peer
by the peer with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include
and should not include them among the TLSA records used to authenticate them among the TLSA records used to authenticate peer connections.
peer connections. In addition, some TLSA records with supported In addition, some TLSA records with supported usages may be "unusable" as a
usages may be "unusable" as a result of invalid or unsupported result of invalid or unsupported parameters.
parameters.
When a peer has TLSA records, but none are "usable", an opportunistic When a peer has TLSA records, but none are "usable", an opportunistic
application must avoid cleartext, but cannot authenticate the peer, application must avoid cleartext, but cannot authenticate the peer,