PR: 2909

Contributed by: Florian Weimer <fweimer@redhat.com>

Fixes to X509 hostname and email address checking. Wildcard matching support.
New test program and manual page.

doc/crypto/X509_check_host.pod

@@ -0,0 +1,76 @@
+=pod
+
+=head1 NAME
+
+X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 certificate matching
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509_check_host(X509 *, const unsigned char *name,
+                     size_t namelen, unsigned int flags);
+ int X509_check_email(X509 *, const unsigned char *address,
+                     size_t addresslen, unsigned int flags);
+ int X509_check_ip(X509 *, const unsigned char *address,
+                   size_t addresslen, unsigned int flags);
+ int X509_check_ip_asc(X509 *, const char *address, unsigned int flags);
+
+=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.
+
+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).
+
+X509_check_email() checks if the certificate matches the specified
+email address.  Only the mailbox syntax of RFC 822 is supported,
+comments are not allowed, and no attempt is made to normalize quoted
+characters.  The B<addresslen> argument must be the number of
+characters in the address string. 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).
+
+X509_check_ip() checks if the certificate matches a specified IPv4 or
+IPv6 address.  The B<address> array is in binary format, in network
+byte order.  The length is either 4 (IPv4) or 16 (IPv6).  Only
+explicitly marked addresses in the certificates are considered; IP
+addresses stored in DNS names and Common Names are ignored.
+
+X509_check_ip_asc() is similar, except that the NUL-terminated
+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>.
+
+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.
+
+If present, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard
+expansion; this only applies to B<X509_check_host>.
+
+=head1 RETURN VALUES
+
+The functions return 1 for a successful match, 0 for a failed match
+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 SEE ALSO
+
+L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 1.1.0.
+
+=cut