From: Viktor Dukhovni <openssl-users@dukhovni.org>
Date: Sun, 22 Jun 2014 05:31:00 +0000 (-0400)
Subject: More complete X509_check_host documentation.
X-Git-Tag: master-post-reformat~680
X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=d241b804099ce28c053ba988eb5532b1a32dd51e

More complete X509_check_host documentation.
---

diff --git a/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod
index 29f48bd978..7b1f294e89 100644
--- a/doc/crypto/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies - X509 verification parameters 
+X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_set1_ip_asc - X509 verification parameters
 
 =head1 SYNOPSIS
 
@@ -204,7 +204,10 @@ connections associated with an B<SSL_CTX> structure B<ctx>:
 
 =head1 SEE ALSO
 
-L<X509_verify_cert(3)|X509_verify_cert(3)>
+L<X509_verify_cert(3)|X509_verify_cert(3)>,
+L<X509_check_host(3)|X509_check_host(3)>,
+L<X509_check_email(3)|X509_check_email(3)>,
+L<X509_check_ip(3)|X509_check_ip(3)>
 
 =head1 HISTORY
 
diff --git a/doc/crypto/X509_check_host.pod b/doc/crypto/X509_check_host.pod
index 7f6adf6424..001b845957 100644
--- a/doc/crypto/X509_check_host.pod
+++ b/doc/crypto/X509_check_host.pod
@@ -25,12 +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).  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).
+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,
@@ -101,7 +107,11 @@ 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_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