1=pod 2 3=head1 NAME 4 5EVP_RSA_gen, 6RSA_generate_key_ex, RSA_generate_key, 7RSA_generate_multi_prime_key - generate RSA key pair 8 9=head1 SYNOPSIS 10 11 #include <openssl/rsa.h> 12 13 EVP_PKEY *EVP_RSA_gen(unsigned int bits); 14 15The following functions have been deprecated since OpenSSL 3.0, and can be 16hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 17see L<openssl_user_macros(7)>: 18 19 int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); 20 int RSA_generate_multi_prime_key(RSA *rsa, int bits, int primes, BIGNUM *e, BN_GENCB *cb); 21 22The following function has been deprecated since OpenSSL 0.9.8, and can be 23hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 24see L<openssl_user_macros(7)>: 25 26 RSA *RSA_generate_key(int bits, unsigned long e, 27 void (*callback)(int, int, void *), void *cb_arg); 28 29=head1 DESCRIPTION 30 31EVP_RSA_gen() generates a new RSA key pair with modulus size I<bits>. 32 33All of the functions described below are deprecated. 34Applications should instead use EVP_RSA_gen(), L<EVP_PKEY_Q_keygen(3)>, or 35L<EVP_PKEY_keygen_init(3)> and L<EVP_PKEY_keygen(3)>. 36 37RSA_generate_key_ex() generates a 2-prime RSA key pair and stores it in the 38B<RSA> structure provided in I<rsa>. 39 40RSA_generate_multi_prime_key() generates a multi-prime RSA key pair and stores 41it in the B<RSA> structure provided in I<rsa>. The number of primes is given by 42the I<primes> parameter. 43If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to 44external circumstances (see L<RAND(7)>), the operation will fail. 45 46The modulus size will be of length I<bits>, the number of primes to form the 47modulus will be I<primes>, and the public exponent will be I<e>. Key sizes 48with I<num> E<lt> 1024 should be considered insecure. The exponent is an odd 49number, typically 3, 17 or 65537. 50 51In order to maintain adequate security level, the maximum number of permitted 52I<primes> depends on modulus bit length: 53 54 <1024 | >=1024 | >=4096 | >=8192 55 ------+--------+--------+------- 56 2 | 3 | 4 | 5 57 58A callback function may be used to provide feedback about the 59progress of the key generation. If I<cb> is not NULL, it 60will be called as follows using the BN_GENCB_call() function 61described on the L<BN_generate_prime(3)> page. 62 63RSA_generate_key() is similar to RSA_generate_key_ex() but 64expects an old-style callback function; see 65L<BN_generate_prime(3)> for information on the old-style callback. 66 67=over 2 68 69=item * 70 71While a random prime number is generated, it is called as 72described in L<BN_generate_prime(3)>. 73 74=item * 75 76When the n-th randomly generated prime is rejected as not 77suitable for the key, I<BN_GENCB_call(cb, 2, n)> is called. 78 79=item * 80 81When a random p has been found with p-1 relatively prime to I<e>, 82it is called as I<BN_GENCB_call(cb, 3, 0)>. 83 84=back 85 86The process is then repeated for prime q and other primes (if any) 87with I<BN_GENCB_call(cb, 3, i)> where I<i> indicates the i-th prime. 88 89=head1 RETURN VALUES 90 91EVP_RSA_gen() returns an I<EVP_PKEY> or NULL on failure. 92 93RSA_generate_multi_prime_key() returns 1 on success or 0 on error. 94RSA_generate_key_ex() returns 1 on success or 0 on error. 95The error codes can be obtained by L<ERR_get_error(3)>. 96 97RSA_generate_key() returns a pointer to the RSA structure or 98NULL if the key generation fails. 99 100=head1 BUGS 101 102I<BN_GENCB_call(cb, 2, x)> is used with two different meanings. 103 104=head1 SEE ALSO 105 106L<EVP_PKEY_Q_keygen(3)> 107L<BN_generate_prime(3)>, L<ERR_get_error(3)>, 108L<RAND_bytes(3)>, L<RAND(7)> 109 110=head1 HISTORY 111 112EVP_RSA_gen() was added in OpenSSL 3.0. 113All other functions described here were deprecated in OpenSSL 3.0. 114For replacement see L<EVP_PKEY-RSA(7)>. 115 116=head1 COPYRIGHT 117 118Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. 119 120Licensed under the Apache License 2.0 (the "License"). You may not use 121this file except in compliance with the License. You can obtain a copy 122in the file LICENSE in the source distribution or at 123L<https://www.openssl.org/source/license.html>. 124 125=cut 126
