| blob | f811f218849fd3581436f77f9fb98653bd31c9fa |
1 .\" $OpenBSD: X509_check_host.3,v 1.3 2018/03/23 14:26:40 schwarze Exp $
2 .\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3 .\"
4 .\" This file was written by Florian Weimer <fweimer@redhat.com> and
5 .\" Viktor Dukhovni <openssl-users@dukhovni.org>.
6 .\" Copyright (c) 2012, 2014, 2015, 2016 The OpenSSL Project. All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: March 23 2018 $
53 .Dt X509_CHECK_HOST 3
54 .Os
55 .Sh NAME
56 .Nm X509_check_host ,
57 .Nm X509_check_email ,
58 .Nm X509_check_ip ,
59 .Nm X509_check_ip_asc
60 .Nd X.509 certificate matching
61 .Sh SYNOPSIS
62 .In openssl/x509v3.h
63 .Ft int
64 .Fo X509_check_host
65 .Fa "X509 *x"
66 .Fa "const char *name"
67 .Fa "size_t namelen"
68 .Fa "unsigned int flags"
69 .Fa "char **peername"
70 .Fc
71 .Ft int
72 .Fo X509_check_email
73 .Fa "X509 *x"
74 .Fa "const char *address"
75 .Fa "size_t addresslen"
76 .Fa "unsigned int flags"
77 .Fc
78 .Ft int
79 .Fo X509_check_ip
80 .Fa "X509 *x"
81 .Fa "const unsigned char *address"
82 .Fa "size_t addresslen"
83 .Fa "unsigned int flags"
84 .Fc
85 .Ft int
86 .Fo X509_check_ip_asc
87 .Fa "X509 *x"
88 .Fa "const char *address"
89 .Fa "unsigned int flags"
90 .Fc
91 .Sh DESCRIPTION
92 The certificate matching functions are used to check whether a
93 certificate matches a given host name, email address, or IP address.
94 The validity of the certificate and its trust level has to be checked by
95 other means.
96 .Pp
97 .Fn X509_check_host
98 checks if the certificate Subject Alternative Name (SAN) or Subject
99 CommonName (CN) matches the specified host name, which must be encoded
100 in the preferred name syntax described in section 3.5 of RFC 1034.
101 By default, wildcards are supported and they match only in the
102 left-most label; they may match part of that label with an
103 explicit prefix or suffix.
104 For example, by default, the host
105 .Fa name
106 .Qq www.example.com
107 would match a certificate with a SAN or CN value of
108 .Qq *.example.com ,
109 .Qq w*.example.com
110 or
111 .Qq *w.example.com .
112 .Pp
113 Per section 6.4.2 of RFC 6125,
114 .Fa name
115 values representing international domain names must be given in A-label
116 form.
117 The
118 .Fa namelen
119 argument must be the number of characters in the name string or zero, in
120 which case the length is calculated with
121 .Fn strlen name .
122 When
123 .Fa name
124 starts with a dot (e.g.\&
125 .Qq .example.com ) ,
126 it will be matched by a certificate valid for any sub-domain of
127 .Fa name ;
128 see also
129 .Fa X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
130 below.
131 .Pp
132 When the certificate is matched and
133 .Fa peername
134 is not
135 .Dv NULL ,
136 a pointer to a copy of the matching SAN or CN from the peer
137 certificate is stored at the address passed in
138 .Fa peername .
139 The application is responsible for freeing the peername via
140 .Xr free 3
141 when it is no longer needed.
142 .Pp
143 .Fn X509_check_email
144 checks if the certificate matches the specified email
145 .Fa address .
146 Only the mailbox syntax of RFC 822 is supported.
147 Comments are not allowed,
148 and no attempt is made to normalize quoted characters.
149 The
150 .Fa addresslen
151 argument must be the number of characters in the address string or zero,
152 in which case the length is calculated with
153 .Fn strlen address .
154 .Pp
155 .Fn X509_check_ip
156 checks if the certificate matches a specified IPv4 or IPv6 address.
157 The
158 .Fa address
159 array is in binary format, in network byte order.
160 The length is either 4 (IPv4) or 16 (IPv6).
161 Only explicitly marked addresses in the certificates are considered;
162 IP addresses stored in DNS names and Common Names are ignored.
163 .Pp
164 .Fn X509_check_ip_asc
165 is similar, except that the NUL-terminated string
166 .Fa address
167 is first converted to the internal representation.
168 .Pp
169 The
170 .Fa flags
171 argument is usually 0, but it can be the bitwise OR of the following
172 flags.
173 .Pp
174 The
175 .Dv X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
176 flag causes the function to consider the subject DN even if the
177 certificate contains at least one subject alternative name of the right
178 type (DNS name or email address as appropriate); the default is to
179 ignore the subject DN when at least one corresponding subject
180 alternative names is present.
181 .Pp
182 The remaining flags are only meaningful for
183 .Fn X509_check_host .
184 .Pp
185 The
186 .Dv X509_CHECK_FLAG_NO_WILDCARDS
187 flag disables wildcard expansion.
188 .Pp
189 The
190 .Dv X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
191 flag suppresses support for
192 .Qq *
193 as a wildcard pattern in labels that have a
194 prefix or suffix, such as
195 .Qq www*
196 or
197 .Qq *www .
198 .Pp
199 The
200 .Dv X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
201 flag allows a
202 .Qq *
203 that constitutes the complete label of a DNS name (e.g.\&
204 .Qq *.example.com )
205 to match more than one label in
206 .Fa name .
207 .Pp
208 The
209 .Dv X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
210 flag restricts
211 .Fa name
212 values which start with
213 .Qq \&. ,
214 that would otherwise match any sub-domain in the peer certificate,
215 to only match direct child sub-domains.
216 Thus, for instance, with this flag set a
217 .Fa name
218 of
219 .Qq .example.com
220 would match a peer certificate with a DNS name of
221 .Qq www.example.com ,
222 but would not match a peer certificate with a DNS name of
223 .Qq www.sub.example.com .
224 .Sh RETURN VALUES
225 The functions return 1 for a successful match, 0 for a failed match and
226 -1 for an internal error: typically a memory allocation failure or an
227 ASN.1 decoding error.
228 .Pp
229 All functions can also return -2 if the input is malformed.
230 For example,
231 .Fn X509_check_host
232 returns -2 if the provided
233 .Fa name
234 contains embedded NUL bytes.
235 .Sh HISTORY
236 These functions first appeared in OpenSSL 1.0.2
237 and have been available since
238 .Ox 6.1 .