Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_add1_chain_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 "SSL_CTX_ADD1_CHAIN_CERT 3SSL"
58 .TH SSL_CTX_ADD1_CHAIN_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 SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert,
65 SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs,
66 SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert,
67 SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain,
68 SSL_build_cert_chain, SSL_CTX_select_current_cert,
69 SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert \- extra
70 chain certificate processing
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& #include <openssl/ssl.h>
75 \&
76 \& int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
77 \& int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
78 \& int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509);
79 \& int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
80 \& int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
81 \& int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);
82 \&
83 \& int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk);
84 \& int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk);
85 \& int SSL_add0_chain_cert(SSL *ssl, X509 *x509);
86 \& int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
87 \& int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
88 \& int SSL_clear_chain_certs(SSL *ssl);
89 \&
90 \& int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
91 \& int SSL_build_cert_chain(SSL *ssl, flags);
92 \&
93 \& int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509);
94 \& int SSL_select_current_cert(SSL *ssl, X509 *x509);
95 \& int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op);
96 \& int SSL_set_current_cert(SSL *ssl, long op);
97 .Ve
98 .SH DESCRIPTION
99 .IX Header "DESCRIPTION"
100 \&\fBSSL_CTX_set0_chain()\fR and \fBSSL_CTX_set1_chain()\fR set the certificate chain
101 associated with the current certificate of \fBctx\fR to \fBsk\fR.
102 .PP
103 \&\fBSSL_CTX_add0_chain_cert()\fR and \fBSSL_CTX_add1_chain_cert()\fR append the single
104 certificate \fBx509\fR to the chain associated with the current certificate of
105 \&\fBctx\fR.
106 .PP
107 \&\fBSSL_CTX_get0_chain_certs()\fR retrieves the chain associated with the current
108 certificate of \fBctx\fR.
109 .PP
110 \&\fBSSL_CTX_clear_chain_certs()\fR clears any existing chain associated with the
111 current certificate of \fBctx\fR. (This is implemented by calling
112 \&\fBSSL_CTX_set0_chain()\fR with \fBsk\fR set to \fBNULL\fR).
113 .PP
114 \&\fBSSL_CTX_build_cert_chain()\fR builds the certificate chain for \fBctx\fR.
115 Normally this uses the chain store
116 or the verify store if the chain store is not set.
117 If the function is successful the built chain will replace any existing chain.
118 The \fBflags\fR parameter can be set to \fBSSL_BUILD_CHAIN_FLAG_UNTRUSTED\fR to use
119 existing chain certificates as untrusted CAs, \fBSSL_BUILD_CHAIN_FLAG_NO_ROOT\fR
120 to omit the root CA from the built chain, \fBSSL_BUILD_CHAIN_FLAG_CHECK\fR to
121 use all existing chain certificates only to build the chain (effectively
122 sanity checking and rearranging them if necessary), the flag
123 \&\fBSSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\fR ignores any errors during verification:
124 if flag \fBSSL_BUILD_CHAIN_FLAG_CLEAR_ERROR\fR is also set verification errors
125 are cleared from the error queue.
126 Details of the chain building process are described in
127 "Certification Path Building" in \fBopenssl\-verification\-options\fR\|(1).
128 .PP
129 Each of these functions operates on the \fIcurrent\fR end entity
130 (i.e. server or client) certificate. This is the last certificate loaded or
131 selected on the corresponding \fBctx\fR structure.
132 .PP
133 \&\fBSSL_CTX_select_current_cert()\fR selects \fBx509\fR as the current end entity
134 certificate, but only if \fBx509\fR has already been loaded into \fBctx\fR using a
135 function such as \fBSSL_CTX_use_certificate()\fR.
136 .PP
137 \&\fBSSL_set0_chain()\fR, \fBSSL_set1_chain()\fR, \fBSSL_add0_chain_cert()\fR,
138 \&\fBSSL_add1_chain_cert()\fR, \fBSSL_get0_chain_certs()\fR, \fBSSL_clear_chain_certs()\fR,
139 \&\fBSSL_build_cert_chain()\fR, \fBSSL_select_current_cert()\fR and \fBSSL_set_current_cert()\fR
140 are similar except they apply to SSL structure \fBssl\fR.
141 .PP
142 \&\fBSSL_CTX_set_current_cert()\fR changes the current certificate to a value based
143 on the \fBop\fR argument. Currently \fBop\fR can be \fBSSL_CERT_SET_FIRST\fR to use
144 the first valid certificate or \fBSSL_CERT_SET_NEXT\fR to set the next valid
145 certificate after the current certificate. These two operations can be
146 used to iterate over all certificates in an \fBSSL_CTX\fR structure.
147 .PP
148 \&\fBSSL_set_current_cert()\fR also supports the option \fBSSL_CERT_SET_SERVER\fR.
149 If \fBssl\fR is a server and has sent a certificate to a connected client
150 this option sets that certificate to the current certificate and returns 1.
151 If the negotiated cipher suite is anonymous (and thus no certificate will
152 be sent) 2 is returned and the current certificate is unchanged. If \fBssl\fR
153 is not a server or a certificate has not been sent 0 is returned and
154 the current certificate is unchanged.
155 .PP
156 All these functions are implemented as macros. Those containing a \fB1\fR
157 increment the reference count of the supplied certificate or chain so it must
158 be freed at some point after the operation. Those containing a \fB0\fR do
159 not increment reference counts and the supplied certificate or chain
160 \&\fBMUST NOT\fR be freed after the operation.
161 .SH NOTES
162 .IX Header "NOTES"
163 The chains associate with an SSL_CTX structure are copied to any SSL
164 structures when \fBSSL_new()\fR is called. SSL structures will not be affected
165 by any chains subsequently changed in the parent SSL_CTX.
166 .PP
167 One chain can be set for each key type supported by a server. So, for example,
168 an RSA and a DSA certificate can (and often will) have different chains.
169 .PP
170 The functions \fBSSL_CTX_build_cert_chain()\fR and \fBSSL_build_cert_chain()\fR can
171 be used to check application configuration and to ensure any necessary
172 subordinate CAs are sent in the correct order. Misconfigured applications
173 sending incorrect certificate chains often cause problems with peers.
174 .PP
175 For example an application can add any set of certificates using
176 \&\fBSSL_CTX_use_certificate_chain_file()\fR then call \fBSSL_CTX_build_cert_chain()\fR
177 with the option \fBSSL_BUILD_CHAIN_FLAG_CHECK\fR to check and reorder them.
178 .PP
179 Applications can issue non fatal warnings when checking chains by setting
180 the flag \fBSSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS\fR and checking the return
181 value.
182 .PP
183 Calling \fBSSL_CTX_build_cert_chain()\fR or \fBSSL_build_cert_chain()\fR is more
184 efficient than the automatic chain building as it is only performed once.
185 Automatic chain building is performed on each new session.
186 .PP
187 If any certificates are added using these functions no certificates added
188 using \fBSSL_CTX_add_extra_chain_cert()\fR will be used.
189 .SH "RETURN VALUES"
190 .IX Header "RETURN VALUES"
191 \&\fBSSL_set_current_cert()\fR with \fBSSL_CERT_SET_SERVER\fR return 1 for success, 2 if
192 no server certificate is used because the cipher suites is anonymous and 0
193 for failure.
194 .PP
195 \&\fBSSL_CTX_build_cert_chain()\fR and \fBSSL_build_cert_chain()\fR return 1 for success
196 and 0 for failure. If the flag \fBSSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\fR and
197 a verification error occurs then 2 is returned.
198 .PP
199 All other functions return 1 for success and 0 for failure.
200 .SH "SEE ALSO"
201 .IX Header "SEE ALSO"
202 \&\fBssl\fR\|(7),
203 \&\fBSSL_CTX_add_extra_chain_cert\fR\|(3)
204 .SH HISTORY
205 .IX Header "HISTORY"
206 These functions were added in OpenSSL 1.0.2.
207 .SH COPYRIGHT
208 .IX Header "COPYRIGHT"
209 Copyright 2013\-2021 The OpenSSL Project Authors. All Rights Reserved.
210 .PP
211 Licensed under the Apache License 2.0 (the "License"). You may not use
212 this file except in compliance with the License. You can obtain a copy
213 in the file LICENSE in the source distribution or at
214 <https://www.openssl.org/source/license.html>.