1X509_VERIFY_CERT(3ossl)             OpenSSL            X509_VERIFY_CERT(3ossl)
2
3
4

NAME

6       X509_build_chain, X509_verify_cert, X509_STORE_CTX_verify - build and
7       verify X509 certificate chain
8

SYNOPSIS

10        #include <openssl/x509_vfy.h>
11
12        STACK_OF(X509) *X509_build_chain(X509 *target, STACK_OF(X509) *certs,
13                                         X509_STORE *store, int with_self_signed,
14                                         OSSL_LIB_CTX *libctx, const char *propq);
15        int X509_verify_cert(X509_STORE_CTX *ctx);
16        int X509_STORE_CTX_verify(X509_STORE_CTX *ctx);
17

DESCRIPTION

19       X509_build_chain() builds a certificate chain starting from target
20       using the optional list of intermediate CA certificates certs.  If
21       store is NULL it builds the chain as far down as possible, ignoring
22       errors.  Else the chain must reach a trust anchor contained in store.
23       It internally uses a X509_STORE_CTX structure associated with the
24       library context libctx and property query string propq, both of which
25       may be NULL.  In case there is more than one possibility for the chain,
26       only one is taken.
27
28       On success it returns a pointer to a new stack of (up_ref'ed)
29       certificates starting with target and followed by all available
30       intermediate certificates.  A self-signed trust anchor is included only
31       if target is the trust anchor of with_self_signed is 1.  If a non-NULL
32       stack is returned the caller is responsible for freeing it.
33
34       The X509_verify_cert() function attempts to discover and validate a
35       certificate chain based on parameters in ctx.  The verification
36       context, of type X509_STORE_CTX, can be constructed using
37       X509_STORE_CTX_new(3) and X509_STORE_CTX_init(3).  It usually includes
38       a target certificate to be verified, a set of certificates serving as
39       trust anchors, a list of non-trusted certificates that may be helpful
40       for chain construction, flags such as X509_V_FLAG_X509_STRICT, and
41       various other optional components such as a callback function that
42       allows customizing the verification outcome.  A complete description of
43       the certificate verification process is contained in the
44       openssl-verification-options(1) manual page.
45
46       Applications rarely call this function directly but it is used by
47       OpenSSL internally for certificate validation, in both the S/MIME and
48       SSL/TLS code.
49
50       A negative return value from X509_verify_cert() can occur if it is
51       invoked incorrectly, such as with no certificate set in ctx, or when it
52       is called twice in succession without reinitialising ctx for the second
53       call.  A negative return value can also happen due to internal resource
54       problems or because an internal inconsistency has been detected.
55       Applications must interpret any return value <= 0 as an error.
56
57       The X509_STORE_CTX_verify() behaves like X509_verify_cert() except that
58       its target certificate is the first element of the list of untrusted
59       certificates in ctx unless a target certificate is set explicitly.
60

RETURN VALUES

62       X509_build_chain() returns NULL on error, else a stack of certificates.
63
64       Both X509_verify_cert() and X509_STORE_CTX_verify() return 1 if a
65       complete chain can be built and validated, otherwise they return 0, and
66       in exceptional circumstances (such as malloc failure and internal
67       errors) they can also return a negative code.
68
69       If a complete chain can be built and validated both functions return 1.
70       If the certificate must be rejected on the basis of the data available
71       or any required certificate status data is not available they return 0.
72       If no definite answer possible they usually return a negative code.
73
74       On error or failure additional error information can be obtained by
75       examining ctx using, for example, X509_STORE_CTX_get_error(3).  Even if
76       verification indicated success, the stored error code may be different
77       from X509_V_OK, likely because a verification callback function has
78       waived the error.
79

SEE ALSO

81       X509_STORE_CTX_new(3), X509_STORE_CTX_init(3),
82       X509_STORE_CTX_get_error(3)
83

HISTORY

85       X509_build_chain() and X509_STORE_CTX_verify() were added in OpenSSL
86       3.0.
87
89       Copyright 2009-2022 The OpenSSL Project Authors. All Rights Reserved.
90
91       Licensed under the Apache License 2.0 (the "License").  You may not use
92       this file except in compliance with the License.  You can obtain a copy
93       in the file LICENSE in the source distribution or at
94       <https://www.openssl.org/source/license.html>.
95
96
97
983.1.1                             2023-08-31           X509_VERIFY_CERT(3ossl)
Impressum