1.\" $OpenBSD: X509_check_host.3,v 1.4 2019/06/06 01:06:59 schwarze Exp $ 2.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file was written by Florian Weimer <fweimer@redhat.com> and 5.\" Viktor Dukhovni <openssl-users@dukhovni.org>. 6.\" Copyright (c) 2012, 2014, 2015, 2016 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: June 6 2019 $ 53.Dt X509_CHECK_HOST 3 54.Os 55.Sh NAME 56.Nm X509_check_host , 57.Nm X509_check_email , 58.Nm X509_check_ip , 59.Nm X509_check_ip_asc 60.Nd X.509 certificate matching 61.Sh SYNOPSIS 62.In openssl/x509v3.h 63.Ft int 64.Fo X509_check_host 65.Fa "X509 *x" 66.Fa "const char *name" 67.Fa "size_t namelen" 68.Fa "unsigned int flags" 69.Fa "char **peername" 70.Fc 71.Ft int 72.Fo X509_check_email 73.Fa "X509 *x" 74.Fa "const char *address" 75.Fa "size_t addresslen" 76.Fa "unsigned int flags" 77.Fc 78.Ft int 79.Fo X509_check_ip 80.Fa "X509 *x" 81.Fa "const unsigned char *address" 82.Fa "size_t addresslen" 83.Fa "unsigned int flags" 84.Fc 85.Ft int 86.Fo X509_check_ip_asc 87.Fa "X509 *x" 88.Fa "const char *address" 89.Fa "unsigned int flags" 90.Fc 91.Sh DESCRIPTION 92The certificate matching functions are used to check whether a 93certificate matches a given host name, email address, or IP address. 94The validity of the certificate and its trust level has to be checked by 95other means. 96.Pp 97.Fn X509_check_host 98checks if the certificate Subject Alternative Name (SAN) or Subject 99CommonName (CN) matches the specified host name, which must be encoded 100in the preferred name syntax described in section 3.5 of RFC 1034. 101By default, wildcards are supported and they match only in the 102left-most label; they may match part of that label with an 103explicit prefix or suffix. 104For example, by default, the host 105.Fa name 106.Qq www.example.com 107would match a certificate with a SAN or CN value of 108.Qq *.example.com , 109.Qq w*.example.com 110or 111.Qq *w.example.com . 112.Pp 113Per section 6.4.2 of RFC 6125, 114.Fa name 115values representing international domain names must be given in A-label 116form. 117The 118.Fa namelen 119argument must be the number of characters in the name string or zero, in 120which case the length is calculated with 121.Fn strlen name . 122When 123.Fa name 124starts with a dot (e.g.\& 125.Qq .example.com ) , 126it will be matched by a certificate valid for any sub-domain of 127.Fa name ; 128see also 129.Fa X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS 130below. 131.Pp 132When the certificate is matched and 133.Fa peername 134is not 135.Dv NULL , 136a pointer to a copy of the matching SAN or CN from the peer 137certificate is stored at the address passed in 138.Fa peername . 139The application is responsible for freeing the peername via 140.Xr free 3 141when it is no longer needed. 142.Pp 143.Fn X509_check_email 144checks if the certificate matches the specified email 145.Fa address . 146Only the mailbox syntax of RFC 822 is supported. 147Comments are not allowed, 148and no attempt is made to normalize quoted characters. 149The 150.Fa addresslen 151argument must be the number of characters in the address string or zero, 152in which case the length is calculated with 153.Fn strlen address . 154.Pp 155.Fn X509_check_ip 156checks if the certificate matches a specified IPv4 or IPv6 address. 157The 158.Fa address 159array is in binary format, in network byte order. 160The length is either 4 (IPv4) or 16 (IPv6). 161Only explicitly marked addresses in the certificates are considered; 162IP addresses stored in DNS names and Common Names are ignored. 163.Pp 164.Fn X509_check_ip_asc 165is similar, except that the NUL-terminated string 166.Fa address 167is first converted to the internal representation. 168.Pp 169The 170.Fa flags 171argument is usually 0, but it can be the bitwise OR of the following 172flags. 173.Pp 174The 175.Dv X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT 176flag causes the function to consider the subject DN even if the 177certificate contains at least one subject alternative name of the right 178type (DNS name or email address as appropriate); the default is to 179ignore the subject DN when at least one corresponding subject 180alternative names is present. 181.Pp 182The remaining flags are only meaningful for 183.Fn X509_check_host . 184.Pp 185The 186.Dv X509_CHECK_FLAG_NO_WILDCARDS 187flag disables wildcard expansion. 188.Pp 189The 190.Dv X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS 191flag suppresses support for 192.Qq * 193as a wildcard pattern in labels that have a 194prefix or suffix, such as 195.Qq www* 196or 197.Qq *www . 198.Pp 199The 200.Dv X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS 201flag allows a 202.Qq * 203that constitutes the complete label of a DNS name (e.g.\& 204.Qq *.example.com ) 205to match more than one label in 206.Fa name . 207.Pp 208The 209.Dv X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS 210flag restricts 211.Fa name 212values which start with 213.Qq \&. , 214that would otherwise match any sub-domain in the peer certificate, 215to only match direct child sub-domains. 216Thus, for instance, with this flag set a 217.Fa name 218of 219.Qq .example.com 220would match a peer certificate with a DNS name of 221.Qq www.example.com , 222but would not match a peer certificate with a DNS name of 223.Qq www.sub.example.com . 224.Sh RETURN VALUES 225The functions return 1 for a successful match, 0 for a failed match and 226-1 for an internal error: typically a memory allocation failure or an 227ASN.1 decoding error. 228.Pp 229All functions can also return -2 if the input is malformed. 230For example, 231.Fn X509_check_host 232returns -2 if the provided 233.Fa name 234contains embedded NUL bytes. 235.Sh SEE ALSO 236.Xr X509_EXTENSION_new 3 , 237.Xr X509_new 3 238.Sh HISTORY 239These functions first appeared in OpenSSL 1.0.2 240and have been available since 241.Ox 6.1 . 242