• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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=head2 RSA key validation
183
184For RSA keys, L<EVP_PKEY_param_check(3)> and L<EVP_PKEY_param_check_quick(3)>
185both return 1 unconditionally.
186
187For RSA keys, L<EVP_PKEY_public_check(3)> conforms to the SP800-56Br1 I<public key
188check> when the OpenSSL FIPS provider is used. The OpenSSL default provider
189performs similiar tests but relaxes the keysize restrictions for backwards
190compatibility.
191
192For RSA keys, L<EVP_PKEY_public_check_quick(3)> is the same as
193L<EVP_PKEY_public_check(3)>.
194
195For RSA keys, L<EVP_PKEY_private_check(3)> conforms to the SP800-56Br1
196I<private key test>.
197
198For RSA keys, L<EVP_PKEY_pairwise_check(3)> conforms to the
199SP800-56Br1 I<KeyPair Validation check> for the OpenSSL FIPS provider. The
200OpenSSL default provider allows testing of the validity of multi-primes.
201
202=head1 CONFORMING TO
203
204=over 4
205
206=item FIPS186-4
207
208Section B.3.6  Generation of Probable Primes with Conditions Based on
209Auxiliary Probable Primes
210
211=item RFC 8017, excluding RSA-PSS and RSA-OAEP
212
213=for comment RSA-PSS, and probably also RSA-OAEP, need separate keytypes,
214and will be described in separate pages for those RSA keytypes.
215
216=back
217
218=head1 EXAMPLES
219
220An B<EVP_PKEY> context can be obtained by calling:
221
222    EVP_PKEY_CTX *pctx =
223        EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
224
225An B<RSA> key can be generated simply like this:
226
227    pkey = EVP_RSA_gen(4096);
228
229or like this:
230
231    EVP_PKEY *pkey = NULL;
232    EVP_PKEY_CTX *pctx =
233        EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
234
235    EVP_PKEY_keygen_init(pctx);
236    EVP_PKEY_generate(pctx, &pkey);
237    EVP_PKEY_CTX_free(pctx);
238
239An B<RSA> key can be generated with key generation parameters:
240
241    unsigned int primes = 3;
242    unsigned int bits = 4096;
243    OSSL_PARAM params[3];
244    EVP_PKEY *pkey = NULL;
245    EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
246
247    EVP_PKEY_keygen_init(pctx);
248
249    params[0] = OSSL_PARAM_construct_uint("bits", &bits);
250    params[1] = OSSL_PARAM_construct_uint("primes", &primes);
251    params[2] = OSSL_PARAM_construct_end();
252    EVP_PKEY_CTX_set_params(pctx, params);
253
254    EVP_PKEY_generate(pctx, &pkey);
255    EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
256    EVP_PKEY_CTX_free(pctx);
257
258=head1 SEE ALSO
259
260L<EVP_RSA_gen(3)>, L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>
261
262=head1 COPYRIGHT
263
264Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
265
266Licensed under the Apache License 2.0 (the "License").  You may not use
267this file except in compliance with the License.  You can obtain a copy
268in the file LICENSE in the source distribution or at
269L<https://www.openssl.org/source/license.html>.
270
271=cut
272