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