Viktor graciously took the time to explain some of the finer details of the new name matching API (see http://www.mail-archive.com/openssl-users@openssl.org/msg74281.html). The discussion was helpful to me, and would likely be helpful to others.
The patch incorporates Viktor's comments, and includes a description and examples of the default matching behavior for X509_check_host(). It also improves flow by breaking the first large paragraph on into two separate prargraphs. The patch also adds a NOTES sections for three topics that did not appear to belong in the description body. The notes section states policies are not applied with the new functions, and extended error information is not available. Finally two additional cross references were added for SSL_get_peer_certificate and X509_verify_cert. ***** diff --git a/doc/crypto/X509_check_host.pod b/doc/crypto/X509_check_host.pod index 113861d..cfbbe82 100644 --- a/doc/crypto/X509_check_host.pod +++ b/doc/crypto/X509_check_host.pod @@ -18,25 +18,29 @@ X509_check_host, X509_check_email, X509_check_ip, X509_check =head1 DESCRIPTION -The certificate matching functions are intended to be called to check -if a certificate matches a given host name, email address, or IP -address. The validity of the certificate and its trust level has to -be checked by other means. +The certificate matching functions are used to check if a certificate +matches a given host name, email address, or IP address. The +validity of the certificate and its trust level has to be checked by +other means. X509_check_host() checks if the certificate matches the specified -host name, which must be encoded in the preferred name syntax -described in section 3.5 of RFC 1034. Per section 6.4.2 of RFC 6125, -B<name> values representing international domain names must be given -in A-label form. The B<namelen> argument must be the number of -characters in the name string or zero in which case the length is -calculated with strlen(name). When B<name> starts with a dot (e.g -".example.com"), it will be matched by a certificate valid for any -sub-domain of B<name>, (see also B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> -below). Applications are strongly advised to use -X509_VERIFY_PARAM_set1_host() in preference to explicitly calling -L<X509_check_host(3)>, hostname checks are out of scope with the -DANE-EE(3) certificate usage, and the internal check will be -suppressed as appropriate when DANE support is added to OpenSSL. +host name, which can be supplied in the Common Name (CN) or Subject +Alternate Name (SAN). By default, wildcards are supported and they +match only in the left-most label; but they may match part of that +label with an explicit prefix or suffix. For example, by default, a +host name of "www.example.com" would match "*.example.com", +"w*.example.com" or "*w.example.com". The host name must be encoded +in the preferred name syntax described in section 3.5 of RFC 1034. +The default behavior can be changed with the flags discussed below. + +In accordance with section 6.4.2 of RFC 6125, B<name> values +representing international domain names must be given in A-label +form. The B<namelen> argument must be the number of characters +in the name string or zero in which case the length is calculated +with strlen(name). If B<name> starts with a dot (e.g ".example.com"), +then it will be matched by a certificate valid for any sub-domain +of B<name>, (see also B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> +below). X509_check_email() checks if the certificate matches the specified email address. Only the mailbox syntax of RFC 822 is supported, @@ -105,6 +109,24 @@ and -1 for an internal error: typically a memory allocation X509_check_ip_asc() can also return -2 if the IP address string is malformed. +=head1 NOTES + +Applications are encouraged to use X509_VERIFY_PARAM_set1_host() +rather than explicitly calling L<X509_check_host(3)>. Host name +checks are out of scope with the DANE-EE(3) certificate usage, +and the internal checks will be suppressed as appropriate when +DANE support is added to OpenSSL. + +The certificate matching functions do B<not> use policies when evaluating +certificates. Policies are the responsibility of the calling application. +For example, X509_check_host() does not fail I<if> the certificate is +declared as "Extended Validation" by the issuer but includes a wildcard +domain name. + +There is no way to determine the reason for the failure if the certificate +matching functions fail. That is, there is no extended error information +provided to the caller. + =head1 SEE ALSO L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, @@ -112,7 +134,9 @@ L<X509_VERIFY_PARAM_set1_host(3)|X509_VERIFY_PARAM_set1_host L<X509_VERIFY_PARAM_add1_host(3)|X509_VERIFY_PARAM_add1_host(3)>, L<X509_VERIFY_PARAM_set1_email(3)|X509_VERIFY_PARAM_set1_email(3)>, L<X509_VERIFY_PARAM_set1_ip(3)|X509_VERIFY_PARAM_set1_ip(3)>, -L<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)> +L<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)>, +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, +L<X509_verify_cert(3)|X509_verify_cert(3)> =head1 HISTORY
diff --git a/doc/crypto/X509_check_host.pod b/doc/crypto/X509_check_host.pod index 113861d..cfbbe82 100644 --- a/doc/crypto/X509_check_host.pod +++ b/doc/crypto/X509_check_host.pod @@ -18,25 +18,29 @@ X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 cert =head1 DESCRIPTION -The certificate matching functions are intended to be called to check -if a certificate matches a given host name, email address, or IP -address. The validity of the certificate and its trust level has to -be checked by other means. +The certificate matching functions are used to check if a certificate +matches a given host name, email address, or IP address. The +validity of the certificate and its trust level has to be checked by +other means. X509_check_host() checks if the certificate matches the specified -host name, which must be encoded in the preferred name syntax -described in section 3.5 of RFC 1034. Per section 6.4.2 of RFC 6125, -B<name> values representing international domain names must be given -in A-label form. The B<namelen> argument must be the number of -characters in the name string or zero in which case the length is -calculated with strlen(name). When B<name> starts with a dot (e.g -".example.com"), it will be matched by a certificate valid for any -sub-domain of B<name>, (see also B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> -below). Applications are strongly advised to use -X509_VERIFY_PARAM_set1_host() in preference to explicitly calling -L<X509_check_host(3)>, hostname checks are out of scope with the -DANE-EE(3) certificate usage, and the internal check will be -suppressed as appropriate when DANE support is added to OpenSSL. +host name, which can be supplied in the Common Name (CN) or Subject +Alternate Name (SAN). By default, wildcards are supported and they +match only in the left-most label; but they may match part of that +label with an explicit prefix or suffix. For example, by default, a +host name of "www.example.com" would match "*.example.com", +"w*.example.com" or "*w.example.com". The host name must be encoded +in the preferred name syntax described in section 3.5 of RFC 1034. +The default behavior can be changed with the flags discussed below. + +In accordance with section 6.4.2 of RFC 6125, B<name> values +representing international domain names must be given in A-label +form. The B<namelen> argument must be the number of characters +in the name string or zero in which case the length is calculated +with strlen(name). If B<name> starts with a dot (e.g ".example.com"), +then it will be matched by a certificate valid for any sub-domain +of B<name>, (see also B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> +below). X509_check_email() checks if the certificate matches the specified email address. Only the mailbox syntax of RFC 822 is supported, @@ -105,6 +109,24 @@ and -1 for an internal error: typically a memory allocation failure. X509_check_ip_asc() can also return -2 if the IP address string is malformed. +=head1 NOTES + +Applications are encouraged to use X509_VERIFY_PARAM_set1_host() +rather than explicitly calling L<X509_check_host(3)>. Host name +checks are out of scope with the DANE-EE(3) certificate usage, +and the internal checks will be suppressed as appropriate when +DANE support is added to OpenSSL. + +The certificate matching functions do B<not> use policies when evaluating +certificates. Policies are the responsibility of the calling application. +For example, X509_check_host() does not fail I<if> the certificate is +declared as "Extended Validation" by the issuer but includes a wildcard +domain name. + +There is no way to determine the reason for the failure if the certificate +matching functions fail. That is, there is no extended error information +provided to the caller. + =head1 SEE ALSO L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, @@ -112,7 +134,9 @@ L<X509_VERIFY_PARAM_set1_host(3)|X509_VERIFY_PARAM_set1_host(3)>, L<X509_VERIFY_PARAM_add1_host(3)|X509_VERIFY_PARAM_add1_host(3)>, L<X509_VERIFY_PARAM_set1_email(3)|X509_VERIFY_PARAM_set1_email(3)>, L<X509_VERIFY_PARAM_set1_ip(3)|X509_VERIFY_PARAM_set1_ip(3)>, -L<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)> +L<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)>, +L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, +L<X509_verify_cert(3)|X509_verify_cert(3)> =head1 HISTORY
