Document the new libctx aware private key functions

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11494)

2 files changed, 83 insertions, 22 deletions

diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 0650b52e07..b1dfe465e7 100644
--- a/doc/man3/PEM_read_bio_PrivateKey.pod
+++ b/doc/man3/PEM_read_bio_PrivateKey.pod
@@ -3,7 +3,8 @@
 =head1 NAME
 
 pem_password_cb,
-PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
+PEM_read_bio_PrivateKey_ex, PEM_read_bio_PrivateKey, PEM_read_PrivateKey_ex,
+PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
 PEM_write_bio_PrivateKey_traditional, PEM_write_PrivateKey,
 PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey,
 PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid,
@@ -33,8 +34,14 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
 
  typedef int pem_password_cb(char *buf, int size, int rwflag, void *u);
 
+ EVP_PKEY *PEM_read_bio_PrivateKey_ex(BIO *bp, EVP_PKEY **x, pem_password_cb *cb,
+                                      void *u, OPENSSL_CTX *libctx,
+                                      const char *propq);
  EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
                                    pem_password_cb *cb, void *u);
+ EVP_PKEY *PEM_read_PrivateKey_ex(FILE *fp, EVP_PKEY **x, pem_password_cb *cb,
+                                  void *u, OPENSSL_CTX *libctx,
+                                  const char *propq);
  EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
                                pem_password_cb *cb, void *u);
  int PEM_write_bio_PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc,
@@ -168,6 +175,9 @@ brevity the term "B<I<TYPE>> functions" will be used below to collectively
 refer to the B<PEM_read_bio_I<TYPE>>(), B<PEM_read_I<TYPE>>(),
 B<PEM_write_bio_I<TYPE>>(), and B<PEM_write_I<TYPE>>() functions.
 
+Some operations have additional variants that take a library context I<libctx>
+and a property query string I<propq>.
+
 The B<PrivateKey> functions read or write a private key in PEM format using an
 EVP_PKEY structure. The write routines use PKCS#8 private key format and are
 equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently
@@ -307,6 +317,12 @@ arbitrary data to be passed to the callback by the application
 I<must> return the number of characters in the passphrase or -1 if
 an error occurred.
 
+Some implementations may need to use cryptographic algorithms during their
+operation. If this is the case and I<libctx> and I<propq> parameters have been
+passed then any algorithm fetches will use that library context and property
+query string. Otherwise the default library context and property query string
+will be used.
+
 =head1 NOTES
 
 The old B<PrivateKey> write routines are retained for compatibility.
@@ -480,6 +496,9 @@ The old Netscape certificate sequences were no longer documented
 in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
 as they will be formally deprecated in a future releases.
 
+PEM_read_bio_PrivateKey_ex() and PEM_read_PrivateKey_ex() were introduced in
+OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2001-2019 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/d2i_PrivateKey.pod b/doc/man3/d2i_PrivateKey.pod
index 4b7a326c0d..ca4876cfd9 100644
--- a/doc/man3/d2i_PrivateKey.pod
+++ b/doc/man3/d2i_PrivateKey.pod
@@ -2,21 +2,29 @@
 
 =head1 NAME
 
-d2i_PrivateKey, d2i_PublicKey, d2i_KeyParams, d2i_AutoPrivateKey,
-i2d_PrivateKey, i2d_PublicKey, i2d_KeyParams, i2d_KeyParams_bio,
-d2i_PrivateKey_bio, d2i_PrivateKey_fp, d2i_KeyParams_bio
+d2i_PrivateKey_ex, d2i_PrivateKey, d2i_PublicKey, d2i_KeyParams,
+d2i_AutoPrivateKey_ex,  d2i_AutoPrivateKey, i2d_PrivateKey, i2d_PublicKey,
+i2d_KeyParams, i2d_KeyParams_bio, d2i_PrivateKey_ex_bio, d2i_PrivateKey_bio,
+d2i_PrivateKey_ex_fp, d2i_PrivateKey_fp, d2i_KeyParams_bio, i2d_PrivateKey_bio,
+i2d_PrivateKey_fp
 - decode and encode functions for reading and saving EVP_PKEY structures
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
+ EVP_PKEY *d2i_PrivateKey_ex(int type, EVP_PKEY **a, const unsigned char **pp,
+                             long length, OPENSSL_CTX *libctx,
+                             const char *propq);
  EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **a, const unsigned char **pp,
                           long length);
  EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **a, const unsigned char **pp,
                          long length);
  EVP_PKEY *d2i_KeyParams(int type, EVP_PKEY **a, const unsigned char **pp,
                          long length);
+ EVP_PKEY *d2i_AutoPrivateKey_ex(EVP_PKEY **a, const unsigned char **pp,
+                                 long length, OPENSSL_CTX *libctx,
+                                 const char *propq);
  EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp,
                               long length);
 
@@ -24,28 +32,54 @@ d2i_PrivateKey_bio, d2i_PrivateKey_fp, d2i_KeyParams_bio
  int i2d_PublicKey(const EVP_PKEY *a, unsigned char **pp);
  int i2d_KeyParams(const EVP_PKEY *a, unsigned char **pp);
  int i2d_KeyParams_bio(BIO *bp, const EVP_PKEY *pkey);
+ EVP_PKEY *d2i_KeyParams_bio(int type, EVP_PKEY **a, BIO *in);
+
 
+ #include <openssl/x509.h>
+
+ EVP_PKEY *d2i_PrivateKey_ex_bio(BIO *bp, EVP_PKEY **a, OPENSSL_CTX *libctx,
+                                 const char *propq);
  EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a);
