1289848Sjkim=pod 2289848Sjkim 3289848Sjkim=head1 NAME 4289848Sjkim 5289848SjkimX509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 certificate matching 6289848Sjkim 7289848Sjkim=head1 SYNOPSIS 8289848Sjkim 9289848Sjkim #include <openssl/x509.h> 10289848Sjkim 11289848Sjkim int X509_check_host(X509 *, const char *name, size_t namelen, 12289848Sjkim unsigned int flags, char **peername); 13289848Sjkim int X509_check_email(X509 *, const char *address, size_t addresslen, 14289848Sjkim unsigned int flags); 15289848Sjkim int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen, 16289848Sjkim unsigned int flags); 17289848Sjkim int X509_check_ip_asc(X509 *, const char *address, unsigned int flags); 18289848Sjkim 19289848Sjkim=head1 DESCRIPTION 20289848Sjkim 21289848SjkimThe certificate matching functions are used to check whether a 22289848Sjkimcertificate matches a given host name, email address, or IP address. 23289848SjkimThe validity of the certificate and its trust level has to be checked by 24289848Sjkimother means. 25289848Sjkim 26289848SjkimX509_check_host() checks if the certificate Subject Alternative 27289848SjkimName (SAN) or Subject CommonName (CN) matches the specified host 28289848Sjkimname, which must be encoded in the preferred name syntax described 29289848Sjkimin section 3.5 of RFC 1034. By default, wildcards are supported 30289848Sjkimand they match only in the left-most label; but they may match 31289848Sjkimpart of that label with an explicit prefix or suffix. For example, 32289848Sjkimby default, the host B<name> "www.example.com" would match a 33289848Sjkimcertificate with a SAN or CN value of "*.example.com", "w*.example.com" 34289848Sjkimor "*w.example.com". 35289848Sjkim 36289848SjkimPer section 6.4.2 of RFC 6125, B<name> values representing international 37289848Sjkimdomain names must be given in A-label form. The B<namelen> argument 38289848Sjkimmust be the number of characters in the name string or zero in which 39289848Sjkimcase the length is calculated with strlen(B<name>). When B<name> starts 40289848Sjkimwith a dot (e.g ".example.com"), it will be matched by a certificate 41289848Sjkimvalid for any sub-domain of B<name>, (see also 42289848SjkimB<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> below). 43289848Sjkim 44289848SjkimWhen the certificate is matched, and B<peername> is not NULL, a 45289848Sjkimpointer to a copy of the matching SAN or CN from the peer certificate 46289848Sjkimis stored at the address passed in B<peername>. The application 47289848Sjkimis responsible for freeing the peername via OPENSSL_free() when it 48289848Sjkimis no longer needed. 49289848Sjkim 50289848SjkimX509_check_email() checks if the certificate matches the specified 51289848Sjkimemail B<address>. Only the mailbox syntax of RFC 822 is supported, 52289848Sjkimcomments are not allowed, and no attempt is made to normalize quoted 53289848Sjkimcharacters. The B<addresslen> argument must be the number of 54289848Sjkimcharacters in the address string or zero in which case the length 55289848Sjkimis calculated with strlen(B<address>). 56289848Sjkim 57289848SjkimX509_check_ip() checks if the certificate matches a specified IPv4 or 58289848SjkimIPv6 address. The B<address> array is in binary format, in network 59289848Sjkimbyte order. The length is either 4 (IPv4) or 16 (IPv6). Only 60289848Sjkimexplicitly marked addresses in the certificates are considered; IP 61289848Sjkimaddresses stored in DNS names and Common Names are ignored. 62289848Sjkim 63289848SjkimX509_check_ip_asc() is similar, except that the NUL-terminated 64289848Sjkimstring B<address> is first converted to the internal representation. 65289848Sjkim 66289848SjkimThe B<flags> argument is usually 0. It can be the bitwise OR of the 67289848Sjkimflags: 68289848Sjkim 69289848Sjkim=over 4 70289848Sjkim 71289848Sjkim=item B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>, 72289848Sjkim 73289848Sjkim=item B<X509_CHECK_FLAG_NO_WILDCARDS>, 74289848Sjkim 75289848Sjkim=item B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS>, 76289848Sjkim 77289848Sjkim=item B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS>. 78289848Sjkim 79289848Sjkim=item B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS>. 80289848Sjkim 81289848Sjkim=back 82289848Sjkim 83289848SjkimThe B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT> flag causes the function 84289848Sjkimto consider the subject DN even if the certificate contains at least 85289848Sjkimone subject alternative name of the right type (DNS name or email 86289848Sjkimaddress as appropriate); the default is to ignore the subject DN 87289848Sjkimwhen at least one corresponding subject alternative names is present. 88289848Sjkim 89289848SjkimIf set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard 90289848Sjkimexpansion; this only applies to B<X509_check_host>. 91289848Sjkim 92289848SjkimIf set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support 93289848Sjkimfor "*" as wildcard pattern in labels that have a prefix or suffix, 94289848Sjkimsuch as: "www*" or "*www"; this only aplies to B<X509_check_host>. 95289848Sjkim 96289848SjkimIf set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that 97289848Sjkimconstitutes the complete label of a DNS name (e.g. "*.example.com") 98289848Sjkimto match more than one label in B<name>; this flag only applies 99289848Sjkimto B<X509_check_host>. 100289848Sjkim 101289848SjkimIf set, B<X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS> restricts B<name> 102289848Sjkimvalues which start with ".", that would otherwise match any sub-domain 103289848Sjkimin the peer certificate, to only match direct child sub-domains. 104289848SjkimThus, for instance, with this flag set a B<name> of ".example.com" 105289848Sjkimwould match a peer certificate with a DNS name of "www.example.com", 106289848Sjkimbut would not match a peer certificate with a DNS name of 107289848Sjkim"www.sub.example.com"; this flag only applies to B<X509_check_host>. 108289848Sjkim 109289848Sjkim=head1 RETURN VALUES 110289848Sjkim 111289848SjkimThe functions return 1 for a successful match, 0 for a failed match 112289848Sjkimand -1 for an internal error: typically a memory allocation failure 113289848Sjkimor an ASN.1 decoding error. 114289848Sjkim 115289848SjkimAll functions can also return -2 if the input is malformed. For example, 116289848SjkimX509_check_host() returns -2 if the provided B<name> contains embedded 117289848SjkimNULs. 118289848Sjkim 119289848Sjkim=head1 NOTES 120289848Sjkim 121289848SjkimApplications are encouraged to use X509_VERIFY_PARAM_set1_host() 122289848Sjkimrather than explicitly calling L<X509_check_host(3)>. Host name 123289848Sjkimchecks are out of scope with the DANE-EE(3) certificate usage, 124289848Sjkimand the internal checks will be suppressed as appropriate when 125289848SjkimDANE support is added to OpenSSL. 126289848Sjkim 127289848Sjkim=head1 SEE ALSO 128289848Sjkim 129289848SjkimL<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, 130289848SjkimL<X509_VERIFY_PARAM_set1_host(3)|X509_VERIFY_PARAM_set1_host(3)>, 131289848SjkimL<X509_VERIFY_PARAM_add1_host(3)|X509_VERIFY_PARAM_add1_host(3)>, 132289848SjkimL<X509_VERIFY_PARAM_set1_email(3)|X509_VERIFY_PARAM_set1_email(3)>, 133289848SjkimL<X509_VERIFY_PARAM_set1_ip(3)|X509_VERIFY_PARAM_set1_ip(3)>, 134289848SjkimL<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)> 135289848Sjkim 136289848Sjkim=head1 HISTORY 137289848Sjkim 138291719SjkimThese functions were added in OpenSSL 1.0.2. 139289848Sjkim 140289848Sjkim=cut 141