xref: /openssl/doc/man7/EVP_PKEY-RSA.pod (revision b6461792) 
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=item "rsa-derive-from-pq"  (B<OSSL_PKEY_PARAM_RSA_DERIVE_FROM_PQ>) <unsigned integer>
136
137Indicate that missing parameters not passed in the parameter list should be
138derived if not provided.  Setting a nonzero value will cause all
139needed exponents and coefficients to be derived if not available.  Setting this
140option requires at least OSSL_PARAM_RSA_FACTOR1, OSSL_PARAM_RSA_FACTOR2,
141and OSSL_PARAM_RSA_N to be provided.  This option is ignored if
142OSSL_KEYMGMT_SELECT_PRIVATE_KEY is not set in the selection parameter.
143
144=back
145
146=head2 RSA key generation parameters for FIPS module testing
147
148When generating RSA keys, the following additional key generation parameters may
149be used for algorithm testing purposes only. Do not use these to generate
150RSA keys for a production environment.
151
152=over 4
153
154=item "xp" (B<OSSL_PKEY_PARAM_RSA_TEST_XP>) <unsigned integer>
155
156=item "xq" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ>) <unsigned integer>
157
158These 2 fields are normally randomly generated and are used to generate "p" and
159"q".
160
161=item "xp1" (B<OSSL_PKEY_PARAM_RSA_TEST_XP1>) <unsigned integer>
162
163=item "xp2" (B<OSSL_PKEY_PARAM_RSA_TEST_XP2>) <unsigned integer>
164
165=item "xq1" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ1>) <unsigned integer>
166
167=item "xq2" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ2>) <unsigned integer>
168
169These 4 fields are normally randomly generated. The prime factors "p1", "p2",
170"q1" and "q2" are determined from these values.
171
172=back
173
174=head2 RSA key parameters for FIPS module testing
175
176The following intermediate values can be retrieved only if the values
177specified in L</"RSA key generation parameters for FIPS module testing"> are set.
178These should not be accessed in a production environment.
179
180=over 4
181
182=item "p1" (B<OSSL_PKEY_PARAM_RSA_TEST_P1>) <unsigned integer>
183
184=item "p2" (B<OSSL_PKEY_PARAM_RSA_TEST_P2>) <unsigned integer>
185
186=item "q1" (B<OSSL_PKEY_PARAM_RSA_TEST_Q1>) <unsigned integer>
187
188=item "q2" (B<OSSL_PKEY_PARAM_RSA_TEST_Q2>) <unsigned integer>
189
190The auxiliary probable primes.
191
192=back
193
194=head2 RSA key validation
195
196For RSA keys, L<EVP_PKEY_param_check(3)> and L<EVP_PKEY_param_check_quick(3)>
197both return 1 unconditionally.
198
199For RSA keys, L<EVP_PKEY_public_check(3)> conforms to the SP800-56Br1 I<public key
200check> when the OpenSSL FIPS provider is used. The OpenSSL default provider
201performs similar tests but relaxes the keysize restrictions for backwards
202compatibility.
203
204For RSA keys, L<EVP_PKEY_public_check_quick(3)> is the same as
205L<EVP_PKEY_public_check(3)>.
206
207For RSA keys, L<EVP_PKEY_private_check(3)> conforms to the SP800-56Br1
208I<private key test>.
209
210For RSA keys, L<EVP_PKEY_pairwise_check(3)> conforms to the
211SP800-56Br1 I<KeyPair Validation check> for the OpenSSL FIPS provider. The
212OpenSSL default provider allows testing of the validity of multi-primes.
213
214=head1 CONFORMING TO
215
216=over 4
217
218=item FIPS186-4
219
220Section B.3.6  Generation of Probable Primes with Conditions Based on
221Auxiliary Probable Primes
222
223=item RFC 8017, excluding RSA-PSS and RSA-OAEP
224
225=for comment RSA-PSS, and probably also RSA-OAEP, need separate keytypes,
226and will be described in separate pages for those RSA keytypes.
227
228=back
229
230=head1 EXAMPLES
231
232An B<EVP_PKEY> context can be obtained by calling:
233
234    EVP_PKEY_CTX *pctx =
235        EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
236
237An B<RSA> key can be generated simply like this:
238
239    pkey = EVP_RSA_gen(4096);
240
241or like this:
242
243    EVP_PKEY *pkey = NULL;
244    EVP_PKEY_CTX *pctx =
245        EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
246
247    EVP_PKEY_keygen_init(pctx);
248    EVP_PKEY_generate(pctx, &pkey);
249    EVP_PKEY_CTX_free(pctx);
250
251An B<RSA> key can be generated with key generation parameters:
252
253    unsigned int primes = 3;
254    unsigned int bits = 4096;
255    OSSL_PARAM params[3];
256    EVP_PKEY *pkey = NULL;
257    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
258
259    EVP_PKEY_keygen_init(pctx);
260
261    params[0] = OSSL_PARAM_construct_uint("bits", &bits);
262    params[1] = OSSL_PARAM_construct_uint("primes", &primes);
263    params[2] = OSSL_PARAM_construct_end();
264    EVP_PKEY_CTX_set_params(pctx, params);
265
266    EVP_PKEY_generate(pctx, &pkey);
267    EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
268    EVP_PKEY_CTX_free(pctx);
269
270=head1 SEE ALSO
271
272L<EVP_RSA_gen(3)>, L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>
273
274=head1 COPYRIGHT
275
276Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
277
278Licensed under the Apache License 2.0 (the "License").  You may not use
279this file except in compliance with the License.  You can obtain a copy
280in the file LICENSE in the source distribution or at
281L<https://www.openssl.org/source/license.html>.
282
283=cut
284