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)
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_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.
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.
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()>
@ -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 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.
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.
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.
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.
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.
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.
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.
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.
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;
@ -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.
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.
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,