-=pod

-

-=head1 NAME

-

-SSL_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

-

-=head1 SYNOPSIS

-

- #include <openssl/ssl.h>

-

- int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x);

- int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d);

- int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type);

- int SSL_use_certificate(SSL *ssl, X509 *x);

- int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len);

- int SSL_use_certificate_file(SSL *ssl, const char *file, int type);

-

- int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file);

-

- int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey);

- int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d,

- long len);

- int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type);

- int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa);

- int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len);

- int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type);

- int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey);

- int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len);

- int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type);

- int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa);

- int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len);

- int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type);

-

- int SSL_CTX_check_private_key(SSL_CTX *ctx);

- int SSL_check_private_key(SSL *ssl);

-

-=head1 DESCRIPTION

-

-These functions load the certificates and private keys into the SSL_CTX

-or SSL object, respectively.

-

-The SSL_CTX_* class of functions loads the certificates and keys into the

-SSL_CTX object B<ctx>. The information is passed to SSL objects B<ssl>

-created from B<ctx> with L<SSL_new(3)|SSL_new(3)> by copying, so that

-changes applied to B<ctx> do not propagate to already existing SSL objects.

-

-The SSL_* class of functions only loads certificates and keys into a

-specific SSL object. The specific information is kept, when

-L<SSL_clear(3)|SSL_clear(3)> is called for this SSL object.

-

-SSL_CTX_use_certificate() loads the certificate B<x> into B<ctx>,

-SSL_use_certificate() loads B<x> into B<ssl>. The rest of the

-certificates needed to form the complete certificate chain can be

-specified using the

-L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>

-function.

-

-SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from

-the memory location B<d> (with length B<len>) into B<ctx>,

-SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B<ssl>.

-

-SSL_CTX_use_certificate_file() loads the first certificate stored in B<file>

-into B<ctx>. The formatting B<type> of the certificate must be specified

-from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.

-SSL_use_certificate_file() loads the certificate from B<file> into B<ssl>.

-See the NOTES section on why SSL_CTX_use_certificate_chain_file()

-should be preferred.

-

-SSL_CTX_use_certificate_chain_file() loads a certificate chain from

-B<file> into B<ctx>. The certificates must be in PEM format and must

-be sorted starting with the certificate to the highest level (root CA).

-There is no corresponding function working on a single SSL object.

-

-SSL_CTX_use_PrivateKey() adds B<pkey> as private key to B<ctx>.

-SSL_CTX_use_RSAPrivateKey() adds the private key B<rsa> of type RSA

-to B<ctx>. SSL_use_PrivateKey() adds B<pkey> as private key to B<ssl>;

-SSL_use_RSAPrivateKey() adds B<rsa> as private key of type RSA to B<ssl>.

-

-SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk>

-stored at memory location B<d> (length B<len>) to B<ctx>.

-SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA

-stored at memory location B<d> (length B<len>) to B<ctx>.

-SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private

-key to B<ssl>.

-

-SSL_CTX_use_PrivateKey_file() adds the first private key found in

-B<file> to B<ctx>. The formatting B<type> of the certificate must be specified

-from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1.

-SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in

-B<file> to B<ctx>. SSL_use_PrivateKey_file() adds the first private key found

-in B<file> to B<ssl>; SSL_use_RSAPrivateKey_file() adds the first private

-RSA key found to B<ssl>.

-

-SSL_CTX_check_private_key() checks the consistency of a private key with

-the corresponding certificate loaded into B<ctx>. If more than one

-key/certificate pair (RSA/DSA) is installed, the last item installed will

-be checked. If e.g. the last item was a RSA certificate or key, the RSA

-key/certificate pair will be checked. SSL_check_private_key() performs

-the same check for B<ssl>. If no key/certificate was explicitly added for

-this B<ssl>, the last item added into B<ctx> will be checked.

-

-=head1 NOTES

-

-The internal certificate store of OpenSSL can hold two private key/certificate

-pairs at a time: one key/certificate of type RSA and one key/certificate

-of type DSA. The certificate used depends on the cipher select, see

-also L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>.

-

-When reading certificates and private keys from file, files of type

-SSL_FILETYPE_ASN1 (also known as B<DER>, binary encoding) can only contain

-one certificate or private key, consequently

-SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting.

-Files of type SSL_FILETYPE_PEM can contain more than one item.

-

-SSL_CTX_use_certificate_chain_file() adds the first certificate found

-in the file to the certificate store. The other certificates are added

-to the store of chain certificates using

-L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>.

-There exists only one extra chain store, so that the same chain is appended

-to both types of certificates, RSA and DSA! If it is not intended to use

-both type of certificate at the same time, it is recommended to use the

-SSL_CTX_use_certificate_chain_file() instead of the

-SSL_CTX_use_certificate_file() function in order to allow the use of

-complete certificate chains even when no trusted CA storage is used or

-when the CA issuing the certificate shall not be added to the trusted

-CA storage.

-

-If additional certificates are needed to complete the chain during the

-TLS negotiation, CA certificates are additionally looked up in the

-locations of trusted CA certificates, see

-L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.

-

-The private keys loaded from file can be encrypted. In order to successfully

-load encrypted keys, a function returning the passphrase must have been

-supplied, see

-L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>.

-(Certificate files might be encrypted as well from the technical point

-of view, it however does not make sense as the data in the certificate

-is considered public anyway.)

-

-=head1 RETURN VALUES

-

-On success, the functions return 1.

-Otherwise check out the error stack to find out the reason.

-

-=head1 SEE ALSO

-

-L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,

-L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,

-L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,

-L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,

-L<SSL_CTX_set_client_cert_cb(3)|SSL_CTX_set_client_cert_cb(3)>,

-L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>

-

-=cut