1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.35)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
54 .\" Avoid warning from groff about undefined register 'F'.
60 . tm Index:\\$1\t\\n%\t"\\$2"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "SSL_CTX_add1_chain_cert 3"
132 .TH SSL_CTX_add1_chain_cert 3 "2017-05-25" "1.0.2l" "OpenSSL"
133 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
134 .\" way too many mistakes in technical documents.
138 SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert,
139 SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs,
140 SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert,
141 SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain,
142 SSL_build_cert_chain, SSL_CTX_select_current_cert,
143 SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert \- extra
144 chain certificate processing
146 .IX Header "SYNOPSIS"
148 \& #include <openssl/ssl.h>
150 \& int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
151 \& int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
152 \& int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509);
153 \& int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
154 \& int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
155 \& int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);
157 \& int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk);
158 \& int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk);
159 \& int SSL_add0_chain_cert(SSL *ssl, X509 *x509);
160 \& int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
161 \& int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
162 \& int SSL_clear_chain_certs(SSL *ssl);
164 \& int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
165 \& int SSL_build_cert_chain(SSL *ssl, flags);
167 \& int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509);
168 \& int SSL_select_current_cert(SSL *ssl, X509 *x509);
169 \& int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op);
170 \& int SSL_set_current_cert(SSL *ssl, long op);
173 .IX Header "DESCRIPTION"
174 \&\fISSL_CTX_set0_chain()\fR and \fISSL_CTX_set1_chain()\fR set the certificate chain
175 associated with the current certificate of \fBctx\fR to \fBsk\fR.
177 \&\fISSL_CTX_add0_chain_cert()\fR and \fISSL_CTX_add1_chain_cert()\fR append the single
178 certificate \fBx509\fR to the chain associated with the current certificate of
181 \&\fISSL_CTX_get0_chain_certs()\fR retrieves the chain associated with the current
182 certificate of \fBctx\fR.
184 \&\fISSL_CTX_clear_chain_certs()\fR clears any existing chain associated with the
185 current certificate of \fBctx\fR. (This is implemented by calling
186 \&\fISSL_CTX_set0_chain()\fR with \fBsk\fR set to \fB\s-1NULL\s0\fR).
188 \&\fISSL_CTX_build_cert_chain()\fR builds the certificate chain for \fBctx\fR normally
189 this uses the chain store or the verify store if the chain store is not set.
190 If the function is successful the built chain will replace any existing chain.
191 The \fBflags\fR parameter can be set to \fB\s-1SSL_BUILD_CHAIN_FLAG_UNTRUSTED\s0\fR to use
192 existing chain certificates as untrusted CAs, \fB\s-1SSL_BUILD_CHAIN_FLAG_NO_ROOT\s0\fR
193 to omit the root \s-1CA\s0 from the built chain, \fB\s-1SSL_BUILD_CHAIN_FLAG_CHECK\s0\fR to
194 use all existing chain certificates only to build the chain (effectively
195 sanity checking and rearranging them if necessary), the flag
196 \&\fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\s0\fR ignores any errors during verification:
197 if flag \fB\s-1SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR\s0\fR is also set verification errors
198 are cleared from the error queue.
200 Each of these functions operates on the \fIcurrent\fR end entity
201 (i.e. server or client) certificate. This is the last certificate loaded or
202 selected on the corresponding \fBctx\fR structure.
204 \&\fISSL_CTX_select_current_cert()\fR selects \fBx509\fR as the current end entity
205 certificate, but only if \fBx509\fR has already been loaded into \fBctx\fR using a
206 function such as \fISSL_CTX_use_certificate()\fR.
208 \&\fISSL_set0_chain()\fR, \fISSL_set1_chain()\fR, \fISSL_add0_chain_cert()\fR,
209 \&\fISSL_add1_chain_cert()\fR, \fISSL_get0_chain_certs()\fR, \fISSL_clear_chain_certs()\fR,
210 \&\fISSL_build_cert_chain()\fR, \fISSL_select_current_cert()\fR and \fISSL_set_current_cert()\fR
211 are similar except they apply to \s-1SSL\s0 structure \fBssl\fR.
213 \&\fISSL_CTX_set_current_cert()\fR changes the current certificate to a value based
214 on the \fBop\fR argument. Currently \fBop\fR can be \fB\s-1SSL_CERT_SET_FIRST\s0\fR to use
215 the first valid certificate or \fB\s-1SSL_CERT_SET_NEXT\s0\fR to set the next valid
216 certificate after the current certificate. These two operations can be
217 used to iterate over all certificates in an \fB\s-1SSL_CTX\s0\fR structure.
219 \&\fISSL_set_current_cert()\fR also supports the option \fB\s-1SSL_CERT_SET_SERVER\s0\fR.
220 If \fBssl\fR is a server and has sent a certificate to a connected client
221 this option sets that certificate to the current certificate and returns 1.
222 If the negotiated ciphersuite is anonymous (and thus no certificate will
223 be sent) 2 is returned and the current certificate is unchanged. If \fBssl\fR
224 is not a server or a certificate has not been sent 0 is returned and
225 the current certificate is unchanged.
227 All these functions are implemented as macros. Those containing a \fB1\fR
228 increment the reference count of the supplied certificate or chain so it must
229 be freed at some point after the operation. Those containing a \fB0\fR do
230 not increment reference counts and the supplied certificate or chain
231 \&\fB\s-1MUST NOT\s0\fR be freed after the operation.
234 The chains associate with an \s-1SSL_CTX\s0 structure are copied to any \s-1SSL\s0
235 structures when \fISSL_new()\fR is called. \s-1SSL\s0 structures will not be affected
236 by any chains subsequently changed in the parent \s-1SSL_CTX.\s0
238 One chain can be set for each key type supported by a server. So, for example,
239 an \s-1RSA\s0 and a \s-1DSA\s0 certificate can (and often will) have different chains.
241 The functions \fISSL_CTX_build_cert_chain()\fR and \fISSL_build_cert_chain()\fR can
242 be used to check application configuration and to ensure any necessary
243 subordinate CAs are sent in the correct order. Misconfigured applications
244 sending incorrect certificate chains often cause problems with peers.
246 For example an application can add any set of certificates using
247 \&\fISSL_CTX_use_certificate_chain_file()\fR then call \fISSL_CTX_build_cert_chain()\fR
248 with the option \fB\s-1SSL_BUILD_CHAIN_FLAG_CHECK\s0\fR to check and reorder them.
250 Applications can issue non fatal warnings when checking chains by setting
251 the flag \fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS\s0\fR and checking the return
254 Calling \fISSL_CTX_build_cert_chain()\fR or \fISSL_build_cert_chain()\fR is more
255 efficient than the automatic chain building as it is only performed once.
256 Automatic chain building is performed on each new session.
258 If any certificates are added using these functions no certificates added
259 using \fISSL_CTX_add_extra_chain_cert()\fR will be used.
261 .IX Header "RETURN VALUES"
262 \&\fISSL_set_current_cert()\fR with \fB\s-1SSL_CERT_SET_SERVER\s0\fR return 1 for success, 2 if
263 no server certificate is used because the ciphersuites is anonymous and 0
266 \&\fISSL_CTX_build_cert_chain()\fR and \fISSL_build_cert_chain()\fR return 1 for success
267 and 0 for failure. If the flag \fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\s0\fR and
268 a verification error occurs then 2 is returned.
270 All other functions return 1 for success and 0 for failure.
272 .IX Header "SEE ALSO"
273 \&\fISSL_CTX_add_extra_chain_cert\fR\|(3)
276 These functions were first added to OpenSSL 1.0.2.