Typo.

[oweals/openssl.git] / doc / crypto / X509_check_host.pod

diff --git a/doc/crypto/X509_check_host.pod b/doc/crypto/X509_check_host.pod
index 64a84d2ab5e490bbe1a402b2460d09349c1fe335..113861d46d798a65b53f6f138da46d2b5416ded5 100644 (file)
--- a/doc/crypto/X509_check_host.pod
+++ b/doc/crypto/X509_check_host.pod
@@ -25,9 +25,18 @@ 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. 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).
+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.
 
 X509_check_email() checks if the certificate matches the specified
 email address.  Only the mailbox syntax of RFC 822 is supported,
@@ -59,6 +68,8 @@ flags:
 
 =item B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>.
 
+=item B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS>.
+
 =back
 
 The B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag causes the function
@@ -74,10 +85,18 @@ If set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support
 for "*" as wildcard pattern in labels that have a prefix or suffix,
 such as: "www*" or "*www"; this only aplies to B<X509_check_host>.
 
-If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>, allows a "*"
-that constitutes the complete label of a DNS name (e.g.
-"*.example.com") to match more than one label in B<name>;
-this only applies to B<X509_check_host>.
+If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that
+constitutes the complete label of a DNS name (e.g. "*.example.com")
+to match more than one label in B<name>; this flag only applies
+to B<X509_check_host>.
+
+If set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name>
+values which start with ".", that would otherwise match any sub-domain
+in the peer certificate, to only match direct child sub-domains.
+Thus, for instance, with this flag set a B<name> of ".example.com"
+would match a peer certificate with a DNS name of "www.example.com",
+but would not match a peer certificate with a DNS name of
+"www.sub.example.com"; this flag only applies to B<X509_check_host>.
 
 =head1 RETURN VALUES
 
@@ -88,7 +107,12 @@ X509_check_ip_asc() can also return -2 if the IP address string is malformed.
 
 =head1 SEE ALSO
 
-L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>
+L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
+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)>
 
 =head1 HISTORY