1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
|
=pod
=head1 NAME
EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA
- EVP_PKEY RSA keytype and algorithm support
=head1 DESCRIPTION
The B<RSA> keytype is implemented in OpenSSL's default and FIPS providers.
That implementation supports the basic RSA keys, containing the modulus I<n>,
the public exponent I<e>, the private exponent I<d>, and a collection of prime
factors, exponents and coefficient for CRT calculations, of which the first
few are known as I<p> and I<q>, I<dP> and I<dQ>, and I<qInv>.
=head2 Common RSA parameters
In addition to the common parameters that all keytypes should support (see
L<provider-keymgmt(7)/Common parameters>), the B<RSA> keytype implementation
supports the following.
=over 4
=item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <unsigned integer>
The RSA "n" value.
=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
The RSA "e" value.
=item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <unsigned integer>
The RSA "d" value.
=item "rsa-factor1" (B<OSSL_PKEY_PARAM_RSA_FACTOR1>) <unsigned integer>
=item "rsa-factor2" (B<OSSL_PKEY_PARAM_RSA_FACTOR2>) <unsigned integer>
=item "rsa-factor3" (B<OSSL_PKEY_PARAM_RSA_FACTOR3>) <unsigned integer>
=item "rsa-factor4" (B<OSSL_PKEY_PARAM_RSA_FACTOR4>) <unsigned integer>
=item "rsa-factor5" (B<OSSL_PKEY_PARAM_RSA_FACTOR5>) <unsigned integer>
=item "rsa-factor6" (B<OSSL_PKEY_PARAM_RSA_FACTOR6>) <unsigned integer>
=item "rsa-factor7" (B<OSSL_PKEY_PARAM_RSA_FACTOR7>) <unsigned integer>
=item "rsa-factor8" (B<OSSL_PKEY_PARAM_RSA_FACTOR8>) <unsigned integer>
=item "rsa-factor9" (B<OSSL_PKEY_PARAM_RSA_FACTOR9>) <unsigned integer>
=item "rsa-factor10" (B<OSSL_PKEY_PARAM_RSA_FACTOR10>) <unsigned integer>
RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017.
Up to eight additional "r_i" prime factors are supported.
=item "rsa-exponent1" (B<OSSL_PKEY_PARAM_RSA_EXPONENT1>) <unsigned integer>
=item "rsa-exponent2" (B<OSSL_PKEY_PARAM_RSA_EXPONENT2>) <unsigned integer>
=item "rsa-exponent3" (B<OSSL_PKEY_PARAM_RSA_EXPONENT3>) <unsigned integer>
=item "rsa-exponent4" (B<OSSL_PKEY_PARAM_RSA_EXPONENT4>) <unsigned integer>
=item "rsa-exponent5" (B<OSSL_PKEY_PARAM_RSA_EXPONENT5>) <unsigned integer>
=item "rsa-exponent6" (B<OSSL_PKEY_PARAM_RSA_EXPONENT6>) <unsigned integer>
=item "rsa-exponent7" (B<OSSL_PKEY_PARAM_RSA_EXPONENT7>) <unsigned integer>
=item "rsa-exponent8" (B<OSSL_PKEY_PARAM_RSA_EXPONENT8>) <unsigned integer>
=item "rsa-exponent9" (B<OSSL_PKEY_PARAM_RSA_EXPONENT9>) <unsigned integer>
=item "rsa-exponent10" (B<OSSL_PKEY_PARAM_RSA_EXPONENT10>) <unsigned integer>
RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known
as "dP", "dQ" and "d_i in RFC8017".
Up to eight additional "d_i" exponents are supported.
=item "rsa-coefficient1" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT1>) <unsigned integer>
=item "rsa-coefficient2" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT2>) <unsigned integer>
=item "rsa-coefficient3" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT3>) <unsigned integer>
=item "rsa-coefficient4" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT4>) <unsigned integer>
=item "rsa-coefficient5" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT5>) <unsigned integer>
=item "rsa-coefficient6" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT6>) <unsigned integer>
=item "rsa-coefficient7" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT7>) <unsigned integer>
=item "rsa-coefficient8" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT8>) <unsigned integer>
=item "rsa-coefficient9" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT9>) <unsigned integer>
RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as
"qInv" and "t_i".
Up to eight additional "t_i" exponents are supported.
=back
=head2 RSA key generation parameters
When generating RSA keys, the following key generation parameters may be used.
=over 4
=item "bits" (B<OSSL_PKEY_PARAM_RSA_BITS>) <unsigned integer>
The value should be the cryptographic length for the B<RSA> cryptosystem, in
bits.
=item "primes" (B<OSSL_PKEY_PARAM_RSA_PRIMES>) <unsigned integer>
The value should be the number of primes for the generated B<RSA> key. The
default is 2. It isn't permitted to specify a larger number of primes than
10. Additionally, the number of primes is limited by the length of the key
being generated so the maximum number could be less.
Some providers may only support a value of 2.
=item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
The RSA "e" value. The value may be any odd number greater than or equal to
65537. The default value is 65537.
For legacy reasons a value of 3 is currently accepted but is deprecated.
=back
=head2 RSA key generation parameters for FIPS module testing
When generating RSA keys, the following additional key generation parameters may
be used for algorithm testing purposes only. Do not use these to generate
RSA keys for a production environment.
=over 4
=item "xp" (B<OSSL_PKEY_PARAM_RSA_TEST_XP>) <unsigned integer>
=item "xq" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ>) <unsigned integer>
These 2 fields are normally randomly generated and are used to generate "p" and
"q".
=item "xp1" (B<OSSL_PKEY_PARAM_RSA_TEST_XP1>) <unsigned integer>
=item "xp2" (B<OSSL_PKEY_PARAM_RSA_TEST_XP2>) <unsigned integer>
=item "xq1" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ1>) <unsigned integer>
=item "xq2" (B<OSSL_PKEY_PARAM_RSA_TEST_XQ2>) <unsigned integer>
These 4 fields are normally randomly generated. The prime factors "p1", "p2",
"q1" and "q2" are determined from these values.
=back
=head2 RSA key parameters for FIPS module testing
The following intermediate values can be retrieved only if the values
specified in L</"RSA key generation parameters for FIPS module testing"> are set.
These should not be accessed in a production environment.
=over 4
=item "p1" (B<OSSL_PKEY_PARAM_RSA_TEST_P1>) <unsigned integer>
=item "p2" (B<OSSL_PKEY_PARAM_RSA_TEST_P2>) <unsigned integer>
=item "q1" (B<OSSL_PKEY_PARAM_RSA_TEST_Q1>) <unsigned integer>
=item "q2" (B<OSSL_PKEY_PARAM_RSA_TEST_Q2>) <unsigned integer>
The auxiliary probable primes.
=back
=head1 CONFORMING TO
=over 4
=item FIPS186-4
Section B.3.6 Generation of Probable Primes with Conditions Based on
Auxiliary Probable Primes
=item RFC 8017, excluding RSA-PSS and RSA-OAEP
=for comment RSA-PSS, and probably also RSA-OAEP, need separate keytypes,
and will be described in separate pages for those RSA keytypes.
=back
=head1 EXAMPLES
An B<EVP_PKEY> context can be obtained by calling:
EVP_PKEY_CTX *pctx =
EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
An B<RSA> key can be generated simply like this:
pkey = EVP_RSA_gen(4096);
or like this:
EVP_PKEY *pkey = NULL;
EVP_PKEY_CTX *pctx =
EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
EVP_PKEY_keygen_init(pctx);
EVP_PKEY_generate(pctx, &pkey);
EVP_PKEY_CTX_free(pctx);
An B<RSA> key can be generated with key generation parameters:
unsigned int primes = 3;
unsigned int bits = 4096;
OSSL_PARAM params[3];
EVP_PKEY *pkey = NULL;
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
EVP_PKEY_keygen_init(pctx);
params[0] = OSSL_PARAM_construct_uint("bits", &bits);
params[1] = OSSL_PARAM_construct_uint("primes", &primes);
params[2] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(pctx, params);
EVP_PKEY_generate(pctx, &pkey);
EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
EVP_PKEY_CTX_free(pctx);
=head1 SEE ALSO
L<EVP_RSA_gen(3)>, L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>
=head1 COPYRIGHT
Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
|