]>
Commit | Line | Data |
---|---|---|
eeb15452 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert, | |
7b6b246f RS |
6 | SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs, |
7 | SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert, | |
8 | SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain, | |
9 | SSL_build_cert_chain, SSL_CTX_select_current_cert, | |
0f78819c DSH |
10 | SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert - extra |
11 | chain certificate processing | |
eeb15452 DSH |
12 | |
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/ssl.h> | |
16 | ||
17 | int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); | |
18 | int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); | |
7b6b246f | 19 | int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509); |
eeb15452 | 20 | int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509); |
7b6b246f RS |
21 | int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk); |
22 | int SSL_CTX_clear_chain_certs(SSL_CTX *ctx); | |
eeb15452 DSH |
23 | |
24 | int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk); | |
25 | int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk); | |
7b6b246f | 26 | int SSL_add0_chain_cert(SSL *ssl, X509 *x509); |
eeb15452 | 27 | int SSL_add1_chain_cert(SSL *ssl, X509 *x509); |
7b6b246f RS |
28 | int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk); |
29 | int SSL_clear_chain_certs(SSL *ssl); | |
eeb15452 DSH |
30 | |
31 | int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags); | |
7b6b246f RS |
32 | int SSL_build_cert_chain(SSL *ssl, flags); |
33 | ||
34 | int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509); | |
35 | int SSL_select_current_cert(SSL *ssl, X509 *x509); | |
0f78819c DSH |
36 | int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op); |
37 | int SSL_set_current_cert(SSL *ssl, long op); | |
eeb15452 DSH |
38 | |
39 | =head1 DESCRIPTION | |
40 | ||
41 | SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain | |
7b6b246f | 42 | associated with the current certificate of B<ctx> to B<sk>. |
eeb15452 DSH |
43 | |
44 | SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single | |
45 | certificate B<x509> to the chain associated with the current certificate of | |
46 | B<ctx>. | |
47 | ||
7b6b246f RS |
48 | SSL_CTX_get0_chain_certs() retrieves the chain associated with the current |
49 | certificate of B<ctx>. | |
50 | ||
51 | SSL_CTX_clear_chain_certs() clears any existing chain associated with the | |
52 | current certificate of B<ctx>. (This is implemented by calling | |
53 | SSL_CTX_set0_chain() with B<sk> set to B<NULL>). | |
54 | ||
f9ac6f69 DDO |
55 | SSL_CTX_build_cert_chain() builds the certificate chain for B<ctx>. |
56 | Normally this uses the chain store | |
57 | or the verify store if the chain store is not set. | |
eeb15452 | 58 | If the function is successful the built chain will replace any existing chain. |
13dc3ce9 DSH |
59 | The B<flags> parameter can be set to B<SSL_BUILD_CHAIN_FLAG_UNTRUSTED> to use |
60 | existing chain certificates as untrusted CAs, B<SSL_BUILD_CHAIN_FLAG_NO_ROOT> | |
61 | to omit the root CA from the built chain, B<SSL_BUILD_CHAIN_FLAG_CHECK> to | |
62 | use all existing chain certificates only to build the chain (effectively | |
63 | sanity checking and rearranging them if necessary), the flag | |
e970f63d DSH |
64 | B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> ignores any errors during verification: |
65 | if flag B<SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR> is also set verification errors | |
66 | are cleared from the error queue. | |
f9ac6f69 DDO |
67 | Details of the chain building process are described in |
68 | L<openssl-verification-options(1)/Certification Path Building>. | |
eeb15452 | 69 | |
7b6b246f RS |
70 | Each of these functions operates on the I<current> end entity |
71 | (i.e. server or client) certificate. This is the last certificate loaded or | |
72 | selected on the corresponding B<ctx> structure. | |
73 | ||
74 | SSL_CTX_select_current_cert() selects B<x509> as the current end entity | |
75 | certificate, but only if B<x509> has already been loaded into B<ctx> using a | |
76 | function such as SSL_CTX_use_certificate(). | |
77 | ||
78 | SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(), | |
79 | SSL_add1_chain_cert(), SSL_get0_chain_certs(), SSL_clear_chain_certs(), | |
0f78819c DSH |
80 | SSL_build_cert_chain(), SSL_select_current_cert() and SSL_set_current_cert() |
81 | are similar except they apply to SSL structure B<ssl>. | |
82 | ||
83 | SSL_CTX_set_current_cert() changes the current certificate to a value based | |
84 | on the B<op> argument. Currently B<op> can be B<SSL_CERT_SET_FIRST> to use | |
85 | the first valid certificate or B<SSL_CERT_SET_NEXT> to set the next valid | |
86 | certificate after the current certificate. These two operations can be | |
87 | used to iterate over all certificates in an B<SSL_CTX> structure. | |
eeb15452 | 88 | |
daddd9a9 DSH |
89 | SSL_set_current_cert() also supports the option B<SSL_CERT_SET_SERVER>. |
90 | If B<ssl> is a server and has sent a certificate to a connected client | |
91 | this option sets that certificate to the current certificate and returns 1. | |
c4de074e | 92 | If the negotiated cipher suite is anonymous (and thus no certificate will |
daddd9a9 DSH |
93 | be sent) 2 is returned and the current certificate is unchanged. If B<ssl> |
94 | is not a server or a certificate has not been sent 0 is returned and | |
95 | the current certificate is unchanged. | |
96 | ||
eeb15452 DSH |
97 | All these functions are implemented as macros. Those containing a B<1> |
98 | increment the reference count of the supplied certificate or chain so it must | |
99 | be freed at some point after the operation. Those containing a B<0> do | |
100 | not increment reference counts and the supplied certificate or chain | |
101 | B<MUST NOT> be freed after the operation. | |
102 | ||
103 | =head1 NOTES | |
104 | ||
105 | The chains associate with an SSL_CTX structure are copied to any SSL | |
106 | structures when SSL_new() is called. SSL structures will not be affected | |
107 | by any chains subsequently changed in the parent SSL_CTX. | |
108 | ||
eeb15452 DSH |
109 | One chain can be set for each key type supported by a server. So, for example, |
110 | an RSA and a DSA certificate can (and often will) have different chains. | |
111 | ||
112 | The functions SSL_CTX_build_cert_chain() and SSL_build_cert_chain() can | |
113 | be used to check application configuration and to ensure any necessary | |
114 | subordinate CAs are sent in the correct order. Misconfigured applications | |
115 | sending incorrect certificate chains often cause problems with peers. | |
116 | ||
13dc3ce9 DSH |
117 | For example an application can add any set of certificates using |
118 | SSL_CTX_use_certificate_chain_file() then call SSL_CTX_build_cert_chain() | |
119 | with the option B<SSL_BUILD_CHAIN_FLAG_CHECK> to check and reorder them. | |
120 | ||
e970f63d DSH |
121 | Applications can issue non fatal warnings when checking chains by setting |
122 | the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS> and checking the return | |
123 | value. | |
124 | ||
eeb15452 DSH |
125 | Calling SSL_CTX_build_cert_chain() or SSL_build_cert_chain() is more |
126 | efficient than the automatic chain building as it is only performed once. | |
127 | Automatic chain building is performed on each new session. | |
128 | ||
129 | If any certificates are added using these functions no certificates added | |
130 | using SSL_CTX_add_extra_chain_cert() will be used. | |
131 | ||
132 | =head1 RETURN VALUES | |
133 | ||
13dc3ce9 | 134 | SSL_set_current_cert() with B<SSL_CERT_SET_SERVER> return 1 for success, 2 if |
c4de074e | 135 | no server certificate is used because the cipher suites is anonymous and 0 |
13dc3ce9 DSH |
136 | for failure. |
137 | ||
e970f63d DSH |
138 | SSL_CTX_build_cert_chain() and SSL_build_cert_chain() return 1 for success |
139 | and 0 for failure. If the flag B<SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR> and | |
140 | a verification error occurs then 2 is returned. | |
141 | ||
13dc3ce9 | 142 | All other functions return 1 for success and 0 for failure. |
eeb15452 | 143 | |
eeb15452 DSH |
144 | =head1 SEE ALSO |
145 | ||
98ca37e4 | 146 | L<ssl(7)>, |
9b86974e | 147 | L<SSL_CTX_add_extra_chain_cert(3)> |
eeb15452 DSH |
148 | |
149 | =head1 HISTORY | |
150 | ||
fc5ecadd | 151 | These functions were added in OpenSSL 1.0.2. |
eeb15452 | 152 | |
e2f92610 RS |
153 | =head1 COPYRIGHT |
154 | ||
38fc02a7 | 155 | Copyright 2013-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 156 | |
4746f25a | 157 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
158 | this file except in compliance with the License. You can obtain a copy |
159 | in the file LICENSE in the source distribution or at | |
160 | L<https://www.openssl.org/source/license.html>. | |
161 | ||
162 | =cut |