secure/lib/libcrypto/man/SSL_set1_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 "SSL_SET1_HOST 3"
 132 .TH SSL_SET1_HOST 3 "2018-11-20" "1.1.1a" "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 SSL_set1_host, SSL_add1_host, SSL_set_hostflags, SSL_get0_peername \- SSL server verification parameters
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& int SSL_set1_host(SSL *s, const char *hostname);
 145 \& int SSL_add1_host(SSL *s, const char *hostname);
 146 \& void SSL_set_hostflags(SSL *s, unsigned int flags);
 147 \& const char *SSL_get0_peername(SSL *s);
 148 .Ve
 149 .SH "DESCRIPTION"
 150 .IX Header "DESCRIPTION"
 151 These functions configure server hostname checks in the \s-1SSL\s0 client.
 152 .PP
 153 \&\fISSL_set1_host()\fR sets the expected \s-1DNS\s0 hostname to \fBname\fR clearing
 154 any previously specified host name or names.  If \fBname\fR is \s-1NULL,\s0
 155 or the empty string the list of hostnames is cleared, and name
 156 checks are not performed on the peer certificate.  When a non-empty
 157 \&\fBname\fR is specified, certificate verification automatically checks
 158 the peer hostname via \fIX509_check_host\fR\|(3) with \fBflags\fR as specified
 159 via \fISSL_set_hostflags()\fR.  Clients that enable \s-1DANE TLSA\s0 authentication
 160 via \fISSL_dane_enable\fR\|(3) should leave it to that function to set
 161 the primary reference identifier of the peer, and should not call
 162 \&\fISSL_set1_host()\fR.
 163 .PP
 164 \&\fISSL_add1_host()\fR adds \fBname\fR as an additional reference identifier
 165 that can match the peer's certificate.  Any previous names set via
 166 \&\fISSL_set1_host()\fR or \fISSL_add1_host()\fR are retained, no change is made
 167 if \fBname\fR is \s-1NULL\s0 or empty.  When multiple names are configured,
 168 the peer is considered verified when any name matches.  This function
 169 is required for \s-1DANE TLSA\s0 in the presence of service name indirection
 170 via \s-1CNAME, MX\s0 or \s-1SRV\s0 records as specified in \s-1RFC7671, RFC7672\s0 or
 171 \&\s-1RFC7673.\s0
 172 .PP
 173 \&\fISSL_set_hostflags()\fR sets the \fBflags\fR that will be passed to
 174 \&\fIX509_check_host\fR\|(3) when name checks are applicable, by default
 175 the \fBflags\fR value is 0.  See \fIX509_check_host\fR\|(3) for the list
 176 of available flags and their meaning.
 177 .PP
 178 \&\fISSL_get0_peername()\fR returns the \s-1DNS\s0 hostname or subject CommonName
 179 from the peer certificate that matched one of the reference
 180 identifiers.  When wildcard matching is not disabled, the name
 181 matched in the peer certificate may be a wildcard name.  When one
 182 of the reference identifiers configured via \fISSL_set1_host()\fR or
 183 \&\fISSL_add1_host()\fR starts with \*(L".\*(R", which indicates a parent domain prefix
 184 rather than a fixed name, the matched peer name may be a sub-domain
 185 of the reference identifier.  The returned string is allocated by
 186 the library and is no longer valid once the associated \fBssl\fR handle
 187 is cleared or freed, or a renegotiation takes place.  Applications
 188 must not free the return value.
 189 .PP
 190 \&\s-1SSL\s0 clients are advised to use these functions in preference to
 191 explicitly calling \fIX509_check_host\fR\|(3).  Hostname checks may be out
 192 of scope with the \s-1RFC7671 \fIDANE\-EE\s0\fR\|(3) certificate usage, and the
 193 internal check will be suppressed as appropriate when \s-1DANE\s0 is
 194 enabled.
 195 .SH "RETURN VALUES"
 196 .IX Header "RETURN VALUES"
 197 \&\fISSL_set1_host()\fR and \fISSL_add1_host()\fR return 1 for success and 0 for
 198 failure.
 199 .PP
 200 \&\fISSL_get0_peername()\fR returns \s-1NULL\s0 if peername verification is not
 201 applicable (as with \s-1RFC7671 \fIDANE\-EE\s0\fR\|(3)), or no trusted peername was
 202 matched.  Otherwise, it returns the matched peername.  To determine
 203 whether verification succeeded call \fISSL_get_verify_result\fR\|(3).
 204 .SH "EXAMPLE"
 205 .IX Header "EXAMPLE"
 206 Suppose \*(L"smtp.example.com\*(R" is the \s-1MX\s0 host of the domain \*(L"example.com\*(R".
 207 The calls below will arrange to match either the \s-1MX\s0 hostname or the
 208 destination domain name in the \s-1SMTP\s0 server certificate.  Wildcards
 209 are supported, but must match the entire label.  The actual name
 210 matched in the certificate (which might be a wildcard) is retrieved,
 211 and must be copied by the application if it is to be retained beyond
 212 the lifetime of the \s-1SSL\s0 connection.
 213 .PP
 214 .Vb 5
 215 \& SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
 216 \& if (!SSL_set1_host(ssl, "smtp.example.com"))
 217 \&     /* error */
 218 \& if (!SSL_add1_host(ssl, "example.com"))
 219 \&     /* error */
 220 \&
 221 \& /* XXX: Perform SSL_connect() handshake and handle errors here */
 222 \&
 223 \& if (SSL_get_verify_result(ssl) == X509_V_OK) {
 224 \&     const char *peername = SSL_get0_peername(ssl);
 225 \&
 226 \&     if (peername != NULL)
 227 \&         /* Name checks were in scope and matched the peername */
 228 \& }
 229 .Ve
 230 .SH "SEE ALSO"
 231 .IX Header "SEE ALSO"
 232 \&\fIX509_check_host\fR\|(3),
 233 \&\fISSL_get_verify_result\fR\|(3).
 234 \&\fISSL_dane_enable\fR\|(3).
 235 .SH "HISTORY"
 236 .IX Header "HISTORY"
 237 These functions were first added to OpenSSL 1.1.0.
 238 .SH "COPYRIGHT"
 239 .IX Header "COPYRIGHT"
 240 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 241 .PP
 242 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 243 this file except in compliance with the License.  You can obtain a copy
 244 in the file \s-1LICENSE\s0 in the source distribution or at
 245 <https://www.openssl.org/source/license.html>.