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