Debian Codegraph @

upstream/debian-unstable/man3/X509_verify_cert.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "X509_VERIFY_CERT 3SSL"
58 .TH X509_VERIFY_CERT 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 X509_build_chain,
65 X509_verify_cert,
66 X509_STORE_CTX_verify \- build and verify X509 certificate chain
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/x509_vfy.h>
71 \&
72 \& STACK_OF(X509) *X509_build_chain(X509 *target, STACK_OF(X509) *certs,
73 \& X509_STORE *store, int with_self_signed,
74 \& OSSL_LIB_CTX *libctx, const char *propq);
75 \& int X509_verify_cert(X509_STORE_CTX *ctx);
76 \& int X509_STORE_CTX_verify(X509_STORE_CTX *ctx);
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 \&\fBX509_build_chain()\fR builds a certificate chain starting from \fItarget\fR
81 using the optional list of intermediate CA certificates \fIcerts\fR.
82 If \fIstore\fR is NULL it builds the chain as far down as possible, ignoring errors.
83 Else the chain must reach a trust anchor contained in \fIstore\fR.
84 It internally uses a \fBX509_STORE_CTX\fR structure associated with the library
85 context \fIlibctx\fR and property query string \fIpropq\fR, both of which may be NULL.
86 In case there is more than one possibility for the chain, only one is taken.
87 .PP
88 On success it returns a pointer to a new stack of (up_ref'ed) certificates
89 starting with \fItarget\fR and followed by all available intermediate certificates.
90 A self-signed trust anchor is included only if \fItarget\fR is the trust anchor
91 of \fIwith_self_signed\fR is 1.
92 If a non-NULL stack is returned the caller is responsible for freeing it.
93 .PP
94 The \fBX509_verify_cert()\fR function attempts to discover and validate a
95 certificate chain based on parameters in \fIctx\fR.
96 The verification context, of type \fBX509_STORE_CTX\fR, can be constructed
97 using \fBX509_STORE_CTX_new\fR\|(3) and \fBX509_STORE_CTX_init\fR\|(3).
98 It usually includes a target certificate to be verified,
99 a set of certificates serving as trust anchors,
100 a list of non-trusted certificates that may be helpful for chain construction,
101 flags such as X509_V_FLAG_X509_STRICT, and various other optional components
102 such as a callback function that allows customizing the verification outcome.
103 A complete description of the certificate verification process is contained in
104 the \fBopenssl\-verification\-options\fR\|(1) manual page.
105 .PP
106 Applications rarely call this function directly but it is used by
107 OpenSSL internally for certificate validation, in both the S/MIME and
108 SSL/TLS code.
109 .PP
110 A negative return value from \fBX509_verify_cert()\fR can occur if it is invoked
111 incorrectly, such as with no certificate set in \fIctx\fR, or when it is called
112 twice in succession without reinitialising \fIctx\fR for the second call.
113 A negative return value can also happen due to internal resource problems
114 or because an internal inconsistency has been detected.
115 Applications must interpret any return value <= 0 as an error.
116 .PP
117 The \fBX509_STORE_CTX_verify()\fR behaves like \fBX509_verify_cert()\fR except that its
118 target certificate is the first element of the list of untrusted certificates
119 in \fIctx\fR unless a target certificate is set explicitly.
120 .PP
121 When the verification target is a raw public key, rather than a certificate,
122 both functions validate the target raw public key.
123 In that case the number of possible checks is significantly reduced.
124 The raw public key can be authenticated only via DANE TLSA records, either
125 locally synthesised or obtained by the application from DNS.
126 Raw public key DANE TLSA records may be added via \fBSSL_add_expected_rpk\fR\|(3) or
127 \&\fBSSL_dane_tlsa_add\fR\|(3).
128 .SH "RETURN VALUES"
129 .IX Header "RETURN VALUES"
130 \&\fBX509_build_chain()\fR returns NULL on error, else a stack of certificates.
131 .PP
132 Both \fBX509_verify_cert()\fR and \fBX509_STORE_CTX_verify()\fR
133 return 1 if a complete chain can be built and validated,
134 otherwise they return 0, and in exceptional circumstances (such as malloc
135 failure and internal errors) they can also return a negative code.
136 .PP
137 If a complete chain can be built and validated both functions return 1.
138 If the certificate must be rejected on the basis of the data available
139 or any required certificate status data is not available they return 0.
140 If no definite answer possible they usually return a negative code.
141 .PP
142 On error or failure additional error information can be obtained by
143 examining \fIctx\fR using, for example, \fBX509_STORE_CTX_get_error\fR\|(3). Even if
144 verification indicated success, the stored error code may be different from
145 X509_V_OK, likely because a verification callback function has waived the error.
146 .SH "SEE ALSO"
147 .IX Header "SEE ALSO"
148 \&\fBSSL_add_expected_rpk\fR\|(3),
149 \&\fBSSL_CTX_dane_enable\fR\|(3),
150 \&\fBSSL_dane_tlsa_add\fR\|(3),
151 \&\fBX509_STORE_CTX_new\fR\|(3),
152 \&\fBX509_STORE_CTX_init\fR\|(3),
153 \&\fBX509_STORE_CTX_init_rpk\fR\|(3),
154 \&\fBX509_STORE_CTX_get_error\fR\|(3)
155 .SH HISTORY
156 .IX Header "HISTORY"
157 \&\fBX509_build_chain()\fR and \fBX509_STORE_CTX_verify()\fR were added in OpenSSL 3.0.
158 .SH COPYRIGHT
159 .IX Header "COPYRIGHT"
160 Copyright 2009\-2023 The OpenSSL Project Authors. All Rights Reserved.
161 .PP
162 Licensed under the Apache License 2.0 (the "License"). You may not use
163 this file except in compliance with the License. You can obtain a copy
164 in the file LICENSE in the source distribution or at
165 <https://www.openssl.org/source/license.html>.