1.\" $OpenBSD: SSL_CTX_use_certificate.3,v 1.17 2025/01/18 10:45:12 tb Exp $ 2.\" full merge up to: OpenSSL 3aaa1bd0 Mar 28 16:35:25 2017 +1000 3.\" selective merge up to: OpenSSL d1f7a1e6 Apr 26 14:05:40 2018 +0100 4.\" 5.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>. 6.\" Copyright (c) 2000, 2001, 2002, 2003, 2005 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 18 2025 $ 54.Dt SSL_CTX_USE_CERTIFICATE 3 55.Os 56.Sh NAME 57.Nm SSL_CTX_use_certificate , 58.Nm SSL_CTX_use_certificate_ASN1 , 59.Nm SSL_CTX_use_certificate_file , 60.Nm SSL_use_certificate , 61.Nm SSL_use_certificate_ASN1 , 62.Nm SSL_use_certificate_chain_file , 63.Nm SSL_use_certificate_file , 64.Nm SSL_CTX_use_certificate_chain_file , 65.Nm SSL_CTX_use_certificate_chain_mem , 66.Nm SSL_CTX_use_PrivateKey , 67.Nm SSL_CTX_use_PrivateKey_ASN1 , 68.Nm SSL_CTX_use_PrivateKey_file , 69.Nm SSL_CTX_use_RSAPrivateKey , 70.Nm SSL_CTX_use_RSAPrivateKey_ASN1 , 71.Nm SSL_CTX_use_RSAPrivateKey_file , 72.Nm SSL_use_PrivateKey_file , 73.Nm SSL_use_PrivateKey_ASN1 , 74.Nm SSL_use_PrivateKey , 75.Nm SSL_use_RSAPrivateKey , 76.Nm SSL_use_RSAPrivateKey_ASN1 , 77.Nm SSL_use_RSAPrivateKey_file , 78.Nm SSL_CTX_check_private_key , 79.Nm SSL_check_private_key 80.Nd load certificate and key data 81.Sh SYNOPSIS 82.In openssl/ssl.h 83.Ft int 84.Fn SSL_CTX_use_certificate "SSL_CTX *ctx" "X509 *x" 85.Ft int 86.Fn SSL_CTX_use_certificate_ASN1 "SSL_CTX *ctx" "int len" "unsigned char *d" 87.Ft int 88.Fn SSL_CTX_use_certificate_file "SSL_CTX *ctx" "const char *file" "int type" 89.Ft int 90.Fn SSL_use_certificate "SSL *ssl" "X509 *x" 91.Ft int 92.Fn SSL_use_certificate_ASN1 "SSL *ssl" "unsigned char *d" "int len" 93.Ft int 94.Fn SSL_use_certificate_chain_file "SSL *ssl" "const char *file" 95.Ft int 96.Fn SSL_use_certificate_file "SSL *ssl" "const char *file" "int type" 97.Ft int 98.Fn SSL_CTX_use_certificate_chain_file "SSL_CTX *ctx" "const char *file" 99.Ft int 100.Fn SSL_CTX_use_certificate_chain_mem "SSL_CTX *ctx" "void *buf" "int len" 101.Ft int 102.Fn SSL_CTX_use_PrivateKey "SSL_CTX *ctx" "EVP_PKEY *pkey" 103.Ft int 104.Fo SSL_CTX_use_PrivateKey_ASN1 105.Fa "int pk" "SSL_CTX *ctx" "unsigned char *d" "long len" 106.Fc 107.Ft int 108.Fn SSL_CTX_use_PrivateKey_file "SSL_CTX *ctx" "const char *file" "int type" 109.Ft int 110.Fn SSL_CTX_use_RSAPrivateKey "SSL_CTX *ctx" "RSA *rsa" 111.Ft int 112.Fn SSL_CTX_use_RSAPrivateKey_ASN1 "SSL_CTX *ctx" "unsigned char *d" "long len" 113.Ft int 114.Fn SSL_CTX_use_RSAPrivateKey_file "SSL_CTX *ctx" "const char *file" "int type" 115.Ft int 116.Fn SSL_use_PrivateKey "SSL *ssl" "EVP_PKEY *pkey" 117.Ft int 118.Fn SSL_use_PrivateKey_ASN1 "int pk" "SSL *ssl" "unsigned char *d" "long len" 119.Ft int 120.Fn SSL_use_PrivateKey_file "SSL *ssl" "const char *file" "int type" 121.Ft int 122.Fn SSL_use_RSAPrivateKey "SSL *ssl" "RSA *rsa" 123.Ft int 124.Fn SSL_use_RSAPrivateKey_ASN1 "SSL *ssl" "const unsigned char *d" "long len" 125.Ft int 126.Fn SSL_use_RSAPrivateKey_file "SSL *ssl" "const char *file" "int type" 127.Ft int 128.Fn SSL_CTX_check_private_key "const SSL_CTX *ctx" 129.Ft int 130.Fn SSL_check_private_key "const SSL *ssl" 131.Sh DESCRIPTION 132These functions load the certificates and private keys into the 133.Vt SSL_CTX 134or 135.Vt SSL 136object, respectively. 137.Pp 138The 139.Fn SSL_CTX_* 140class of functions loads the certificates and keys into the 141.Vt SSL_CTX 142object 143.Fa ctx . 144The information is passed to 145.Vt SSL 146objects 147.Fa ssl 148created from 149.Fa ctx 150with 151.Xr SSL_new 3 152by copying, so that changes applied to 153.Fa ctx 154do not propagate to already existing 155.Vt SSL 156objects. 157.Pp 158The 159.Fn SSL_* 160class of functions only loads certificates and keys into a specific 161.Vt SSL 162object. 163The specific information is kept when 164.Xr SSL_clear 3 165is called for this 166.Vt SSL 167object. 168.Pp 169.Fn SSL_CTX_use_certificate 170loads the certificate 171.Fa x 172into 173.Fa ctx ; 174.Fn SSL_use_certificate 175loads 176.Fa x 177into 178.Fa ssl . 179The rest of the certificates needed to form the complete certificate chain can 180be specified using the 181.Xr SSL_CTX_add_extra_chain_cert 3 182function. 183.Pp 184.Fn SSL_CTX_use_certificate_ASN1 185loads the ASN1 encoded certificate from the memory location 186.Fa d 187(with length 188.Fa len ) 189into 190.Fa ctx ; 191.Fn SSL_use_certificate_ASN1 192loads the ASN1 encoded certificate into 193.Fa ssl . 194.Pp 195.Fn SSL_CTX_use_certificate_file 196loads the first certificate stored in 197.Fa file 198into 199.Fa ctx . 200The formatting 201.Fa type 202of the certificate must be specified from the known types 203.Dv SSL_FILETYPE_PEM 204and 205.Dv SSL_FILETYPE_ASN1 . 206.Fn SSL_use_certificate_file 207loads the certificate from 208.Fa file 209into 210.Fa ssl . 211See the 212.Sx NOTES 213section on why 214.Fn SSL_CTX_use_certificate_chain_file 215should be preferred. 216.Pp 217The 218.Fn SSL_CTX_use_certificate_chain* 219functions load a certificate chain into 220.Fa ctx . 221The certificates must be in PEM format and must be sorted starting with the 222subject's certificate (actual client or server certificate), 223followed by intermediate CA certificates if applicable, 224and ending at the highest level (root) CA. 225With the exception of 226.Fn SSL_use_certificate_chain_file , 227there is no corresponding function working on a single 228.Vt SSL 229object. 230.Pp 231.Fn SSL_CTX_use_PrivateKey 232adds 233.Fa pkey 234as private key to 235.Fa ctx . 236.Fn SSL_CTX_use_RSAPrivateKey 237adds the private key 238.Fa rsa 239of type RSA to 240.Fa ctx . 241.Fn SSL_use_PrivateKey 242adds 243.Fa pkey 244as private key to 245.Fa ssl ; 246.Fn SSL_use_RSAPrivateKey 247adds 248.Fa rsa 249as private key of type RSA to 250.Fa ssl . 251If a certificate has already been set and the private does not belong to the 252certificate, an error is returned. 253To change a certificate private key pair, 254the new certificate needs to be set with 255.Fn SSL_use_certificate 256or 257.Fn SSL_CTX_use_certificate 258before setting the private key with 259.Fn SSL_CTX_use_PrivateKey 260or 261.Fn SSL_use_PrivateKey . 262.Pp 263.Fn SSL_CTX_use_PrivateKey_ASN1 264adds the private key of type 265.Fa pk 266stored at memory location 267.Fa d 268(length 269.Fa len ) 270to 271.Fa ctx . 272.Fn SSL_CTX_use_RSAPrivateKey_ASN1 273adds the private key of type RSA stored at memory location 274.Fa d 275(length 276.Fa len ) 277to 278.Fa ctx . 279.Fn SSL_use_PrivateKey_ASN1 280and 281.Fn SSL_use_RSAPrivateKey_ASN1 282add the private key to 283.Fa ssl . 284.Pp 285.Fn SSL_CTX_use_PrivateKey_file 286adds the first private key found in 287.Fa file 288to 289.Fa ctx . 290The formatting 291.Fa type 292of the private key must be specified from the known types 293.Dv SSL_FILETYPE_PEM 294and 295.Dv SSL_FILETYPE_ASN1 . 296.Fn SSL_CTX_use_RSAPrivateKey_file 297adds the first private RSA key found in 298.Fa file 299to 300.Fa ctx . 301.Fn SSL_use_PrivateKey_file 302adds the first private key found in 303.Fa file 304to 305.Fa ssl ; 306.Fn SSL_use_RSAPrivateKey_file 307adds the first private RSA key found to 308.Fa ssl . 309.Pp 310The 311.Fn SSL_CTX_check_private_key 312function is seriously misnamed. 313It compares the 314.Em public 315key components and parameters of an OpenSSL private key with the 316corresponding certificate loaded into 317.Fa ctx . 318If more than one key/certificate pair (RSA/ECDSA) is installed, 319the last item installed will be compared. 320If, e.g., the last item was an RSA certificate or key, 321the RSA key/certificate pair will be checked. 322.Fn SSL_check_private_key 323performs the same 324.Em public 325key comparison for 326.Fa ssl . 327If no key/certificate was explicitly added for this 328.Fa ssl , 329the last item added into 330.Fa ctx 331will be checked. 332.Pp 333Despite the name, neither 334.Fn SSL_CTX_check_private_key 335nor 336.Fn SSL_check_private_key 337checks whether the private key component is indeed a private key, 338nor whether it matches the public key component. 339They merely compare the public materials (e.g. exponent and modulus of 340an RSA key) and/or key parameters (e.g. EC params of an EC key) of a 341key pair. 342.Sh NOTES 343The internal certificate store of OpenSSL can hold several private 344key/certificate pairs at a time. 345The certificate used depends on the cipher selected. 346See also 347.Xr SSL_CTX_set_cipher_list 3 . 348.Pp 349When reading certificates and private keys from file, files of type 350.Dv SSL_FILETYPE_ASN1 351(also known as 352.Em DER , 353binary encoding) can only contain one certificate or private key; consequently, 354.Fn SSL_CTX_use_certificate_chain_file 355is only applicable to PEM formatting. 356Files of type 357.Dv SSL_FILETYPE_PEM 358can contain more than one item. 359.Pp 360.Fn SSL_CTX_use_certificate_chain_file 361adds the first certificate found in the file to the certificate store. 362The other certificates are added to the store of chain certificates using 363.Xr SSL_CTX_add1_chain_cert 3 . 364It is recommended to use the 365.Fn SSL_CTX_use_certificate_chain_file 366instead of the 367.Fn SSL_CTX_use_certificate_file 368function in order to allow the use of complete certificate chains even when no 369trusted CA storage is used or when the CA issuing the certificate shall not be 370added to the trusted CA storage. 371.Pp 372If additional certificates are needed to complete the chain during the TLS 373negotiation, CA certificates are additionally looked up in the locations of 374trusted CA certificates (see 375.Xr SSL_CTX_load_verify_locations 3 ) . 376.Pp 377The private keys loaded from file can be encrypted. 378In order to successfully load encrypted keys, 379a function returning the passphrase must have been supplied (see 380.Xr SSL_CTX_set_default_passwd_cb 3 ) . 381(Certificate files might be encrypted as well from the technical point of view, 382it however does not make sense as the data in the certificate is considered 383public anyway.) 384.Sh RETURN VALUES 385On success, the functions return 1. 386Otherwise check out the error stack to find out the reason. 387.Sh SEE ALSO 388.Xr ssl 3 , 389.Xr SSL_clear 3 , 390.Xr SSL_CTX_add1_chain_cert 3 , 391.Xr SSL_CTX_add_extra_chain_cert 3 , 392.Xr SSL_CTX_load_verify_locations 3 , 393.Xr SSL_CTX_set_cipher_list 3 , 394.Xr SSL_CTX_set_client_CA_list 3 , 395.Xr SSL_CTX_set_client_cert_cb 3 , 396.Xr SSL_CTX_set_default_passwd_cb 3 , 397.Xr SSL_new 3 , 398.Xr X509_check_private_key 3 399.Sh HISTORY 400.Fn SSL_use_certificate , 401.Fn SSL_use_certificate_file , 402.Fn SSL_use_RSAPrivateKey , 403and 404.Fn SSL_use_RSAPrivateKey_file 405appeared in SSLeay 0.4 or earlier. 406.Fn SSL_use_certificate_ASN1 407and 408.Fn SSL_use_RSAPrivateKey_ASN1 409first appeared in SSLeay 0.5.1. 410.Fn SSL_use_PrivateKey_file , 411.Fn SSL_use_PrivateKey_ASN1 , 412and 413.Fn SSL_use_PrivateKey 414first appeared in SSLeay 0.6.0. 415.Fn SSL_CTX_use_certificate , 416.Fn SSL_CTX_use_certificate_ASN1 , 417.Fn SSL_CTX_use_certificate_file , 418.Fn SSL_CTX_use_PrivateKey , 419.Fn SSL_CTX_use_PrivateKey_ASN1 , 420.Fn SSL_CTX_use_PrivateKey_file , 421.Fn SSL_CTX_use_RSAPrivateKey , 422.Fn SSL_CTX_use_RSAPrivateKey_ASN1 , 423and 424.Fn SSL_CTX_use_RSAPrivateKey_file 425first appeared in SSLeay 0.6.1. 426.Fn SSL_CTX_check_private_key 427and 428.Fn SSL_check_private_key 429first appeared in SSLeay 0.6.5. 430All these functions have been available since 431.Ox 2.4 . 432.Pp 433.Fn SSL_CTX_use_certificate_chain_file 434first appeared in OpenSSL 0.9.4 and has been available since 435.Ox 2.6 . 436.Pp 437.Fn SSL_use_certificate_chain_file 438first appeared in OpenSSL 1.1.0 and has been available since 439.Ox 6.9 . 440.Pp 441Support for DER encoded private keys 442.Pq Dv SSL_FILETYPE_ASN1 443in 444.Fn SSL_CTX_use_PrivateKey_file 445and 446.Fn SSL_use_PrivateKey_file 447was added in 0.9.8. 448.Pp 449.Fn SSL_CTX_use_certificate_chain_mem 450first appeared in 451.Ox 5.7 . 452