summaryrefslogtreecommitdiff
path: root/src/lib/libssl/man/SSL_set1_host.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libssl/man/SSL_set1_host.3172
1 files changed, 0 insertions, 172 deletions
diff --git a/src/lib/libssl/man/SSL_set1_host.3 b/src/lib/libssl/man/SSL_set1_host.3
deleted file mode 100644
index 2a3935c3f2..0000000000
--- a/src/lib/libssl/man/SSL_set1_host.3
+++ /dev/null
@@ -1,172 +0,0 @@
1.\" $OpenBSD: SSL_set1_host.3,v 1.4 2021/03/31 16:56:46 tb Exp $
2.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200
3.\"
4.\" This file was written by Viktor Dukhovni <viktor@openssl.org>
5.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in
16.\" the documentation and/or other materials provided with the
17.\" distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\" software must display the following acknowledgment:
21.\" "This product includes software developed by the OpenSSL Project
22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\" endorse or promote products derived from this software without
26.\" prior written permission. For written permission, please contact
27.\" openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\" nor may "OpenSSL" appear in their names without prior written
31.\" permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\" acknowledgment:
35.\" "This product includes software developed by the OpenSSL Project
36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: March 31 2021 $
52.Dt SSL_SET1_HOST 3
53.Os
54.Sh NAME
55.Nm SSL_set1_host ,
56.Nm SSL_set_hostflags ,
57.Nm SSL_get0_peername
58.Nd SSL server verification parameters
59.Sh SYNOPSIS
60.In openssl/ssl.h
61.Ft int
62.Fo SSL_set1_host
63.Fa "SSL *ssl"
64.Fa "const char *hostname"
65.Fc
66.Ft void
67.Fo SSL_set_hostflags
68.Fa "SSL *ssl"
69.Fa "unsigned int flags"
70.Fc
71.Ft const char *
72.Fo SSL_get0_peername
73.Fa "SSL *ssl"
74.Fc
75.Sh DESCRIPTION
76.Fn SSL_set1_host
77configures a server hostname check in the
78.Fa ssl
79client, setting the expected DNS hostname to
80.Fa hostname
81and clearing any previously specified hostname.
82If
83.Fa hostname
84is
85.Dv NULL
86or the empty string, name checks are not performed on the peer certificate.
87If a nonempty
88.Fa hostname
89is specified, certificate verification automatically checks the peer
90hostname via
91.Xr X509_check_host 3
92with
93.Fa flags
94set to 0.
95.Pp
96.Fn SSL_set_hostflags
97sets the flags that will be passed to
98.Xr X509_check_host 3
99when name checks are applicable,
100by default the flags value is 0.
101See
102.Xr X509_check_host 3
103for the list of available flags and their meaning.
104.Pp
105.Fn SSL_get0_peername
106returns the DNS hostname or subject CommonName from the peer certificate
107that matched one of the reference identifiers.
108Unless wildcard matching is disabled, the name matched in the peer
109certificate may be a wildcard name.
110A reference identifier starting with
111.Sq \&.
112indicates a parent domain prefix rather than a fixed name.
113In this case, the matched peername may be a sub-domain
114of the reference identifier.
115The returned string is owned by the library and is no longer valid
116once the associated
117.Fa ssl
118object is cleared or freed, or if a renegotiation takes place.
119Applications must not free the return value.
120.Pp
121SSL clients are advised to use these functions in preference to
122explicitly calling
123.Xr X509_check_host 3 .
124.Sh RETURN VALUES
125.Fn SSL_set1_host
126returns 1 for success or 0 for failure.
127.Pp
128.Fn SSL_get0_peername
129returns the matched peername or
130.Dv NULL
131if peername verification is not applicable
132or no trusted peername was matched.
133Use
134.Xr SSL_get_verify_result 3
135to determine whether verification succeeded.
136.Sh EXAMPLES
137The calls below check the hostname.
138Wildcards are supported, but they must match the entire label.
139The actual name matched in the certificate (which might be a wildcard)
140is retrieved, and must be copied by the application if it is to be
141retained beyond the lifetime of the SSL connection.
142.Bd -literal
143if (!SSL_set1_host(ssl, "smtp.example.com"))
144 /* error */
145
146/* XXX: Perform SSL_connect() handshake and handle errors here */
147
148if (SSL_get_verify_result(ssl) == X509_V_OK) {
149 const char *peername = SSL_get0_peername(ssl);
150
151 if (peername != NULL)
152 /* Name checks were in scope and matched the peername */
153}
154.Ed
155.Sh SEE ALSO
156.Xr ssl 3 ,
157.Xr SSL_CTX_set_verify 3 ,
158.Xr SSL_get_peer_certificate 3 ,
159.Xr SSL_get_verify_result 3 ,
160.Xr X509_check_host 3 ,
161.Xr X509_VERIFY_PARAM_set1_host 3
162.Sh HISTORY
163All three functions first appeared in OpenSSL 1.1.0.
164.Fn SSL_set1_host
165has been available since
166.Ox 6.5 ,
167and
168.Fn SSL_set_hostflags
169and
170.Fn SSL_get0_peername
171since
172.Ox 6.9 .