Add convenience functions and macros for asymmetric key generation

Add EVP_PKEY_gen(), EVP_PKEY_Q_gen(), EVP_RSA_gen(), and EVP_EC_gen().
Also export auxiliary function OSSL_EC_curve_nid2name()
and improve deprecation info on RSA and EC key generation/management functions.

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

5 files changed, 83 insertions, 40 deletions

diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod
index 48b6aa7843..f45c5ac8d2 100644
--- a/doc/man3/EC_GROUP_new.pod
+++ b/doc/man3/EC_GROUP_new.pod
@@ -20,8 +20,9 @@ EC_GROUP_set_curve_GFp,
 EC_GROUP_get_curve_GFp,
 EC_GROUP_set_curve_GF2m,
 EC_GROUP_get_curve_GF2m,
-EC_get_builtin_curves - Functions for creating and destroying EC_GROUP
-objects
+EC_get_builtin_curves,
+OSSL_EC_curve_nid2name -
+Functions for creating and destroying EC_GROUP objects
 
 =head1 SYNOPSIS
 
@@ -52,6 +53,7 @@ objects
                                              ECPKPARAMETERS *params);
 
  size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
+ const char *OSSL_EC_curve_nid2name(int nid);
 
 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
 B<OPENSSL_API_COMPAT> with a suitable version value, see
@@ -173,6 +175,8 @@ in the EC_GROUP is public anyway, this function is unnecessary.
 Its use can be safely replaced with EC_GROUP_free().
 If I<group> is NULL nothing is done.
 
+OSSL_EC_curve_nid2name() converts a curve I<nid> into the corresponding name.
+
 =head1 RETURN VALUES
 
 All EC_GROUP_new* functions return a pointer to the newly constructed group, or
@@ -184,6 +188,8 @@ available.
 EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(),
 EC_GROUP_get_curve_GF2m() return 1 on success or 0 on error.
 
+OSSL_EC_curve_nid2name() returns a character string constant, or NULL on error.
+
 =head1 SEE ALSO
 
 L<crypto(7)>, L<EC_GROUP_copy(3)>,
diff --git a/doc/man3/EC_KEY_new.pod b/doc/man3/EC_KEY_new.pod
index a572e490e1..a816a0745d 100644
--- a/doc/man3/EC_KEY_new.pod
+++ b/doc/man3/EC_KEY_new.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+EVP_EC_gen,
 EC_KEY_get_method, EC_KEY_set_method, EC_KEY_new_ex,
 EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags,
 EC_KEY_new_by_curve_name_ex, EC_KEY_new_by_curve_name, EC_KEY_free,
@@ -20,6 +21,8 @@ EC_KEY objects
 
  #include <openssl/ec.h>
 
+ EVP_PKEY *EVP_EC_gen(const char *curve);
+
 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
 B<OPENSSL_API_COMPAT> with a suitable version value, see
 L<openssl_user_macros(7)>:
@@ -65,8 +68,11 @@ L<openssl_user_macros(7)>:
 
 =head1 DESCRIPTION
 
-All of the functions described on this page are deprecated.
-Applications should instead use L<EVP_PKEY_new(3)> and L<EVP_PKEY_free(3)>.
+EVP_EC_gen() generates a new EC key pair on the given I<curve>.
+
+All of the functions described below are deprecated.
+Applications should instead use EVP_EC_gen(), L<EVP_PKEY_Q_keygen(3)>, or
+L<EVP_PKEY_keygen_init(3)> and L<EVP_PKEY_keygen(3)>.
 
 An EC_KEY represents a public key and, optionally, the associated private
 key.
@@ -152,7 +158,6 @@ EC_KEY_decoded_from_explicit_params() returns 1 if the group of the I<key> was
 decoded from data with explicitly encoded group parameters, -1 if the I<key>
 is NULL or the group parameters are missing, and 0 otherwise.
 
