diff options
author | Viktor Dukhovni <viktor@dukhovni.org> | 2014-05-21 10:57:44 +0100 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2014-05-21 11:31:28 +0100 |
commit | 397a8e747dc3f964196caed5ca4e08d4b598362a (patch) | |
tree | 5830abbfbe6e1918e47adf8719b0da9657b4266f /doc/crypto | |
parent | 558c94efc00ce15a9fcc9370598d8841392ff0f3 (diff) |
Fixes to host checking.
Fixes to host checking wild card support and add support for
setting host checking flags when verifying a certificate
chain.
Diffstat (limited to 'doc/crypto')
-rw-r--r-- | doc/crypto/X509_VERIFY_PARAM_set_flags.pod | 48 | ||||
-rw-r--r-- | doc/crypto/X509_check_host.pod | 33 |
2 files changed, 72 insertions, 9 deletions
diff --git a/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod index 46cac2bea2..1059d4ff84 100644 --- a/doc/crypto/X509_VERIFY_PARAM_set_flags.pod +++ b/doc/crypto/X509_VERIFY_PARAM_set_flags.pod @@ -26,6 +26,17 @@ X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_ge void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); + int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, + const unsigned char *name, size_t namelen); + void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param, + unsigned int flags); + int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param, + const unsigned char *email, size_t emaillen); + int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param, + const unsigned char *ip, size_t iplen); + int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, + const char *ipasc); + =head1 DESCRIPTION These functions manipulate the B<X509_VERIFY_PARAM> structure associated with @@ -61,12 +72,43 @@ X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>. That is the maximum number of untrusted CA certificates that can appear in a chain. +X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to B<name>. If +B<name> is NUL-terminated, B<namelen> may be zero, otherwise B<namelen> must +be set to the length of B<name>. When a hostname is specified, certificate +verification automatically invokes L<X509_check_host(3)> with flags equal to +the B<flags> argument given to B<X509_VERIFY_PARAM_set_hostflags()> (default +zero). Applications are strongly advised to use this interface 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_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to +B<email>. If B<email is NUL-terminated, B<emaillen> may be zero, otherwise +B<emaillen> must be set to the length of B<email>. When an email address +is specified, certificate verification automatically invokes +L<X509_check_email(3)>. + +X509_VERIFY_PARAM_set1_ip() sets the expected IP address to B<ip>. +The B<ip> argument is in binary format, in network byte-order and +B<iplen> must be set to 4 for IPv4 and 16 for IPv6. When an IP +address is specified, certificate verification automatically invokes +L<X509_check_ip(3)>. + +X509_VERIFY_PARAM_set1_ip_asc() sets the expected IP address to +B<ipasc>. The B<ipasc> argument is a NUL-terminal ASCII string: +dotted decimal quad for IPv4 and colon-separated hexadecimal for +IPv6. The condensed "::" notation is supported for IPv6 addresses. + =head1 RETURN VALUES -X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), +X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), -X509_VERIFY_PARAM_add0_policy() and X509_VERIFY_PARAM_set1_policies() return 1 -for success and 0 for failure. +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() and +X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for +failure. X509_VERIFY_PARAM_get_flags() returns the current verification flags. diff --git a/doc/crypto/X509_check_host.pod b/doc/crypto/X509_check_host.pod index 5ac2137a50..64a84d2ab5 100644 --- a/doc/crypto/X509_check_host.pod +++ b/doc/crypto/X509_check_host.pod @@ -47,17 +47,38 @@ 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>. +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>. + +=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 only applies to B<X509_check_host>. + =head1 RETURN VALUES The functions return 1 for a successful match, 0 for a failed match |