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,
string B<address> is first converted to the internal representation.
The B<flags> argument is usually 0. It can be the bitwise OR of the
-flags B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>,
-B<X509_CHECK_FLAG_NO_WILDCARDS>.
+flags:
+
+=over 4
+
+=item B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>,
+
+=item B<X509_CHECK_FLAG_NO_WILDCARDS>,
+
+=item B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS>,
+
+=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
-to check the subject DN even if the certificate contains a subject
-alternative name extension is present; the default is to ignore the
-subject DN in preference of the extension.
+to consider the subject DN even if the certificate contains at least
+one subject alternative name of the right type (DNS name or email
+address as appropriate); the default is to ignore the subject DN
+when at least one corresponding subject alternative names is present.
-If present, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard
+If set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard
expansion; this only applies to B<X509_check_host>.
+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 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
The functions return 1 for a successful match, 0 for a failed match
=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
projects / oweals / openssl.git / blobdiff