X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fssl%2FSSL_CTX_use_certificate.pod;h=6514d015f854ba22c490d46cb5a6e0be361c3efa;hb=fae4772c24b89526f70c74fa14a85c5c16bced9a;hp=58fa3e6a84f6a71388b31f91e310c9dd7eaf1df7;hpb=7403c34b0b511e0dd0e31eeb7008abc566dd6b82;p=openssl.git

diff --git a/doc/ssl/SSL_CTX_use_certificate.pod b/doc/ssl/SSL_CTX_use_certificate.pod
index 58fa3e6a84..6514d015f8 100644
--- a/doc/ssl/SSL_CTX_use_certificate.pod
+++ b/doc/ssl/SSL_CTX_use_certificate.pod
@@ -16,6 +16,7 @@ SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_f
  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_use_certificate_chain_file(SSL *ssl, 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,
@@ -31,8 +32,8 @@ SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_f
  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);
+ int SSL_CTX_check_private_key(const SSL_CTX *ctx);
+ int SSL_check_private_key(const SSL *ssl);
 
 =head1 DESCRIPTION
 
@@ -68,13 +69,21 @@ 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.
+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. SSL_use_certificate_chain_file() is
+similar except it loads the cerificate chain into B<ssl>.
 
 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>.
@@ -101,10 +110,9 @@ 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)>.
+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
@@ -114,16 +122,13 @@ 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 intented 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.
+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
@@ -149,6 +154,13 @@ 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