Updated text for the patch based on Viktor's reply to JW and JB on the list.
The updted text includes the a statement that its not possible to determine which named matched (this may be added in the future); and the two-label rule could make an application vulnerable to attacks on ccTLDs like "*.co.uk" (the two-label rule stops attacks on gTLDs like "*.com"). diff --git a/doc/crypto/X509_check_host.pod b/doc/crypto/X509_check_host.pod index 113861d..6f4318b 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,35 @@ 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 matches a wildcard +domain name. + +The host name matching function uses a two-label rule for wildcard host +names. That means a certificate presented with a host name for a gTLD +like "*.com" will B<not> match "example.com" because there is one label +in "*.com". However, the two-label rule will not catch ccTLD attacks. +For example, if the certificate presents a host name of "*.co.uk", then +the name will match "example.co.uk", "google.co.uk", "microsoft.co.uk", +etc. + +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. + +There is no way to determine the host name that matched if there are +multiple names in the certificate. + =head1 SEE ALSO L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, @@ -112,7 +145,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 On Fri, Jul 4, 2014 at 4:48 AM, The default queue via RT <[email protected]> wrote: > > Greetings, > > This message has been automatically generated in response to the > creation of a trouble ticket regarding: > "PATCH: Update to X509_check_host documentation", > a summary of which appears below. > > There is no need to reply to this message right now. Your ticket has been > assigned an ID of [openssl.org #3429]. > > Please include the string: > > [openssl.org #3429] > > in the subject line of all future correspondence about this issue. To do so, > you may reply to this message. > > Thank you, > [email protected] > > ------------------------------------------------------------------------- > Viktor graciously took the time to explain some of the finer details > of the new name matching API (see > http://www.mail-archive.com/[email protected]/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. > > ***** > <SNIP>
diff --git a/doc/crypto/X509_check_host.pod b/doc/crypto/X509_check_host.pod index 113861d..6f4318b 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,35 @@ 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 matches a wildcard +domain name. + +The host name matching function uses a two-label rule for wildcard host +names. That means a certificate presented with a host name for a gTLD +like "*.com" will B<not> match "example.com" because there is one label +in "*.com". However, the two-label rule will not catch ccTLD attacks. +For example, if the certificate presents a host name of "*.co.uk", then +the name will match "example.co.uk", "google.co.uk", "microsoft.co.uk", +etc. + +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. + +There is no way to determine the host name that matched if there are +multiple names in the certificate. + =head1 SEE ALSO L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, @@ -112,7 +145,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
