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