From ee84152fae23f962c5f81ca45ca27a271c989152 Mon Sep 17 00:00:00 2001 From: Viktor Dukhovni <openssl-users@dukhovni.org> Date: Sat, 16 Jan 2016 15:43:14 -0500 Subject: [PATCH] Start a new line after each sentence-ending period. This avoids explicit double spaces between sentences. Reviewed-by: Rich Salz <rsalz@openssl.org> --- doc/ssl/SSL_CTX_dane_enable.pod | 210 ++++++++++++++++---------------- 1 file changed, 104 insertions(+), 106 deletions(-) diff --git a/doc/ssl/SSL_CTX_dane_enable.pod b/doc/ssl/SSL_CTX_dane_enable.pod index 3ffc675ce3..a9c24e1b34 100644 --- a/doc/ssl/SSL_CTX_dane_enable.pod +++ b/doc/ssl/SSL_CTX_dane_enable.pod @@ -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_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()> @@ -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. - -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; @@ -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, -- 2.25.1