-Although deprecated in OpenSSL 3.0 and should no longer be used,
 EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator
 for faster point multiplication. See also L<EC_POINT_add(3)>.
 Modern versions should instead switch to named curves which OpenSSL has
@@ -208,6 +213,7 @@ of the buffer or 0 on error.
 
 =head1 SEE ALSO
 
+L<EVP_PKEY_Q_keygen(3)>
 L<crypto(7)>, L<EC_GROUP_new(3)>,
 L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>,
 L<EC_POINT_add(3)>,
@@ -217,7 +223,9 @@ L<OSSL_LIB_CTX(3)>
 
 =head1 HISTORY
 
-All of these functions were deprecated in OpenSSL 3.0.
+EVP_EC_gen() was added in OpenSSL 3.0.
+All other functions described here were deprecated in OpenSSL 3.0.
+For replacement see L<EVP_PKEY-EC(7)>.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/EVP_PKEY_gen.pod b/doc/man3/EVP_PKEY_keygen.pod
index 979de8601e..08d2b1db0f 100644
--- a/doc/man3/EVP_PKEY_gen.pod
+++ b/doc/man3/EVP_PKEY_keygen.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-EVP_PKEY_keygen_init, EVP_PKEY_paramgen_init, EVP_PKEY_gen,
+EVP_PKEY_Q_keygen,
+EVP_PKEY_keygen_init, EVP_PKEY_paramgen_init, EVP_PKEY_generate,
 EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb,
 EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data,
 EVP_PKEY_CTX_get_app_data,
@@ -14,9 +15,12 @@ EVP_PKEY_paramgen, EVP_PKEY_keygen
 
  #include <openssl/evp.h>
 
+ EVP_PKEY *EVP_PKEY_Q_keygen(OSSL_LIB_CTX *libctx, const char *propq,
+                             const char *type, ...);
+
  int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
