secure/lib/libcrypto/man/man3/X509_check_host.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "X509_CHECK_HOST 3"
 136 .TH X509_CHECK_HOST 3 "2020-03-31" "1.1.1f" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc \- X.509 certificate matching
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/x509v3.h>
 147 \&
 148 \& int X509_check_host(X509 *, const char *name, size_t namelen,
 149 \&                     unsigned int flags, char **peername);
 150 \& int X509_check_email(X509 *, const char *address, size_t addresslen,
 151 \&                      unsigned int flags);
 152 \& int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen,
 153 \&                   unsigned int flags);
 154 \& int X509_check_ip_asc(X509 *, const char *address, unsigned int flags);
 155 .Ve
 156 .SH "DESCRIPTION"
 157 .IX Header "DESCRIPTION"
 158 The certificate matching functions are used to check whether a
 159 certificate matches a given host name, email address, or \s-1IP\s0 address.
 160 The validity of the certificate and its trust level has to be checked by
 161 other means.
 162 .PP
 163 \&\fBX509_check_host()\fR checks if the certificate Subject Alternative
 164 Name (\s-1SAN\s0) or Subject CommonName (\s-1CN\s0) matches the specified host
 165 name, which must be encoded in the preferred name syntax described
 166 in section 3.5 of \s-1RFC 1034.\s0  By default, wildcards are supported
 167 and they match  only in the left-most label; but they may match
 168 part of that label with an explicit prefix or suffix.  For example,
 169 by default, the host \fBname\fR \*(L"www.example.com\*(R" would match a
 170 certificate with a \s-1SAN\s0 or \s-1CN\s0 value of \*(L"*.example.com\*(R", \*(L"w*.example.com\*(R"
 171 or \*(L"*w.example.com\*(R".
 172 .PP
 173 Per section 6.4.2 of \s-1RFC 6125,\s0 \fBname\fR values representing international
 174 domain names must be given in A\-label form.  The \fBnamelen\fR argument
 175 must be the number of characters in the name string or zero in which
 176 case the length is calculated with strlen(\fBname\fR).  When \fBname\fR starts
 177 with a dot (e.g \*(L".example.com\*(R"), it will be matched by a certificate
 178 valid for any sub-domain of \fBname\fR, (see also
 179 \&\fBX509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS\fR below).
 180 .PP
 181 When the certificate is matched, and \fBpeername\fR is not \s-1NULL,\s0 a
 182 pointer to a copy of the matching \s-1SAN\s0 or \s-1CN\s0 from the peer certificate
 183 is stored at the address passed in \fBpeername\fR.  The application
 184 is responsible for freeing the peername via \fBOPENSSL_free()\fR when it
 185 is no longer needed.
 186 .PP
 187 \&\fBX509_check_email()\fR checks if the certificate matches the specified
 188 email \fBaddress\fR.  Only the mailbox syntax of \s-1RFC 822\s0 is supported,
 189 comments are not allowed, and no attempt is made to normalize quoted
 190 characters.  The \fBaddresslen\fR argument must be the number of
 191 characters in the address string or zero in which case the length
 192 is calculated with strlen(\fBaddress\fR).
 193 .PP
 194 \&\fBX509_check_ip()\fR checks if the certificate matches a specified IPv4 or
 195 IPv6 address.  The \fBaddress\fR array is in binary format, in network
 196 byte order.  The length is either 4 (IPv4) or 16 (IPv6).  Only
 197 explicitly marked addresses in the certificates are considered; \s-1IP\s0
 198 addresses stored in \s-1DNS\s0 names and Common Names are ignored.
 199 .PP
 200 \&\fBX509_check_ip_asc()\fR is similar, except that the NUL-terminated
 201 string \fBaddress\fR is first converted to the internal representation.
 202 .PP
 203 The \fBflags\fR argument is usually 0.  It can be the bitwise \s-1OR\s0 of the
 204 flags:
 205 .IP "\fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR," 4
 206 .IX Item "X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT,"
 207 .PD 0
 208 .IP "\fBX509_CHECK_FLAG_NEVER_CHECK_SUBJECT\fR," 4
 209 .IX Item "X509_CHECK_FLAG_NEVER_CHECK_SUBJECT,"
 210 .IP "\fBX509_CHECK_FLAG_NO_WILDCARDS\fR," 4
 211 .IX Item "X509_CHECK_FLAG_NO_WILDCARDS,"
 212 .IP "\fBX509_CHECK_FLAG_NO_PARTIAL_WILDCARDS\fR," 4
 213 .IX Item "X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS,"
 214 .IP "\fBX509_CHECK_FLAG_MULTI_LABEL_WILDCARDS\fR." 4
 215 .IX Item "X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS."
 216 .IP "\fBX509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS\fR." 4
 217 .IX Item "X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS."
 218 .PD
 219 .PP
 220 The \fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR flag causes the function
 221 to consider the subject \s-1DN\s0 even if the certificate contains at least
 222 one subject alternative name of the right type (\s-1DNS\s0 name or email
 223 address as appropriate); the default is to ignore the subject \s-1DN\s0
 224 when at least one corresponding subject alternative names is present.
 225 .PP
 226 The \fBX509_CHECK_FLAG_NEVER_CHECK_SUBJECT\fR flag causes the function to never
 227 consider the subject \s-1DN\s0 even if the certificate contains no subject alternative
 228 names of the right type (\s-1DNS\s0 name or email address as appropriate); the default
 229 is to use the subject \s-1DN\s0 when no corresponding subject alternative names are
 230 present.
 231 If both \fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR and
 232 \&\fBX509_CHECK_FLAG_NEVER_CHECK_SUBJECT\fR are specified, the latter takes
 233 precedence and the subject \s-1DN\s0 is not checked for matching names.
 234 .PP
 235 If set, \fBX509_CHECK_FLAG_NO_WILDCARDS\fR disables wildcard
 236 expansion; this only applies to \fBX509_check_host\fR.
 237 .PP
 238 If set, \fBX509_CHECK_FLAG_NO_PARTIAL_WILDCARDS\fR suppresses support
 239 for \*(L"*\*(R" as wildcard pattern in labels that have a prefix or suffix,
 240 such as: \*(L"www*\*(R" or \*(L"*www\*(R"; this only applies to \fBX509_check_host\fR.
 241 .PP
 242 If set, \fBX509_CHECK_FLAG_MULTI_LABEL_WILDCARDS\fR allows a \*(L"*\*(R" that
 243 constitutes the complete label of a \s-1DNS\s0 name (e.g. \*(L"*.example.com\*(R")
 244 to match more than one label in \fBname\fR; this flag only applies
 245 to \fBX509_check_host\fR.
 246 .PP
 247 If set, \fBX509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS\fR restricts \fBname\fR
 248 values which start with \*(L".\*(R", that would otherwise match any sub-domain
 249 in the peer certificate, to only match direct child sub-domains.
 250 Thus, for instance, with this flag set a \fBname\fR of \*(L".example.com\*(R"
 251 would match a peer certificate with a \s-1DNS\s0 name of \*(L"www.example.com\*(R",
 252 but would not match a peer certificate with a \s-1DNS\s0 name of
 253 \&\*(L"www.sub.example.com\*(R"; this flag only applies to \fBX509_check_host\fR.
 254 .SH "RETURN VALUES"
 255 .IX Header "RETURN VALUES"
 256 The functions return 1 for a successful match, 0 for a failed match
 257 and \-1 for an internal error: typically a memory allocation failure
 258 or an \s-1ASN.1\s0 decoding error.
 259 .PP
 260 All functions can also return \-2 if the input is malformed. For example,
 261 \&\fBX509_check_host()\fR returns \-2 if the provided \fBname\fR contains embedded
 262 NULs.
 263 .SH "NOTES"
 264 .IX Header "NOTES"
 265 Applications are encouraged to use \fBX509_VERIFY_PARAM_set1_host()\fR
 266 rather than explicitly calling \fBX509_check_host\fR\|(3). Host name
 267 checks may be out of scope with the \s-1\fBDANE\-EE\s0\fR\|(3) certificate usage,
 268 and the internal checks will be suppressed as appropriate when
 269 \&\s-1DANE\s0 support is enabled.
 270 .SH "SEE ALSO"
 271 .IX Header "SEE ALSO"
 272 \&\fBSSL_get_verify_result\fR\|(3),
 273 \&\fBX509_VERIFY_PARAM_set1_host\fR\|(3),
 274 \&\fBX509_VERIFY_PARAM_add1_host\fR\|(3),
 275 \&\fBX509_VERIFY_PARAM_set1_email\fR\|(3),
 276 \&\fBX509_VERIFY_PARAM_set1_ip\fR\|(3),
 277 \&\fBX509_VERIFY_PARAM_set1_ipasc\fR\|(3)
 278 .SH "HISTORY"
 279 .IX Header "HISTORY"
 280 These functions were added in OpenSSL 1.0.2.
 281 .SH "COPYRIGHT"
 282 .IX Header "COPYRIGHT"
 283 Copyright 2012\-2018 The OpenSSL Project Authors. All Rights Reserved.
 284 .PP
 285 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 286 this file except in compliance with the License.  You can obtain a copy
 287 in the file \s-1LICENSE\s0 in the source distribution or at
 288 <https://www.openssl.org/source/license.html>.