Sortix 1.1dev nightly manual
This manual documents Sortix 1.1dev nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
X509_VERIFY_PARAM_SET_FLAGS(3) | Library Functions Manual | X509_VERIFY_PARAM_SET_FLAGS(3) |
NAME
X509_VERIFY_PARAM_new
,
X509_VERIFY_PARAM_free
,
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_VERIFY_PARAM_add0_table
,
X509_VERIFY_PARAM_lookup
,
X509_VERIFY_PARAM_get_count
,
X509_VERIFY_PARAM_get0
,
X509_VERIFY_PARAM_table_cleanup
—
X509 verification parameters
SYNOPSIS
#include
<openssl/x509_vfy.h>
X509_VERIFY_PARAM *
X509_VERIFY_PARAM_new
(void);
void
X509_VERIFY_PARAM_free
(X509_VERIFY_PARAM
*param);
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);
int
X509_VERIFY_PARAM_add0_table
(X509_VERIFY_PARAM
*param);
const X509_VERIFY_PARAM *
X509_VERIFY_PARAM_lookup
(const
char *name);
int
X509_VERIFY_PARAM_get_count
(void);
const X509_VERIFY_PARAM *
X509_VERIFY_PARAM_get0
(int
id);
void
X509_VERIFY_PARAM_table_cleanup
(void);
DESCRIPTION
These functions manipulate an X509_VERIFY_PARAM object associated with a certificate verification operation.X509_VERIFY_PARAM_new
() allocates and
initializes an empty X509_VERIFY_PARAM
object.
X509_VERIFY_PARAM_free
() clears all data
contained in param and releases all memory
used by it. If param is a
NULL
pointer, no action occurs.
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.
X509_VERIFY_PARAM_get_flags
() returns the
flags in param.
X509_VERIFY_PARAM_clear_flags
() clears the
flags flags in
param.
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
verification time in param to
t. Normally the current time is used.
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.
X509_VERIFY_PARAM_add0_table
() adds
param to a static list of
X509_VERIFY_PARAM objects maintained by the
library. This function is extremely dangerous because contrary to the name of
the function, if the list already contains an object that happens to have the
same name, that old object is not only silently removed from the list, but
also silently freed, which may silently invalidate various pointers existing
elsewhere in the program.
X509_VERIFY_PARAM_lookup
() searches this list
for an object of the given name. If no match
is found, the predefined objects built-in to the library are also inspected.
X509_VERIFY_PARAM_get_count
() returns the sum
of the number of objects on this list and the number of predefined objects
built-in to the library. Note that this is not necessarily the total number of
X509_VERIFY_PARAM objects existing in the
program because there may be additional such objects that were never added to
the list.
X509_VERIFY_PARAM_get0
() accesses predefined
and user-defined objects using id as an
index, useful for looping over objects without knowing their names. An
argument less than the number of predefined objects selects one of the
predefined objects; a higher argument selects an object from the list.
X509_VERIFY_PARAM_table_cleanup
() deletes all
objects from this list. It is extremely dangerous because it also invalidates
all data that was contained in all objects that were on the list and because
it frees all these objects, which may invalidate various pointers existing
elsewhere in the program.
RETURN VALUES
X509_VERIFY_PARAM_new
() returns a pointer to
the new object, or NULL
on allocation
failure.
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
(),
X509_VERIFY_PARAM_set1_policies
(), and
X509_VERIFY_PARAM_add0_table
() 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.
X509_VERIFY_PARAM_lookup
() and
X509_VERIFY_PARAM_get0
() return a pointer
to an existing built-in or user-defined object, or
NULL
if no object with the given
name is found, or if
id is at least
X509_VERIFY_PARAM_get_count
().
X509_VERIFY_PARAM_get_count
() returns a
number of objects.
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. Policy checking is automatically enabled if any of these flags are
set.
If X509_V_FLAG_NOTIFY_POLICY
is set and the
policy checking is successful a special status code is set 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.
The X509_V_FLAG_NO_CHECK_TIME
flag suppresses
checking the validity period of certificates and CRLs against the current
time. If X509_VERIFY_PARAM_set_time
() is
used to specify a verification time, the check is not suppressed.
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_set0_param(3), X509_STORE_set1_param(3), X509_verify_cert(3)HISTORY
X509_VERIFY_PARAM_new
(),
X509_VERIFY_PARAM_free
(),
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
(),
X509_VERIFY_PARAM_get_depth
(),
X509_VERIFY_PARAM_add0_table
(),
X509_VERIFY_PARAM_lookup
(), and
X509_VERIFY_PARAM_table_cleanup
() 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
(),
X509_VERIFY_PARAM_set1_ip_asc
(),
X509_VERIFY_PARAM_get_count
(), and
X509_VERIFY_PARAM_get0
() 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.July 23, 2021 | Debian |