secure/lib/libcrypto/man/X509_check_host.3

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