1.\" $OpenBSD: SSL_CTX_use_certificate.3,v 1.2 2016/12/01 22:17:32 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: December 1 2016 $ 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" "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 certificate 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 304.Fn SSL_CTX_check_private_key 305checks the consistency of a private key with the corresponding certificate 306loaded into 307.Fa ctx . 308If more than one key/certificate pair (RSA/DSA) is installed, 309the last item installed will be checked. 310If, e.g., the last item was a RSA certificate or key, 311the RSA key/certificate pair will be checked. 312.Fn SSL_check_private_key 313performs the same check for 314.Fa ssl . 315If no key/certificate was explicitly added for this 316.Fa ssl , 317the last item added into 318.Fa ctx 319will be checked. 320.Sh NOTES 321The internal certificate store of OpenSSL can hold two private key/certificate 322pairs at a time: 323one key/certificate of type RSA and one key/certificate of type DSA. 324The certificate used depends on the cipher select, see also 325.Xr SSL_CTX_set_cipher_list 3 . 326.Pp 327When reading certificates and private keys from file, files of type 328.Dv SSL_FILETYPE_ASN1 329(also known as 330.Em DER , 331binary encoding) can only contain one certificate or private key; consequently, 332.Fn SSL_CTX_use_certificate_chain_file 333is only applicable to PEM formatting. 334Files of type 335.Dv SSL_FILETYPE_PEM 336can contain more than one item. 337.Pp 338.Fn SSL_CTX_use_certificate_chain_file 339adds the first certificate found in the file to the certificate store. 340The other certificates are added to the store of chain certificates using 341.Xr SSL_CTX_add_extra_chain_cert 3 . 342There exists only one extra chain store, so that the same chain is appended 343to both types of certificates, RSA and DSA! 344If it is not intended to use both type of certificate at the same time, 345it is recommended to use the 346.Fn SSL_CTX_use_certificate_chain_file 347instead of the 348.Fn SSL_CTX_use_certificate_file 349function in order to allow the use of complete certificate chains even when no 350trusted CA storage is used or when the CA issuing the certificate shall not be 351added to the trusted CA storage. 352.Pp 353If additional certificates are needed to complete the chain during the TLS 354negotiation, CA certificates are additionally looked up in the locations of 355trusted CA certificates (see 356.Xr SSL_CTX_load_verify_locations 3 ) . 357.Pp 358The private keys loaded from file can be encrypted. 359In order to successfully load encrypted keys, 360a function returning the passphrase must have been supplied (see 361.Xr SSL_CTX_set_default_passwd_cb 3 ) . 362(Certificate files might be encrypted as well from the technical point of view, 363it however does not make sense as the data in the certificate is considered 364public anyway.) 365.Sh RETURN VALUES 366On success, the functions return 1. 367Otherwise check out the error stack to find out the reason. 368.Sh SEE ALSO 369.Xr ssl 3 , 370.Xr SSL_clear 3 , 371.Xr SSL_CTX_add_extra_chain_cert 3 , 372.Xr SSL_CTX_load_verify_locations 3 , 373.Xr SSL_CTX_set_cipher_list 3 , 374.Xr SSL_CTX_set_client_cert_cb 3 , 375.Xr SSL_CTX_set_default_passwd_cb 3 , 376.Xr SSL_new 3 377.Sh HISTORY 378Support for DER encoded private keys 379.Pq Dv SSL_FILETYPE_ASN1 380in 381.Fn SSL_CTX_use_PrivateKey_file 382and 383.Fn SSL_use_PrivateKey_file 384was added in 0.9.8. 385