NAME
X509_VERIFY_PARAM_get0_name
,
X509_VERIFY_PARAM_set1_name
,
X509_VERIFY_PARAM_set_flags
,
X509_VERIFY_PARAM_clear_flags
,
X509_VERIFY_PARAM_get_flags
,
X509_VERIFY_PARAM_set_purpose
,
X509_VERIFY_PARAM_set_trust
,
X509_VERIFY_PARAM_set_time
,
X509_VERIFY_PARAM_add0_policy
,
X509_VERIFY_PARAM_set1_policies
,
X509_VERIFY_PARAM_set_depth
,
X509_VERIFY_PARAM_get_depth
,
X509_VERIFY_PARAM_set1_host
,
X509_VERIFY_PARAM_add1_host
,
X509_VERIFY_PARAM_set_hostflags
,
X509_VERIFY_PARAM_get0_peername
,
X509_VERIFY_PARAM_set1_email
,
X509_VERIFY_PARAM_set1_ip
,
X509_VERIFY_PARAM_set1_ip_asc
—
X509 verification parameters
SYNOPSIS
#include
<openssl/x509_vfy.h>
const char *
X509_VERIFY_PARAM_get0_name
(const
X509_VERIFY_PARAM *param);
int
X509_VERIFY_PARAM_set1_name
(X509_VERIFY_PARAM
*param, const char *name);
int
X509_VERIFY_PARAM_set_flags
(X509_VERIFY_PARAM
*param, unsigned long flags);
int
X509_VERIFY_PARAM_clear_flags
(X509_VERIFY_PARAM
*param, unsigned long flags);
unsigned long
X509_VERIFY_PARAM_get_flags
(X509_VERIFY_PARAM
*param);
int
X509_VERIFY_PARAM_set_purpose
(X509_VERIFY_PARAM
*param, int purpose);
int
X509_VERIFY_PARAM_set_trust
(X509_VERIFY_PARAM
*param, int trust);
void
X509_VERIFY_PARAM_set_time
(X509_VERIFY_PARAM
*param, time_t t);
int
X509_VERIFY_PARAM_add0_policy
(X509_VERIFY_PARAM
*param, ASN1_OBJECT *policy);
int
X509_VERIFY_PARAM_set1_policies
(X509_VERIFY_PARAM
*param, STACK_OF(ASN1_OBJECT) *policies);
void
X509_VERIFY_PARAM_set_depth
(X509_VERIFY_PARAM
*param, int depth);
int
X509_VERIFY_PARAM_get_depth
(const
X509_VERIFY_PARAM *param);
int
X509_VERIFY_PARAM_set1_host
(X509_VERIFY_PARAM
*param, const char *name, size_t
namelen);
int
X509_VERIFY_PARAM_add1_host
(X509_VERIFY_PARAM
*param, const char *name, size_t
namelen);
void
X509_VERIFY_PARAM_set_hostflags
(X509_VERIFY_PARAM
*param, unsigned int flags);
char *
X509_VERIFY_PARAM_get0_peername
(X509_VERIFY_PARAM
*param);
int
X509_VERIFY_PARAM_set1_email
(X509_VERIFY_PARAM
*param, const char *email,
size_t emaillen);
int
X509_VERIFY_PARAM_set1_ip
(X509_VERIFY_PARAM
*param, const unsigned char *ip,
size_t iplen);
int
X509_VERIFY_PARAM_set1_ip_asc
(X509_VERIFY_PARAM
*param, const char *ipasc);
DESCRIPTION
These functions manipulate an X509_VERIFY_PARAM object associated with a certificate verification operation.
X509_VERIFY_PARAM_get0_name
()
returns the name of the given param object, usually
describing its purpose, for example "default", "pkcs7",
"smime_sign", "ssl_client", or "ssl_server".
For user-defined objects, the returned pointer may be
NULL
even if the object is otherwise valid.
X509_VERIFY_PARAM_set1_name
()
sets the name of param to a copy of
name, or to NULL
if
name is NULL
.
X509_VERIFY_PARAM_set_flags
()
sets the flags in param by OR'ing it with
flags. See the
VERIFICATION FLAGS section for
a complete description of values the flags parameter
can take.
If the flags argument includes any of the
flags contained in X509_V_FLAG_POLICY_MASK
, that is,
any of X509_V_FLAG_POLICY_CHECK
,
X509_V_FLAG_EXPLICIT_POLICY
,
X509_V_FLAG_INHIBIT_ANY
, and
X509_V_FLAG_INHIBIT_MAP
, then
X509_V_FLAG_POLICY_CHECK
is set in addition to the
flags contained in the flags argument.
X509_VERIFY_PARAM_get_flags
()
returns the flags in param.
X509_VERIFY_PARAM_clear_flags
()
clears the specified flags in
param.
Calling this function can result in unusual internal states of the
param object, for example having a verification time
configured but having X509_V_FLAG_USE_CHECK_TIME
unset, or having X509_V_FLAG_EXPLICIT_POLICY
set but
X509_V_FLAG_POLICY_CHECK
unset, which may have
surprising effects.
X509_VERIFY_PARAM_set_purpose
()
sets the verification purpose identifier in
param. This determines the acceptable purpose of the
certificate chain, for example
X509_PURPOSE_SSL_CLIENT
or
X509_PURPOSE_SSL_SERVER
. Standard purposes are
listed in
X509_check_purpose(3), and additional purposes can be defined
with
X509_PURPOSE_add(3).
X509_VERIFY_PARAM_set_trust
()
sets the trust setting in param to
trust.
X509_VERIFY_PARAM_set_time
()
sets the flag X509_V_FLAG_USE_CHECK_TIME
in
param in addition to the flags already set and sets
the verification time to t. If this function is not
called, the current time is used instead, or the UNIX Epoch (January 1,
1970) if X509_V_FLAG_USE_CHECK_TIME
is manually set
using X509_VERIFY_PARAM_set_flags
().
X509_VERIFY_PARAM_add0_policy
()
enables policy checking (it is disabled by default) and adds
policy to the acceptable policy set.
X509_VERIFY_PARAM_set1_policies
()
enables policy checking (it is disabled by default) and sets the acceptable
policy set to policies. Any existing policy set is
cleared. The policies parameter can be
NULL
to clear an existing policy set.
X509_VERIFY_PARAM_set_depth
()
sets the maximum verification depth to depth. That is
the maximum number of untrusted CA certificates that can appear in a
chain.
X509_VERIFY_PARAM_set1_host
()
sets the expected DNS hostname to name clearing any
previously specified hostname or names. If name is
NULL
or empty, the list of hostnames is cleared, and
name checks are not performed on the peer certificate.
namelen should be set to the length of
name. For historical compatibility, if
name is NUL-terminated, namelen
may be specified as zero. When a hostname is specified, certificate
verification automatically invokes
X509_check_host(3) with flags equal to the
flags argument given to
X509_VERIFY_PARAM_set_hostflags
()
(default zero). X509_VERIFY_PARAM_set1_host
() will
fail if name contains any embedded 0 bytes.
X509_VERIFY_PARAM_add1_host
()
adds name as an additional reference identifier that
can match the peer's certificate. Any previous names set via
X509_VERIFY_PARAM_set1_host
() and
X509_VERIFY_PARAM_add1_host
() are retained. No
change is made if name is NULL
or empty. namelen should be set to the length of
name. For historical compatibility, if
name is NUL-terminated, namelen
may be specified as zero.
X509_VERIFY_PARAM_add1_host
() will fail if
name contains any embedded 0 bytes. When multiple
names are configured, the peer is considered verified when any name
matches.
X509_VERIFY_PARAM_get0_peername
()
returns the DNS hostname or subject CommonName from the peer certificate
that matched one of the reference identifiers. When wildcard matching is not
disabled, or when a reference identifier specifies a parent domain (starts
with ".") rather than a hostname, the peer name may be a wildcard
name or a sub-domain of the reference identifier respectively.
X509_VERIFY_PARAM_set1_email
()
sets the expected RFC 822 email address to email.
emaillen should be set to the length of
email. For historical compatibility, if
email is NUL-terminated,
emaillen may be specified as zero,
X509_VERIFY_PARAM_set1_email
() will fail if
email is NULL, an empty string, or contains embedded 0
bytes. When an email address is specified, certificate verification
automatically invokes
X509_check_email(3).
X509_VERIFY_PARAM_set1_ip
()
sets the expected IP address to ip. The
ip argument is in binary format, in network
byte-order, and iplen must be set to 4 for IPv4 and 16
for IPv6. X509_VERIFY_PARAM_set1_ip
() will fail if
ip is NULL or if iplen is not 4
or 16. When an IP address is specified, certificate verification
automatically invokes
X509_check_ip(3).
X509_VERIFY_PARAM_set1_ip_asc
()
sets the expected IP address to ipasc. The
ipasc argument is a NUL-terminal ASCII string: dotted
decimal quad for IPv4 and colon-separated hexadecimal for IPv6. The
condensed "::" notation is supported for IPv6 addresses.
X509_VERIFY_PARAM_set1_ip_asc
() will fail if
ipasc is unparsable.
RETURN VALUES
X509_VERIFY_PARAM_set1_name
(),
X509_VERIFY_PARAM_set_flags
(),
X509_VERIFY_PARAM_clear_flags
(),
X509_VERIFY_PARAM_set_purpose
(),
X509_VERIFY_PARAM_set_trust
(),
X509_VERIFY_PARAM_add0_policy
(), and
X509_VERIFY_PARAM_set1_policies
() return 1 for
success or 0 for failure.
X509_VERIFY_PARAM_set1_host
(),
X509_VERIFY_PARAM_add1_host
(),
X509_VERIFY_PARAM_set1_email
(),
X509_VERIFY_PARAM_set1_ip
(), and
X509_VERIFY_PARAM_set1_ip_asc
() return 1 for success
or 0 for failure. A failure from these routines will poison the
X509_VERIFY_PARAM object so that future calls to
X509_verify_cert(3) using the poisoned object will fail.
X509_VERIFY_PARAM_get_flags
() returns the
current verification flags.
X509_VERIFY_PARAM_get_depth
() returns the
current verification depth.
X509_VERIFY_PARAM_get0_name
() and
X509_VERIFY_PARAM_get0_peername
() return pointers to
strings that are only valid during the lifetime of the given
param object and that must not be freed by the
application program.
VERIFICATION FLAGS
The verification flags consists of zero or more of the following flags OR'ed together.
X509_V_FLAG_CRL_CHECK
enables CRL checking
for the certificate chain leaf certificate. An error occurs if a suitable
CRL cannot be found.
X509_V_FLAG_CRL_CHECK_ALL
enables CRL
checking for the entire certificate chain.
X509_V_FLAG_IGNORE_CRITICAL
disables critical extension checking. By default any unhandled critical
extensions in certificates or (if checked) CRLs results in a fatal error. If
this flag is set, unhandled critical extensions are ignored.
WARNING: setting
this option for anything other than debugging purposes can be a security
risk. Finer control over which extensions are supported can be performed in
the verification callback.
The X509_V_FLAG_X509_STRICT
flag disables
workarounds for some broken certificates and makes the verification strictly
apply X509 rules.
X509_V_FLAG_ALLOW_PROXY_CERTS
enables
proxy certificate verification.
X509_V_FLAG_POLICY_CHECK
enables
certificate policy checking; by default no policy checking is performed.
Additional information is sent to the verification callback relating to
policy checking.
X509_V_FLAG_EXPLICIT_POLICY
,
X509_V_FLAG_INHIBIT_ANY
, and
X509_V_FLAG_INHIBIT_MAP
set the “require
explicit policy”, “inhibit any policy”, and
“inhibit policy mapping” flags, respectively, as defined in
RFC 3280. These three flags are ignored unless
X509_V_FLAG_POLICY_CHECK
is also set.
If X509_V_FLAG_NOTIFY_POLICY
is set and
policy checking is successful, a special status code is sent to the
verification callback. This permits it to examine the valid policy tree and
perform additional checks or simply log it for debugging purposes.
By default some additional features such as indirect CRLs and CRLs
signed by different keys are disabled. If
X509_V_FLAG_EXTENDED_CRL_SUPPORT
is set, they are
enabled.
If X509_V_FLAG_USE_DELTAS
is set, delta
CRLs (if present) are used to determine certificate status. If not set,
deltas are ignored.
X509_V_FLAG_CHECK_SS_SIGNATURE
enables
checking of the root CA self signed certificate signature. By default this
check is disabled because it doesn't add any additional security but in some
cases applications might want to check the signature anyway. A side effect
of not checking the root CA signature is that disabled or unsupported
message digests on the root CA are not treated as fatal errors.
The X509_V_FLAG_CB_ISSUER_CHECK
flag enables debugging of certificate issuer checks. It is
not needed unless you
are logging certificate verification. If this flag is set then additional
status codes will be sent to the verification callback and it
must be
prepared to handle such cases without assuming they are hard errors.
When X509_V_FLAG_TRUSTED_FIRST
is set,
construction of the certificate chain in
X509_verify_cert(3) will search the trust store for issuer
certificates before searching the provided untrusted certificates. Local
issuer certificates are often more likely to satisfy local security
requirements and lead to a locally trusted root. This is especially
important when some certificates in the trust store have explicit trust
settings; see the trust settings options of the x509
command in openssl(1).
The X509_V_FLAG_NO_ALT_CHAINS
flag
suppresses checking for alternative chains. By default, unless
X509_V_FLAG_TRUSTED_FIRST
is set, when building a
certificate chain, if the first certificate chain found is not trusted, then
OpenSSL will attempt to replace untrusted certificates supplied by the peer
with certificates from the trust store to see if an alternative chain can be
found that is trusted.
The X509_V_FLAG_PARTIAL_CHAIN
flag causes
intermediate certificates in the trust store to be treated as trust-anchors,
in the same way as the self-signed root CA certificates. This makes it
possible to trust certificates issued by an intermediate CA without having
to trust its ancestor root CA.
If
X509_V_FLAG_USE_CHECK_TIME
is set, the validity
period of certificates and CRLs is checked. In this case,
X509_V_FLAG_NO_CHECK_TIME
is ignored. If the
validation time was set with
X509_VERIFY_PARAM_set_time
(),
that time is used. If X509_VERIFY_PARAM_set_time
()
was not called, the UNIX Epoch (January 1, 1970) is used.
If neither
X509_V_FLAG_USE_CHECK_TIME
nor
X509_V_FLAG_NO_CHECK_TIME
is set, the validity
period of certificates and CRLs is checked using the current time. This is
the default behaviour. In this case, if a validation time was set with
X509_VERIFY_PARAM_set_time
()
but X509_V_FLAG_USE_CHECK_TIME
was later cleared
with X509_VERIFY_PARAM_clear_flags
(), the configured
validation time is ignored and the current time is used anyway.
If X509_V_FLAG_USE_CHECK_TIME
is not set
but X509_V_FLAG_NO_CHECK_TIME
is set, the validity
period of certificates and CRLs is not checked at all, and like in the
previous case, any configured validation time is ignored.
EXAMPLES
Enable CRL checking when performing certificate verification during SSL connections associated with an SSL_CTX structure ctx:
X509_VERIFY_PARAM *param; param = X509_VERIFY_PARAM_new(); X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); SSL_CTX_set1_param(ctx, param); X509_VERIFY_PARAM_free(param);
SEE ALSO
SSL_set1_host(3), SSL_set1_param(3), X509_check_host(3), X509_STORE_CTX_new(3), X509_STORE_new(3), X509_verify_cert(3), X509_VERIFY_PARAM_new(3)
HISTORY
X509_VERIFY_PARAM_set1_name
(),
X509_VERIFY_PARAM_set_flags
(),
X509_VERIFY_PARAM_set_purpose
(),
X509_VERIFY_PARAM_set_trust
(),
X509_VERIFY_PARAM_set_time
(),
X509_VERIFY_PARAM_add0_policy
(),
X509_VERIFY_PARAM_set1_policies
(),
X509_VERIFY_PARAM_set_depth
(), and
X509_VERIFY_PARAM_get_depth
() first appeared in
OpenSSL 0.9.8. X509_VERIFY_PARAM_clear_flags
() and
X509_VERIFY_PARAM_get_flags
() first appeared in
OpenSSL 0.9.8a. All these functions have been available since
OpenBSD 4.5.
X509_VERIFY_PARAM_get0_name
(),
X509_VERIFY_PARAM_set1_host
(),
X509_VERIFY_PARAM_add1_host
(),
X509_VERIFY_PARAM_set_hostflags
(),
X509_VERIFY_PARAM_get0_peername
(),
X509_VERIFY_PARAM_set1_email
(),
X509_VERIFY_PARAM_set1_ip
(), and
X509_VERIFY_PARAM_set1_ip_asc
() first appeared in
OpenSSL 1.0.2 and have been available since OpenBSD
6.3.
BUGS
Delta CRL checking is currently primitive. Only a single delta can be used and (partly due to limitations of X509_STORE) constructed CRLs are not maintained.
If CRLs checking is enabled, CRLs are expected to be available in the corresponding X509_STORE structure. No attempt is made to download CRLs from the CRL distribution points extension.