SSL_CTX_use_certificate.pod revision 120631
1170530Ssam=pod 2178354Ssam 3170530Ssam=head1 NAME 4170530Ssam 5170530SsamSSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_file, SSL_use_certificate, SSL_use_certificate_ASN1, SSL_use_certificate_file, SSL_CTX_use_certificate_chain_file, SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key - load certificate and key data 6170530Ssam 7170530Ssam=head1 SYNOPSIS 8170530Ssam 9170530Ssam #include <openssl/ssl.h> 10170530Ssam 11170530Ssam int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x); 12170530Ssam int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d); 13170530Ssam int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type); 14170530Ssam int SSL_use_certificate(SSL *ssl, X509 *x); 15170530Ssam int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len); 16170530Ssam int SSL_use_certificate_file(SSL *ssl, const char *file, int type); 17170530Ssam 18170530Ssam int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file); 19170530Ssam 20170530Ssam int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey); 21170530Ssam int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d, 22170530Ssam long len); 23170530Ssam int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type); 24170530Ssam int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa); 25170530Ssam int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len); 26170530Ssam int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type); 27170530Ssam int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey); 28170530Ssam int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len); 29170530Ssam int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type); 30170530Ssam int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa); 31170530Ssam int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len); 32170530Ssam int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type); 33170530Ssam 34170530Ssam int SSL_CTX_check_private_key(SSL_CTX *ctx); 35170530Ssam int SSL_check_private_key(SSL *ssl); 36178354Ssam 37170530Ssam=head1 DESCRIPTION 38170530Ssam 39170530SsamThese functions load the certificates and private keys into the SSL_CTX 40170530Ssamor SSL object, respectively. 41170530Ssam 42170530SsamThe SSL_CTX_* class of functions loads the certificates and keys into the 43170530SsamSSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl> 44170530Ssamcreated from B<ctx> with L<SSL_new(3)|SSL_new(3)> by copying, so that 45170530Ssamchanges applied to B<ctx> do not propagate to already existing SSL objects. 46170530Ssam 47170530SsamThe SSL_* class of functions only loads certificates and keys into a 48170530Ssamspecific SSL object. The specific information is kept, when 49170530SsamL<SSL_clear(3)|SSL_clear(3)> is called for this SSL object. 50195377Ssam 51178354SsamSSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>, 52170530SsamSSL_use_certificate() loads B<x> into B<ssl>. The rest of the 53170530Ssamcertificates needed to form the complete certificate chain can be 54170530Ssamspecified using the 55170530SsamL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> 56170530Ssamfunction. 57178354Ssam 58205277SrpauloSSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from 59178354Ssamthe memory location B<d> (with length B<len>) into B<ctx>, 60178354SsamSSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>. 61178354Ssam 62178354SsamSSL_CTX_use_certificate_file() loads the first certificate stored in B<file> 63178354Ssaminto B<ctx>. The formatting B<type> of the certificate must be specified 64178354Ssamfrom the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. 65178354SsamSSL_use_certificate_file() loads the certificate from B<file> into B<ssl>. 66178354SsamSee the NOTES section on why SSL_CTX_use_certificate_chain_file() 67178354Ssamshould be preferred. 68178354Ssam 69178354SsamSSL_CTX_use_certificate_chain_file() loads a certificate chain from 70178354SsamB<file> into B<ctx>. The certificates must be in PEM format and must 71178354Ssambe sorted starting with the subject's certificate (actual client or server 72178354Ssamcertificate), followed by intermediate CA certificates if applicable, and 73178354Ssamending at the highest level (root) CA. 74178354SsamThere is no corresponding function working on a single SSL object. 75170530Ssam 76170530SsamSSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>. 77170530SsamSSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA 78170530Ssamto B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>; 79170530SsamSSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>. 80170530Ssam 81170530SsamSSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk> 82170530Ssamstored at memory location B<d> (length B<len>) to B<ctx>. 83173273SsamSSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA 84193115Ssamstored at memory location B<d> (length B<len>) to B<ctx>. 85193115SsamSSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private 86193115Ssamkey to B<ssl>. 87193115Ssam 88173273SsamSSL_CTX_use_PrivateKey_file() adds the first private key found in 89173273SsamB<file> to B<ctx>. The formatting B<type> of the certificate must be specified 90193115Ssamfrom the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. 91193115SsamSSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in 92193115SsamB<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found 93193115Ssamin B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private 94193115SsamRSA key found to B<ssl>. 95193115Ssam 96193115SsamSSL_CTX_check_private_key() checks the consistency of a private key with 97193115Ssamthe corresponding certificate loaded into B<ctx>. If more than one 98193115Ssamkey/certificate pair (RSA/DSA) is installed, the last item installed will 99193115Ssambe checked. If e.g. the last item was a RSA certificate or key, the RSA 100193115Ssamkey/certificate pair will be checked. SSL_check_private_key() performs 101193115Ssamthe same check for B<ssl>. If no key/certificate was explicitly added for 102193115Ssamthis B<ssl>, the last item added into B<ctx> will be checked. 103193115Ssam 104193115Ssam=head1 NOTES 105193115Ssam 106193115SsamThe internal certificate store of OpenSSL can hold two private key/certificate 107193115Ssampairs at a time: one key/certificate of type RSA and one key/certificate 108193115Ssamof type DSA. The certificate used depends on the cipher select, see 109195377Ssamalso L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>. 110195377Ssam 111195377SsamWhen reading certificates and private keys from file, files of type 112195377SsamSSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain 113195377Ssamone certificate or private key, consequently 114195377SsamSSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting. 115195377SsamFiles of type SSL_FILETYPE_PEM can contain more than one item. 116195377Ssam 117195377SsamSSL_CTX_use_certificate_chain_file() adds the first certificate found 118195377Ssamin the file to the certificate store. The other certificates are added 119178354Ssamto the store of chain certificates using 120195377SsamL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>. 121178354SsamThere exists only one extra chain store, so that the same chain is appended 122195377Ssamto both types of certificates, RSA and DSA! If it is not intended to use 123195377Ssamboth type of certificate at the same time, it is recommended to use the 124195377SsamSSL_CTX_use_certificate_chain_file() instead of the 125178354SsamSSL_CTX_use_certificate_file() function in order to allow the use of 126178354Ssamcomplete certificate chains even when no trusted CA storage is used or 127178354Ssamwhen the CA issuing the certificate shall not be added to the trusted 128178354SsamCA storage. 129178354Ssam 130184280SsamIf additional certificates are needed to complete the chain during the 131195377SsamTLS negotiation, CA certificates are additionally looked up in the 132195377Ssamlocations of trusted CA certificates, see 133195377SsamL<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>. 134195377Ssam 135195377SsamThe private keys loaded from file can be encrypted. In order to successfully 136195377Ssamload encrypted keys, a function returning the passphrase must have been 137195377Ssamsupplied, see 138195377SsamL<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>. 139195377Ssam(Certificate files might be encrypted as well from the technical point 140195377Ssamof view, it however does not make sense as the data in the certificate 141195377Ssamis considered public anyway.) 142195377Ssam 143195377Ssam=head1 RETURN VALUES 144195377Ssam 145195377SsamOn success, the functions return 1. 146195377SsamOtherwise check out the error stack to find out the reason. 147195377Ssam 148195377Ssam=head1 SEE ALSO 149195377Ssam 150195377SsamL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>, 151195377SsamL<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, 152195377SsamL<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>, 153178354SsamL<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, 154195377SsamL<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>, 155170530SsamL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> 156178354Ssam 157178354Ssam=cut 158170530Ssam