b9fa413a08
Fix a limitation in SSL_CTX_use_certificate_chain_file(): use algorithm
specific chains instead of the shared chain.
Update docs.
(cherry picked from commit a4339ea3ba)
Conflicts:
CHANGES
165 lines
8.2 KiB
Text
165 lines
8.2 KiB
Text
=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(const SSL_CTX *ctx);
|
|
int SSL_check_private_key(const 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 subject's certificate (actual client or server
|
|
certificate), followed by intermediate CA certificates if applicable, and
|
|
ending at 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>.
|
|
If a certificate has already been set and the private does not belong
|
|
to the certificate an error is returned. To change a certificate, private
|
|
key pair the new certificate needs to be set with SSL_use_certificate()
|
|
or SSL_CTX_use_certificate() before setting the private key with
|
|
SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey().
|
|
|
|
|
|
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 several private
|
|
key/certificate pairs at a time. The certificate used depends on the
|
|
cipher selected, 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_add1_chain_cert(3)|SSL_CTX_add1_chain_cert(3)>. Note: versions of OpenSSL before 1.0.2 only had a single
|
|
certificate chain store for all certificate types, OpenSSL 1.0.2 and later
|
|
have a separate chain store for each type. SSL_CTX_use_certificate_chain_file()
|
|
should be used 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)>
|
|
|
|
=head1 HISTORY
|
|
|
|
Support for DER encoded private keys (SSL_FILETYPE_ASN1) in
|
|
SSL_CTX_use_PrivateKey_file() and SSL_use_PrivateKey_file() was added
|
|
in 0.9.8 .
|
|
|
|
=cut
|