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 =back
 127
 128 =head1 CONFORMING TO
 129
 130 =over 4
 131
 132 =item RFC 8017, excluding RSA-PSS and RSA-OAEP
 133
 134 =for comment RSA-PSS, and probably also RSA-OAEP, need separate keytypes,
 135 and will be described in separate pages for those RSA keytypes.
 136
 137 =back
 138
 139 =head1 EXAMPLES
 140
 141 An B<EVP_PKEY> context can be obtained by calling:
 142
 143     EVP_PKEY_CTX *pctx =
 144         EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
 145
 146 An B<RSA> key can be generated like this:
 147
 148     EVP_PKEY *pkey = NULL;
 149     EVP_PKEY_CTX *pctx =
 150         EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
 151
 152     EVP_PKEY_keygen_init(pctx);
 153     EVP_PKEY_gen(pctx, &pkey);
 154     EVP_PKEY_CTX_free(pctx);
 155
 156 An B<RSA> key can be generated with key generation parameters:
 157
 158     unsigned int primes = 3;
 159     unsigned int bits = 4096;
 160     OSSL_PARAM params[3];
 161     EVP_PKEY *pkey = NULL;
 162     EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
 163
 164     EVP_PKEY_keygen_init(pctx);
 165
 166     params[0] = OSSL_PARAM_construct_uint("bits", &bits);
 167     params[1] = OSSL_PARAM_construct_uint("primes", &primes);
 168     params[2] = OSSL_PARAM_construct_end();
 169     EVP_PKEY_CTX_set_params(pctx, params);
 170
 171     EVP_PKEY_gen(pctx, &pkey);
 172     EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
 173     EVP_PKEY_CTX_free(pctx);
 174
 175 =head1 SEE ALSO
 176
 177 L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>
 178
 179 =head1 COPYRIGHT
 180
 181 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 182
 183 Licensed under the Apache License 2.0 (the "License").  You may not use
 184 this file except in compliance with the License.  You can obtain a copy
 185 in the file LICENSE in the source distribution or at
 186 L<https://www.openssl.org/source/license.html>.
 187
 188 =cut