1EVP_PKEY-RSA(7ossl) OpenSSL EVP_PKEY-RSA(7ossl)
2
6 EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA - EVP_PKEY RSA keytype and algorithm
7 support
8
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 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 "n" (OSSL_PKEY_PARAM_RSA_N) <unsigned integer>
22 The RSA modulus "n" value.
23 "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 "d" (OSSL_PKEY_PARAM_RSA_D) <unsigned integer>
31 The RSA private exponent "d" value.
32 "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 "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 "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 RSA key generation parameters
83 When generating RSA keys, the following key generation parameters may
84 be used.
85 "bits" (OSSL_PKEY_PARAM_RSA_BITS) <unsigned integer>
87 The value should be the cryptographic length for the RSA
88 cryptosystem, in bits.
89 "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 "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 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 "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 "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 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 "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 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 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 For RSA keys, EVP_PKEY_public_check_quick(3) is the same as
140 EVP_PKEY_public_check(3).
141 For RSA keys, EVP_PKEY_private_check(3) conforms to the SP800-56Br1
143 private key test.
144 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
150 FIPS186-4
151 Section B.3.6 Generation of Probable Primes with Conditions Based
152 on Auxiliary Probable Primes
153 RFC 8017, excluding RSA-PSS and RSA-OAEP
155
157 An EVP_PKEY context can be obtained by calling:
158 EVP_PKEY_CTX *pctx =
160 EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
161 An RSA key can be generated simply like this:
163 pkey = EVP_RSA_gen(4096);
165 or like this:
167 EVP_PKEY *pkey = NULL;
169 EVP_PKEY_CTX *pctx =
170 EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
171 EVP_PKEY_keygen_init(pctx);
173 EVP_PKEY_generate(pctx, &pkey);
174 EVP_PKEY_CTX_free(pctx);
175 An RSA key can be generated with key generation parameters:
177 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 EVP_PKEY_keygen_init(pctx);
185 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 EVP_PKEY_generate(pctx, &pkey);
192 EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
193 EVP_PKEY_CTX_free(pctx);
194
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 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>.
2053.1.1 2023-08-31 EVP_PKEY-RSA(7ossl)