1.\" $OpenBSD: SSL_CTX_add_extra_chain_cert.3,v 1.7 2020/01/02 09:09:16 schwarze Exp $ 2.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 3.\" 4.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org> and 5.\" Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2000, 2002, 2013, 2015 The OpenSSL Project. 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: January 2 2020 $ 54.Dt SSL_CTX_ADD_EXTRA_CHAIN_CERT 3 55.Os 56.Sh NAME 57.Nm SSL_CTX_add_extra_chain_cert , 58.Nm SSL_CTX_get_extra_chain_certs_only , 59.Nm SSL_CTX_get_extra_chain_certs , 60.Nm SSL_CTX_clear_extra_chain_certs 61.Nd add, retrieve, and clear extra chain certificates 62.Sh SYNOPSIS 63.In openssl/ssl.h 64.Ft long 65.Fn SSL_CTX_add_extra_chain_cert "SSL_CTX *ctx" "X509 *x509" 66.Ft long 67.Fn SSL_CTX_get_extra_chain_certs_only "SSL_CTX *ctx" "STACK_OF(X509) **certs" 68.Ft long 69.Fn SSL_CTX_get_extra_chain_certs "SSL_CTX *ctx" "STACK_OF(X509) **certs" 70.Ft long 71.Fn SSL_CTX_clear_extra_chain_certs "SSL_CTX *ctx" 72.Sh DESCRIPTION 73.Fn SSL_CTX_add_extra_chain_cert 74adds the certificate 75.Fa x509 76to the extra chain certificates associated with 77.Fa ctx . 78Several certificates can be added one after another. 79.Pp 80.Fn SSL_CTX_get_extra_chain_certs_only 81retrieves an internal pointer to the stack of extra chain certificates 82associated with 83.Fa ctx , 84or set 85.Pf * Fa certs 86to 87.Dv NULL 88if there are none. 89.Pp 90.Fn SSL_CTX_get_extra_chain_certs 91does the same except that it retrieves an internal pointer 92to the chain associated with the certificate 93if there are no extra chain certificates. 94.Pp 95.Fn SSL_CTX_clear_extra_chain_certs 96clears all extra chain certificates associated with 97.Fa ctx . 98.Pp 99These functions are implemented as macros. 100.Pp 101When sending a certificate chain, extra chain certificates are sent 102in order following the end entity certificate. 103.Pp 104If no chain is specified, the library will try to complete the chain from the 105available CA certificates in the trusted CA storage, see 106.Xr SSL_CTX_load_verify_locations 3 . 107.Pp 108The x509 certificate provided to 109.Fn SSL_CTX_add_extra_chain_cert 110will be freed by the library when the 111.Vt SSL_CTX 112is destroyed. 113An application should not free the 114.Fa x509 115object, nor the 116.Pf * Fa certs 117object retrieved by 118.Fn SSL_CTX_get_extra_chain_certs . 119.Sh RETURN VALUES 120These functions return 1 on success or 0 for failure. 121Check out the error stack to find out the reason for failure. 122.Sh SEE ALSO 123.Xr ssl 3 , 124.Xr SSL_CTX_add1_chain_cert 3 , 125.Xr SSL_CTX_ctrl 3 , 126.Xr SSL_CTX_load_verify_locations 3 , 127.Xr SSL_CTX_set_client_cert_cb 3 , 128.Xr SSL_CTX_use_certificate 3 129.Sh HISTORY 130.Fn SSL_CTX_add_extra_chain_cert 131first appeared in SSLeay 0.9.1 and has been available since 132.Ox 2.6 . 133.Pp 134.Fn SSL_CTX_get_extra_chain_certs 135and 136.Fn SSL_CTX_clear_extra_chain_certs 137first appeared in OpenSSL 1.0.1 and have been available since 138.Ox 5.3 . 139.Pp 140.Fn SSL_CTX_get_extra_chain_certs_only 141first appeared in OpenSSL 1.0.2 and has been available since 142.Ox 6.7 . 143.Sh CAVEATS 144Certificates added with 145.Fn SSL_CTX_add_extra_chain_cert 146are ignored when certificates are also available that have been 147added using the functions documented in 148.Xr SSL_CTX_set1_chain 3 . 149.Pp 150Only one set of extra chain certificates can be specified per 151.Vt SSL_CTX 152structure using 153.Fn SSL_CTX_add_extra_chain_cert . 154Different chains for different certificates (for example if both 155RSA and DSA certificates are specified by the same server) or 156different SSL structures with the same parent 157.Vt SSL_CTX 158require using the functions documented in 159.Xr SSL_CTX_set1_chain 3 160instead. 161