]>
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 | ||
9 | #include <openssl/x509.h> | |
10 | ||
297c67fc VD |
11 | int X509_check_host(X509 *, const char *name, size_t namelen, |
12 | unsigned int flags, char **peername); | |
13 | int X509_check_email(X509 *, const char *address, size_t addresslen, | |
14 | unsigned int flags); | |
15 | int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen, | |
16 | unsigned int flags); | |
d88926f1 DSH |
17 | int X509_check_ip_asc(X509 *, const char *address, unsigned int flags); |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | The certificate matching functions are intended to be called to check | |
22 | if a certificate matches a given host name, email address, or IP | |
23 | address. The validity of the certificate and its trust level has to | |
24 | be checked by other means. | |
25 | ||
26 | X509_check_host() checks if the certificate matches the specified | |
27 | host name, which must be encoded in the preferred name syntax | |
d241b804 VD |
28 | described in section 3.5 of RFC 1034. Per section 6.4.2 of RFC 6125, |
29 | B<name> values representing international domain names must be given | |
30 | in A-label form. The B<namelen> argument must be the number of | |
31 | characters in the name string or zero in which case the length is | |
32 | calculated with strlen(name). When B<name> starts with a dot (e.g | |
33 | ".example.com"), it will be matched by a certificate valid for any | |
34 | sub-domain of B<name>, (see also B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> | |
ced3d915 VD |
35 | below). When the certificate is matched and B<peername> is not |
36 | NULL a pointer to a copy of the matching hostname or CommonName | |
37 | from the peer certificate is stored at the address passed in | |
38 | B<peername>. The application is responsible for freeing the peername | |
39 | via OPENSSL_free() when it is no longer needed. Applications are | |
40 | advised to use X509_VERIFY_PARAM_set1_host() in preference to | |
41 | explicitly calling L<X509_check_host(3)>, hostname checks are out | |
42 | of scope with the DANE-EE(3) certificate usage, and the internal | |
43 | check will be suppressed as appropriate when DANE support is added | |
44 | to OpenSSL. | |
d88926f1 DSH |
45 | |
46 | X509_check_email() checks if the certificate matches the specified | |
47 | email address. Only the mailbox syntax of RFC 822 is supported, | |
48 | comments are not allowed, and no attempt is made to normalize quoted | |
49 | characters. The B<addresslen> argument must be the number of | |
50 | characters in the address string. The B<namelen> argument must be | |
51 | the number of characters in the name string or zero in which case the | |
52 | length is calculated with strlen(name). | |
53 | ||
54 | X509_check_ip() checks if the certificate matches a specified IPv4 or | |
55 | IPv6 address. The B<address> array is in binary format, in network | |
56 | byte order. The length is either 4 (IPv4) or 16 (IPv6). Only | |
57 | explicitly marked addresses in the certificates are considered; IP | |
58 | addresses stored in DNS names and Common Names are ignored. | |
59 | ||
60 | X509_check_ip_asc() is similar, except that the NUL-terminated | |
61 | string B<address> is first converted to the internal representation. | |
62 | ||
63 | The B<flags> argument is usually 0. It can be the bitwise OR of the | |
397a8e74 VD |
64 | flags: |
65 | ||
66 | =over 4 | |
67 | ||
68 | =item B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>, | |
69 | ||
70 | =item B<X509_CHECK_FLAG_NO_WILDCARDS>, | |
71 | ||
72 | =item B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS>, | |
73 | ||
74 | =item B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>. | |
75 | ||
a09e4d24 VD |
76 | =item B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS>. |
77 | ||
397a8e74 | 78 | =back |
d88926f1 DSH |
79 | |
80 | The B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag causes the function | |
397a8e74 VD |
81 | to consider the subject DN even if the certificate contains at least |
82 | one subject alternative name of the right type (DNS name or email | |
83 | address as appropriate); the default is to ignore the subject DN | |
84 | when at least one corresponding subject alternative names is present. | |
d88926f1 | 85 | |
397a8e74 | 86 | If set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard |
d88926f1 DSH |
87 | expansion; this only applies to B<X509_check_host>. |
88 | ||
397a8e74 VD |
89 | If set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support |
90 | for "*" as wildcard pattern in labels that have a prefix or suffix, | |
91 | such as: "www*" or "*www"; this only aplies to B<X509_check_host>. | |
92 | ||
a09e4d24 VD |
93 | If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that |
94 | constitutes the complete label of a DNS name (e.g. "*.example.com") | |
95 | to match more than one label in B<name>; this flag only applies | |
96 | to B<X509_check_host>. | |
97 | ||
98 | If set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name> | |
99 | values which start with ".", that would otherwise match any sub-domain | |
100 | in the peer certificate, to only match direct child sub-domains. | |
101 | Thus, for instance, with this flag set a B<name> of ".example.com" | |
102 | would match a peer certificate with a DNS name of "www.example.com", | |
103 | but would not match a peer certificate with a DNS name of | |
104 | "www.sub.example.com"; this flag only applies to B<X509_check_host>. | |
397a8e74 | 105 | |
d88926f1 DSH |
106 | =head1 RETURN VALUES |
107 | ||
108 | The functions return 1 for a successful match, 0 for a failed match | |
109 | and -1 for an internal error: typically a memory allocation failure. | |
110 | ||
111 | X509_check_ip_asc() can also return -2 if the IP address string is malformed. | |
112 | ||
113 | =head1 SEE ALSO | |
114 | ||
d241b804 VD |
115 | L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, |
116 | L<X509_VERIFY_PARAM_set1_host(3)|X509_VERIFY_PARAM_set1_host(3)>, | |
8abffa4a | 117 | L<X509_VERIFY_PARAM_add1_host(3)|X509_VERIFY_PARAM_add1_host(3)>, |
d241b804 VD |
118 | L<X509_VERIFY_PARAM_set1_email(3)|X509_VERIFY_PARAM_set1_email(3)>, |
119 | L<X509_VERIFY_PARAM_set1_ip(3)|X509_VERIFY_PARAM_set1_ip(3)>, | |
120 | L<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)> | |
d88926f1 DSH |
121 | |
122 | =head1 HISTORY | |
123 | ||
124 | These functions were added in OpenSSL 1.1.0. | |
125 | ||
126 | =cut |