Add SSL/SSL_CTX_use_cert_and_key()

Add functions that will do the work of assigning certificate, privatekey
and chain certs to an SSL or SSL_CTX. If no privatekey is given, use the
publickey. This will permit the keys to pass validation for both ECDSA
and RSA. If a private key has already been set for the certificate, it
is discarded. A real private key can be set later.

This is an all-or-nothing setting of these parameters. Unlike the
SSL/SSL_CTX_use_certificate() and SSL/SSL_CTX_use_PrivateKey() functions,
the existing cert or privatekey is not modified (i.e. parameters copied).
This permits the existing cert/privatekey to be replaced.

It replaces the sequence of:
* SSL_use_certificate()
* SSL_use_privatekey()
* SSL_set1_chain()
And may actually be faster, as multiple checks are consolidated.

The private key can be NULL, if so an ENGINE module needs to contain the
actual private key that is to be used.

Note that ECDH (using the certificate's ECDSA key) ciphers do not work
without the private key being present, based on how the private key is
used in ECDH. ECDH does not offer PFS; ECDHE ciphers should be used instead.

Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Ben Kaduk <kaduk@mit.edu>
(Merged from https://github.com/openssl/openssl/pull/1130)

1 files changed, 19 insertions, 2 deletions

diff --git a/doc/man3/SSL_CTX_use_certificate.pod b/doc/man3/SSL_CTX_use_certificate.pod
index 22420f97d8..a0c92e6e7b 100644
--- a/doc/man3/SSL_CTX_use_certificate.pod
+++ b/doc/man3/SSL_CTX_use_certificate.pod
@@ -11,7 +11,8 @@ 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
+SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key,
+SSL_CTX_use_cert_and_key, SSL_use_cert_and_key
 - load certificate and key data
 
 =head1 SYNOPSIS
@@ -45,6 +46,9 @@ SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key
  int SSL_CTX_check_private_key(const SSL_CTX *ctx);
  int SSL_check_private_key(const SSL *ssl);
 
+ int SSL_CTX_use_cert_and_key(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);
+ int SSL_use_cert_and_key(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);
+
 =head1 DESCRIPTION
 
 These functions load the certificates and private keys into the SSL_CTX
@@ -94,6 +98,19 @@ 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_cert_and_key() and SSL_use_cert_and_key() assign the X.509
+certificate B<x>, private key B<key>, and certificate B<chain> onto the
+corresponding B<ssl> or B<ctx>. The B<pkey> argument must be the private
+key of the X.509 certificate B<x>. If the B<override> argument is 0, then
+B<x>, B<pkey> and B<chain> are set only if all were not previously set.
+If B<override> is non-0, then the certificate, private key and chain certs
+are always set. If B<pkey> is NULL, then the public key of B<x> is used as
+the private key. This is intended to be used with hardware (via the ENGINE
+inteface) that stores the private key securely, such that it cannot be
+accessed by OpenSSL. The reference count of the public key is incremented
+(twice if there is no private key); it is not copied nor duplicated. This
+allows all private key validations checks to succeed without an actual
+private key being assigned via SSL_CTX_use_PrivateKey(), etc.
 
 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>.
@@ -170,7 +187,7 @@ L<SSL_CTX_add_extra_chain_cert(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy