]>
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. | |
96 | ||
397a8e74 | 97 | If set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard |
d88926f1 DSH |
98 | expansion; this only applies to B<X509_check_host>. |
99 | ||
397a8e74 VD |
100 | If set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support |
101 | for "*" as wildcard pattern in labels that have a prefix or suffix, | |
186bb907 | 102 | such as: "www*" or "*www"; this only applies to B<X509_check_host>. |
397a8e74 | 103 | |
a09e4d24 VD |
104 | If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that |
105 | constitutes the complete label of a DNS name (e.g. "*.example.com") | |
106 | to match more than one label in B<name>; this flag only applies | |
107 | to B<X509_check_host>. | |
108 | ||
109 | If set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name> | |
110 | values which start with ".", that would otherwise match any sub-domain | |
111 | in the peer certificate, to only match direct child sub-domains. | |
112 | Thus, for instance, with this flag set a B<name> of ".example.com" | |
113 | would match a peer certificate with a DNS name of "www.example.com", | |
114 | but would not match a peer certificate with a DNS name of | |
115 | "www.sub.example.com"; this flag only applies to B<X509_check_host>. | |
397a8e74 | 116 | |
d88926f1 DSH |
117 | =head1 RETURN VALUES |
118 | ||
119 | The functions return 1 for a successful match, 0 for a failed match | |
0923e7df EK |
120 | and -1 for an internal error: typically a memory allocation failure |
121 | or an ASN.1 decoding error. | |
d88926f1 | 122 | |
0923e7df EK |
123 | All functions can also return -2 if the input is malformed. For example, |
124 | X509_check_host() returns -2 if the provided B<name> contains embedded | |
125 | NULs. | |
d88926f1 | 126 | |
b73ac027 VD |
127 | =head1 NOTES |
128 | ||
129 | Applications are encouraged to use X509_VERIFY_PARAM_set1_host() | |
130 | rather than explicitly calling L<X509_check_host(3)>. Host name | |
131 | checks are out of scope with the DANE-EE(3) certificate usage, | |
132 | and the internal checks will be suppressed as appropriate when | |
133 | DANE support is added to OpenSSL. | |
134 | ||
d88926f1 DSH |
135 | =head1 SEE ALSO |
136 | ||
9b86974e RS |
137 | L<SSL_get_verify_result(3)>, |
138 | L<X509_VERIFY_PARAM_set1_host(3)>, | |
139 | L<X509_VERIFY_PARAM_add1_host(3)>, | |
140 | L<X509_VERIFY_PARAM_set1_email(3)>, | |
141 | L<X509_VERIFY_PARAM_set1_ip(3)>, | |
142 | L<X509_VERIFY_PARAM_set1_ipasc(3)> | |
d88926f1 DSH |
143 | |
144 | =head1 HISTORY | |
145 | ||
2bfbeb26 | 146 | These functions were added in OpenSSL 1.0.2. |
d88926f1 | 147 | |
e2f92610 RS |
148 | =head1 COPYRIGHT |
149 | ||
6738bf14 | 150 | Copyright 2012-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
151 | |
152 | Licensed under the OpenSSL license (the "License"). You may not use | |
153 | this file except in compliance with the License. You can obtain a copy | |
154 | in the file LICENSE in the source distribution or at | |
155 | L<https://www.openssl.org/source/license.html>. | |
156 | ||
157 | =cut |