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