| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert,
|
|---|
| 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,
|
|---|
| 10 | SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert - extra
|
|---|
| 11 | chain certificate processing
|
|---|
| 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);
|
|---|
| 19 | int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509);
|
|---|
| 20 | int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
|
|---|
| 21 | int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
|
|---|
| 22 | int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);
|
|---|
| 23 |
|
|---|
| 24 | int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk);
|
|---|
| 25 | int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk);
|
|---|
| 26 | int SSL_add0_chain_cert(SSL *ssl, X509 *x509);
|
|---|
| 27 | int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
|
|---|
| 28 | int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
|
|---|
| 29 | int SSL_clear_chain_certs(SSL *ssl);
|
|---|
| 30 |
|
|---|
| 31 | int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
|
|---|
| 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);
|
|---|
| 36 | int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op);
|
|---|
| 37 | int SSL_set_current_cert(SSL *ssl, long op);
|
|---|
| 38 |
|
|---|
| 39 | =head1 DESCRIPTION
|
|---|
| 40 |
|
|---|
| 41 | SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain
|
|---|
| 42 | associated with the current certificate of B<ctx> to B<sk>.
|
|---|
| 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 |
|
|---|
| 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 |
|
|---|
| 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.
|
|---|
| 58 | If the function is successful the built chain will replace any existing chain.
|
|---|
| 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
|
|---|
| 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.
|
|---|
| 67 | Details of the chain building process are described in
|
|---|
| 68 | L<openssl-verification-options(1)/Certification Path Building>.
|
|---|
| 69 |
|
|---|
| 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(),
|
|---|
| 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.
|
|---|
| 88 |
|
|---|
| 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.
|
|---|
| 92 | If the negotiated cipher suite is anonymous (and thus no certificate will
|
|---|
| 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 |
|
|---|
| 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 |
|
|---|
| 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 |
|
|---|
| 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 |
|
|---|
| 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 |
|
|---|
| 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 |
|
|---|
| 134 | SSL_set_current_cert() with B<SSL_CERT_SET_SERVER> return 1 for success, 2 if
|
|---|
| 135 | no server certificate is used because the cipher suites is anonymous and 0
|
|---|
| 136 | for failure.
|
|---|
| 137 |
|
|---|
| 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 |
|
|---|
| 142 | All other functions return 1 for success and 0 for failure.
|
|---|
| 143 |
|
|---|
| 144 | =head1 SEE ALSO
|
|---|
| 145 |
|
|---|
| 146 | L<ssl(7)>,
|
|---|
| 147 | L<SSL_CTX_add_extra_chain_cert(3)>
|
|---|
| 148 |
|
|---|
| 149 | =head1 HISTORY
|
|---|
| 150 |
|
|---|
| 151 | These functions were added in OpenSSL 1.0.2.
|
|---|
| 152 |
|
|---|
| 153 | =head1 COPYRIGHT
|
|---|
| 154 |
|
|---|
| 155 | Copyright 2013-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 156 |
|
|---|
| 157 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 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
|
|---|
