1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA 6b077aed3SPierre Pronchery- EVP_PKEY RSA keytype and algorithm support 7b077aed3SPierre Pronchery 8b077aed3SPierre Pronchery=head1 DESCRIPTION 9b077aed3SPierre Pronchery 10b077aed3SPierre ProncheryThe B<RSA> keytype is implemented in OpenSSL's default and FIPS providers. 11b077aed3SPierre ProncheryThat implementation supports the basic RSA keys, containing the modulus I<n>, 12b077aed3SPierre Proncherythe public exponent I<e>, the private exponent I<d>, and a collection of prime 13b077aed3SPierre Proncheryfactors, exponents and coefficient for CRT calculations, of which the first 14b077aed3SPierre Proncheryfew are known as I<p> and I<q>, I<dP> and I<dQ>, and I<qInv>. 15b077aed3SPierre Pronchery 16b077aed3SPierre Pronchery=head2 Common RSA parameters 17b077aed3SPierre Pronchery 18b077aed3SPierre ProncheryIn addition to the common parameters that all keytypes should support (see 19b077aed3SPierre ProncheryL<provider-keymgmt(7)/Common parameters>), the B<RSA> keytype implementation 20b077aed3SPierre Proncherysupports the following. 21b077aed3SPierre Pronchery 22b077aed3SPierre Pronchery=over 4 23b077aed3SPierre Pronchery 24b077aed3SPierre Pronchery=item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <unsigned integer> 25b077aed3SPierre Pronchery 26b077aed3SPierre ProncheryThe RSA modulus "n" value. 27b077aed3SPierre Pronchery 28b077aed3SPierre Pronchery=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer> 29b077aed3SPierre Pronchery 30b077aed3SPierre ProncheryThe RSA public exponent "e" value. 31b077aed3SPierre ProncheryThis value must always be set when creating a raw key using L<EVP_PKEY_fromdata(3)>. 32b077aed3SPierre ProncheryNote that when a decryption operation is performed, that this value is used for 33b077aed3SPierre Proncheryblinding purposes to prevent timing attacks. 34b077aed3SPierre Pronchery 35b077aed3SPierre Pronchery=item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <unsigned integer> 36b077aed3SPierre Pronchery 37b077aed3SPierre ProncheryThe RSA private exponent "d" value. 38b077aed3SPierre Pronchery 39b077aed3SPierre Pronchery=item "rsa-factor1" (B<OSSL_PKEY_PARAM_RSA_FACTOR1>) <unsigned integer> 40b077aed3SPierre Pronchery 41b077aed3SPierre Pronchery=item "rsa-factor2" (B<OSSL_PKEY_PARAM_RSA_FACTOR2>) <unsigned integer> 42b077aed3SPierre Pronchery 43b077aed3SPierre Pronchery=item "rsa-factor3" (B<OSSL_PKEY_PARAM_RSA_FACTOR3>) <unsigned integer> 44b077aed3SPierre Pronchery 45b077aed3SPierre Pronchery=item "rsa-factor4" (B<OSSL_PKEY_PARAM_RSA_FACTOR4>) <unsigned integer> 46b077aed3SPierre Pronchery 47b077aed3SPierre Pronchery=item "rsa-factor5" (B<OSSL_PKEY_PARAM_RSA_FACTOR5>) <unsigned integer> 48b077aed3SPierre Pronchery 49b077aed3SPierre Pronchery=item "rsa-factor6" (B<OSSL_PKEY_PARAM_RSA_FACTOR6>) <unsigned integer> 50b077aed3SPierre Pronchery 51b077aed3SPierre Pronchery=item "rsa-factor7" (B<OSSL_PKEY_PARAM_RSA_FACTOR7>) <unsigned integer> 52b077aed3SPierre Pronchery 53b077aed3SPierre Pronchery=item "rsa-factor8" (B<OSSL_PKEY_PARAM_RSA_FACTOR8>) <unsigned integer> 54b077aed3SPierre Pronchery 55b077aed3SPierre Pronchery=item "rsa-factor9" (B<OSSL_PKEY_PARAM_RSA_FACTOR9>) <unsigned integer> 56b077aed3SPierre Pronchery 57b077aed3SPierre Pronchery=item "rsa-factor10" (B<OSSL_PKEY_PARAM_RSA_FACTOR10>) <unsigned integer> 58b077aed3SPierre Pronchery 59b077aed3SPierre ProncheryRSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017. 60b077aed3SPierre ProncheryUp to eight additional "r_i" prime factors are supported. 61b077aed3SPierre Pronchery 62b077aed3SPierre Pronchery=item "rsa-exponent1" (B<OSSL_PKEY_PARAM_RSA_EXPONENT1>) <unsigned integer> 63b077aed3SPierre Pronchery 64b077aed3SPierre Pronchery=item "rsa-exponent2" (B<OSSL_PKEY_PARAM_RSA_EXPONENT2>) <unsigned integer> 65b077aed3SPierre Pronchery 66b077aed3SPierre Pronchery=item "rsa-exponent3" (B<OSSL_PKEY_PARAM_RSA_EXPONENT3>) <unsigned integer> 67b077aed3SPierre Pronchery 68b077aed3SPierre Pronchery=item "rsa-exponent4" (B<OSSL_PKEY_PARAM_RSA_EXPONENT4>) <unsigned integer> 69b077aed3SPierre Pronchery 70b077aed3SPierre Pronchery=item "rsa-exponent5" (B<OSSL_PKEY_PARAM_RSA_EXPONENT5>) <unsigned integer> 71b077aed3SPierre Pronchery 72b077aed3SPierre Pronchery=item "rsa-exponent6" (B<OSSL_PKEY_PARAM_RSA_EXPONENT6>) <unsigned integer> 73b077aed3SPierre Pronchery 74b077aed3SPierre Pronchery=item "rsa-exponent7" (B<OSSL_PKEY_PARAM_RSA_EXPONENT7>) <unsigned integer> 75b077aed3SPierre Pronchery 76b077aed3SPierre Pronchery=item "rsa-exponent8" (B<OSSL_PKEY_PARAM_RSA_EXPONENT8>) <unsigned integer> 77b077aed3SPierre Pronchery 78b077aed3SPierre Pronchery=item "rsa-exponent9" (B<OSSL_PKEY_PARAM_RSA_EXPONENT9>) <unsigned integer> 79b077aed3SPierre Pronchery 80b077aed3SPierre Pronchery=item "rsa-exponent10" (B<OSSL_PKEY_PARAM_RSA_EXPONENT10>) <unsigned integer> 81b077aed3SPierre Pronchery 82b077aed3SPierre ProncheryRSA CRT (Chinese Remainder Theorem) exponents. The exponents are known 83*e0c4386eSCy Schubertas "dP", "dQ" and "d_i" in RFC8017. 84b077aed3SPierre ProncheryUp to eight additional "d_i" exponents are supported. 85b077aed3SPierre Pronchery 86b077aed3SPierre Pronchery=item "rsa-coefficient1" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT1>) <unsigned integer> 87b077aed3SPierre Pronchery 88b077aed3SPierre Pronchery=item "rsa-coefficient2" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT2>) <unsigned integer> 89b077aed3SPierre Pronchery 90b077aed3SPierre Pronchery=item "rsa-coefficient3" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT3>) <unsigned integer> 91b077aed3SPierre Pronchery 92b077aed3SPierre Pronchery=item "rsa-coefficient4" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT4>) <unsigned integer> 93b077aed3SPierre Pronchery 94b077aed3SPierre Pronchery=item "rsa-coefficient5" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT5>) <unsigned integer> 95b077aed3SPierre Pronchery 96b077aed3SPierre Pronchery=item "rsa-coefficient6" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT6>) <unsigned integer> 97b077aed3SPierre Pronchery 98b077aed3SPierre Pronchery=item "rsa-coefficient7" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT7>) <unsigned integer> 99b077aed3SPierre Pronchery 100b077aed3SPierre Pronchery=item "rsa-coefficient8" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT8>) <unsigned integer> 101b077aed3SPierre Pronchery 102b077aed3SPierre Pronchery=item "rsa-coefficient9" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT9>) <unsigned integer> 103b077aed3SPierre Pronchery 104b077aed3SPierre ProncheryRSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as 105b077aed3SPierre Pronchery"qInv" and "t_i". 106b077aed3SPierre ProncheryUp to eight additional "t_i" exponents are supported. 107b077aed3SPierre Pronchery 108b077aed3SPierre Pronchery=back 109b077aed3SPierre Pronchery 110b077aed3SPierre Pronchery=head2 RSA key generation parameters 111b077aed3SPierre Pronchery 112b077aed3SPierre ProncheryWhen generating RSA keys, the following key generation parameters may be used. 113b077aed3SPierre Pronchery 114b077aed3SPierre Pronchery=over 4 115b077aed3SPierre Pronchery 116b077aed3SPierre Pronchery=item "bits" (B<OSSL_PKEY_PARAM_RSA_BITS>) <unsigned integer> 117b077aed3SPierre Pronchery 118b077aed3SPierre ProncheryThe value should be the cryptographic length for the B<RSA> cryptosystem, in 119b077aed3SPierre Proncherybits. 120b077aed3SPierre Pronchery 121b077aed3SPierre Pronchery=item "primes" (B<OSSL_PKEY_PARAM_RSA_PRIMES>) <unsigned integer> 122b077aed3SPierre Pronchery 123b077aed3SPierre ProncheryThe value should be the number of primes for the generated B<RSA> key. The 124b077aed3SPierre Proncherydefault is 2. It isn't permitted to specify a larger number of primes than 125b077aed3SPierre Pronchery10. Additionally, the number of primes is limited by the length of the key 126b077aed3SPierre Proncherybeing generated so the maximum number could be less. 127b077aed3SPierre ProncherySome providers may only support a value of 2. 128b077aed3SPierre Pronchery 129b077aed3SPierre Pronchery=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer> 130b077aed3SPierre Pronchery 131b077aed3SPierre ProncheryThe RSA "e" value. The value may be any odd number greater than or equal to 132b077aed3SPierre Pronchery65537. The default value is 65537. 133b077aed3SPierre ProncheryFor legacy reasons a value of 3 is currently accepted but is deprecated. 134b077aed3SPierre Pronchery 135b077aed3SPierre Pronchery=back 136b077aed3SPierre Pronchery 137b077aed3SPierre Pronchery=head2 RSA key generation parameters for FIPS module testing 138b077aed3SPierre Pronchery 139b077aed3SPierre ProncheryWhen generating RSA keys, the following additional key generation parameters may 140b077aed3SPierre Proncherybe used for algorithm testing purposes only. Do not use these to generate 141b077aed3SPierre ProncheryRSA keys for a production environment. 142b077aed3SPierre Pronchery 143b077aed3SPierre Pronchery=over 4 144b077aed3SPierre Pronchery 145b077aed3SPierre Pronchery=item "xp" (B<OSSL_PKEY_PARAM_RSA_TEST_XP>) <unsigned integer> 146b077aed3SPierre Pronchery 147b077aed3SPierre Pronchery=item "xq" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ>) <unsigned integer> 148b077aed3SPierre Pronchery 149b077aed3SPierre ProncheryThese 2 fields are normally randomly generated and are used to generate "p" and 150b077aed3SPierre Pronchery"q". 151b077aed3SPierre Pronchery 152b077aed3SPierre Pronchery=item "xp1" (B<OSSL_PKEY_PARAM_RSA_TEST_XP1>) <unsigned integer> 153b077aed3SPierre Pronchery 154b077aed3SPierre Pronchery=item "xp2" (B<OSSL_PKEY_PARAM_RSA_TEST_XP2>) <unsigned integer> 155b077aed3SPierre Pronchery 156b077aed3SPierre Pronchery=item "xq1" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ1>) <unsigned integer> 157b077aed3SPierre Pronchery 158b077aed3SPierre Pronchery=item "xq2" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ2>) <unsigned integer> 159b077aed3SPierre Pronchery 160b077aed3SPierre ProncheryThese 4 fields are normally randomly generated. The prime factors "p1", "p2", 161b077aed3SPierre Pronchery"q1" and "q2" are determined from these values. 162b077aed3SPierre Pronchery 163b077aed3SPierre Pronchery=back 164b077aed3SPierre Pronchery 165b077aed3SPierre Pronchery=head2 RSA key parameters for FIPS module testing 166b077aed3SPierre Pronchery 167b077aed3SPierre ProncheryThe following intermediate values can be retrieved only if the values 168b077aed3SPierre Proncheryspecified in L</"RSA key generation parameters for FIPS module testing"> are set. 169b077aed3SPierre ProncheryThese should not be accessed in a production environment. 170b077aed3SPierre Pronchery 171b077aed3SPierre Pronchery=over 4 172b077aed3SPierre Pronchery 173b077aed3SPierre Pronchery=item "p1" (B<OSSL_PKEY_PARAM_RSA_TEST_P1>) <unsigned integer> 174b077aed3SPierre Pronchery 175b077aed3SPierre Pronchery=item "p2" (B<OSSL_PKEY_PARAM_RSA_TEST_P2>) <unsigned integer> 176b077aed3SPierre Pronchery 177b077aed3SPierre Pronchery=item "q1" (B<OSSL_PKEY_PARAM_RSA_TEST_Q1>) <unsigned integer> 178b077aed3SPierre Pronchery 179b077aed3SPierre Pronchery=item "q2" (B<OSSL_PKEY_PARAM_RSA_TEST_Q2>) <unsigned integer> 180b077aed3SPierre Pronchery 181b077aed3SPierre ProncheryThe auxiliary probable primes. 182b077aed3SPierre Pronchery 183b077aed3SPierre Pronchery=back 184b077aed3SPierre Pronchery 185b077aed3SPierre Pronchery=head2 RSA key validation 186b077aed3SPierre Pronchery 187b077aed3SPierre ProncheryFor RSA keys, L<EVP_PKEY_param_check(3)> and L<EVP_PKEY_param_check_quick(3)> 188b077aed3SPierre Proncheryboth return 1 unconditionally. 189b077aed3SPierre Pronchery 190b077aed3SPierre ProncheryFor RSA keys, L<EVP_PKEY_public_check(3)> conforms to the SP800-56Br1 I<public key 191b077aed3SPierre Proncherycheck> when the OpenSSL FIPS provider is used. The OpenSSL default provider 192aa795734SPierre Proncheryperforms similar tests but relaxes the keysize restrictions for backwards 193b077aed3SPierre Proncherycompatibility. 194b077aed3SPierre Pronchery 195b077aed3SPierre ProncheryFor RSA keys, L<EVP_PKEY_public_check_quick(3)> is the same as 196b077aed3SPierre ProncheryL<EVP_PKEY_public_check(3)>. 197b077aed3SPierre Pronchery 198b077aed3SPierre ProncheryFor RSA keys, L<EVP_PKEY_private_check(3)> conforms to the SP800-56Br1 199b077aed3SPierre ProncheryI<private key test>. 200b077aed3SPierre Pronchery 201b077aed3SPierre ProncheryFor RSA keys, L<EVP_PKEY_pairwise_check(3)> conforms to the 202b077aed3SPierre ProncherySP800-56Br1 I<KeyPair Validation check> for the OpenSSL FIPS provider. The 203b077aed3SPierre ProncheryOpenSSL default provider allows testing of the validity of multi-primes. 204b077aed3SPierre Pronchery 205b077aed3SPierre Pronchery=head1 CONFORMING TO 206b077aed3SPierre Pronchery 207b077aed3SPierre Pronchery=over 4 208b077aed3SPierre Pronchery 209b077aed3SPierre Pronchery=item FIPS186-4 210b077aed3SPierre Pronchery 211b077aed3SPierre ProncherySection B.3.6 Generation of Probable Primes with Conditions Based on 212b077aed3SPierre ProncheryAuxiliary Probable Primes 213b077aed3SPierre Pronchery 214b077aed3SPierre Pronchery=item RFC 8017, excluding RSA-PSS and RSA-OAEP 215b077aed3SPierre Pronchery 216b077aed3SPierre Pronchery=for comment RSA-PSS, and probably also RSA-OAEP, need separate keytypes, 217b077aed3SPierre Proncheryand will be described in separate pages for those RSA keytypes. 218b077aed3SPierre Pronchery 219b077aed3SPierre Pronchery=back 220b077aed3SPierre Pronchery 221b077aed3SPierre Pronchery=head1 EXAMPLES 222b077aed3SPierre Pronchery 223b077aed3SPierre ProncheryAn B<EVP_PKEY> context can be obtained by calling: 224b077aed3SPierre Pronchery 225b077aed3SPierre Pronchery EVP_PKEY_CTX *pctx = 226b077aed3SPierre Pronchery EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); 227b077aed3SPierre Pronchery 228b077aed3SPierre ProncheryAn B<RSA> key can be generated simply like this: 229b077aed3SPierre Pronchery 230b077aed3SPierre Pronchery pkey = EVP_RSA_gen(4096); 231b077aed3SPierre Pronchery 232b077aed3SPierre Proncheryor like this: 233b077aed3SPierre Pronchery 234b077aed3SPierre Pronchery EVP_PKEY *pkey = NULL; 235b077aed3SPierre Pronchery EVP_PKEY_CTX *pctx = 236b077aed3SPierre Pronchery EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); 237b077aed3SPierre Pronchery 238b077aed3SPierre Pronchery EVP_PKEY_keygen_init(pctx); 239b077aed3SPierre Pronchery EVP_PKEY_generate(pctx, &pkey); 240b077aed3SPierre Pronchery EVP_PKEY_CTX_free(pctx); 241b077aed3SPierre Pronchery 242b077aed3SPierre ProncheryAn B<RSA> key can be generated with key generation parameters: 243b077aed3SPierre Pronchery 244b077aed3SPierre Pronchery unsigned int primes = 3; 245b077aed3SPierre Pronchery unsigned int bits = 4096; 246b077aed3SPierre Pronchery OSSL_PARAM params[3]; 247b077aed3SPierre Pronchery EVP_PKEY *pkey = NULL; 248b077aed3SPierre Pronchery EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL); 249b077aed3SPierre Pronchery 250b077aed3SPierre Pronchery EVP_PKEY_keygen_init(pctx); 251b077aed3SPierre Pronchery 252b077aed3SPierre Pronchery params[0] = OSSL_PARAM_construct_uint("bits", &bits); 253b077aed3SPierre Pronchery params[1] = OSSL_PARAM_construct_uint("primes", &primes); 254b077aed3SPierre Pronchery params[2] = OSSL_PARAM_construct_end(); 255b077aed3SPierre Pronchery EVP_PKEY_CTX_set_params(pctx, params); 256b077aed3SPierre Pronchery 257b077aed3SPierre Pronchery EVP_PKEY_generate(pctx, &pkey); 258b077aed3SPierre Pronchery EVP_PKEY_print_private(bio_out, pkey, 0, NULL); 259b077aed3SPierre Pronchery EVP_PKEY_CTX_free(pctx); 260b077aed3SPierre Pronchery 261b077aed3SPierre Pronchery=head1 SEE ALSO 262b077aed3SPierre Pronchery 263b077aed3SPierre ProncheryL<EVP_RSA_gen(3)>, L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)> 264b077aed3SPierre Pronchery 265b077aed3SPierre Pronchery=head1 COPYRIGHT 266b077aed3SPierre Pronchery 267b077aed3SPierre ProncheryCopyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. 268b077aed3SPierre Pronchery 269b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 270b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 271b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 272b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 273b077aed3SPierre Pronchery 274b077aed3SPierre Pronchery=cut 275