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