1EVP_PKEY-RSA(7ossl)                 OpenSSL                EVP_PKEY-RSA(7ossl)
2
3
4

NAME

6       EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA - EVP_PKEY RSA keytype and algorithm
7       support
8

DESCRIPTION

10       The RSA keytype is implemented in OpenSSL's default and FIPS providers.
11       That implementation supports the basic RSA keys, containing the modulus
12       n, the public exponent e, the private exponent d, and a collection of
13       prime factors, exponents and coefficient for CRT calculations, of which
14       the first few are known as p and q, dP and dQ, and qInv.
15
16   Common RSA parameters
17       In addition to the common parameters that all keytypes should support
18       (see "Common parameters" in provider-keymgmt(7)), the RSA keytype
19       implementation supports the following.
20
21       "n" (OSSL_PKEY_PARAM_RSA_N) <unsigned integer>
22           The RSA modulus "n" value.
23
24       "e" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer>
25           The RSA public exponent "e" value.  This value must always be set
26           when creating a raw key using EVP_PKEY_fromdata(3).  Note that when
27           a decryption operation is performed, that this value is used for
28           blinding purposes to prevent timing attacks.
29
30       "d" (OSSL_PKEY_PARAM_RSA_D) <unsigned integer>
31           The RSA private exponent "d" value.
32
33       "rsa-factor1" (OSSL_PKEY_PARAM_RSA_FACTOR1) <unsigned integer>
34       "rsa-factor2" (OSSL_PKEY_PARAM_RSA_FACTOR2) <unsigned integer>
35       "rsa-factor3" (OSSL_PKEY_PARAM_RSA_FACTOR3) <unsigned integer>
36       "rsa-factor4" (OSSL_PKEY_PARAM_RSA_FACTOR4) <unsigned integer>
37       "rsa-factor5" (OSSL_PKEY_PARAM_RSA_FACTOR5) <unsigned integer>
38       "rsa-factor6" (OSSL_PKEY_PARAM_RSA_FACTOR6) <unsigned integer>
39       "rsa-factor7" (OSSL_PKEY_PARAM_RSA_FACTOR7) <unsigned integer>
40       "rsa-factor8" (OSSL_PKEY_PARAM_RSA_FACTOR8) <unsigned integer>
41       "rsa-factor9" (OSSL_PKEY_PARAM_RSA_FACTOR9) <unsigned integer>
42       "rsa-factor10" (OSSL_PKEY_PARAM_RSA_FACTOR10) <unsigned integer>
43           RSA prime factors. The factors are known as "p", "q" and "r_i" in
44           RFC8017.  Up to eight additional "r_i" prime factors are supported.
45
46       "rsa-exponent1" (OSSL_PKEY_PARAM_RSA_EXPONENT1) <unsigned integer>
47       "rsa-exponent2" (OSSL_PKEY_PARAM_RSA_EXPONENT2) <unsigned integer>
48       "rsa-exponent3" (OSSL_PKEY_PARAM_RSA_EXPONENT3) <unsigned integer>
49       "rsa-exponent4" (OSSL_PKEY_PARAM_RSA_EXPONENT4) <unsigned integer>
50       "rsa-exponent5" (OSSL_PKEY_PARAM_RSA_EXPONENT5) <unsigned integer>
51       "rsa-exponent6" (OSSL_PKEY_PARAM_RSA_EXPONENT6) <unsigned integer>
52       "rsa-exponent7" (OSSL_PKEY_PARAM_RSA_EXPONENT7) <unsigned integer>
53       "rsa-exponent8" (OSSL_PKEY_PARAM_RSA_EXPONENT8) <unsigned integer>
54       "rsa-exponent9" (OSSL_PKEY_PARAM_RSA_EXPONENT9) <unsigned integer>
55       "rsa-exponent10" (OSSL_PKEY_PARAM_RSA_EXPONENT10) <unsigned integer>
56           RSA CRT (Chinese Remainder Theorem) exponents. The exponents are
57           known as "dP", "dQ" and "d_i in RFC8017".  Up to eight additional
58           "d_i" exponents are supported.
59
60       "rsa-coefficient1" (OSSL_PKEY_PARAM_RSA_COEFFICIENT1) <unsigned
61       integer>
62       "rsa-coefficient2" (OSSL_PKEY_PARAM_RSA_COEFFICIENT2) <unsigned
63       integer>
64       "rsa-coefficient3" (OSSL_PKEY_PARAM_RSA_COEFFICIENT3) <unsigned
65       integer>
66       "rsa-coefficient4" (OSSL_PKEY_PARAM_RSA_COEFFICIENT4) <unsigned
67       integer>
68       "rsa-coefficient5" (OSSL_PKEY_PARAM_RSA_COEFFICIENT5) <unsigned
69       integer>
70       "rsa-coefficient6" (OSSL_PKEY_PARAM_RSA_COEFFICIENT6) <unsigned
71       integer>
72       "rsa-coefficient7" (OSSL_PKEY_PARAM_RSA_COEFFICIENT7) <unsigned
73       integer>
74       "rsa-coefficient8" (OSSL_PKEY_PARAM_RSA_COEFFICIENT8) <unsigned
75       integer>
76       "rsa-coefficient9" (OSSL_PKEY_PARAM_RSA_COEFFICIENT9) <unsigned
77       integer>
78           RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients
79           are known as "qInv" and "t_i".  Up to eight additional "t_i"
80           exponents are supported.
81
82   RSA key generation parameters
83       When generating RSA keys, the following key generation parameters may
84       be used.
85
86       "bits" (OSSL_PKEY_PARAM_RSA_BITS) <unsigned integer>
87           The value should be the cryptographic length for the RSA
88           cryptosystem, in bits.
89
90       "primes" (OSSL_PKEY_PARAM_RSA_PRIMES) <unsigned integer>
91           The value should be the number of primes for the generated RSA key.
92           The default is 2.  It isn't permitted to specify a larger number of
93           primes than 10.  Additionally, the number of primes is limited by
94           the length of the key being generated so the maximum number could
95           be less.  Some providers may only support a value of 2.
96
97       "e" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer>
98           The RSA "e" value. The value may be any odd number greater than or
99           equal to 65537. The default value is 65537.  For legacy reasons a
100           value of 3 is currently accepted but is deprecated.
101
102   RSA key generation parameters for FIPS module testing
103       When generating RSA keys, the following additional key generation
104       parameters may be used for algorithm testing purposes only. Do not use
105       these to generate RSA keys for a production environment.
106
107       "xp" (OSSL_PKEY_PARAM_RSA_TEST_XP) <unsigned integer>
108       "xq" (OSSL_PKEY_PARAM_RSA_TEST_XQ) <unsigned integer>
109           These 2 fields are normally randomly generated and are used to
110           generate "p" and "q".
111
112       "xp1" (OSSL_PKEY_PARAM_RSA_TEST_XP1) <unsigned integer>
113       "xp2" (OSSL_PKEY_PARAM_RSA_TEST_XP2) <unsigned integer>
114       "xq1" (OSSL_PKEY_PARAM_RSA_TEST_XQ1) <unsigned integer>
115       "xq2" (OSSL_PKEY_PARAM_RSA_TEST_XQ2) <unsigned integer>
116           These 4 fields are normally randomly generated. The prime factors
117           "p1", "p2", "q1" and "q2" are determined from these values.
118
119   RSA key parameters for FIPS module testing
120       The following intermediate values can be retrieved only if the values
121       specified in "RSA key generation parameters for FIPS module testing"
122       are set.  These should not be accessed in a production environment.
123
124       "p1" (OSSL_PKEY_PARAM_RSA_TEST_P1) <unsigned integer>
125       "p2" (OSSL_PKEY_PARAM_RSA_TEST_P2) <unsigned integer>
126       "q1" (OSSL_PKEY_PARAM_RSA_TEST_Q1) <unsigned integer>
127       "q2" (OSSL_PKEY_PARAM_RSA_TEST_Q2) <unsigned integer>
128           The auxiliary probable primes.
129
130   RSA key validation
131       For RSA keys, EVP_PKEY_param_check(3) and EVP_PKEY_param_check_quick(3)
132       both return 1 unconditionally.
133
134       For RSA keys, EVP_PKEY_public_check(3) conforms to the SP800-56Br1
135       public key check when the OpenSSL FIPS provider is used. The OpenSSL
136       default provider performs similiar tests but relaxes the keysize
137       restrictions for backwards compatibility.
138
139       For RSA keys, EVP_PKEY_public_check_quick(3) is the same as
140       EVP_PKEY_public_check(3).
141
142       For RSA keys, EVP_PKEY_private_check(3) conforms to the SP800-56Br1
143       private key test.
144
145       For RSA keys, EVP_PKEY_pairwise_check(3) conforms to the SP800-56Br1
146       KeyPair Validation check for the OpenSSL FIPS provider. The OpenSSL
147       default provider allows testing of the validity of multi-primes.
148

