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 "n" value.
27
28=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
29
30The RSA "e" value.
31
32=item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <unsigned integer>
33
34The 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
56RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017.
57Up 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
79RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known
80as "dP", "dQ" and "d_i in RFC8017".
81Up 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
101RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as
102"qInv" and "t_i".
103Up to eight additional "t_i" exponents are supported.
104
105=back
106
107=head2 RSA key generation parameters
108
109When 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
115The value should be the cryptographic length for the B<RSA> cryptosystem, in
116bits.
117
118=item "primes" (B<OSSL_PKEY_PARAM_RSA_PRIMES>) <unsigned integer>
119
120The value should be the number of primes for the generated B<RSA> key.  The
121default is 2.  It isn't permitted to specify a larger number of primes than
12210.  Additionally, the number of primes is limited by the length of the key
123being generated so the maximum number could be less.
124Some providers may only support a value of 2.
125
126=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
127
128The RSA "e" value. The value may be any odd number greater than or equal to
12965537. The default value is 65537.
130For 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
136When generating RSA keys, the following additional key generation parameters may
137be used for algorithm testing purposes only. Do not use these to generate
138RSA 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
146These 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
157These 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
164The following intermediate values can be retrieved only if the values
165specified in L</"RSA key generation parameters for FIPS module testing"> are set.
166These 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
178The auxiliary probable primes.
179
180=back
181
182=head1 CONFORMING TO
183
184=over 4
185
186=item FIPS186-4
187
188Section B.3.6  Generation of Probable Primes with Conditions Based on
189Auxiliary Probable Primes
190
191=item RFC 8017, excluding RSA-PSS and RSA-OAEP
192
193=for comment RSA-PSS, and probably also RSA-OAEP, need separate keytypes,
194and will be described in separate pages for those RSA keytypes.
195
196=back
197
198=head1 EXAMPLES
199
200An B<EVP_PKEY> context can be obtained by calling:
201
202    EVP_PKEY_CTX *pctx =
203        EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
204
205An B<RSA> key can be generated simply like this:
206
207    pkey = EVP_RSA_gen(4096);
208
209or like this:
210
211    EVP_PKEY *pkey = NULL;
212    EVP_PKEY_CTX *pctx =
213        EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
214
215    EVP_PKEY_keygen_init(pctx);
216    EVP_PKEY_generate(pctx, &pkey);
217    EVP_PKEY_CTX_free(pctx);
218
219An B<RSA> key can be generated with key generation parameters:
220
221    unsigned int primes = 3;
222    unsigned int bits = 4096;
223    OSSL_PARAM params[3];
224    EVP_PKEY *pkey = NULL;
225    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
226
227    EVP_PKEY_keygen_init(pctx);
228
229    params[0] = OSSL_PARAM_construct_uint("bits", &bits);
230    params[1] = OSSL_PARAM_construct_uint("primes", &primes);
231    params[2] = OSSL_PARAM_construct_end();
232    EVP_PKEY_CTX_set_params(pctx, params);
233
234    EVP_PKEY_generate(pctx, &pkey);
235    EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
236    EVP_PKEY_CTX_free(pctx);
237
238=head1 SEE ALSO
239
240L<EVP_RSA_gen(3)>, L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>
241
242=head1 COPYRIGHT
243
244Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
245
246Licensed under the Apache License 2.0 (the "License").  You may not use
247this file except in compliance with the License.  You can obtain a copy
248in the file LICENSE in the source distribution or at
249L<https://www.openssl.org/source/license.html>.
250
251=cut
252