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