doc/man7/EVP_PKEY-RSA.pod

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