Following the license change, modify the boilerplates in doc/man3/

[openssl.git] / doc / man3 / SSL_CTX_use_certificate.pod

diff --git a/doc/man3/SSL_CTX_use_certificate.pod b/doc/man3/SSL_CTX_use_certificate.pod
index 1feb576c69ffc10be0e3abe1d9365147c47748bc..72608c84daf0504754dd83fb35a1110a8cf50875 100644 (file)
--- 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
+interface) 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>.
@@ -103,7 +120,7 @@ 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
+B<file> to B<ctx>. The formatting B<type> of the private key 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
@@ -153,6 +170,13 @@ L<SSL_CTX_set_default_passwd_cb(3)>.
 of view, it however does not make sense as the data in the certificate
 is considered public anyway.)
 
+All of the functions to set a new certificate will replace any existing
+certificate of the same type that has already been set. Similarly all of the
+functions to set a new private key will replace any private key that has already
+been set. Applications should call L<SSL_CTX_check_private_key(3)> or
+L<SSL_check_private_key(3)> as appropriate after loading a new certificate and
+private key to confirm that the certificate and key match.
+
 =head1 RETURN VALUES
 
 On success, the functions return 1.
@@ -170,9 +194,9 @@ L<SSL_CTX_add_extra_chain_cert(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.