]>
Commit | Line | Data |
---|---|---|
d88926f1 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 certificate matching | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
c684a2d3 | 9 | #include <openssl/x509v3.h> |
d88926f1 | 10 | |
297c67fc | 11 | int X509_check_host(X509 *, const char *name, size_t namelen, |
1bc74519 | 12 | unsigned int flags, char **peername); |
297c67fc | 13 | int X509_check_email(X509 *, const char *address, size_t addresslen, |
1bc74519 | 14 | unsigned int flags); |
297c67fc | 15 | int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen, |
1bc74519 | 16 | unsigned int flags); |
d88926f1 DSH |
17 | int X509_check_ip_asc(X509 *, const char *address, unsigned int flags); |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
b73ac027 VD |
21 | The certificate matching functions are used to check whether a |
22 | certificate matches a given host name, email address, or IP address. | |
23 | The validity of the certificate and its trust level has to be checked by | |
24 | other means. | |
25 | ||
26 | X509_check_host() checks if the certificate Subject Alternative | |
27 | Name (SAN) or Subject CommonName (CN) matches the specified host | |
28 | name, which must be encoded in the preferred name syntax described | |
29 | in section 3.5 of RFC 1034. By default, wildcards are supported | |
30 | and they match only in the left-most label; but they may match | |
31 | part of that label with an explicit prefix or suffix. For example, | |
32 | by default, the host B<name> "www.example.com" would match a | |
33 | certificate with a SAN or CN value of "*.example.com", "w*.example.com" | |
34 | or "*w.example.com". | |
35 | ||
36 | Per section 6.4.2 of RFC 6125, B<name> values representing international | |
37 | domain names must be given in A-label form. The B<namelen> argument | |
38 | must be the number of characters in the name string or zero in which | |
39 | case the length is calculated with strlen(B<name>). When B<name> starts | |
40 | with a dot (e.g ".example.com"), it will be matched by a certificate | |
41 | valid for any sub-domain of B<name>, (see also | |
42 | B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> below). | |
43 | ||
44 | When the certificate is matched, and B<peername> is not NULL, a | |
45 | pointer to a copy of the matching SAN or CN from the peer certificate | |
46 | is stored at the address passed in B<peername>. The application | |
47 | is responsible for freeing the peername via OPENSSL_free() when it | |
48 | is no longer needed. | |
d88926f1 DSH |
49 | |
50 | X509_check_email() checks if the certificate matches the specified | |
b73ac027 | 51 | email B<address>. Only the mailbox syntax of RFC 822 is supported, |
d88926f1 DSH |
52 | comments are not allowed, and no attempt is made to normalize quoted |
53 | characters. The B<addresslen> argument must be the number of | |
b73ac027 VD |
54 | characters in the address string or zero in which case the length |
55 | is calculated with strlen(B<address>). | |
d88926f1 DSH |
56 | |
57 | X509_check_ip() checks if the certificate matches a specified IPv4 or | |
58 | IPv6 address. The B<address> array is in binary format, in network | |
59 | byte order. The length is either 4 (IPv4) or 16 (IPv6). Only | |
60 | explicitly marked addresses in the certificates are considered; IP | |
61 | addresses stored in DNS names and Common Names are ignored. | |
62 | ||
63 | X509_check_ip_asc() is similar, except that the NUL-terminated | |
64 | string B<address> is first converted to the internal representation. | |
65 | ||
66 | The B<flags> argument is usually 0. It can be the bitwise OR of the | |
397a8e74 VD |
67 | flags: |
68 | ||
69 | =over 4 | |
70 | ||
71 | =item B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>, | |
72 | ||
dd60efea VD |
73 | =item B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT>, |
74 | ||
397a8e74 VD |
75 | =item B<X509_CHECK_FLAG_NO_WILDCARDS>, |
76 | ||
77 | =item B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS>, | |
78 | ||
79 | =item B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>. | |
80 | ||
a09e4d24 VD |
81 | =item B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS>. |
82 | ||
397a8e74 | 83 | =back |
d88926f1 DSH |
84 | |
85 | The B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag causes the function | |
397a8e74 VD |
86 | to consider the subject DN even if the certificate contains at least |
87 | one subject alternative name of the right type (DNS name or email | |
88 | address as appropriate); the default is to ignore the subject DN | |
89 | when at least one corresponding subject alternative names is present. | |
d88926f1 | 90 | |
dd60efea VD |
91 | The B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT> flag causes the function to never |
92 | consider the subject DN even if the certificate contains no subject alternative | |
93 | names of the right type (DNS name or email address as appropriate); the default | |
94 | is to use the subject DN when no corresponding subject alternative names are | |
95 | present. | |
55a6250f VD |
96 | If both B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> and |
97 | B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT> are specified, the latter takes | |
98 | precedence and the subject DN is not checked for matching names. | |
dd60efea | 99 | |
397a8e74 | 100 | If set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard |
d88926f1 DSH |
101 | expansion; this only applies to B<X509_check_host>. |
102 | ||
397a8e74 VD |
103 | If set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support |
104 | for "*" as wildcard pattern in labels that have a prefix or suffix, | |
186bb907 | 105 | such as: "www*" or "*www"; this only applies to B<X509_check_host>. |
397a8e74 | 106 | |
a09e4d24 VD |
107 | If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that |
108 | constitutes the complete label of a DNS name (e.g. "*.example.com") | |
109 | to match more than one label in B<name>; this flag only applies | |
110 | to B<X509_check_host>. | |
111 | ||
112 | If set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name> | |
113 | values which start with ".", that would otherwise match any sub-domain | |
114 | in the peer certificate, to only match direct child sub-domains. | |
115 | Thus, for instance, with this flag set a B<name> of ".example.com" | |
116 | would match a peer certificate with a DNS name of "www.example.com", | |
117 | but would not match a peer certificate with a DNS name of | |
118 | "www.sub.example.com"; this flag only applies to B<X509_check_host>. | |
397a8e74 | 119 | |
d88926f1 DSH |
120 | =head1 RETURN VALUES |
121 | ||
122 | The functions return 1 for a successful match, 0 for a failed match | |
0923e7df EK |
123 | and -1 for an internal error: typically a memory allocation failure |
124 | or an ASN.1 decoding error. | |
d88926f1 | 125 | |
0923e7df EK |
126 | All functions can also return -2 if the input is malformed. For example, |
127 | X509_check_host() returns -2 if the provided B<name> contains embedded | |
128 | NULs. | |
d88926f1 | 129 | |
b73ac027 VD |
130 | =head1 NOTES |
131 | ||
132 | Applications are encouraged to use X509_VERIFY_PARAM_set1_host() | |
133 | rather than explicitly calling L<X509_check_host(3)>. Host name | |
55a6250f | 134 | checks may be out of scope with the DANE-EE(3) certificate usage, |
b73ac027 | 135 | and the internal checks will be suppressed as appropriate when |
55a6250f | 136 | DANE support is enabled. |
b73ac027 | 137 | |
d88926f1 DSH |
138 | =head1 SEE ALSO |
139 | ||
9b86974e RS |
140 | L<SSL_get_verify_result(3)>, |
141 | L<X509_VERIFY_PARAM_set1_host(3)>, | |
142 | L<X509_VERIFY_PARAM_add1_host(3)>, | |
143 | L<X509_VERIFY_PARAM_set1_email(3)>, | |
144 | L<X509_VERIFY_PARAM_set1_ip(3)>, | |
145 | L<X509_VERIFY_PARAM_set1_ipasc(3)> | |
d88926f1 DSH |
146 | |
147 | =head1 HISTORY | |
148 | ||
2bfbeb26 | 149 | These functions were added in OpenSSL 1.0.2. |
d88926f1 | 150 | |
e2f92610 RS |
151 | =head1 COPYRIGHT |
152 | ||
6738bf14 | 153 | Copyright 2012-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
154 | |
155 | Licensed under the OpenSSL license (the "License"). You may not use | |
156 | this file except in compliance with the License. You can obtain a copy | |
157 | in the file LICENSE in the source distribution or at | |
158 | L<https://www.openssl.org/source/license.html>. | |
159 | ||
160 | =cut |