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_get_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level, 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);

time_t
X509_VERIFY_PARAM_get_time(const, X509_VERIFY_PARAM, *param");

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);

void
X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param, int auth_level);

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_set_auth_level() sets the security level as defined in SSL_CTX_set_security_level(3) for certificate chain validation. For a certificate chain to validate, the public keys of all the certificates must meet the specified security level. The signature algorithm security level is not enforced for the chain's trust anchor certificate, which is either directly trusted or validated by means other than its signature.

From the point of view of the X.509 library, the default security level is 0. However, the SSL library uses a different default security level of 1 and calls X509_VERIFY_PARAM_set_auth_level() with its own level before validating a certificate 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_time() always returns the configured verification time. It does so even if the returned time will not be used because the flag X509_V_FLAG_USE_CHECK_TIME is unset.

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 deprecated flag that used to enable proxy certificate verification. In LibreSSL, this flag has no effect.

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.

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 deprecated X509_V_FLAG_CB_ISSUER_CHECK flag used to enable debugging of certificate issuer checks. It is provided for binary backwards compatibility and has no effect.

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.

X509_VERIFY_PARAM_set_auth_level() first appeared in OpenSSL 1.1.0 and X509_VERIFY_PARAM_get_time() in OpenSSL 1.1.0d. Both functions have been available since OpenBSD 7.2.

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.