186 lines
9.0 KiB
HTML
Executable File
186 lines
9.0 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>X509_check_host</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 certificate matching</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/x509v3.h></pre>
|
|
<pre>
|
|
int X509_check_host(X509 *, const char *name, size_t namelen,
|
|
unsigned int flags, char **peername);
|
|
int X509_check_email(X509 *, const char *address, size_t addresslen,
|
|
unsigned int flags);
|
|
int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen,
|
|
unsigned int flags);
|
|
int X509_check_ip_asc(X509 *, const char *address, unsigned int flags);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>The certificate matching functions are used to check whether a
|
|
certificate matches a given hostname, email address, or IP address.
|
|
The validity of the certificate and its trust level has to be checked by
|
|
other means.</p>
|
|
<p>X509_check_host() checks if the certificate Subject Alternative
|
|
Name (SAN) or Subject CommonName (CN) matches the specified host
|
|
name, which must be encoded in the preferred name syntax described
|
|
in section 3.5 of <a href="http://www.ietf.org/rfc/rfc1034.txt" class="rfc">RFC 1034</a>. By default, wildcards are supported
|
|
and they match only in the left-most label; but they may match
|
|
part of that label with an explicit prefix or suffix. For example,
|
|
by default, the host <strong>name</strong> "www.example.com" would match a
|
|
certificate with a SAN or CN value of "*.example.com", "w*.example.com"
|
|
or "*w.example.com".</p>
|
|
<p>Per section 6.4.2 of <a href="http://www.ietf.org/rfc/rfc6125.txt" class="rfc">RFC 6125</a>, <strong>name</strong> values representing international
|
|
domain names must be given in A-label form. The <strong>namelen</strong> argument
|
|
must be the number of characters in the name string or zero in which
|
|
case the length is calculated with strlen(<strong>name</strong>). When <strong>name</strong> starts
|
|
with a dot (e.g ".example.com"), it will be matched by a certificate
|
|
valid for any sub-domain of <strong>name</strong>, (see also
|
|
<strong>X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS</strong> below).</p>
|
|
<p>When the certificate is matched, and <strong>peername</strong> is not NULL, a
|
|
pointer to a copy of the matching SAN or CN from the peer certificate
|
|
is stored at the address passed in <strong>peername</strong>. The application
|
|
is responsible for freeing the peername via <code>OPENSSL_free()</code> when it
|
|
is no longer needed.</p>
|
|
<p>X509_check_email() checks if the certificate matches the specified
|
|
email <strong>address</strong>. Only the mailbox syntax of <a href="http://www.ietf.org/rfc/rfc822.txt" class="rfc">RFC 822</a> is supported,
|
|
comments are not allowed, and no attempt is made to normalize quoted
|
|
characters. The <strong>addresslen</strong> argument must be the number of
|
|
characters in the address string or zero in which case the length
|
|
is calculated with strlen(<strong>address</strong>).</p>
|
|
<p>X509_check_ip() checks if the certificate matches a specified IPv4 or
|
|
IPv6 address. The <strong>address</strong> array is in binary format, in network
|
|
byte order. The length is either 4 (IPv4) or 16 (IPv6). Only
|
|
explicitly marked addresses in the certificates are considered; IP
|
|
addresses stored in DNS names and Common Names are ignored.</p>
|
|
<p>X509_check_ip_asc() is similar, except that the NUL-terminated
|
|
string <strong>address</strong> is first converted to the internal representation.</p>
|
|
<p>The <strong>flags</strong> argument is usually 0. It can be the bitwise OR of the
|
|
flags:</p>
|
|
<dl>
|
|
<dt><strong><a name="x509_check_flag_always_check_subject" class="item"><strong>X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT</strong>,</a></strong></dt>
|
|
|
|
<dt><strong><a name="x509_check_flag_never_check_subject" class="item"><strong>X509_CHECK_FLAG_NEVER_CHECK_SUBJECT</strong>,</a></strong></dt>
|
|
|
|
<dt><strong><a name="x509_check_flag_no_wildcards" class="item"><strong>X509_CHECK_FLAG_NO_WILDCARDS</strong>,</a></strong></dt>
|
|
|
|
<dt><strong><a name="x509_check_flag_no_partial_wildcards" class="item"><strong>X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS</strong>,</a></strong></dt>
|
|
|
|
<dt><strong><a name="x509_check_flag_multi_label_wildcards" class="item"><strong>X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS</strong>.</a></strong></dt>
|
|
|
|
<dt><strong><a name="x509_check_flag_single_label_subdomains" class="item"><strong>X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS</strong>.</a></strong></dt>
|
|
|
|
</dl>
|
|
<p>The <strong>X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT</strong> flag causes the function
|
|
to consider the subject DN even if the certificate contains at least
|
|
one subject alternative name of the right type (DNS name or email
|
|
address as appropriate); the default is to ignore the subject DN
|
|
when at least one corresponding subject alternative names is present.</p>
|
|
<p>The <strong>X509_CHECK_FLAG_NEVER_CHECK_SUBJECT</strong> flag causes the function to never
|
|
consider the subject DN even if the certificate contains no subject alternative
|
|
names of the right type (DNS name or email address as appropriate); the default
|
|
is to use the subject DN when no corresponding subject alternative names are
|
|
present.
|
|
If both <strong>X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT</strong> and
|
|
<strong>X509_CHECK_FLAG_NEVER_CHECK_SUBJECT</strong> are specified, the latter takes
|
|
precedence and the subject DN is not checked for matching names.</p>
|
|
<p>If set, <strong>X509_CHECK_FLAG_NO_WILDCARDS</strong> disables wildcard
|
|
expansion; this only applies to <strong>X509_check_host</strong>.</p>
|
|
<p>If set, <strong>X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS</strong> suppresses support
|
|
for "*" as wildcard pattern in labels that have a prefix or suffix,
|
|
such as: "www*" or "*www"; this only applies to <strong>X509_check_host</strong>.</p>
|
|
<p>If set, <strong>X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS</strong> allows a "*" that
|
|
constitutes the complete label of a DNS name (e.g. "*.example.com")
|
|
to match more than one label in <strong>name</strong>; this flag only applies
|
|
to <strong>X509_check_host</strong>.</p>
|
|
<p>If set, <strong>X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS</strong> restricts <strong>name</strong>
|
|
values which start with ".", that would otherwise match any sub-domain
|
|
in the peer certificate, to only match direct child sub-domains.
|
|
Thus, for instance, with this flag set a <strong>name</strong> of ".example.com"
|
|
would match a peer certificate with a DNS name of "www.example.com",
|
|
but would not match a peer certificate with a DNS name of
|
|
"www.sub.example.com"; this flag only applies to <strong>X509_check_host</strong>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p>The functions return 1 for a successful match, 0 for a failed match
|
|
and -1 for an internal error: typically a memory allocation failure
|
|
or an ASN.1 decoding error.</p>
|
|
<p>All functions can also return -2 if the input is malformed. For example,
|
|
X509_check_host() returns -2 if the provided <strong>name</strong> contains embedded
|
|
NULs.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>Applications are encouraged to use X509_VERIFY_PARAM_set1_host()
|
|
rather than explicitly calling <em>X509_check_host(3)</em>. Hostname
|
|
checks may be out of scope with the DANE-EE(3) certificate usage,
|
|
and the internal checks will be suppressed as appropriate when
|
|
DANE support is enabled.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>SSL_get_verify_result(3)</em>,
|
|
<em>X509_VERIFY_PARAM_set1_host(3)</em>,
|
|
<em>X509_VERIFY_PARAM_add1_host(3)</em>,
|
|
<em>X509_VERIFY_PARAM_set1_email(3)</em>,
|
|
<em>X509_VERIFY_PARAM_set1_ip(3)</em>,
|
|
<em>X509_VERIFY_PARAM_set1_ipasc(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>These functions were added in OpenSSL 1.0.2.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2012-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|