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

CONFORMING TO

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

EXAMPLES

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

SEE ALSO

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