OpenSuSE Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
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=>

home | help