c6533f2ffcb7e8dc723e529ce309a334cbbb0508
[openssl.git] / doc / man7 / EVP_PKEY-RSA.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA
6 - EVP_PKEY RSA keytype and algorithm support
7
8 =head1 DESCRIPTION
9
10 The B<RSA> keytype is implemented in OpenSSL's default and FIPS providers.
11 That implementation supports the basic RSA keys, containing the modulus I<n>,
12 the public exponent I<e>, the private exponent I<d>, and a collection of prime
13 factors, exponents and coefficient for CRT calculations, of which the first
14 few are known as I<p> and I<q>, I<dP> and I<dQ>, and I<qInv>.
15
16 =head2 Common RSA parameters
17
18 In addition to the common parameters that all keytypes should support (see
19 L<provider-keymgmt(7)/Common parameters>), the B<RSA> keytype implementation
20 supports the following.
21
22 =over 4
23
24 =item "n" (B<OSSL_PKEY_PARAM_RSA_N>) <unsigned integer>
25
26 The RSA "n" value.
27
28 =item "e" (B<OSSL_PKEY_PARAM_RSA_E>) <unsigned integer>
29
30 The RSA "e" value.
31
32 =item "d" (B<OSSL_PKEY_PARAM_RSA_D>) <unsigned integer>
33
34 The RSA "d" value.
35
36 =item "rsa-factor1" (B<OSSL_PKEY_PARAM_RSA_FACTOR1>) <unsigned integer>
37
38 =item "rsa-factor2" (B<OSSL_PKEY_PARAM_RSA_FACTOR2>) <unsigned integer>
39
40 =item "rsa-factor3" (B<OSSL_PKEY_PARAM_RSA_FACTOR3>) <unsigned integer>
41
42 =item "rsa-factor4" (B<OSSL_PKEY_PARAM_RSA_FACTOR4>) <unsigned integer>
43
44 =item "rsa-factor5" (B<OSSL_PKEY_PARAM_RSA_FACTOR5>) <unsigned integer>
45
46 =item "rsa-factor6" (B<OSSL_PKEY_PARAM_RSA_FACTOR6>) <unsigned integer>
47
48 =item "rsa-factor7" (B<OSSL_PKEY_PARAM_RSA_FACTOR7>) <unsigned integer>
49
50 =item "rsa-factor8" (B<OSSL_PKEY_PARAM_RSA_FACTOR8>) <unsigned integer>
51
52 =item "rsa-factor9" (B<OSSL_PKEY_PARAM_RSA_FACTOR9>) <unsigned integer>
53
54 =item "rsa-factor10" (B<OSSL_PKEY_PARAM_RSA_FACTOR10>) <unsigned integer>
55
56 RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017.
57 Up to eight additional "r_i" prime factors are supported.
58
59 =item "rsa-exponent1" (B<OSSL_PKEY_PARAM_RSA_EXPONENT1>) <unsigned integer>
60
61 =item "rsa-exponent2" (B<OSSL_PKEY_PARAM_RSA_EXPONENT2>) <unsigned integer>
62
63 =item "rsa-exponent3" (B<OSSL_PKEY_PARAM_RSA_EXPONENT3>) <unsigned integer>
64
65 =item "rsa-exponent4" (B<OSSL_PKEY_PARAM_RSA_EXPONENT4>) <unsigned integer>
66
67 =item "rsa-exponent5" (B<OSSL_PKEY_PARAM_RSA_EXPONENT5>) <unsigned integer>
68
69 =item "rsa-exponent6" (B<OSSL_PKEY_PARAM_RSA_EXPONENT6>) <unsigned integer>
70
71 =item "rsa-exponent7" (B<OSSL_PKEY_PARAM_RSA_EXPONENT7>) <unsigned integer>
72
73 =item "rsa-exponent8" (B<OSSL_PKEY_PARAM_RSA_EXPONENT8>) <unsigned integer>
74
75 =item "rsa-exponent9" (B<OSSL_PKEY_PARAM_RSA_EXPONENT9>) <unsigned integer>
76
77 =item "rsa-exponent10" (B<OSSL_PKEY_PARAM_RSA_EXPONENT10>) <unsigned integer>
78
79 RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known
80 as "dP", "dQ" and "d_i in RFC8017".
81 Up to eight additional "d_i" exponents are supported.
82
83 =item "rsa-coefficient1" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT1>) <unsigned integer>
84
85 =item "rsa-coefficient2" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT2>) <unsigned integer>
86
87 =item "rsa-coefficient3" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT3>) <unsigned integer>
88
89 =item "rsa-coefficient4" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT4>) <unsigned integer>
90
91 =item "rsa-coefficient5" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT5>) <unsigned integer>
92
93 =item "rsa-coefficient6" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT6>) <unsigned integer>
94
95 =item "rsa-coefficient7" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT7>) <unsigned integer>
96
97 =item "rsa-coefficient8" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT8>) <unsigned integer>
98
99 =item "rsa-coefficient9" (B<OSSL_PKEY_PARAM_RSA_COEFFICIENT9>) <unsigned integer>
100
101 RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as
102 "qInv" and "t_i".
103 Up to eight additional "t_i" exponents are supported.
104
105 =back
106
107 =head2 RSA key generation parameters
108
109 When generating RSA keys, the following key generation parameters may be used.
110
111 =over 4
112
113 =item "bits" (B<OSSL_PKEY_PARAM_RSA_BITS>) <unsigned integer>
114
115 The value should be the cryptographic length for the B<RSA> cryptosystem, in
116 bits.
117
118 =item "primes" (B<OSSL_PKEY_PARAM_RSA_PRIMES>) <unsigned integer>
119
120 The value should be the number of primes for the generated B<RSA> key.  The
121 default is 2.  It isn't permitted to specify a larger number of primes than
122 10.  Additionally, the number of primes is limited by the length of the key
123 being generated so the maximum number could be less.
124
125 =back
126
127 =head1 CONFORMING TO
128
129 =over 4
130
131 =item RFC 8017, excluding RSA-PSS and RSA-OAEP
132
133 =for comment RSA-PSS, and probably also RSA-OAEP, need separate keytypes,
134 and will be described in separate pages for those RSA keytypes.
135
136 =back
137
138 =head1 EXAMPLES
139
140 An B<EVP_PKEY> context can be obtained by calling:
141
142     EVP_PKEY_CTX *pctx =
143         EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
144
145 An B<RSA> key can be generated like this:
146
147     EVP_PKEY *pkey = NULL;
148     EVP_PKEY_CTX *pctx =
149         EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
150
151     EVP_PKEY_keygen_init(pctx);
152     EVP_PKEY_gen(pctx, &pkey);
153     EVP_PKEY_CTX_free(pctx);
154
155 An B<RSA> key can be generated with key generation parameters:
156
157     unsigned int primes = 3;
158     unsigned int bits = 4096;
159     OSSL_PARAM params[3];
160     EVP_PKEY *pkey = NULL;
161     EVP_PKEY_CTX *pctx =
162         EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
163
164     params[0] = OSSL_PARAM_construct_uint("bits", bits);
165     params[1] = OSSL_PARAM_construct_uint("primes", primes);
166     params[2] = OSSL_PARAM_END;
167     EVP_PKEY_keygen_init(pctx);
168     EVP_PKEY_CTX_set_params(pctx, params);
169     EVP_PKEY_gen(pctx, &pkey);
170     EVP_PKEY_CTX_free(pctx);
171
172 =head1 SEE ALSO
173
174 L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>
175
176 =head1 COPYRIGHT
177
178 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
179
180 Licensed under the Apache License 2.0 (the "License").  You may not use
181 this file except in compliance with the License.  You can obtain a copy
182 in the file LICENSE in the source distribution or at
183 L<https://www.openssl.org/source/license.html>.
184
185 =cut