Import a manual page for SSL_set1_host(3), which we already have since 6.5,

and for SSL_get0_peername(3), which tb@ will soon make available, from the OpenSSL 1.1.1 branch, which is still under a free license, deleting parts that do not apply to OpenBSD, and tweaked by me. Several improvements and OK by tb@.
author: schwarze <> 2020-09-17 07:56:38 +0000
committer: schwarze <> 2020-09-17 07:56:38 +0000
commit: eca320a8712112c5711439902e616353d0069121 (patch)
tree: cf305c21448150dd3afdc2172690277617a09c68
parent: 615363fd933cf5613a0c1380020975122fa025a8 (diff)
download: openbsd-eca320a8712112c5711439902e616353d0069121.tar.gz
openbsd-eca320a8712112c5711439902e616353d0069121.tar.bz2
openbsd-eca320a8712112c5711439902e616353d0069121.zip
1 files changed, 155 insertions, 0 deletions
diff --git a/src/lib/libssl/man/SSL_set1_host.3 b/src/lib/libssl/man/SSL_set1_host.3
new file mode 100644
index 0000000000..29623498f5
--- /dev/null
+++ b/src/lib/libssl/man/SSL_set1_host.3
@@ -0,0 +1,155 @@
+.\" $OpenBSD: SSL_set1_host.3,v 1.1 2020/09/17 07:56:38 schwarze Exp $
+.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200
+.\"
+.\" This file was written by Viktor Dukhovni <viktor@openssl.org>
+.\" Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: September 17 2020 $
+.Dt SSL_SET1_HOST 3
+.Os
+.Sh NAME
+.Nm SSL_set1_host ,
+.Nm SSL_get0_peername
+.Nd SSL server verification parameters
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft int
+.Fo SSL_set1_host
+.Fa "SSL *ssl"
+.Fa "const char *hostname"
+.Fc
+.Ft const char *
+.Fo SSL_get0_peername
+.Fa "SSL *ssl"
+.Fc
+.Sh DESCRIPTION
+.Fn SSL_set1_host
+configures a server hostname check in the
+.Fa ssl
+client, setting the expected DNS hostname to
+.Fa hostname
+and clearing any previously specified hostname.
+If
+.Fa hostname
+is
+.Dv NULL
+or the empty string, name checks are not performed on the peer certificate.
+If a nonempty
+.Fa hostname
+is specified, certificate verification automatically checks the peer
+hostname via
+.Xr X509_check_host 3
+with
+.Fa flags
+set to 0.
+.Pp
+.Fn SSL_get0_peername
+returns the DNS hostname or subject CommonName from the peer certificate
+that matched one of the reference identifiers.
+Unless wildcard matching is disabled, the name matched in the peer
+certificate may be a wildcard name.
+A reference identifier starting with
+.Sq \&.
+indicates a parent domain prefix rather than a fixed name.
+In this case, the matched peername may be a sub-domain
+of the reference identifier.
+The returned string is owned by the library and is no longer valid
+once the associated
+.Fa ssl
+object is cleared or freed, or if a renegotiation takes place.
+Applications must not free the return value.
+.Pp
+SSL clients are advised to use these functions in preference to
+explicitly calling
+.Xr X509_check_host 3 .
+.Sh RETURN VALUES
+.Fn SSL_set1_host
+returns 1 for success or 0 for failure.
+.Pp
+.Fn SSL_get0_peername
+returns the matched peername or
+.Dv NULL
+if peername verification is not applicable
+or no trusted peername was matched.
+Use
+.Xr SSL_get_verify_result 3
+to determine whether verification succeeded.
+.Sh EXAMPLES
+The calls below check the hostname.
+Wildcards are supported, but they must match the entire label.
+The actual name matched in the certificate (which might be a wildcard)
+is retrieved, and must be copied by the application if it is to be
+retained beyond the lifetime of the SSL connection.
+.Bd -literal
+if (!SSL_set1_host(ssl, "smtp.example.com"))
+        /* error */
+/* XXX: Perform SSL_connect() handshake and handle errors here */
+if (SSL_get_verify_result(ssl) == X509_V_OK) {
+        const char *peername = SSL_get0_peername(ssl);
+        if (peername != NULL)
+                /* Name checks were in scope and matched the peername */
+}
+.Ed
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_CTX_set_verify 3 ,
+.Xr SSL_get_peer_certificate 3 ,
+.Xr SSL_get_verify_result 3 ,
+.Xr X509_check_host 3 ,
+.Xr X509_VERIFY_PARAM_set1_host 3
+.Sh HISTORY
+Both functions first appeared in OpenSSL 1.1.0.
+.Fn SSL_set1_host
+has been available since
+.Ox 6.5 ,
+and
+.Fn SSL_get0_peername
+since
+.Ox 6.8 .
author	schwarze <>	2020-09-17 07:56:38 +0000
committer	schwarze <>	2020-09-17 07:56:38 +0000
commit	eca320a8712112c5711439902e616353d0069121 (patch)
tree	cf305c21448150dd3afdc2172690277617a09c68
parent	615363fd933cf5613a0c1380020975122fa025a8 (diff)
download	openbsd-eca320a8712112c5711439902e616353d0069121.tar.gz openbsd-eca320a8712112c5711439902e616353d0069121.tar.bz2 openbsd-eca320a8712112c5711439902e616353d0069121.zip