+ EVP_PKEY *d2i_PrivateKey_ex_fp(FILE *fp, EVP_PKEY **a, OPENSSL_CTX *libctx,
+                                const char *propq);
  EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a)
- EVP_PKEY *d2i_KeyParams_bio(int type, EVP_PKEY **a, BIO *in);
+
+ int i2d_PrivateKey_bio(BIO *bp, const EVP_PKEY *pkey);
+ int i2d_PrivateKey_fp(FILE *fp, const EVP_PKEY *pkey);
 
 =head1 DESCRIPTION
 
-d2i_PrivateKey() decodes a private key using algorithm B<type>. It attempts to
-use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The
-B<type> parameter should be a public key algorithm constant such as
-B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match B<type>.
+d2i_PrivateKey_ex() decodes a private key using algorithm I<type>. It attempts
+to use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The
+I<type> parameter should be a public key algorithm constant such as
+B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match I<type>. Some
+private key decoding implementations may use cryptographic algorithms (for
+example to automatically derive the public key if it is not explicitly
+included in the encoding). In this case the supplied library context I<libctx>
+and property query string I<propq> are used.
+d2i_PrivateKey() does the same as d2i_PrivateKey_ex() except that the default
+library context and property query string are used.
 d2i_PublicKey() does the same for public keys.
 d2i_KeyParams() does the same for key parameters.
 
-d2i_AutoPrivateKey() is similar to d2i_PrivateKey() except it attempts to
-automatically detect the private key format.
+The d2i_PrivateKey_ex_bio() and d2i_PrivateKey_bio() functions are similar to
+d2i_PrivateKey_ex() and d2i_PrivateKey() respectively except that they decode
+the data read from the given BIO. The d2i_PrivateKey_ex_fp() and
+d2i_PrivateKey_fp() functions are the same except that they read the data from
+the given FILE.
+
+d2i_AutoPrivateKey_ex() and d2i_AutoPrivateKey() are similar to
+d2i_PrivateKey_ex() and d2i_PrivateKey() respectively except that they attempt
+to automatically detect the private key format.
 
-i2d_PrivateKey() encodes B<key>. It uses a key specific format or, if none is
+i2d_PrivateKey() encodes I<a>. It uses a key specific format or, if none is
 defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format.
 i2d_PublicKey() does the same for public keys.
 i2d_KeyParams() does the same for key parameters.
 These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>.
+i2d_PrivateKey_bio() and i2d_PrivateKey_fp() do the same thing except that they
+encode to a B<BIO> or B<FILE> respectrively. Again, these work similarly to the
+functions described in L<d2i_X509(3)>.
 
 =head1 NOTES
 
@@ -53,30 +87,38 @@ All these functions use DER format and unencrypted keys. Applications wishing
 to encrypt or decrypt private keys should use other functions such as
 d2i_PKCS8PrivateKey() instead.
 
-If the B<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey()
+If the I<*a> is not NULL when calling d2i_PrivateKey() or d2i_AutoPrivateKey()
 (i.e. an existing structure is being reused) and the key format is PKCS#8
-then B<*a> will be freed and replaced on a successful call.
+then I<*a> will be freed and replaced on a successful call.
 
-To decode a key with type B<EVP_PKEY_EC>, d2i_PublicKey() requires B<*a> to be
+To decode a key with type B<EVP_PKEY_EC>, d2i_PublicKey() requires I<*a> to be
 a non-NULL EVP_PKEY structure assigned an EC_KEY structure referencing the proper
 EC_GROUP.
 
 =head1 RETURN VALUES
 
-The d2i_PrivateKey(), d2i_AutoPrivateKey(), d2i_PrivateKey_bio(), d2i_PrivateKey_fp(),
-d2i_PublicKey(), d2i_KeyParams() and d2i_KeyParams_bio() functions return a valid
-B<EVP_KEY> structure or B<NULL> if an error occurs. The error code can be
-obtained by calling L<ERR_get_error(3)>.
+The d2i_PrivateKey_ex(), d2i_PrivateKey(), d2i_AutoPrivateKey_ex(),
+d2i_AutoPrivateKey(), d2i_PrivateKey_ex_bio(), d2i_PrivateKey_bio(),
+d2i_PrivateKey_ex_fp(), d2i_PrivateKey_fp(), d2i_PublicKey(), d2i_KeyParams()
+and d2i_KeyParams_bio() functions return a valid B<EVP_KEY> structure or B<NULL>
+if an error occurs. The error code can be obtained by calling
+L<ERR_get_error(3)>.
 
-i2d_PrivateKey(), i2d_PublicKey(), i2d_KeyParams() i2d_KeyParams_bio() return
-the number of bytes successfully encoded or a negative value if an error occurs.
-The error code can be obtained by calling L<ERR_get_error(3)>.
+i2d_PrivateKey(), i2d_PrivateKey_bio(), i2d_PrivateKey_fp(), i2d_PublicKey(),
+i2d_KeyParams() i2d_KeyParams_bio() return the number of bytes successfully
+encoded or a negative value if an error occurs. The error code can be obtained
+by calling L<ERR_get_error(3)>.
 
 =head1 SEE ALSO
 
 L<crypto(7)>,
 L<d2i_PKCS8PrivateKey_bio(3)>
 
+=head1 HISTORY
+
+d2i_PrivateKey_ex(), d2i_PrivateKey_ex_bio(), d2i_PrivateKey_ex_fp(), and
+d2i_AutoPrivateKey_ex() were added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.