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 . 173