- int EVP_PKEY_gen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
+ int EVP_PKEY_generate(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
  int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
  int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
 
@@ -57,16 +61,16 @@ After initialization, generation parameters may be provided with
 L<EVP_PKEY_CTX_ctrl(3)> or L<EVP_PKEY_CTX_set_params(3)>, or any other
 function described in those manuals.
 
-EVP_PKEY_gen() performs the generation operation, the resulting key
+EVP_PKEY_generate() performs the generation operation, the resulting key
 parameters or key are written to I<*ppkey>.  If I<*ppkey> is NULL when this
 function is called, it will be allocated, and should be freed by the caller
 when no longer useful, using L<EVP_PKEY_free(3)>.
 
 EVP_PKEY_paramgen() and EVP_PKEY_keygen() do exactly the same thing as
-EVP_PKEY_gen(), after checking that the corresponding EVP_PKEY_paramgen_init()
+EVP_PKEY_generate(), after checking that the corresponding EVP_PKEY_paramgen_init()
 or EVP_PKEY_keygen_init() was used to initialize I<ctx>.
 These are older functions that are kept for backward compatibility.
-It is safe to use EVP_PKEY_gen() instead.
+It is safe to use EVP_PKEY_generate() instead.
 
 The function EVP_PKEY_set_cb() sets the key or parameter generation callback
 to I<cb>. The function EVP_PKEY_CTX_get_cb() returns the key or parameter
@@ -87,6 +91,18 @@ and retrieve an opaque pointer. This can be used to set some application
 defined value which can be retrieved in the callback: for example a handle
 which is used to update a "progress dialog".
 
+EVP_PKEY_Q_keygen() abstracts from the explicit use of B<EVP_PKEY_CTX> while
+providing a 'quick' but limited way of generating a new asymmetric key pair.
+It provides shorthands for simple and common cases of key generation.
+As usual, the library context I<libctx> and property query I<propq>
+can be given for fetching algorithms from providers.
+If I<type> is C<RSA>,
+a B<size_t> parameter must be given to specify the size of the RSA key.
+If I<type> is C<EC>,
+a string parameter must be given to specify the name of the EC curve.
+If I<type> is C<X25519>, C<X448>, C<ED25519>, or C<ED448>
+no further parameter is needed.
+
 =head1 RETURN VALUES
 
 EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and
@@ -94,6 +110,8 @@ EVP_PKEY_paramgen() return 1 for success and 0 or a negative value for failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
+EVP_PKEY_Q_keygen() returns an B<EVP_PKEY>, or NULL on failure.
+
 =head1 NOTES
 
 After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm
@@ -187,6 +205,7 @@ Example of generation callback for OpenSSL public key implementations:
 
 =head1 SEE ALSO
 
+L<EVP_RSA_gen(3)>, L<EVP_EC_gen(3)>,
 L<EVP_PKEY_CTX_new(3)>,
 L<EVP_PKEY_encrypt(3)>,
 L<EVP_PKEY_decrypt(3)>,
@@ -203,7 +222,7 @@ EVP_PKEY_CTX_get_cb(), EVP_PKEY_CTX_get_keygen_info(),
 EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() were added in
 OpenSSL 1.0.0.
 
-EVP_PKEY_gen() was added in OpenSSL 3.0.
+EVP_PKEY_Q_keygen() and EVP_PKEY_generate() were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/RSA_generate_key.pod b/doc/man3/RSA_generate_key.pod
index f8d4ba1484..7e96360ab8 100644
--- a/doc/man3/RSA_generate_key.pod
+++ b/doc/man3/RSA_generate_key.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+EVP_RSA_gen,
 RSA_generate_key_ex, RSA_generate_key,
 RSA_generate_multi_prime_key - generate RSA key pair
 
@@ -9,6 +10,8 @@ RSA_generate_multi_prime_key - generate RSA key pair
 
  #include <openssl/rsa.h>
 
+ EVP_PKEY *EVP_RSA_gen(unsigned int bits);
+
 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
 B<OPENSSL_API_COMPAT> with a suitable version value, see
 L<openssl_user_macros(7)>:
@@ -16,44 +19,42 @@ L<openssl_user_macros(7)>:
  int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
  int RSA_generate_multi_prime_key(RSA *rsa, int bits, int primes, BIGNUM *e, BN_GENCB *cb);
 
-Deprecated since OpenSSL 0.9.8, can be hidden entirely by defining
-B<OPENSSL_API_COMPAT> with a suitable version value, see
-L<openssl_user_macros(7)>:
+Deprecated since OpenSSL 0.9.8:
 
  RSA *RSA_generate_key(int bits, unsigned long e,
                        void (*callback)(int, int, void *), void *cb_arg);
 
 =head1 DESCRIPTION
 
-All of the functions described on this page are deprecated.
-Applications should instead use L<EVP_PKEY_keygen_init(3)> and
-L<EVP_PKEY_keygen(3)>.
+EVP_RSA_gen() generates a new RSA key pair with modulus size I<bits>.
+
+All of the functions described below are deprecated.
+Applications should instead use EVP_RSA_gen(), L<EVP_PKEY_Q_keygen(3)>, or
+L<EVP_PKEY_keygen_init(3)> and L<EVP_PKEY_keygen(3)>.
 
 RSA_generate_key_ex() generates a 2-prime RSA key pair and stores it in the
-B<RSA> structure provided in B<rsa>. The pseudo-random number generator must
-be seeded prior to calling RSA_generate_key_ex().
+B<RSA> structure provided in I<rsa>.
 
 RSA_generate_multi_prime_key() generates a multi-prime RSA key pair and stores
-it in the B<RSA> structure provided in B<rsa>. The number of primes is given by
-the B<primes> parameter. The random number generator must be seeded when
-calling RSA_generate_multi_prime_key().
+it in the B<RSA> structure provided in I<rsa>. The number of primes is given by
+the I<primes> parameter.
 If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
 external circumstances (see L<RAND(7)>), the operation will fail.
 
-The modulus size will be of length B<bits>, the number of primes to form the
-modulus will be B<primes>, and the public exponent will be B<e>. Key sizes
-with B<num> E<lt> 1024 should be considered insecure. The exponent is an odd
+The modulus size will be of length I<bits>, the number of primes to form the
+modulus will be I<primes>, and the public exponent will be I<e>. Key sizes
+with I<num> E<lt> 1024 should be considered insecure. The exponent is an odd
 number, typically 3, 17 or 65537.
 
 In order to maintain adequate security level, the maximum number of permitted
-B<primes> depends on modulus bit length:
+I<primes> depends on modulus bit length:
 
    <1024 | >=1024 | >=4096 | >=8192
    ------+--------+--------+-------
      2   |   3    |   4    |   5
 
 A callback function may be used to provide feedback about the
-progress of the key generation. If B<cb> is not B<NULL>, it
+progress of the key generation. If I<cb> is not NULL, it
 will be called as follows using the BN_GENCB_call() function
 described on the L<BN_generate_prime(3)> page.
 
@@ -71,42 +72,44 @@ described in L<BN_generate_prime(3)>.
 =item *
 
 When the n-th randomly generated prime is rejected as not
-suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called.
+suitable for the key, I<BN_GENCB_call(cb, 2, n)> is called.
 
 =item *
 
-When a random p has been found with p-1 relatively prime to B<e>,
-it is called as B<BN_GENCB_call(cb, 3, 0)>.
+When a random p has been found with p-1 relatively prime to I<e>,
+it is called as I<BN_GENCB_call(cb, 3, 0)>.
 
 =back
 
 The process is then repeated for prime q and other primes (if any)
-with B<BN_GENCB_call(cb, 3, i)> where B<i> indicates the i-th prime.
+with I<BN_GENCB_call(cb, 3, i)> where I<i> indicates the i-th prime.
 
 =head1 RETURN VALUES
 
+EVP_RSA_gen() returns an I<EVP_PKEY> or NULL on failure.
+
 RSA_generate_multi_prime_key() returns 1 on success or 0 on error.
 RSA_generate_key_ex() returns 1 on success or 0 on error.
 The error codes can be obtained by L<ERR_get_error(3)>.
 
 RSA_generate_key() returns a pointer to the RSA structure or
-B<NULL> if the key generation fails.
+NULL if the key generation fails.
 
 =head1 BUGS
 
-B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
+I<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
 
 =head1 SEE ALSO
 
-L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<BN_generate_prime(3)>,
-L<RAND(7)>
+L<EVP_PKEY_Q_keygen(3)>
+L<BN_generate_prime(3)>, L<ERR_get_error(3)>,
+L<RAND_bytes(3)>, L<RAND(7)>
 
 =head1 HISTORY
 
-All of these functions were deprecated in OpenSSL 3.0.
-
-RSA_generate_key() was deprecated in OpenSSL 0.9.8; use
-RSA_generate_key_ex() instead.
+EVP_RSA_gen() was added in OpenSSL 3.0.
+All other functions described here were deprecated in OpenSSL 3.0.
+For replacement see L<EVP_PKEY-RSA(7)>.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/RSA_new.pod b/doc/man3/RSA_new.pod
index 8c2651fe59..1396a66335 100644
--- a/doc/man3/RSA_new.pod
+++ b/doc/man3/RSA_new.pod
@@ -8,6 +8,8 @@ RSA_new, RSA_free - allocate and free RSA objects
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0:
+
  RSA *RSA_new(void);
 
  void RSA_free(RSA *rsa);
@@ -35,6 +37,11 @@ L<ERR_get_error(3)>,
 L<RSA_generate_key(3)>,
 L<RSA_new_method(3)>
 
+=head1 HISTORY
+
+All functions described here were deprecated in OpenSSL 3.0.
+For replacement see EVP_PKEY-RSA(7).
+
 =head1 COPYRIGHT
 
 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.