More complete X509_check_host documentation.
[openssl.git] / doc / crypto / X509_check_host.pod
index 7f6adf642429d44b66fcf0820dd1c25dda2dcccf..001b84595728820497449cc226b431783ebe5d21 100644 (file)
@@ -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