Debian Codegraph @

upstream/debian-unstable/man7/EVP_PKEY-RSA.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_PKEY-RSA 7SSL"
58 .TH EVP_PKEY-RSA 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_PKEY\-RSA, EVP_KEYMGMT\-RSA, RSA
65 \&\- EVP_PKEY RSA keytype and algorithm support
66 .SH DESCRIPTION
67 .IX Header "DESCRIPTION"
68 The \fBRSA\fR keytype is implemented in OpenSSL's default and FIPS providers.
69 That implementation supports the basic RSA keys, containing the modulus \fIn\fR,
70 the public exponent \fIe\fR, the private exponent \fId\fR, and a collection of prime
71 factors, exponents and coefficient for CRT calculations, of which the first
72 few are known as \fIp\fR and \fIq\fR, \fIdP\fR and \fIdQ\fR, and \fIqInv\fR.
73 .SS "Common RSA parameters"
74 .IX Subsection "Common RSA parameters"
75 In addition to the common parameters that all keytypes should support (see
76 "Common parameters" in \fBprovider\-keymgmt\fR\|(7)), the \fBRSA\fR keytype implementation
77 supports the following.
78 .IP """n"" (\fBOSSL_PKEY_PARAM_RSA_N\fR) <unsigned integer>" 4
79 .IX Item """n"" (OSSL_PKEY_PARAM_RSA_N) <unsigned integer>"
80 The RSA modulus "n" value.
81 .IP """e"" (\fBOSSL_PKEY_PARAM_RSA_E\fR) <unsigned integer>" 4
82 .IX Item """e"" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer>"
83 The RSA public exponent "e" value.
84 This value must always be set when creating a raw key using \fBEVP_PKEY_fromdata\fR\|(3).
85 Note that when a decryption operation is performed, that this value is used for
86 blinding purposes to prevent timing attacks.
87 .IP """d"" (\fBOSSL_PKEY_PARAM_RSA_D\fR) <unsigned integer>" 4
88 .IX Item """d"" (OSSL_PKEY_PARAM_RSA_D) <unsigned integer>"
89 The RSA private exponent "d" value.
90 .IP """rsa\-factor1"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR1\fR) <unsigned integer>" 4
91 .IX Item """rsa-factor1"" (OSSL_PKEY_PARAM_RSA_FACTOR1) <unsigned integer>"
92 .PD 0
93 .IP """rsa\-factor2"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR2\fR) <unsigned integer>" 4
94 .IX Item """rsa-factor2"" (OSSL_PKEY_PARAM_RSA_FACTOR2) <unsigned integer>"
95 .IP """rsa\-factor3"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR3\fR) <unsigned integer>" 4
96 .IX Item """rsa-factor3"" (OSSL_PKEY_PARAM_RSA_FACTOR3) <unsigned integer>"
97 .IP """rsa\-factor4"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR4\fR) <unsigned integer>" 4
98 .IX Item """rsa-factor4"" (OSSL_PKEY_PARAM_RSA_FACTOR4) <unsigned integer>"
99 .IP """rsa\-factor5"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR5\fR) <unsigned integer>" 4
100 .IX Item """rsa-factor5"" (OSSL_PKEY_PARAM_RSA_FACTOR5) <unsigned integer>"
101 .IP """rsa\-factor6"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR6\fR) <unsigned integer>" 4
102 .IX Item """rsa-factor6"" (OSSL_PKEY_PARAM_RSA_FACTOR6) <unsigned integer>"
103 .IP """rsa\-factor7"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR7\fR) <unsigned integer>" 4
104 .IX Item """rsa-factor7"" (OSSL_PKEY_PARAM_RSA_FACTOR7) <unsigned integer>"
105 .IP """rsa\-factor8"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR8\fR) <unsigned integer>" 4
106 .IX Item """rsa-factor8"" (OSSL_PKEY_PARAM_RSA_FACTOR8) <unsigned integer>"
107 .IP """rsa\-factor9"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR9\fR) <unsigned integer>" 4
108 .IX Item """rsa-factor9"" (OSSL_PKEY_PARAM_RSA_FACTOR9) <unsigned integer>"
109 .IP """rsa\-factor10"" (\fBOSSL_PKEY_PARAM_RSA_FACTOR10\fR) <unsigned integer>" 4
110 .IX Item """rsa-factor10"" (OSSL_PKEY_PARAM_RSA_FACTOR10) <unsigned integer>"
111 .PD
112 RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017.
113 Up to eight additional "r_i" prime factors are supported.
114 .IP """rsa\-exponent1"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT1\fR) <unsigned integer>" 4
115 .IX Item """rsa-exponent1"" (OSSL_PKEY_PARAM_RSA_EXPONENT1) <unsigned integer>"
116 .PD 0
117 .IP """rsa\-exponent2"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT2\fR) <unsigned integer>" 4
118 .IX Item """rsa-exponent2"" (OSSL_PKEY_PARAM_RSA_EXPONENT2) <unsigned integer>"
119 .IP """rsa\-exponent3"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT3\fR) <unsigned integer>" 4
120 .IX Item """rsa-exponent3"" (OSSL_PKEY_PARAM_RSA_EXPONENT3) <unsigned integer>"
121 .IP """rsa\-exponent4"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT4\fR) <unsigned integer>" 4
122 .IX Item """rsa-exponent4"" (OSSL_PKEY_PARAM_RSA_EXPONENT4) <unsigned integer>"
123 .IP """rsa\-exponent5"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT5\fR) <unsigned integer>" 4
124 .IX Item """rsa-exponent5"" (OSSL_PKEY_PARAM_RSA_EXPONENT5) <unsigned integer>"
125 .IP """rsa\-exponent6"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT6\fR) <unsigned integer>" 4
126 .IX Item """rsa-exponent6"" (OSSL_PKEY_PARAM_RSA_EXPONENT6) <unsigned integer>"
127 .IP """rsa\-exponent7"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT7\fR) <unsigned integer>" 4
128 .IX Item """rsa-exponent7"" (OSSL_PKEY_PARAM_RSA_EXPONENT7) <unsigned integer>"
129 .IP """rsa\-exponent8"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT8\fR) <unsigned integer>" 4
130 .IX Item """rsa-exponent8"" (OSSL_PKEY_PARAM_RSA_EXPONENT8) <unsigned integer>"
131 .IP """rsa\-exponent9"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT9\fR) <unsigned integer>" 4
132 .IX Item """rsa-exponent9"" (OSSL_PKEY_PARAM_RSA_EXPONENT9) <unsigned integer>"
133 .IP """rsa\-exponent10"" (\fBOSSL_PKEY_PARAM_RSA_EXPONENT10\fR) <unsigned integer>" 4
134 .IX Item """rsa-exponent10"" (OSSL_PKEY_PARAM_RSA_EXPONENT10) <unsigned integer>"
135 .PD
136 RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known
137 as "dP", "dQ" and "d_i" in RFC8017.
138 Up to eight additional "d_i" exponents are supported.
139 .IP """rsa\-coefficient1"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT1\fR) <unsigned integer>" 4
140 .IX Item """rsa-coefficient1"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT1) <unsigned integer>"
141 .PD 0
142 .IP """rsa\-coefficient2"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT2\fR) <unsigned integer>" 4
143 .IX Item """rsa-coefficient2"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT2) <unsigned integer>"
144 .IP """rsa\-coefficient3"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT3\fR) <unsigned integer>" 4
145 .IX Item """rsa-coefficient3"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT3) <unsigned integer>"
146 .IP """rsa\-coefficient4"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT4\fR) <unsigned integer>" 4
147 .IX Item """rsa-coefficient4"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT4) <unsigned integer>"
148 .IP """rsa\-coefficient5"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT5\fR) <unsigned integer>" 4
149 .IX Item """rsa-coefficient5"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT5) <unsigned integer>"
150 .IP """rsa\-coefficient6"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT6\fR) <unsigned integer>" 4
151 .IX Item """rsa-coefficient6"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT6) <unsigned integer>"
152 .IP """rsa\-coefficient7"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT7\fR) <unsigned integer>" 4
153 .IX Item """rsa-coefficient7"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT7) <unsigned integer>"
154 .IP """rsa\-coefficient8"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT8\fR) <unsigned integer>" 4
155 .IX Item """rsa-coefficient8"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT8) <unsigned integer>"
156 .IP """rsa\-coefficient9"" (\fBOSSL_PKEY_PARAM_RSA_COEFFICIENT9\fR) <unsigned integer>" 4
157 .IX Item """rsa-coefficient9"" (OSSL_PKEY_PARAM_RSA_COEFFICIENT9) <unsigned integer>"
158 .PD
159 RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as
160 "qInv" and "t_i".
161 Up to eight additional "t_i" exponents are supported.
162 .SS "RSA key generation parameters"
163 .IX Subsection "RSA key generation parameters"
164 When generating RSA keys, the following key generation parameters may be used.
165 .IP """bits"" (\fBOSSL_PKEY_PARAM_RSA_BITS\fR) <unsigned integer>" 4
166 .IX Item """bits"" (OSSL_PKEY_PARAM_RSA_BITS) <unsigned integer>"
167 The value should be the cryptographic length for the \fBRSA\fR cryptosystem, in
168 bits.
169 .IP """primes"" (\fBOSSL_PKEY_PARAM_RSA_PRIMES\fR) <unsigned integer>" 4
170 .IX Item """primes"" (OSSL_PKEY_PARAM_RSA_PRIMES) <unsigned integer>"
171 The value should be the number of primes for the generated \fBRSA\fR key. The
172 default is 2. It isn't permitted to specify a larger number of primes than
173 10. Additionally, the number of primes is limited by the length of the key
174 being generated so the maximum number could be less.
175 Some providers may only support a value of 2.
176 .IP """e"" (\fBOSSL_PKEY_PARAM_RSA_E\fR) <unsigned integer>" 4
177 .IX Item """e"" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer>"
178 The RSA "e" value. The value may be any odd number greater than or equal to
179 65537. The default value is 65537.
180 For legacy reasons a value of 3 is currently accepted but is deprecated.
181 .IP """rsa-derive-from-pq"" (\fBOSSL_PKEY_PARAM_RSA_DERIVE_FROM_PQ\fR) <unsigned integer>" 4
182 .IX Item """rsa-derive-from-pq"" (OSSL_PKEY_PARAM_RSA_DERIVE_FROM_PQ) <unsigned integer>"
183 Indicate that missing parameters not passed in the parameter list should be
184 derived if not provided. Setting a nonzero value will cause all
185 needed exponents and coefficients to be derived if not available. Setting this
186 option requires at least OSSL_PARAM_RSA_FACTOR1, OSSL_PARAM_RSA_FACTOR2,
187 and OSSL_PARAM_RSA_N to be provided. This option is ignored if
188 OSSL_KEYMGMT_SELECT_PRIVATE_KEY is not set in the selection parameter.
189 .SS "RSA key generation parameters for FIPS module testing"
190 .IX Subsection "RSA key generation parameters for FIPS module testing"
191 When generating RSA keys, the following additional key generation parameters may
192 be used for algorithm testing purposes only. Do not use these to generate
193 RSA keys for a production environment.
194 .IP """xp"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XP\fR) <unsigned integer>" 4
195 .IX Item """xp"" (OSSL_PKEY_PARAM_RSA_TEST_XP) <unsigned integer>"
196 .PD 0
197 .IP """xq"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XQ\fR) <unsigned integer>" 4
198 .IX Item """xq"" (OSSL_PKEY_PARAM_RSA_TEST_XQ) <unsigned integer>"
199 .PD
200 These 2 fields are normally randomly generated and are used to generate "p" and
201 "q".
202 .IP """xp1"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XP1\fR) <unsigned integer>" 4
203 .IX Item """xp1"" (OSSL_PKEY_PARAM_RSA_TEST_XP1) <unsigned integer>"
204 .PD 0
205 .IP """xp2"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XP2\fR) <unsigned integer>" 4
206 .IX Item """xp2"" (OSSL_PKEY_PARAM_RSA_TEST_XP2) <unsigned integer>"
207 .IP """xq1"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XQ1\fR) <unsigned integer>" 4
208 .IX Item """xq1"" (OSSL_PKEY_PARAM_RSA_TEST_XQ1) <unsigned integer>"
209 .IP """xq2"" (\fBOSSL_PKEY_PARAM_RSA_TEST_XQ2\fR) <unsigned integer>" 4
210 .IX Item """xq2"" (OSSL_PKEY_PARAM_RSA_TEST_XQ2) <unsigned integer>"
211 .PD
212 These 4 fields are normally randomly generated. The prime factors "p1", "p2",
213 "q1" and "q2" are determined from these values.
214 .SS "RSA key parameters for FIPS module testing"
215 .IX Subsection "RSA key parameters for FIPS module testing"
216 The following intermediate values can be retrieved only if the values
217 specified in "RSA key generation parameters for FIPS module testing" are set.
218 These should not be accessed in a production environment.
219 .IP """p1"" (\fBOSSL_PKEY_PARAM_RSA_TEST_P1\fR) <unsigned integer>" 4
220 .IX Item """p1"" (OSSL_PKEY_PARAM_RSA_TEST_P1) <unsigned integer>"
221 .PD 0
222 .IP """p2"" (\fBOSSL_PKEY_PARAM_RSA_TEST_P2\fR) <unsigned integer>" 4
223 .IX Item """p2"" (OSSL_PKEY_PARAM_RSA_TEST_P2) <unsigned integer>"
224 .IP """q1"" (\fBOSSL_PKEY_PARAM_RSA_TEST_Q1\fR) <unsigned integer>" 4
225 .IX Item """q1"" (OSSL_PKEY_PARAM_RSA_TEST_Q1) <unsigned integer>"
226 .IP """q2"" (\fBOSSL_PKEY_PARAM_RSA_TEST_Q2\fR) <unsigned integer>" 4
227 .IX Item """q2"" (OSSL_PKEY_PARAM_RSA_TEST_Q2) <unsigned integer>"
228 .PD
229 The auxiliary probable primes.
230 .SS "RSA key validation"
231 .IX Subsection "RSA key validation"
232 For RSA keys, \fBEVP_PKEY_param_check\fR\|(3) and \fBEVP_PKEY_param_check_quick\fR\|(3)
233 both return 1 unconditionally.
234 .PP
235 For RSA keys, \fBEVP_PKEY_public_check\fR\|(3) conforms to the SP800\-56Br1 \fIpublic key
236 check\fR when the OpenSSL FIPS provider is used. The OpenSSL default provider
237 performs similar tests but relaxes the keysize restrictions for backwards
238 compatibility.
239 .PP
240 For RSA keys, \fBEVP_PKEY_public_check_quick\fR\|(3) is the same as
241 \&\fBEVP_PKEY_public_check\fR\|(3).
242 .PP
243 For RSA keys, \fBEVP_PKEY_private_check\fR\|(3) conforms to the SP800\-56Br1
244 \&\fIprivate key test\fR.
245 .PP
246 For RSA keys, \fBEVP_PKEY_pairwise_check\fR\|(3) conforms to the
247 SP800\-56Br1 \fIKeyPair Validation check\fR for the OpenSSL FIPS provider. The
248 OpenSSL default provider allows testing of the validity of multi-primes.
249 .SH "CONFORMING TO"
250 .IX Header "CONFORMING TO"
251 .IP FIPS186\-4 4
252 .IX Item "FIPS186-4"
253 Section B.3.6 Generation of Probable Primes with Conditions Based on
254 Auxiliary Probable Primes
255 .IP "RFC 8017, excluding RSA-PSS and RSA-OAEP" 4
256 .IX Item "RFC 8017, excluding RSA-PSS and RSA-OAEP"
257 .SH EXAMPLES
258 .IX Header "EXAMPLES"
259 An \fBEVP_PKEY\fR context can be obtained by calling:
260 .PP
261 .Vb 2
262 \& EVP_PKEY_CTX *pctx =
263 \& EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
264 .Ve
265 .PP
266 An \fBRSA\fR key can be generated simply like this:
267 .PP
268 .Vb 1
269 \& pkey = EVP_RSA_gen(4096);
270 .Ve
271 .PP
272 or like this:
273 .PP
274 .Vb 3
275 \& EVP_PKEY *pkey = NULL;
276 \& EVP_PKEY_CTX *pctx =
277 \& EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
278 \&
279 \& EVP_PKEY_keygen_init(pctx);
280 \& EVP_PKEY_generate(pctx, &pkey);
281 \& EVP_PKEY_CTX_free(pctx);
282 .Ve
283 .PP
284 An \fBRSA\fR key can be generated with key generation parameters:
285 .PP
286 .Vb 5
287 \& unsigned int primes = 3;
288 \& unsigned int bits = 4096;
289 \& OSSL_PARAM params[3];
290 \& EVP_PKEY *pkey = NULL;
291 \& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
292 \&
293 \& EVP_PKEY_keygen_init(pctx);
294 \&
295 \& params[0] = OSSL_PARAM_construct_uint("bits", &bits);
296 \& params[1] = OSSL_PARAM_construct_uint("primes", &primes);
297 \& params[2] = OSSL_PARAM_construct_end();
298 \& EVP_PKEY_CTX_set_params(pctx, params);
299 \&
300 \& EVP_PKEY_generate(pctx, &pkey);
301 \& EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
302 \& EVP_PKEY_CTX_free(pctx);
303 .Ve
304 .SH "SEE ALSO"
305 .IX Header "SEE ALSO"
306 \&\fBEVP_RSA_gen\fR\|(3), \fBEVP_KEYMGMT\fR\|(3), \fBEVP_PKEY\fR\|(3), \fBprovider\-keymgmt\fR\|(7)
307 .SH COPYRIGHT
308 .IX Header "COPYRIGHT"
309 Copyright 2020\-2024 The OpenSSL Project Authors. All Rights Reserved.
310 .PP
311 Licensed under the Apache License 2.0 (the "License"). You may not use
312 this file except in compliance with the License. You can obtain a copy
313 in the file LICENSE in the source distribution or at
314 <https://www.openssl.org/source/license.html>.