x SuSE Linux 13.1-RELEASE x
x SuSE Linux 13.1-RELEASEx
X509_VERIFY_CERT(3ossl) OpenSSL X509_VERIFY_CERT(3ossl)
NAME
X509_verify_cert, X509_STORE_CTX_verify, X509_build_chain - build and
verify X509 certificate chain
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(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() attempts to build and validate a certificate chain
for the target certificate set in ctx. The verification context, of
type X509_STORE_CTX, must first be constructed with
X509_STORE_CTX_new(3) and initialised with X509_STORE_CTX_init(3). It
carries the target certificate, the trust store, an optional stack of
untrusted certificates that may assist chain construction, verification
parameters such as flags and a verification purpose, an optional
verification callback, and, after a call, the verification outcome.
A X509_STORE_CTX can be used for only one verification. Calling
X509_verify_cert() a second time on the same context without
reinitialising it fails with a negative return value, and
X509_STORE_CTX_get_error(3) subsequently returns
X509_V_ERR_INVALID_CALL.
When the target is a certificate, the function performs the following
steps in order. The first step that fails aborts verification, except
where a verification callback explicitly waives the error (see "THE
VERIFICATION CALLBACK" below):
1. Chain construction. Starting from the target certificate, the
verification machinery seeks an issuer for the certificate
currently at the top of the chain, drawing candidates from ctx's
untrusted stack and from the trust store. By default the search is
untrusted-first: the untrusted stack is examined before the trust
store. Setting X509_V_FLAG_TRUSTED_FIRST on ctx's verification
parameters reverses this. When an untrusted-first search fails to
reach a trust anchor and X509_V_FLAG_NO_ALT_CHAINS is not set, the
search is retried with progressively shorter untrusted prefixes in
an attempt to find an alternative trusted path. The chain length is
bounded by the configured depth limit (see
X509_VERIFY_PARAM_set_depth(3)); exceeding it yields
X509_V_ERR_CERT_CHAIN_TOO_LONG. If more than one chain is possible,
only one is taken.
Failure to build a chain to a trust anchor yields an error such as
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.
2. Certificate extension validation per RFC 5280, including basic
constraints, key usage and the verification purpose set via
X509_VERIFY_PARAM_set_purpose(3).
3. 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 is checked separately before chain construction begins
(X509_V_ERR_EE_KEY_TOO_SMALL).
4. Identity checks against any hostnames, email addresses or IP
addresses configured on the verification parameters
(X509_VERIFY_PARAM_set1_host(3) and related).
5. Revocation checks via CRLs and, when configured, OCSP. The set of
checks performed is controlled by flags such as
X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL.
6. Signature and validity period checks on every certificate in the
chain, walking from the trust anchor down to the target. The
signature on the chain's terminating certificate is not verified:
trust is taken from its presence in the trust store rather than
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 promoted to anchor status.
X509_V_FLAG_CHECK_SS_SIGNATURE requests that the self-signature on
a self-signed terminator be verified; it has no effect when the
terminator is a non-self-signed certificate. Validity periods are
checked on every certificate, including the terminator.
7. Name constraint validation per RFC 5280 section 4.2.1.10; see
NAME_CONSTRAINTS_check(3) for details of the matching primitive and
the general-name types it covers.
8. RFC 3779 path validation of AS-number and IP-address delegation
extensions, performed by default unless OpenSSL was built with
no-rfc3779.
9. Certificate policy validation, performed only when
X509_V_FLAG_POLICY_CHECK is set.
Several X509_V_FLAG_* values modify the behaviour of these checks;
representative ones are named at the relevant step above, but the list
there is not exhaustive. The complete set of verification flags, the
effect each one has, and the functions used to query and modify them
are documented in X509_VERIFY_PARAM_set_flags(3).
Applications rarely call X509_verify_cert() directly. It is invoked
internally by OpenSSL during S/MIME and CMS verification and during the
TLS handshake.
X509_STORE_CTX_verify() behaves identically to X509_verify_cert()
except for the selection of the target certificate: if no target has
been set on ctx (see X509_STORE_CTX_set_cert(3)) and the untrusted
stack is nonempty, the first certificate in the untrusted stack is
adopted as the target before verification begins. If a target was set
explicitly, X509_STORE_CTX_verify() uses it and does not consult the
untrusted stack for this purpose.
Raw public key targets
When the verification target is a raw public key rather than 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 significantly reduced: there are no extensions,
names, CRLs or signatures to verify. 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 same chain-construction algorithm as X509_verify_cert() (see
"X509_verify_cert and X509_STORE_CTX_verify" above). It internally uses
a X509_STORE_CTX structure associated with the library context libctx
and property query string propq, both of which may be NULL. The role of
certs depends on store:
o 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.
o 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.
Because the internal X509_STORE_CTX is allocated and freed inside
X509_build_chain(), search-policy flags such as
X509_V_FLAG_TRUSTED_FIRST and X509_V_FLAG_NO_ALT_CHAINS and the
configured depth limit always take their default values, 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, may also return a partial
chain).
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.
The caller is responsible for freeing the returned stack.
THE VERIFICATION CALLBACK
Each X509_STORE_CTX carries a verification callback with the signature
int (*verify_cb)(int ok, X509_STORE_CTX *ctx);
This callback is invoked by X509_verify_cert() and
X509_STORE_CTX_verify() at multiple points during verification, both to
report errors and to notify of progress. It is installed by
X509_STORE_CTX_set_verify_cb(3) on the context, or it is inherited at
X509_STORE_CTX_init(3) time from the X509_STORE (see
X509_STORE_set_verify_cb_func(3)). If neither has been set, a default
callback is used which simply returns its ok argument unchanged,
causing every error to abort verification.
When the callback is called
There are two distinct invocation patterns:
Error notification (ok = 0)
The callback is called with ok set to 0 each time a check fails.
Before the call, the verification machinery records the
X509_V_ERR_* code describing the failure on ctx, and for
certificate-level errors also records the depth at which the error
was detected and the certificate in question. The callback inspects
these via X509_STORE_CTX_get_error(3),
X509_STORE_CTX_get_error_depth(3), and
X509_STORE_CTX_get_current_cert(3). CRL- and OCSP-related errors
update only the error code; the depth and current certificate
retain their values from a preceding context.
Per-certificate success notification (ok = 1)
During the signature-and-validity pass, after each certificate in
the chain has been checked successfully, the callback is called
with ok set to 1. The current certificate, current issuer, and
error depth (queryable respectively via
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
has just been accepted. The callback may use this to log progress,
but must return a nonzero value, otherwise verification is aborted.
The callback's return value controls subsequent verification:
o A nonzero return value causes verification to continue. For an
error notification this constitutes waiving the error.
o A zero return value causes verification to abort 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. A subsequent successful
return from X509_verify_cert() therefore does not imply that
X509_STORE_CTX_get_error(3) will return X509_V_OK: it may still hold
the last error code that was waived. This is intentional. 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. Callers should treat installing a callback that
waives errors as a deliberate weakening of the security guarantees of
X509_verify_cert(), to be done only for specific, well-understood error
codes. The following pitfalls are common:
o 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
intend to.
o 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. The
caller cannot distinguish this from a genuine failure based on the
return value alone.
o 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 this information and can also mask a later error if
the callback is invoked again before verification completes.
o 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 within 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").
o 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.
o 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.
o 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.
RETURN VALUES
X509_verify_cert() and X509_STORE_CTX_verify() return:
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 occurs 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.
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
Several aspects of chain construction depart from the recommendations
of RFC 4158 (Certification Path Building) and from strict RFC 5280 path
validation. 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.
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.
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.
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.
SEE ALSO
NAME_CONSTRAINTS_check(3), SSL_add_expected_rpk(3),
SSL_CTX_dane_enable(3), SSL_dane_tlsa_add(3), X509_STORE_CTX_new(3),
X509_STORE_CTX_init(3), X509_STORE_CTX_init_rpk(3),
X509_STORE_CTX_get_error(3), X509_STORE_CTX_set_verify_cb(3),
X509_STORE_set_verify_cb_func(3), X509_VERIFY_PARAM_set_flags(3)
HISTORY
X509_build_chain() and X509_STORE_CTX_verify() were added in OpenSSL
3.0.
COPYRIGHT
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>.
3.5.9 2026-09-29 X509_VERIFY_CERT(3ossl)
Want to link to this manual page? Use this URL:
<https://star2.abcm.com/cgi-bin/linux-man?query=X509_STORE_CTX_verify&sektion=3&manpath=>