1.\" 2.\" $OpenBSD: SSL_CTX_use_certificate.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ 3.\" 4.Dd $Mdocdate: November 5 2016 $ 5.Dt SSL_CTX_USE_CERTIFICATE 3 6.Os 7.Sh NAME 8.Nm SSL_CTX_use_certificate , 9.Nm SSL_CTX_use_certificate_ASN1 , 10.Nm SSL_CTX_use_certificate_file , 11.Nm SSL_use_certificate , 12.Nm SSL_use_certificate_ASN1 , 13.Nm SSL_use_certificate_file , 14.Nm SSL_CTX_use_certificate_chain_file , 15.Nm SSL_CTX_use_certificate_chain_mem , 16.Nm SSL_CTX_use_PrivateKey , 17.Nm SSL_CTX_use_PrivateKey_ASN1 , 18.Nm SSL_CTX_use_PrivateKey_file , 19.Nm SSL_CTX_use_RSAPrivateKey , 20.Nm SSL_CTX_use_RSAPrivateKey_ASN1 , 21.Nm SSL_CTX_use_RSAPrivateKey_file , 22.Nm SSL_use_PrivateKey_file , 23.Nm SSL_use_PrivateKey_ASN1 , 24.Nm SSL_use_PrivateKey , 25.Nm SSL_use_RSAPrivateKey , 26.Nm SSL_use_RSAPrivateKey_ASN1 , 27.Nm SSL_use_RSAPrivateKey_file , 28.Nm SSL_CTX_check_private_key , 29.Nm SSL_check_private_key 30.Nd load certificate and key data 31.Sh SYNOPSIS 32.In openssl/ssl.h 33.Ft int 34.Fn SSL_CTX_use_certificate "SSL_CTX *ctx" "X509 *x" 35.Ft int 36.Fn SSL_CTX_use_certificate_ASN1 "SSL_CTX *ctx" "int len" "unsigned char *d" 37.Ft int 38.Fn SSL_CTX_use_certificate_file "SSL_CTX *ctx" "const char *file" "int type" 39.Ft int 40.Fn SSL_use_certificate "SSL *ssl" "X509 *x" 41.Ft int 42.Fn SSL_use_certificate_ASN1 "SSL *ssl" "unsigned char *d" "int len" 43.Ft int 44.Fn SSL_use_certificate_file "SSL *ssl" "const char *file" "int type" 45.Ft int 46.Fn SSL_CTX_use_certificate_chain_file "SSL_CTX *ctx" "const char *file" 47.Ft int 48.Fn SSL_CTX_use_certificate_chain_mem "SSL_CTX *ctx" "void *buf" "int len" 49.Ft int 50.Fn SSL_CTX_use_PrivateKey "SSL_CTX *ctx" "EVP_PKEY *pkey" 51.Ft int 52.Fo SSL_CTX_use_PrivateKey_ASN1 53.Fa "int pk" "SSL_CTX *ctx" "unsigned char *d" "long len" 54.Fc 55.Ft int 56.Fn SSL_CTX_use_PrivateKey_file "SSL_CTX *ctx" "const char *file" "int type" 57.Ft int 58.Fn SSL_CTX_use_RSAPrivateKey "SSL_CTX *ctx" "RSA *rsa" 59.Ft int 60.Fn SSL_CTX_use_RSAPrivateKey_ASN1 "SSL_CTX *ctx" "unsigned char *d" "long len" 61.Ft int 62.Fn SSL_CTX_use_RSAPrivateKey_file "SSL_CTX *ctx" "const char *file" "int type" 63.Ft int 64.Fn SSL_use_PrivateKey "SSL *ssl" "EVP_PKEY *pkey" 65.Ft int 66.Fn SSL_use_PrivateKey_ASN1 "int pk" "SSL *ssl" "unsigned char *d" "long len" 67.Ft int 68.Fn SSL_use_PrivateKey_file "SSL *ssl" "const char *file" "int type" 69.Ft int 70.Fn SSL_use_RSAPrivateKey "SSL *ssl" "RSA *rsa" 71.Ft int 72.Fn SSL_use_RSAPrivateKey_ASN1 "SSL *ssl" "unsigned char *d" "long len" 73.Ft int 74.Fn SSL_use_RSAPrivateKey_file "SSL *ssl" "const char *file" "int type" 75.Ft int 76.Fn SSL_CTX_check_private_key "const SSL_CTX *ctx" 77.Ft int 78.Fn SSL_check_private_key "const SSL *ssl" 79.Sh DESCRIPTION 80These functions load the certificates and private keys into the 81.Vt SSL_CTX 82or 83.Vt SSL 84object, respectively. 85.Pp 86The 87.Fn SSL_CTX_* 88class of functions loads the certificates and keys into the 89.Vt SSL_CTX 90object 91.Fa ctx . 92The information is passed to 93.Vt SSL 94objects 95.Fa ssl 96created from 97.Fa ctx 98with 99.Xr SSL_new 3 100by copying, so that changes applied to 101.Fa ctx 102do not propagate to already existing 103.Vt SSL 104objects. 105.Pp 106The 107.Fn SSL_* 108class of functions only loads certificates and keys into a specific 109.Vt SSL 110object. 111The specific information is kept when 112.Xr SSL_clear 3 113is called for this 114.Vt SSL 115object. 116.Pp 117.Fn SSL_CTX_use_certificate 118loads the certificate 119.Fa x 120into 121.Fa ctx ; 122.Fn SSL_use_certificate 123loads 124.Fa x 125into 126.Fa ssl . 127The rest of the certificates needed to form the complete certificate chain can 128be specified using the 129.Xr SSL_CTX_add_extra_chain_cert 3 130function. 131.Pp 132.Fn SSL_CTX_use_certificate_ASN1 133loads the ASN1 encoded certificate from the memory location 134.Fa d 135(with length 136.Fa len ) 137into 138.Fa ctx ; 139.Fn SSL_use_certificate_ASN1 140loads the ASN1 encoded certificate into 141.Fa ssl . 142.Pp 143.Fn SSL_CTX_use_certificate_file 144loads the first certificate stored in 145.Fa file 146into 147.Fa ctx . 148The formatting 149.Fa type 150of the certificate must be specified from the known types 151.Dv SSL_FILETYPE_PEM 152and 153.Dv SSL_FILETYPE_ASN1 . 154.Fn SSL_use_certificate_file 155loads the certificate from 156.Fa file 157into 158.Fa ssl . 159See the 160.Sx NOTES 161section on why 162.Fn SSL_CTX_use_certificate_chain_file 163should be preferred. 164.Pp 165The 166.Fn SSL_CTX_use_certificate_chain* 167functions load a certificate chain into 168.Fa ctx . 169The certificates must be in PEM format and must be sorted starting with the 170subject's certificate (actual client or server certificate), 171followed by intermediate CA certificates if applicable, 172and ending at the highest level (root) CA. 173There is no corresponding function working on a single 174.Vt SSL 175object. 176.Pp 177.Fn SSL_CTX_use_PrivateKey 178adds 179.Fa pkey 180as private key to 181.Fa ctx . 182.Fn SSL_CTX_use_RSAPrivateKey 183adds the private key 184.Fa rsa 185of type RSA to 186.Fa ctx . 187.Fn SSL_use_PrivateKey 188adds 189.Fa pkey 190as private key to 191.Fa ssl ; 192.Fn SSL_use_RSAPrivateKey 193adds 194.Fa rsa 195as private key of type RSA to 196.Fa ssl . 197If a certificate has already been set and the private does not belong to the 198certificate, an error is returned. 199To change a certificate private key pair, 200the new certificate needs to be set with 201.Fn SSL_use_certificate 202or 203.Fn SSL_CTX_use_certificate 204before setting the private key with 205.Fn SSL_CTX_use_PrivateKey 206or 207.Fn SSL_use_PrivateKey . 208.Pp 209.Fn SSL_CTX_use_PrivateKey_ASN1 210adds the private key of type 211.Fa pk 212stored at memory location 213.Fa d 214(length 215.Fa len ) 216to 217.Fa ctx . 218.Fn SSL_CTX_use_RSAPrivateKey_ASN1 219adds the private key of type RSA stored at memory location 220.Fa d 221(length 222.Fa len ) 223to 224.Fa ctx . 225.Fn SSL_use_PrivateKey_ASN1 226and 227.Fn SSL_use_RSAPrivateKey_ASN1 228add the private key to 229.Fa ssl . 230.Pp 231.Fn SSL_CTX_use_PrivateKey_file 232adds the first private key found in 233.Fa file 234to 235.Fa ctx . 236The formatting 237.Fa type 238of the certificate must be specified from the known types 239.Dv SSL_FILETYPE_PEM 240and 241.Dv SSL_FILETYPE_ASN1 . 242.Fn SSL_CTX_use_RSAPrivateKey_file 243adds the first private RSA key found in 244.Fa file 245to 246.Fa ctx . 247.Fn SSL_use_PrivateKey_file 248adds the first private key found in 249.Fa file 250to 251.Fa ssl ; 252.Fn SSL_use_RSAPrivateKey_file 253adds the first private RSA key found to 254.Fa ssl . 255.Pp 256.Fn SSL_CTX_check_private_key 257checks the consistency of a private key with the corresponding certificate 258loaded into 259.Fa ctx . 260If more than one key/certificate pair (RSA/DSA) is installed, 261the last item installed will be checked. 262If, e.g., the last item was a RSA certificate or key, 263the RSA key/certificate pair will be checked. 264.Fn SSL_check_private_key 265performs the same check for 266.Fa ssl . 267If no key/certificate was explicitly added for this 268.Fa ssl , 269the last item added into 270.Fa ctx 271will be checked. 272.Sh NOTES 273The internal certificate store of OpenSSL can hold two private key/certificate 274pairs at a time: 275one key/certificate of type RSA and one key/certificate of type DSA. 276The certificate used depends on the cipher select, see also 277.Xr SSL_CTX_set_cipher_list 3 . 278.Pp 279When reading certificates and private keys from file, files of type 280.Dv SSL_FILETYPE_ASN1 281(also known as 282.Em DER , 283binary encoding) can only contain one certificate or private key; consequently, 284.Fn SSL_CTX_use_certificate_chain_file 285is only applicable to PEM formatting. 286Files of type 287.Dv SSL_FILETYPE_PEM 288can contain more than one item. 289.Pp 290.Fn SSL_CTX_use_certificate_chain_file 291adds the first certificate found in the file to the certificate store. 292The other certificates are added to the store of chain certificates using 293.Xr SSL_CTX_add_extra_chain_cert 3 . 294There exists only one extra chain store, so that the same chain is appended 295to both types of certificates, RSA and DSA! 296If it is not intended to use both type of certificate at the same time, 297it is recommended to use the 298.Fn SSL_CTX_use_certificate_chain_file 299instead of the 300.Fn SSL_CTX_use_certificate_file 301function in order to allow the use of complete certificate chains even when no 302trusted CA storage is used or when the CA issuing the certificate shall not be 303added to the trusted CA storage. 304.Pp 305If additional certificates are needed to complete the chain during the TLS 306negotiation, CA certificates are additionally looked up in the locations of 307trusted CA certificates (see 308.Xr SSL_CTX_load_verify_locations 3 ) . 309.Pp 310The private keys loaded from file can be encrypted. 311In order to successfully load encrypted keys, 312a function returning the passphrase must have been supplied (see 313.Xr SSL_CTX_set_default_passwd_cb 3 ) . 314(Certificate files might be encrypted as well from the technical point of view, 315it however does not make sense as the data in the certificate is considered 316public anyway.) 317.Sh RETURN VALUES 318On success, the functions return 1. 319Otherwise check out the error stack to find out the reason. 320.Sh SEE ALSO 321.Xr ssl 3 , 322.Xr SSL_clear 3 , 323.Xr SSL_CTX_add_extra_chain_cert 3 , 324.Xr SSL_CTX_load_verify_locations 3 , 325.Xr SSL_CTX_set_cipher_list 3 , 326.Xr SSL_CTX_set_client_cert_cb 3 , 327.Xr SSL_CTX_set_default_passwd_cb 3 , 328.Xr SSL_new 3 329.Sh HISTORY 330Support for DER encoded private keys 331.Pq Dv SSL_FILETYPE_ASN1 332in 333.Fn SSL_CTX_use_PrivateKey_file 334and 335.Fn SSL_use_PrivateKey_file 336was added in 0.9.8. 337