LIBRESSL-X509_VERIFY_PARAM_SET_FLAGS(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💖 X509_VERIFY_PARAM_SET_FL(3) — X509 verification parameters 💖

okay so bestie, this whole page comes from the Library Functions Manual, and it’s all libcrypto business. The main character is the X509_VERIFY_PARAM object — the little vibe-check controller attached to a certificate verification operation. These functions name it, flag it, time it, and set up hostname / email / IP checks. Let’s get into it. 🫶

✨ 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_get_hostflags
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 🌸

okay so this is the libcrypto situation, and you literally include this header:

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

       unsigned int
       X509_VERIFY_PARAM_get_hostflags(const X509_VERIFY_PARAM *param);

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

and yes bestie, that X509_VERIFY_PARAM_get_time prototype is serving exactly the characters printed above — comma, quote, all of it. We copy code exactly here, no edits, no cap. 💅

🔥 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. lowkey chaotic, but that’s what the page says. 😭
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.

⚠️ bestie, the poisoning thing is real: if one of those host / email / IP setters fails, the object is poisoned and later X509_verify_cert(3) calls using it 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_get_hostflags() — returns the host flags previously set by a call to X509_VERIFY_PARAM_set_hostflags() or 0 by default.
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 ✨

Okay bestie, this is the good part — the flags themselves. The verification flags are basically a little squad of zero or more of these bad boys OR'ed together. Pick your faves, stack 'em up, go off 💅

X509_V_FLAG_CRL_CHECK — turns on CRL checking for the leaf certificate of the certificate chain. If a suitable CRL can't be found, boom, that's an error. 😭
X509_V_FLAG_CRL_CHECK_ALL — same energy but for the entire certificate chain. Not just the leaf, the whole fam 🫶
X509_V_FLAG_IGNORE_CRITICAL — disables critical extension checking. By default, any unhandled critical extensions in certificates (or in CRLs, if those are being checked) is a fatal error. Set this flag and those unhandled critical extensions just get ignored. WARNING: setting this for literally anything other than debugging purposes can be a security risk 😬 If you want finer control over which extensions are supported, do that in the verification callback instead, no cap.
X509_V_FLAG_X509_STRICT — disables workarounds for some broken certificates and makes verification strictly apply X509 rules. No more being nice about it, periodt 📏
X509_V_FLAG_ALLOW_PROXY_CERTS — a deprecated flag that used to enable proxy certificate verification. In LibreSSL, this flag has no effect. It's giving "I'm here but I'm not doing anything" 💀
X509_V_FLAG_POLICY_CHECK — enables certificate policy checking; by default no policy checking is performed. When it is, additional info gets sent to the verification callback about the policy checking. ✨
X509_V_FLAG_EXPLICIT_POLICY, X509_V_FLAG_INHIBIT_ANY, and X509_V_FLAG_INHIBIT_MAP — these three set the “require explicit policy”, “inhibit any policy”, and “inhibit policy mapping” flags, respectively, exactly as defined in RFC 3280. Big caveat: these three are ignored unless X509_V_FLAG_POLICY_CHECK is also set. So don't be out here setting them alone and expecting a vibe 🎀
X509_V_FLAG_NOTIFY_POLICY — if this is set and policy checking succeeds, a special status code gets sent to the verification callback. Little notification, lowkey cute 🔔
X509_V_FLAG_EXTENDED_CRL_SUPPORT — by default some extra features like indirect CRLs and CRLs signed by different keys are disabled. Set this and they're enabled. Unlocked 🔓
X509_V_FLAG_USE_DELTAS — if set, delta CRLs (if present) are used to determine certificate status. If not set, deltas are simply 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. iykyk 🔥
X509_V_FLAG_CB_ISSUER_CHECK — deprecated flag that used to enable debugging of certificate issuer checks. It's provided for binary backwards compatibility and has no effect. Respectfully, it's retired 💀
X509_V_FLAG_TRUSTED_FIRST — when 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). 👑
X509_V_FLAG_NO_ALT_CHAINS — 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. This flag says "no thank you, we're not doing the alternates today" 🚫
X509_V_FLAG_PARTIAL_CHAIN — 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. Honestly iconic behavior 🌈
X509_V_FLAG_USE_CHECK_TIME — if 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. Like, ancient times 🕰️
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. Rude but factual 🙃
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. We're just not looking at the clock, bestie 💅

🌸 EXAMPLES 🌸

Wanna enable CRL checking when performing certificate verification during SSL connections associated with an SSL_CTX structure ctx? Say less. Do this:

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

🎀 HISTORY 🎀

Okay so, storytime 📖

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. Then 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. Old money 💸

Next batch: 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. Glow up ✨

Then 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.

And X509_VERIFY_PARAM_get_hostflags() first appeared in OpenSSL 1.1.0i and has been available since OpenBSD 7.9. Fresh out the oven 🔥

💀 BUGS 💀

Bestie, some things are still a work in progress:

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. It's giving "we're trying our best" 😭
If CRL 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. So don't come for it — it literally won't go fetch them for you 🙈

And that's the whole page, bestie! 🫶 This one came from the Debian edition, dated November 7, 2025, for X509_VERIFY_PARAM_SET_FLAGS(3) — go forth and verify those params responsibly 💖✨🎀

📦 where this page comes from

alpine 3.24: libressl-doc 4.3.1-r0 · custom
arch rolling: libressl 4.4.0-1 · ISC AND custom:OpenSSL
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms