secure/lib/libcrypto/man/X509_check_host.3

   1 .\" Automatically generated by Pod::Man 4.07 (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 "2017-11-02" "1.0.2m" "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/x509.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_NO_WILDCARDS\fR," 4
 205 .IX Item "X509_CHECK_FLAG_NO_WILDCARDS,"
 206 .IP "\fBX509_CHECK_FLAG_NO_PARTIAL_WILDCARDS\fR," 4
 207 .IX Item "X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS,"
 208 .IP "\fBX509_CHECK_FLAG_MULTI_LABEL_WILDCARDS\fR." 4
 209 .IX Item "X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS."
 210 .IP "\fBX509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS\fR." 4
 211 .IX Item "X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS."
 212 .PD
 213 .PP
 214 The \fBX509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT\fR flag causes the function
 215 to consider the subject \s-1DN\s0 even if the certificate contains at least
 216 one subject alternative name of the right type (\s-1DNS\s0 name or email
 217 address as appropriate); the default is to ignore the subject \s-1DN\s0
 218 when at least one corresponding subject alternative names is present.
 219 .PP
 220 If set, \fBX509_CHECK_FLAG_NO_WILDCARDS\fR disables wildcard
 221 expansion; this only applies to \fBX509_check_host\fR.
 222 .PP
 223 If set, \fBX509_CHECK_FLAG_NO_PARTIAL_WILDCARDS\fR suppresses support
 224 for \*(L"*\*(R" as wildcard pattern in labels that have a prefix or suffix,
 225 such as: \*(L"www*\*(R" or \*(L"*www\*(R"; this only aplies to \fBX509_check_host\fR.
 226 .PP
 227 If set, \fBX509_CHECK_FLAG_MULTI_LABEL_WILDCARDS\fR allows a \*(L"*\*(R" that
 228 constitutes the complete label of a \s-1DNS\s0 name (e.g. \*(L"*.example.com\*(R")
 229 to match more than one label in \fBname\fR; this flag only applies
 230 to \fBX509_check_host\fR.
 231 .PP
 232 If set, \fBX509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS\fR restricts \fBname\fR
 233 values which start with \*(L".\*(R", that would otherwise match any sub-domain
 234 in the peer certificate, to only match direct child sub-domains.
 235 Thus, for instance, with this flag set a \fBname\fR of \*(L".example.com\*(R"
 236 would match a peer certificate with a \s-1DNS\s0 name of \*(L"www.example.com\*(R",
 237 but would not match a peer certificate with a \s-1DNS\s0 name of
 238 \&\*(L"www.sub.example.com\*(R"; this flag only applies to \fBX509_check_host\fR.
 239 .SH "RETURN VALUES"
 240 .IX Header "RETURN VALUES"
 241 The functions return 1 for a successful match, 0 for a failed match
 242 and \-1 for an internal error: typically a memory allocation failure
 243 or an \s-1ASN.1\s0 decoding error.
 244 .PP
 245 All functions can also return \-2 if the input is malformed. For example,
 246 \&\fIX509_check_host()\fR returns \-2 if the provided \fBname\fR contains embedded
 247 NULs.
 248 .SH "NOTES"
 249 .IX Header "NOTES"
 250 Applications are encouraged to use \fIX509_VERIFY_PARAM_set1_host()\fR
 251 rather than explicitly calling \fIX509_check_host\fR\|(3). Host name
 252 checks are out of scope with the \s-1\fIDANE\-EE\s0\fR\|(3) certificate usage,
 253 and the internal checks will be suppressed as appropriate when
 254 \&\s-1DANE\s0 support is added to OpenSSL.
 255 .SH "SEE ALSO"
 256 .IX Header "SEE ALSO"
 257 \&\fISSL_get_verify_result\fR\|(3),
 258 \&\fIX509_VERIFY_PARAM_set1_host\fR\|(3),
 259 \&\fIX509_VERIFY_PARAM_add1_host\fR\|(3),
 260 \&\fIX509_VERIFY_PARAM_set1_email\fR\|(3),
 261 \&\fIX509_VERIFY_PARAM_set1_ip\fR\|(3),
 262 \&\fIX509_VERIFY_PARAM_set1_ipasc\fR\|(3)
 263 .SH "HISTORY"
 264 .IX Header "HISTORY"
 265 These functions were added in OpenSSL 1.0.2.