CONFORMING TO

150       FIPS186-4
151           Section B.3.6  Generation of Probable Primes with Conditions Based
152           on Auxiliary Probable Primes
153
154       RFC 8017, excluding RSA-PSS and RSA-OAEP
155

EXAMPLES

157       An EVP_PKEY context can be obtained by calling:
158
159           EVP_PKEY_CTX *pctx =
160               EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
161
162       An RSA key can be generated simply like this:
163
164           pkey = EVP_RSA_gen(4096);
165
166       or like this:
167
168           EVP_PKEY *pkey = NULL;
169           EVP_PKEY_CTX *pctx =
170               EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
171
172           EVP_PKEY_keygen_init(pctx);
173           EVP_PKEY_generate(pctx, &pkey);
174           EVP_PKEY_CTX_free(pctx);
175
176       An RSA key can be generated with key generation parameters:
177
178           unsigned int primes = 3;
179           unsigned int bits = 4096;
180           OSSL_PARAM params[3];
181           EVP_PKEY *pkey = NULL;
182           EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
183
184           EVP_PKEY_keygen_init(pctx);
185
186           params[0] = OSSL_PARAM_construct_uint("bits", &bits);
187           params[1] = OSSL_PARAM_construct_uint("primes", &primes);
188           params[2] = OSSL_PARAM_construct_end();
189           EVP_PKEY_CTX_set_params(pctx, params);
190
191           EVP_PKEY_generate(pctx, &pkey);
192           EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
193           EVP_PKEY_CTX_free(pctx);
194

SEE ALSO

196       EVP_RSA_gen(3), EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7)
197
199       Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
200
201       Licensed under the Apache License 2.0 (the "License").  You may not use
202       this file except in compliance with the License.  You can obtain a copy
203       in the file LICENSE in the source distribution or at
204       <https://www.openssl.org/source/license.html>.
205
206
207
2083.0.9                             2023-07-27               EVP_PKEY-RSA(7ossl)
Impressum