diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-03-20 13:49:08 +0100 |
---|---|---|
committer | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-05-11 12:46:42 +0200 |
commit | f925315203f77d0241183ccabfc784d259b0a152 (patch) | |
tree | 2d92c75d7e19d48de1ed8da32b724b3603f5a3c6 | |
parent | 6dbb277627de86578577185084378135605d2df1 (diff) |
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)
34 files changed, 232 insertions, 150 deletions
diff --git a/CHANGES.md b/CHANGES.md index 69863b27da..80a7bc7075 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -405,6 +405,12 @@ OpenSSL 3.0 *Dmitry Belyavskiy* + * Added convenience functions for generating asymmetric key pairs: + The 'quick' one-shot (yet somewhat limited) function L<EVP_PKEY_Q_keygen(3)> + and macros for the most common cases: <EVP_RSA_gen(3)> and L<EVP_EC_gen(3)>. + + *David von Oheimb* + * All of the low-level EC_KEY functions have been deprecated including: EC_KEY_OpenSSL, EC_KEY_get_default_method, EC_KEY_set_default_method, @@ -429,7 +435,8 @@ OpenSSL 3.0 Applications that need to implement an EC_KEY_METHOD need to consider implementation of the functionality in a special provider. For replacement of the functions manipulating the EC_KEY objects - see the EVP_PKEY-EC(7) manual page. + see the L<EVP_PKEY-EC(7)> manual page. + A simple way of generating EC keys is L<EVP_EC_gen(3)>. Additionally functions that read and write EC_KEY objects such as o2i_ECPublicKey, i2o_ECPublicKey, ECParameters_print_fp, EC_KEY_print_fp, @@ -825,7 +832,7 @@ OpenSSL 3.0 * All of the low-level RSA functions have been deprecated including: - RSA_new_method, RSA_size, RSA_security_bits, RSA_get0_pss_params, + RSA_new, RSA_new_method, RSA_size, RSA_security_bits, RSA_get0_pss_params, RSA_get_version, RSA_get0_engine, RSA_generate_key_ex, RSA_generate_multi_prime_key, RSA_X931_derive_ex, RSA_X931_generate_key_ex, RSA_check_key, RSA_check_key_ex, RSA_public_encrypt, RSA_private_encrypt, @@ -858,6 +865,9 @@ OpenSSL 3.0 time. Instead applications should use L<EVP_PKEY_encrypt_init(3)>, L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>. + For replacement of the functions manipulating the RSA objects + see the L<EVP_PKEY-RSA(7)> manual page. + A simple way of generating RSA keys is L<EVP_RSA_gen(3)>. All of these low-level RSA functions have been deprecated without replacement: @@ -26,6 +26,7 @@ OpenSSL 3.0 RC4, RC5, and DES to the legacy provider. * Moved the EVP digests MD2, MD4, MDC2, WHIRLPOOL and RIPEMD-160 to the legacy provider. + * Added convenience functions for generating asymmetric key pairs. * Deprecated the `OCSP_REQ_CTX` type and functions. * Deprecated the `EC_KEY` and `EC_KEY_METHOD` types and functions. * Deprecated the `RSA` and `RSA_METHOD` types and functions. diff --git a/crypto/conf/conf_def.c b/crypto/conf/conf_def.c index ea6b5bf244..25fcc0400c 100644 --- a/crypto/conf/conf_def.c +++ b/crypto/conf/conf_def.c @@ -11,8 +11,8 @@ #include <stdio.h> #include <string.h> +#include "e_os.h" /* strcasecmp and struct stat */ #ifdef __TANDEM -# include <strings.h> /* strcasecmp */ # include <sys/types.h> /* needed for stat.h */ # include <sys/stat.h> /* struct stat */ #endif @@ -28,7 +28,6 @@ # include <sys/stat.h> # ifdef _WIN32 # define stat _stat -# define strcasecmp _stricmp # endif #endif diff --git a/crypto/ec/ec_backend.c b/crypto/ec/ec_backend.c index 6acfa21f69..defcb649fb 100644 --- a/crypto/ec/ec_backend.c +++ b/crypto/ec/ec_backend.c @@ -328,7 +328,7 @@ int ossl_ec_group_todata(const EC_GROUP *group, OSSL_PARAM_BLD *tmpl, if (curve_nid != NID_undef) { /* Named curve */ - const char *curve_name = ossl_ec_curve_nid2name(curve_nid); + const char *curve_name = OSSL_EC_curve_nid2name(curve_nid); if (curve_name == NULL || !ossl_param_build_set_utf8_string(tmpl, params, diff --git a/crypto/evp/ctrl_params_translate.c b/crypto/evp/ctrl_params_translate.c index f48e723c33..3a49aea931 100644 --- a/crypto/evp/ctrl_params_translate.c +++ b/crypto/evp/ctrl_params_translate.c @@ -1482,7 +1482,7 @@ static int get_payload_group_name(enum state state, if (grp != NULL) nid = EC_GROUP_get_curve_name(grp); if (nid != NID_undef) - ctx->p2 = (char *)ossl_ec_curve_nid2name(nid); + ctx->p2 = (char *)OSSL_EC_curve_nid2name(nid); } break; #endif diff --git a/crypto/evp/ec_support.c b/crypto/evp/ec_support.c index 24337a5eac..8550be65e7 100644 --- a/crypto/evp/ec_support.c +++ b/crypto/evp/ec_support.c @@ -115,7 +115,7 @@ static const EC_NAME2NID curve_list[] = { {"SM2", NID_sm2 }, }; -const char *ossl_ec_curve_nid2name(int nid) +const char *OSSL_EC_curve_nid2name(int nid) { size_t i; diff --git a/crypto/evp/evp_lib.c b/crypto/evp/evp_lib.c index 842ee51b8d..5cd3cc6112 100644 --- a/crypto/evp/evp_lib.c +++ b/crypto/evp/evp_lib.c @@ -14,11 +14,14 @@ #include "internal/deprecated.h" #include <stdio.h> +#include <string.h> +#include "e_os.h" /* strcasecmp */ #include "internal/cryptlib.h" #include <openssl/evp.h> #include <openssl/objects.h> #include <openssl/params.h> #include <openssl/core_names.h> +#include <openssl/rsa.h> #include <openssl/dh.h> #include <openssl/ec.h> #include "crypto/evp.h" @@ -27,6 +30,7 @@ #include "evp_local.h" #if !defined(FIPS_MODULE) + int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type) { return evp_cipher_param_to_asn1_ex(c, type, NULL); @@ -1111,3 +1115,59 @@ int EVP_PKEY_CTX_get_group_name(EVP_PKEY_CTX *ctx, char *name, size_t namelen) return -1; return 1; } + +/* + * evp_pkey_keygen() abstracts from the explicit use of B<EVP_PKEY_CTX> + * while providing a generic way of generating a new asymmetric key pair + * of algorithm type I<name> (e.g., C<RSA> or C<EC>). + * The library context I<libctx> and property query I<propq> + * are used when fetching algorithms from providers. + * The I<params> specify algorithm-specific parameters + * such as the RSA modulus size or the name of an EC curve. + */ +static EVP_PKEY *evp_pkey_keygen(OSSL_LIB_CTX *libctx, const char *name, + const char *propq, OSSL_PARAM *params) +{ + EVP_PKEY *pkey = NULL; + EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(libctx, name, propq); + + if (ctx != NULL + && EVP_PKEY_keygen_init(ctx) > 0 + && EVP_PKEY_CTX_set_params(ctx, params)) + (void)EVP_PKEY_generate(ctx, &pkey); + + EVP_PKEY_CTX_free(ctx); + return pkey; +} + +EVP_PKEY *EVP_PKEY_Q_keygen(OSSL_LIB_CTX *libctx, const char *propq, + const char *type, ...) +{ + va_list args; + size_t bits; + char *name; + OSSL_PARAM params[] = { OSSL_PARAM_END, OSSL_PARAM_END }; + EVP_PKEY *ret = NULL; + + va_start(args, type); + + if (strcasecmp(type, "RSA") == 0) { + bits = va_arg(args, size_t); + params[0] = OSSL_PARAM_construct_size_t(OSSL_PKEY_PARAM_RSA_BITS, &bits); + } else if (strcasecmp(type, "EC") == 0) { + name = va_arg(args, char *); + params[0] = OSSL_PARAM_construct_utf8_string(OSSL_PKEY_PARAM_GROUP_NAME, + name, 0); + } else if (strcasecmp(type, "ED25519") != 0 + && strcasecmp(type, "X25519") != 0 + && strcasecmp(type, "ED448") != 0 + && strcasecmp(type, "X448") != 0) { + ERR_raise(ERR_LIB_EVP, ERR_R_PASSED_INVALID_ARGUMENT); + goto end; + } + ret = evp_pkey_keygen(libctx, type, propq, params); + + end: + va_end(args); + return ret; +} diff --git a/crypto/evp/pmeth_gn.c b/crypto/evp/pmeth_gn.c index e184db26a0..94499b1d45 100644 --- a/crypto/evp/pmeth_gn.c +++ b/crypto/evp/pmeth_gn.c @@ -123,7 +123,7 @@ static int ossl_callback_to_pkey_gencb(const OSSL_PARAM params[], void *arg) return ctx->pkey_gencb(ctx); } -int EVP_PKEY_gen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey) +int EVP_PKEY_generate(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey) { int ret = 0; OSSL_CALLBACK cb; @@ -262,7 +262,7 @@ int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey) ERR_raise(ERR_LIB_EVP, EVP_R_OPERATION_NOT_INITIALIZED); return -1; } - return EVP_PKEY_gen(ctx, ppkey); + return EVP_PKEY_generate(ctx, ppkey); } int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey) @@ -271,7 +271,7 @@ int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey) ERR_raise(ERR_LIB_EVP, EVP_R_OPERATION_NOT_INITIALIZED); return -1; } - return EVP_PKEY_gen(ctx, ppkey); + return EVP_PKEY_generate(ctx, ppkey); } void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb) diff --git a/doc/build.info b/doc/build.info index 8ee9ca10e3..ec3baa2373 100644 --- a/doc/build.info +++ b/doc/build.info @@ -1206,10 +1206,6 @@ DEPEND[html/man3/EVP_PKEY_fromdata.html]=man3/EVP_PKEY_fromdata.pod GENERATE[html/man3/EVP_PKEY_fromdata.html]=man3/EVP_PKEY_fromdata.pod DEPEND[man/man3/EVP_PKEY_fromdata.3]=man3/EVP_PKEY_fromdata.pod GENERATE[man/man3/EVP_PKEY_fromdata.3]=man3/EVP_PKEY_fromdata.pod -DEPEND[html/man3/EVP_PKEY_gen.html]=man3/EVP_PKEY_gen.pod -GENERATE[html/man3/EVP_PKEY_gen.html]=man3/EVP_PKEY_gen.pod -DEPEND[man/man3/EVP_PKEY_gen.3]=man3/EVP_PKEY_gen.pod -GENERATE[man/man3/EVP_PKEY_gen.3]=man3/EVP_PKEY_gen.pod DEPEND[html/man3/EVP_PKEY_get_default_digest_nid.html]=man3/EVP_PKEY_get_default_digest_nid.pod GENERATE[html/man3/EVP_PKEY_get_default_digest_nid.html]=man3/EVP_PKEY_get_default_digest_nid.pod DEPEND[man/man3/EVP_PKEY_get_default_digest_nid.3]=man3/EVP_PKEY_get_default_digest_nid.pod @@ -1230,6 +1226,10 @@ DEPEND[html/man3/EVP_PKEY_is_a.html]=man3/EVP_PKEY_is_a.pod GENERATE[html/man3/EVP_PKEY_is_a.html]=man3/EVP_PKEY_is_a.pod DEPEND[man/man3/EVP_PKEY_is_a.3]=man3/EVP_PKEY_is_a.pod GENERATE[man/man3/EVP_PKEY_is_a.3]=man3/EVP_PKEY_is_a.pod +DEPEND[html/man3/EVP_PKEY_keygen.html]=man3/EVP_PKEY_keygen.pod +GENERATE[html/man3/EVP_PKEY_keygen.html]=man3/EVP_PKEY_keygen.pod +DEPEND[man/man3/EVP_PKEY_keygen.3]=man3/EVP_PKEY_keygen.pod +GENERATE[man/man3/EVP_PKEY_keygen.3]=man3/EVP_PKEY_keygen.pod DEPEND[html/man3/EVP_PKEY_meth_get_count.html]=man3/EVP_PKEY_meth_get_count.pod GENERATE[html/man3/EVP_PKEY_meth_get_count.html]=man3/EVP_PKEY_meth_get_count.pod DEPEND[man/man3/EVP_PKEY_meth_get_count.3]=man3/EVP_PKEY_meth_get_count.pod @@ -2999,12 +2999,12 @@ html/man3/EVP_PKEY_derive.html \ html/man3/EVP_PKEY_encapsulate.html \ html/man3/EVP_PKEY_encrypt.html \ html/man3/EVP_PKEY_fromdata.html \ -html/man3/EVP_PKEY_gen.html \ html/man3/EVP_PKEY_get_default_digest_nid.html \ html/man3/EVP_PKEY_get_field_type.html \ html/man3/EVP_PKEY_get_group_name.html \ html/man3/EVP_PKEY_gettable_params.html \ html/man3/EVP_PKEY_is_a.html \ +html/man3/EVP_PKEY_keygen.html \ html/man3/EVP_PKEY_meth_get_count.html \ html/man3/EVP_PKEY_meth_new.html \ html/man3/EVP_PKEY_new.html \ @@ -3586,12 +3586,12 @@ man/man3/EVP_PKEY_derive.3 \ man/man3/EVP_PKEY_encapsulate.3 \ man/man3/EVP_PKEY_encrypt.3 \ man/man3/EVP_PKEY_fromdata.3 \ -man/man3/EVP_PKEY_gen.3 \ man/man3/EVP_PKEY_get_default_digest_nid.3 \ man/man3/EVP_PKEY_get_field_type.3 \ man/man3/EVP_PKEY_get_group_name.3 \ man/man3/EVP_PKEY_gettable_params.3 \ man/man3/EVP_PKEY_is_a.3 \ +man/man3/EVP_PKEY_keygen.3 \ man/man3/EVP_PKEY_meth_get_count.3 \ man/man3/EVP_PKEY_meth_new.3 \ man/man3/EVP_PKEY_new.3 \ 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. diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod index c5ba90ec8c..9da5d9c6ef 100644 --- a/doc/man7/EVP_PKEY-DH.pod +++ b/doc/man7/EVP_PKEY-DH.pod @@ -154,7 +154,7 @@ A B<DH> key can be generated with a named safe prime group by calling: |