diff --git a/src/lib/libssl/man/SSL_set1_host.3 b/src/lib/libssl/man/SSL_set1_host.3 new file mode 100644 index 0000000000..29623498f5 --- /dev/null +++ b/src/lib/libssl/man/SSL_set1_host.3
@@ -0,0 +1,155 @@
	1	.\" $OpenBSD: SSL_set1_host.3,v 1.1 2020/09/17 07:56:38 schwarze 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: September 17 2020 $
	52	.Dt SSL_SET1_HOST 3
	53	.Os
	54	.Sh NAME
	55	.Nm SSL_set1_host ,
	56	.Nm SSL_get0_peername
	57	.Nd SSL server verification parameters
	58	.Sh SYNOPSIS
	59	.In openssl/ssl.h
	60	.Ft int
	61	.Fo SSL_set1_host
	62	.Fa "SSL *ssl"
	63	.Fa "const char *hostname"
	64	.Fc
	65	.Ft const char *
	66	.Fo SSL_get0_peername
	67	.Fa "SSL *ssl"
	68	.Fc
	69	.Sh DESCRIPTION
	70	.Fn SSL_set1_host
	71	configures a server hostname check in the
	72	.Fa ssl
	73	client, setting the expected DNS hostname to
	74	.Fa hostname
	75	and clearing any previously specified hostname.
	76	If
	77	.Fa hostname
	78	is
	79	.Dv NULL
	80	or the empty string, name checks are not performed on the peer certificate.
	81	If a nonempty
	82	.Fa hostname
	83	is specified, certificate verification automatically checks the peer
	84	hostname via
	85	.Xr X509_check_host 3
	86	with
	87	.Fa flags
	88	set to 0.
	89	.Pp
	90	.Fn SSL_get0_peername
	91	returns the DNS hostname or subject CommonName from the peer certificate
	92	that matched one of the reference identifiers.
	93	Unless wildcard matching is disabled, the name matched in the peer
	94	certificate may be a wildcard name.
	95	A reference identifier starting with
	96	.Sq \&.
	97	indicates a parent domain prefix rather than a fixed name.
	98	In this case, the matched peername may be a sub-domain
	99	of the reference identifier.
	100	The returned string is owned by the library and is no longer valid
	101	once the associated
	102	.Fa ssl
	103	object is cleared or freed, or if a renegotiation takes place.
	104	Applications must not free the return value.
	105	.Pp
	106	SSL clients are advised to use these functions in preference to
	107	explicitly calling
	108	.Xr X509_check_host 3 .
	109	.Sh RETURN VALUES
	110	.Fn SSL_set1_host
	111	returns 1 for success or 0 for failure.
	112	.Pp
	113	.Fn SSL_get0_peername
	114	returns the matched peername or
	115	.Dv NULL
	116	if peername verification is not applicable
	117	or no trusted peername was matched.
	118	Use
	119	.Xr SSL_get_verify_result 3
	120	to determine whether verification succeeded.
	121	.Sh EXAMPLES
	122	The calls below check the hostname.
	123	Wildcards are supported, but they must match the entire label.
	124	The actual name matched in the certificate (which might be a wildcard)
	125	is retrieved, and must be copied by the application if it is to be
	126	retained beyond the lifetime of the SSL connection.
	127	.Bd -literal
	128	if (!SSL_set1_host(ssl, "smtp.example.com"))
	129	/* error */
	130
	131	/* XXX: Perform SSL_connect() handshake and handle errors here */
	132
	133	if (SSL_get_verify_result(ssl) == X509_V_OK) {
	134	const char *peername = SSL_get0_peername(ssl);
	135
	136	if (peername != NULL)
	137	/* Name checks were in scope and matched the peername */
	138	}
	139	.Ed
	140	.Sh SEE ALSO
	141	.Xr ssl 3 ,
	142	.Xr SSL_CTX_set_verify 3 ,
	143	.Xr SSL_get_peer_certificate 3 ,
	144	.Xr SSL_get_verify_result 3 ,
	145	.Xr X509_check_host 3 ,
	146	.Xr X509_VERIFY_PARAM_set1_host 3
	147	.Sh HISTORY
	148	Both functions first appeared in OpenSSL 1.1.0.
	149	.Fn SSL_set1_host
	150	has been available since
	151	.Ox 6.5 ,
	152	and
	153	.Fn SSL_get0_peername
	154	since
	155	.Ox 6.8 .