X509_VERIFY_PARAM_SET_FLAGS(3) | Library Functions Manual | X509_VERIFY_PARAM_SET_FLAGS(3)

# 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

library “libcrypto”
`#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.

June 8, 2025 | Debian