X509_VERIFY_CERT(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

✨ NAME ✨

okay so this is the X509_VERIFY_CERT(3SSL) page, and it's about three functions, bestie: X509_verify_cert, X509_STORE_CTX_verify, and X509_build_chain — they build and verify X509 certificate chains 💖

📜 SYNOPSIS

#include <openssl/x509_vfy.h>

int X509_verify_cert(X509_STORE_CTX *ctx);
int X509_STORE_CTX_verify(X509_STORE_CTX *ctx);
STACK_OF(X509) *X509_build_chain(const X509 *target, STACK_OF(X509) *certs,
                                 X509_STORE *store, int with_self_signed,
                                 OSSL_LIB_CTX *libctx, const char *propq);

🌸 DESCRIPTION 🌸

💫 X509_verify_cert and X509_STORE_CTX_verify

X509_verify_cert() is the girl who tries to build and validate a certificate chain for the target certificate that's been set in ctx. Before you even call her, though, that verification context — type X509_STORE_CTX — has to be built with X509_STORE_CTX_new(3) and initialised with X509_STORE_CTX_init(3). No skipping steps, bestie 🙈

And like, that context is carrying a LOT of baggage (affectionate). It holds:

  • the target certificate
  • the trust store
  • an optional stack of untrusted certificates that might help with chain construction
  • verification parameters like flags and a verification purpose
  • an optional verification callback
  • and, once you've actually called the thing, the verification outcome
Not me reusing a X509_STORE_CTX… 💀 A X509_STORE_CTX can be used for only one verification. If you call X509_verify_cert() a second time on the same context without reinitialising it, it fails with a negative return value, and X509_STORE_CTX_get_error(3) will then return X509_V_ERR_INVALID_CALL. One and done, periodt.

When the target is a certificate, the function does these steps in order. The first step that fails aborts verification — unless a verification callback explicitly waives the error (peep [THE VERIFICATION CALLBACK](#) below, iykyk):

  1. Chain construction. Starting from the target certificate, the verification machinery hunts for an issuer for whatever certificate is currently at the top of the chain, pulling candidates from ctx's untrusted stack and from the trust store. By default the search is untrusted-first: the untrusted stack gets examined before the trust store. Setting X509_V_FLAG_TRUSTED_FIRST on ctx's verification parameters flips that around. And when an untrusted-first search fails to reach a trust anchor and X509_V_FLAG_NO_ALT_CHAINS is not set, the search gets retried with progressively shorter untrusted prefixes, trying to find an alternative trusted path. Chain length is bounded by the configured depth limit (see X509_VERIFY_PARAM_set_depth(3)) — blow past it and you get X509_V_ERR_CERT_CHAIN_TOO_LONG. And if more than one chain is possible? Only one is taken. 💅

Failing to build a chain to a trust anchor gives you an error like X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT, X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY, X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN, X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT, or X509_V_ERR_CERT_CHAIN_TOO_LONG.

  1. Certificate extension validation per RFC 5280, which covers basic constraints, key usage, and the verification purpose set via X509_VERIFY_PARAM_set_purpose(3).
  2. Security level checks against the configured authentication level, covering issuer key sizes (X509_V_ERR_CA_KEY_TOO_SMALL) and signature algorithm strength (X509_V_ERR_CA_MD_TOO_WEAK). The leaf key gets checked separately, before chain construction even begins (X509_V_ERR_EE_KEY_TOO_SMALL) 👑
  3. Identity checks against any hostnames, email addresses, or IP addresses configured on the verification parameters (X509_VERIFY_PARAM_set1_host(3) and related).
  4. Revocation checks via CRLs and, when configured, OCSP. Which checks actually happen is controlled by flags like X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL.
  5. Signature and validity period checks on every certificate in the chain, walking from the trust anchor down to the target. Here's the wild part: the signature on the chain's terminating certificate is not verified — trust comes from its presence in the trust store, not from its signature. This applies both to a conventional self-signed trust anchor and, when X509_V_FLAG_PARTIAL_CHAIN is in effect, to a non-self-signed intermediate that got promoted to anchor status. X509_V_FLAG_CHECK_SS_SIGNATURE asks for the self-signature on a self-signed terminator to be verified; it has no effect when the terminator is a non-self-signed certificate. Validity periods, though? Checked on every certificate, terminator included. no cap 🫶
  6. Name constraint validation per RFC 5280 section 4.2.1.10; check out NAME_CONSTRAINTS_check(3) for the deets on the matching primitive and the general-name types it covers.
  7. RFC 3779 path validation of AS-number and IP-address delegation extensions, done by default unless OpenSSL was built with no-rfc3779.
  8. Certificate policy validation, which only happens when X509_V_FLAG_POLICY_CHECK is set.

Several X509_V_FLAG_* values tweak how all these checks behave; the representative ones get name-dropped at the relevant step above, but that list is not exhaustive — the complete set of verification flags, what each one does, and the functions for querying and modifying them live in X509_VERIFY_PARAM_set_flags(3).

Real talk: applications rarely call X509_verify_cert() directly. It gets invoked internally by OpenSSL during S/MIME and CMS verification and during the TLS handshake. She's booked and busy ✨

X509_STORE_CTX_verify() behaves identically to X509_verify_cert() — literally the same — except for how the target certificate gets selected: if no target has been set on ctx (see X509_STORE_CTX_set_cert(3)) and the untrusted stack is nonempty, then the first certificate in the untrusted stack gets adopted as the target before verification starts. But if a target was set explicitly, X509_STORE_CTX_verify() uses that one and does not go digging in the untrusted stack for a substitute.

🔑 Raw public key targets

When the verification target is a raw public key instead of a certificate (set via X509_STORE_CTX_init_rpk(3)), both functions validate the raw public key instead of a certificate chain. The set of possible checks is, ngl, significantly reduced: there are no extensions, no names, no CRLs, and no signatures to verify. it's giving minimalist 😭

The raw public key can be authenticated only via DANE TLSA records — either locally synthesised or obtained by the application from DNS. Raw public key DANE TLSA records may be added via SSL_add_expected_rpk(3) or SSL_dane_tlsa_add(3).

🦋 X509_build_chain

X509_build_chain() builds a certificate chain starting from target, using the very same chain-construction algorithm as X509_verify_cert() (scroll up to "X509_verify_cert and X509_STORE_CTX_verify", bestie 💖). Internally it uses a X509_STORE_CTX structure associated with the library context libctx and the property query string propq — both of which may be NULL.

The role of certs depends entirely on store:

  • If store is non-NULL, certs is treated as an optional list of untrusted intermediate certificates that may help complete the chain, and the chain must reach a trust anchor contained in store. If no chain to a trust anchor can be built, the function fails and returns NULL.
  • If store is NULL, certs is installed as the trusted stack for the internal context (see X509_STORE_CTX_set0_trusted_stack(3)). In this mode the function builds the chain as far as it can but does not require it to reach an anchor: if chain construction fails partway, the partial chain built so far is still returned. we love a flexible queen 🎀

Because the internal X509_STORE_CTX is allocated and freed inside X509_build_chain(), some stuff just... always defaults. Specifically:

  • search-policy flags like X509_V_FLAG_TRUSTED_FIRST and X509_V_FLAG_NO_ALT_CHAINS always take their default values
  • the configured depth limit always takes its default value
  • and the specific X509_V_ERR_* code that caused chain construction to fail is not reported back

The function signals only success or failure through its return value (and, when store is NULL, it may also return a partial chain). That's the tea ☕

On success, the returned stack starts with a newly up-referenced target, followed by the issuer certificates that were found. A self-signed certificate at the top of the chain is included in the returned stack when either with_self_signed is 1, or the chain consists solely of target (for example because target itself is self-signed or no further issuer could be found). When the chain has more than one element and with_self_signed is 0, the self-signed top is omitted from the result. main character gets left out, tragic 💀

The caller is responsible for freeing the returned stack. don't forget, bestie, she's not gonna clean up after herself 🙈

🔍 THE VERIFICATION CALLBACK

okay so every single X509_STORE_CTX walks around carrying a verification callback, and its signature is literally this:

int (*verify_cb)(int ok, X509_STORE_CTX *ctx);

This callback gets called by X509_verify_cert() and X509_STORE_CTX_verify() at like, multiple points during verification — partly to spill the tea about errors, partly to keep you posted on progress. Bestie, where does it even come from? Two places: you can install it right on the context with X509_STORE_CTX_set_verify_cb(3), or it gets inherited at X509_STORE_CTX_init(3) time from the X509_STORE (peep X509_STORE_set_verify_cb_func(3)). And if nobody set anything? A default callback steps in that just… returns its ok argument unchanged. Which means every error aborts verification. No exceptions, no mercy. 💀

📞 When the callback is called

There are two distinct invocation patterns, and they are not the same vibe:

💔 Error notification (ok = 0)

The callback gets called with ok set to 0 every time a check fails. Before the call happens, the verification machinery writes the X509_V_ERR_* code describing the failure onto ctx, and for certificate-level errors it also records the depth where the error was spotted plus the cert in question. Your callback can snoop all of that via X509_STORE_CTX_get_error(3), X509_STORE_CTX_get_error_depth(3), and X509_STORE_CTX_get_current_cert(3). But heads up 🫶: CRL- and OCSP-related errors only update the error code — the depth and current certificate just keep whatever values they had from a preceding context. They do not refresh. Not even a little.

✨ Per-certificate success notification (ok = 1)

During the signature-and-validity pass, once each certificate in the chain has been checked successfully, the callback gets called with ok set to 1. The current certificate, current issuer, and error depth — queryable respectively through X509_STORE_CTX_get_current_cert(3), X509_STORE_CTX_get0_current_issuer(3), and X509_STORE_CTX_get_error_depth(3) — describe the certificate that just got accepted. The callback can use this to log progress (slay, live your logging dreams) but it must return a nonzero value, otherwise verification is aborted. Yeah. Even on the good news call. 😭

The callback's return value controls what happens next in verification:

  • A nonzero return value — verification continues. For an error notification, this is what "waiving the error" means.
  • A zero return value — verification aborts immediately. The function returns 0 to its caller in this case, regardless of whether the callback was invoked with ok = 0 or ok = 1.

🩹 Sticky errors

When the callback waives an error by returning nonzero, the underlying check is treated as passed for control-flow purposes, but the error code recorded on ctx is not reset to X509_V_OK. So a subsequent successful return from X509_verify_cert() does not imply that X509_STORE_CTX_get_error(3) will return X509_V_OK — it may still be holding the last error code that got waived. And this is intentional, bestie. Only the callback itself is permitted to overwrite the error code, via X509_STORE_CTX_set_error(3), and only at its own risk. 👑

⚠️ Dangers

A verification callback that returns nonzero on an error notification has, by definition, suppressed an authentication check that OpenSSL considered necessary. Like, that's the whole thing. Callers should treat installing a callback that waives errors as a deliberate weakening of the security guarantees of X509_verify_cert() — something you do only for specific, well-understood error codes. And the following pitfalls are common, so listen up:

  • Blanket waivers. A callback that returns 1 unconditionally turns X509_verify_cert() into "accept anything" and is almost always wrong outside of diagnostics. Inspect the error code via X509_STORE_CTX_get_error(3) and waive only the specific codes you actually intend to waive. Not the whole menu. 🙈
  • Failing a success notification. Because the callback is also called with ok = 1, a callback that mistakenly returns 0 in that case causes verification to fail even though every check passed. And the caller cannot distinguish this from a genuine failure based on the return value alone. It's giving chaos.
  • Clearing the error code. The sticky-error rule exists so that a waived error remains visible to the caller after verification returns. A callback that calls X509_STORE_CTX_set_error(3) with X509_V_OK hides that information — and can also mask a later error if the callback is invoked again before verification completes. 💀
  • Mutating the verification context. The X509_STORE_CTX is live during the callback: the verification routines are actively reading its chain, parameters, and other state. Calling context-mutating functions from inside the callback — for example, replacing the verified chain via X509_STORE_CTX_set0_verified_chain(3), swapping the trust store or untrusted stack, or changing verification flags, depth, purpose, or target — can corrupt the in-progress verification, produce inconsistent behaviour between later steps of the pipeline, or, in the case of the verified chain, cause use-after-free. The only mutators reasonable from within a callback are the error-related setters (X509_STORE_CTX_set_error(3), X509_STORE_CTX_set_error_depth(3), X509_STORE_CTX_set_current_cert(3)), and even those should be used sparingly (see "Sticky errors"). Sparingly!! 🌸
  • Heavy work in the callback. The callback is on the hot path of every certificate check; expensive work performed there will slow every TLS handshake or S/MIME verification that uses the surrounding context. Don't be doing your taxes in there.
  • Trusting the depth alone. The error depth, from X509_STORE_CTX_get_error_depth(3), records where an error was detected during chain processing — not the position of the certificate in the final chain. Always consult X509_STORE_CTX_get_current_cert(3) in addition to the depth when deciding whether to waive.
  • Fragility with respect to check order. The set of errors the callback observes, and the order in which it observes them, depends on the internal order in which verification checks are performed. When a certificate has more than one problem, only the first check to detect a problem causes the callback to be invoked for that certificate; later checks are not reached unless the callback waives the earlier error. This ordering is an implementation detail and is not part of the stable API: a refactor that reorders internal checks without altering the binary success/failure contract of X509_verify_cert() may still change which X509_V_ERR_* code the callback sees, or whether a given code is reported at all. Callbacks that branch on a specific error code being reported, or that assume earlier checks have already filtered out certain conditions, can therefore change behaviour silently across OpenSSL releases. Write callbacks defensively: re-fetch the error code and the current certificate via X509_STORE_CTX_get_error(3) and X509_STORE_CTX_get_current_cert(3) afresh on each invocation, and treat "this error code never appears" as an assumption that may be invalidated. More fundamentally, because the set and order of error notifications is not a stable contract, the callback cannot be relied upon to observe any particular condition or sequence of conditions; that makes it an unsound mechanism for enforcing or modifying security policy. Use of the verification callback to alter verification outcomes — to waive errors, to inject conditional acceptance, or to gate behaviour on a specific X509_V_ERR_* code being reported — is therefore discouraged in production code. Reserve the callback for diagnostic and logging purposes, where future changes in which errors appear, or in what order, are not security-relevant. 🧚

The default callback waives nothing and is the safe choice; it is the right behaviour for almost all production uses. Periodt. 💖

🔁 RETURN VALUES

X509_verify_cert() and X509_STORE_CTX_verify() return one of these:

  • 1 — if a complete chain has been built and every check either succeeded or was waived by the verification callback. Note that the latter case does not guarantee that X509_STORE_CTX_get_error(3) returns X509_V_OK — see "Sticky errors". The return value is the authoritative success/failure signal: callers do not need to additionally check that X509_STORE_CTX_get_error(3) returns X509_V_OK to consider verification successful. They may consult it to learn whether, and which, errors were waived by the verification callback.
  • 0 — if verification was rejected. This happens when a check failed and the callback did not waive the error, when a trust decision actively rejected the chain, or when the verification callback returned 0 from a success notification (see "THE VERIFICATION CALLBACK"). When a certificate would have failed more than one check, the specific X509_V_ERR_* code returned by X509_STORE_CTX_get_error(3) reflects whichever check fired first; this ordering is an implementation detail and is not stable across releases. Callers must therefore treat the return value as the authoritative success/failure signal, and treat the specific error code as diagnostic information that may shift over time.
  • A negative value — on a hard error that prevented verification from running to completion. The documented cases are: ctx is NULL; ctx has no target certificate set; ctx has already been used for a previous verification; memory allocation failed; the trust store lookup function returned an error; or an internal invariant was violated. In these cases X509_STORE_CTX_get_error(3) returns an appropriate X509_V_ERR_* value (X509_V_ERR_INVALID_CALL, X509_V_ERR_OUT_OF_MEM, X509_V_ERR_STORE_LOOKUP or X509_V_ERR_UNSPECIFIED).

In all failure modes, additional information can be obtained from X509_STORE_CTX_get_error(3) and the related accessors. Applications must treat any return value <= 0 as verification not having succeeded. No cap, that's just the rule.

X509_build_chain() returns NULL on error. Otherwise it returns a newly allocated stack of certificates that the caller must free; the stack may represent only a partial chain when store is NULL. 🦋

💀 BUGS 💀 (bestie, sit down for this one)

Okay so several aspects of chain construction depart from the recommendations of RFC 4158 (Certification Path Building) and from strict RFC 5280 path validation. Like, it's not perfect and it never claimed to be. Callers should be aware of the following 👇

The chain search is not optimised in the manner described by RFC 4158 sections 3.1 to 3.5. Candidate issuers are not scored against the set of heuristics RFC 4158 recommends; at each step the first viable candidate is committed to, with the only preference being for a candidate whose validity period covers the current time. There is no tree-traversal backtracking: when an initial chain does not reach a trust anchor, the search is retried with progressively shorter untrusted prefixes (unless X509_V_FLAG_NO_ALT_CHAINS is set), but different candidate issuers at intermediate positions of the same chain are not tried. In simple hierarchical PKIs this is rarely an issue. In cross-certified or bridged PKI environments X509_verify_cert() may fail to find a valid certification path even when one demonstrably exists in the available certificate set. it's giving "the answer was RIGHT THERE and it didn't look" 💀

Issuer key usage is not enforced during chain construction. RFC 5280 section 6.1.4(n) and RFC 4158 section 3.5.3 call for verifying that an issuer candidate's keyUsage extension permits certificate signing (keyCertSign) before that candidate is selected. OpenSSL defers this check to the later extension-validation pass: if two candidate issuers exist for a certificate, and the one lacking keyCertSign happens to be selected first, verification fails on the extension check rather than backing off and trying the other candidate. The misuse is ultimately caught, but a chain that would have validated through the alternative issuer is not built. so close bestie, so close 😭

X509_V_FLAG_PARTIAL_CHAIN relaxes the trust-anchor requirement from the one defined by RFC 5280 section 6.1.1(d). With the flag set, any certificate in the trust store is acceptable as the terminator of the chain, even if it is not a self-signed root. This is an intentional and now-common deviation that supports modern practices such as pinning trust to a specific intermediate, or shortening chains by treating a sufficiently-trusted intermediate as the trust point and eliding the root above it. Callers should nevertheless be aware that the chain returned in this mode does not necessarily terminate at an RFC 5280-style trust anchor. iconic behaviour, just know what you signed up for ✨

⏰ THIS NEXT ONE IS THE MATH JUMPSCARE ⏰

NAME_CONSTRAINTS_check(3) caps each per-pair check at 2**20 comparisons, but the chain orchestrator issues N(N-1)/2 such checks for an N-certificate chain. An adversary submitting a maximally constructed chain can therefore force up to approximately 6.3 million name-constraint comparisons in a four-certificate chain (one leaf and three name-constrained signers), or approximately 5.2 billion at the default chain-depth limit of 100. ngl that's a lot of comparisons, no cap 💅

🌈 SEE ALSO 🌈

hiii go read these next, they're literally the whole friend group 🫶

📜 HISTORY 📜

X509_build_chain() and X509_STORE_CTX_verify() were added in OpenSSL 3.0. newer era, new functions, we love to see it 🦋

Copyright 2009-2026 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

that's the whole page bestie!! you made it all the way to the bottom, ate and left no crumbs 🎀✨

and for the lil footer credits: this was page X509_VERIFY_CERT(3SSL) from OpenSSL 4.0.3, dated 2026-09-29 — mwah, go forth and verify some certs 💖 🦋👑

📦 where this page comes from