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