[openssl-commits] [openssl] master update
Viktor Dukhovni
viktor at openssl.org
Sat Jan 16 22:17:34 UTC 2016
The branch master has been updated
via ee84152fae23f962c5f81ca45ca27a271c989152 (commit)
via 80f63d667824867b325371f0e7ede0315d82bd79 (commit)
from 8d887efa2ebd8ceff261514efbd6460c262172b3 (commit)
- Log -----------------------------------------------------------------
commit ee84152fae23f962c5f81ca45ca27a271c989152
Author: Viktor Dukhovni <openssl-users at dukhovni.org>
Date: Sat Jan 16 15:43:14 2016 -0500
Start a new line after each sentence-ending period.
This avoids explicit double spaces between sentences.
Reviewed-by: Rich Salz <rsalz at openssl.org>
commit 80f63d667824867b325371f0e7ede0315d82bd79
Author: Viktor Dukhovni <openssl-users at dukhovni.org>
Date: Sat Jan 16 15:29:44 2016 -0500
Make SSL_dane_enable() requirement more clear.
Also s/s/ssl/ as appropriate in the code example.
Suggested by Claus Assmann.
Reviewed-by: Rich Salz <rsalz at openssl.org>
-----------------------------------------------------------------------
Summary of changes:
doc/ssl/SSL_CTX_dane_enable.pod | 218 ++++++++++++++++++++--------------------
1 file changed, 108 insertions(+), 110 deletions(-)
diff --git a/doc/ssl/SSL_CTX_dane_enable.pod b/doc/ssl/SSL_CTX_dane_enable.pod
index c3c203e..a9c24e1 100644
--- a/doc/ssl/SSL_CTX_dane_enable.pod
+++ b/doc/ssl/SSL_CTX_dane_enable.pod
@@ -27,122 +27,121 @@ TLS client
These functions implement support for DANE TLSA (RFC6698 and RFC7671)
peer authentication.
-SSL_CTX_dane_enable() must be called first to initialize the
-shared state required for DANE support. Individual connections
-associated with the context can then enable per-connection DANE
-support as appropriate. DANE authentication is implemented in the
-L<X509_verify_cert(3)> function, and applications that override
-L<X509_verify_cert(3)> via L<SSL_CTX_set_cert_verify_callback(3)>
-are responsible to authenticate the peer chain in whatever manner
-they see fit.
-
-SSL_CTX_dane_mtype_set() may then be called zero or more times to
-to adjust the supported digest algorithms. 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
-B<md> argument specifies the associated digest algorithm handle.
-The B<ord> argument specifies a strength ordinal. Algorithms with
-a larger strength ordinal are considered more secure. Strength
-ordinals are used to implement RFC7671 digest algorithm agility.
+SSL_CTX_dane_enable() must be called first to initialize the shared state
+required for DANE support.
+Individual connections associated with the context can then enable
+per-connection DANE support as appropriate.
+DANE authentication is implemented in the L<X509_verify_cert(3)> function, and
+applications that override L<X509_verify_cert(3)> via
+L<SSL_CTX_set_cert_verify_callback(3)> are responsible to authenticate the peer
+chain in whatever manner they see fit.
+
+SSL_CTX_dane_mtype_set() may then be called zero or more times to to adjust the
+supported digest algorithms.
+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 B<md>
+argument specifies the associated digest algorithm handle.
+The B<ord> argument specifies a strength ordinal.
+Algorithms with a larger strength ordinal are considered more secure.
+Strength ordinals are used to implement RFC7671 digest algorithm agility.
Specifying a B<NULL> digest algorithm for a matching type disables
-support for that matching type. Matching type Full(0) cannot be
-modified or disabled.
+support for that matching type.
+Matching type Full(0) cannot be modified or disabled.
By default, matching type C<SHA2-256(1)> (see RFC7218 for definitions
of the DANE TLSA parameter acronyms) is mapped to C<EVP_sha256()>
with a strength ordinal of C<1> and matching type C<SHA2-512(2)>
is mapped to C<EVP_sha512()> with a strength ordinal of C<2>.
-SSL_dane_enable() may be called before the SSL handshake is
-initiated with L<SSL_connect(3)> to enable DANE for that connection.
+SSL_dane_enable() must be called before the SSL handshake is initiated with
+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 B<basedomain> argument specifies the RFC7671 TLSA base domain,
which will be the primary peer reference identifier for certificate
-name checks. Additional server names can be specified via
-L<SSL_add1_host(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)>.
+name checks.
+Additional server names can be specified via L<SSL_add1_host(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
-load each of the TLSA records that apply to the remote TLS peer.
+SSL_dane_tlsa_add() may then be called one or more times, to load each of the
+TLSA records that apply to the remote TLS peer.
(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>
-field is provided in binary (wire RDATA) form, not the hexadecimal ASCII
-presentation form, with an explicit length passed via B<dlen>.
-A return value of 0 indicates that "unusable" TLSA records
-(with invalid or unsupported parameters) were provided, a negative
-return value indicates an internal error in processing the records.
-If DANE authentication is enabled, but no TLSA records are added
-successfully, authentication will fail, and the handshake may not
-complete, depending on the B<mode> argument of L<SSL_set_verify(3)>
-and any verification callback.
-
-SSL_get0_dane_authority() can be used to get more detailed information
-about the matched DANE trust-anchor after successful connection
-completion. The return value is negative if DANE verification
-failed (or was not enabled), 0 if an EE TLSA record directly matched
-the leaf certificate, or a positive number indicating the depth at
-which a TA record matched an issuer certificate.
-
-If the B<mcert> argument is not B<NULL> and a TLSA record matched
-a chain certificate, a pointer to the matching certificate is
-returned via B<mcert>. The returned address is a short-term internal
-reference to the certificate and must not be freed by the application.
+The arguments specify the fields of the TLSA record.
+The B<data> field is provided in binary (wire RDATA) form, not the hexadecimal
+ASCII presentation form, with an explicit length passed via B<dlen>.
+A return value of 0 indicates that "unusable" TLSA records (with invalid or
+unsupported parameters) were provided, a negative return value indicates an
+internal error in processing the records.
+If DANE authentication is enabled, but no TLSA records are added successfully,
+authentication will fail, and the handshake may not complete, depending on the
+B<mode> argument of L<SSL_set_verify(3)> and any verification callback.
+
+SSL_get0_dane_authority() can be used to get more detailed information about
+the matched DANE trust-anchor after successful connection completion.
+The return value is negative if DANE verification failed (or was not enabled),
+0 if an EE TLSA record directly matched the leaf certificate, or a positive
+number indicating the depth at which a TA record matched an issuer certificate.
+
+If the B<mcert> argument is not B<NULL> and a TLSA record matched a chain
+certificate, a pointer to the matching certificate is returned via B<mcert>.
+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
-L<X509_up_ref(3)> to obtain a long-term reference which must then
-be freed via L<X509_free(3)> once no longer needed.
-
-If no TLSA records directly matched any elements of the certificate
-chain, but a DANE-TA(2) SPKI(1) Full(0) record provided the public
-key that signed an element of the chain, then that key is returned
-via B<mspki> argument (if not NULL). In this case the return value
-is the depth of the top-most element of the validated certificate
-chain. As with B<mcert> this is a short-term internal reference,
-and 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
-TLSA record that matched the peer certificate chain. 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,
-the storage pointed to by the B<usage>, B<selector>, B<mtype> and
-B<data> parameters is updated to the corresponding TLSA record
-fields. The B<data> field is in binary wire form, and is therefore
-not NUL-terminated, its length is returned via the B<dlen> parameter.
-If any of these parameters is NULL, the corresponding field
-is not returned. The B<data> 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.
+L<X509_up_ref(3)> to obtain a long-term reference which must then be freed via
+L<X509_free(3)> once no longer needed.
+
+If no TLSA records directly matched any elements of the certificate chain, but
+a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an
+element of the chain, then that key is returned via B<mspki> argument (if not
+NULL).
+In this case the return value is the depth of the top-most element of the
+validated certificate chain.
+As with B<mcert> this is a short-term internal reference, and
+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 TLSA record that
+matched the peer certificate chain.
+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, the storage pointed to by the B<usage>,
+B<selector>, B<mtype> and B<data> parameters is updated to the corresponding
+TLSA record fields.
+The B<data> field is in binary wire form, and is therefore not NUL-terminated,
+its length is returned via the B<dlen> parameter.
+If any of these parameters is NULL, the corresponding field is not returned.
+The B<data> 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.
=head1 RETURN VALUES
The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(),
-SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value
-on success. Negative return values indicate resource problems (out
-of memory, etc.) in the SSL library, while a return value of B<0>
-indicates incorrect usage or invalid input, such as an unsupported
-TLSA 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 C<Full(0)> (binary ASN.1
-DER form) certificate or a public key that fails to parse.
-
-The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa()
-return a negative value when DANE authentication failed or was not
-enabled, a non-negative value indicates the chain depth at which
-the TLSA record matched a chain certificate, or the depth of the
-top-most certificate, when the TLSA record is a full public key
-that is its signer.
+SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success.
+Negative return values indicate resource problems (out of memory, etc.) in the
+SSL library, while a return value of B<0> indicates incorrect usage or invalid
+input, such as an unsupported TLSA 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 C<Full(0)> (binary ASN.1 DER form)
+certificate or a public key that fails to parse.
+
+The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a
+negative value when DANE authentication failed or was not enabled, a
+non-negative value indicates the chain depth at which the TLSA record matched a
+chain certificate, or the depth of the top-most certificate, when the TLSA
+record is a full public key that is its signer.
=head1 EXAMPLE
-Suppose "smtp.example.com" is the MX host of the domain "example.com",
-and has DNSSEC-validated TLSA records. The calls below will perform
-DANE authentication and arrange to match either the MX hostname or
-the destination domain name in the SMTP 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
+Suppose "smtp.example.com" is the MX host of the domain "example.com", and has
+DNSSEC-validated TLSA records.
+The calls below will perform DANE authentication and arrange to match either
+the MX hostname or the destination domain name in the SMTP 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 SSL connection.
SSL_CTX *ctx;
@@ -210,9 +209,9 @@ the lifetime of the SSL connection.
const char *peername = SSL_get0_peername(ssl);
EVP_PKEY *mspki = NULL;
- int depth = SSL_get0_dane_authority(s, NULL, &mspki);
+ int depth = SSL_get0_dane_authority(ssl, NULL, &mspki);
if (depth >= 0) {
- (void) SSL_get0_dane_tlsa(s, &usage, &selector, &mtype, NULL, NULL);
+ (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL);
printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype,
(mspki != NULL) ? "TA public key verified certificate" :
depth ? "matched TA certificate" : "matched EE certificate",
@@ -233,18 +232,17 @@ the lifetime of the SSL connection.
=head1 NOTES
-It is expected that the majority of clients employing DANE TLS will
-be doing "opportunistic DANE TLS" in the sense of RFC7672 and
-RFC7435. That is, they will use DANE authentication when
-DNSSEC-validated TLSA records are published for a given peer, and
-otherwise will use unauthenticated TLS or even cleartext.
-
-Such applications should generally treat any TLSA records published
-by the peer with usages PKIX-TA(0) and PKIX-EE(1) as "unusable",
-and should not include them among the TLSA records used to authenticate
-peer connections. In addition, some TLSA records with supported
-usages may be "unusable" as a result of invalid or unsupported
-parameters.
+It is expected that the majority of clients employing DANE TLS will be doing
+"opportunistic DANE TLS" in the sense of RFC7672 and RFC7435.
+That is, they will use DANE authentication when DNSSEC-validated TLSA records
+are published for a given peer, and otherwise will use unauthenticated TLS or
+even cleartext.
+
+Such applications should generally treat any TLSA records published by the peer
+with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include
+them among the TLSA records used to authenticate peer connections.
+In addition, some TLSA records with supported usages may be "unusable" as a
+result of invalid or unsupported parameters.
When a peer has TLSA records, but none are "usable", an opportunistic
application must avoid cleartext, but cannot authenticate the peer,
More information about the openssl-commits
mailing list