1.\" $OpenBSD: SSL_CTX_add1_chain_cert.3,v 1.2 2025/01/18 10:45:12 tb Exp $ 2.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org> 5.\" and Rob Stradling <rob.stradling@comodo.com>. 6.\" Copyright (c) 2013 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: January 18 2025 $ 53.Dt SSL_CTX_ADD1_CHAIN_CERT 3 54.Os 55.Sh NAME 56.Nm SSL_CTX_set0_chain , 57.Nm SSL_CTX_set1_chain , 58.Nm SSL_CTX_add0_chain_cert , 59.Nm SSL_CTX_add1_chain_cert , 60.Nm SSL_CTX_get0_chain_certs , 61.Nm SSL_CTX_clear_chain_certs , 62.Nm SSL_set0_chain , 63.Nm SSL_set1_chain , 64.Nm SSL_add0_chain_cert , 65.Nm SSL_add1_chain_cert , 66.Nm SSL_get0_chain_certs , 67.Nm SSL_clear_chain_certs 68.Nd extra chain certificate processing 69.Sh SYNOPSIS 70.In openssl/ssl.h 71.Ft int 72.Fo SSL_CTX_set0_chain 73.Fa "SSL_CTX *ctx" 74.Fa "STACK_OF(X509) *chain" 75.Fc 76.Ft int 77.Fo SSL_CTX_set1_chain 78.Fa "SSL_CTX *ctx" 79.Fa "STACK_OF(X509) *chain" 80.Fc 81.Ft int 82.Fo SSL_CTX_add0_chain_cert 83.Fa "SSL_CTX *ctx" 84.Fa "X509 *cert" 85.Fc 86.Ft int 87.Fo SSL_CTX_add1_chain_cert 88.Fa "SSL_CTX *ctx" 89.Fa "X509 *cert" 90.Fc 91.Ft int 92.Fo SSL_CTX_get0_chain_certs 93.Fa "SSL_CTX *ctx" 94.Fa "STACK_OF(X509) **chain" 95.Fc 96.Ft int 97.Fo SSL_CTX_clear_chain_certs 98.Fa "SSL_CTX *ctx" 99.Fc 100.Ft int 101.Fo SSL_set0_chain 102.Fa "SSL *ssl" 103.Fa "STACK_OF(X509) *chain" 104.Fc 105.Ft int 106.Fo SSL_set1_chain 107.Fa "SSL *ssl" 108.Fa "STACK_OF(X509) *chain" 109.Fc 110.Ft int 111.Fo SSL_add0_chain_cert 112.Fa "SSL *ssl" 113.Fa "X509 *cert" 114.Fc 115.Ft int 116.Fo SSL_add1_chain_cert 117.Fa "SSL *ssl" 118.Fa "X509 *cert" 119.Fc 120.Ft int 121.Fo SSL_get0_chain_certs 122.Fa "SSL *ssl" 123.Fa "STACK_OF(X509) **chain" 124.Fc 125.Ft int 126.Fo SSL_clear_chain_certs 127.Fa "SSL *ssl" 128.Fc 129.Sh DESCRIPTION 130.Fn SSL_CTX_set0_chain 131and 132.Fn SSL_CTX_set1_chain 133set the certificate chain associated with the current certificate of 134.Fa ctx 135to 136.Fa chain . 137The 138.Fa chain 139is not supposed to include the current certificate itself. 140.Pp 141.Fn SSL_CTX_add0_chain_cert 142and 143.Fn SSL_CTX_add1_chain_cert 144append the single certificate 145.Fa cert 146to the chain associated with the current certificate of 147.Fa ctx . 148.Pp 149.Fn SSL_CTX_get0_chain_certs 150retrieves the chain associated with the current certificate of 151.Fa ctx . 152.Pp 153.Fn SSL_CTX_clear_chain_certs 154clears the existing chain associated with the current certificate of 155.Fa ctx , 156if any. 157This is equivalent to calling 158.Fn SSL_CTX_set0_chain 159with 160.Fa chain 161set to 162.Dv NULL . 163.Pp 164Each of these functions operates on the 165.Em current 166end entity (i.e. server or client) certificate. 167This is the last certificate loaded or selected on the corresponding 168.Fa ctx 169structure, for example using 170.Xr SSL_CTX_use_certificate 3 . 171.Pp 172.Fn SSL_set0_chain , 173.Fn SSL_set1_chain , 174.Fn SSL_add0_chain_cert , 175.Fn SSL_add1_chain_cert , 176.Fn SSL_get0_chain_certs , 177and 178.Fn SSL_clear_chain_certs 179are similar except that they operate on the 180.Fa ssl 181connection. 182.Pp 183The functions containing a 184.Sy 1 185in their name increment the reference count of the supplied certificate 186or chain, so it must be freed at some point after the operation. 187Those containing a 188.Sy 0 189do not increment reference counts and the supplied certificate or chain 190must not be freed after the operation. 191.Pp 192The chains associated with an 193.Vt SSL_CTX 194structure are copied to the new 195.Vt SSL 196structure when 197.Xr SSL_new 3 198is called. 199Existing 200.Vt SSL 201structures are not affected by any chains subsequently changed 202in the parent 203.Vt SSL_CTX . 204.Pp 205One chain can be set for each key type supported by a server. 206So, for example, an RSA and an ECDSA certificate can have 207different chains. 208.Pp 209If any certificates are added using these functions, no certificates 210added using 211.Xr SSL_CTX_add_extra_chain_cert 3 212will be used. 213.Sh RETURN VALUES 214These functions return 1 for success or 0 for failure. 215.Sh SEE ALSO 216.Xr ssl 3 , 217.Xr SSL_CTX_add_extra_chain_cert 3 , 218.Xr SSL_CTX_use_certificate 3 219.Sh HISTORY 220These functions first appeared in OpenSSL 1.0.2 221and have been available since 222.Ox 6.5 . 223