]>
Commit | Line | Data |
---|---|---|
2186cd8e UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | RSA_padding_add_PKCS1_type_1, RSA_padding_check_PKCS1_type_1, | |
6 | RSA_padding_add_PKCS1_type_2, RSA_padding_check_PKCS1_type_2, | |
7 | RSA_padding_add_PKCS1_OAEP, RSA_padding_check_PKCS1_OAEP, | |
f0e4a860 | 8 | RSA_padding_add_PKCS1_OAEP_mgf1, RSA_padding_check_PKCS1_OAEP_mgf1, |
4d524e10 | 9 | RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption |
2186cd8e UM |
10 | padding |
11 | ||
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/rsa.h> | |
15 | ||
4fd8a3e1 P |
16 | Deprecated since OpenSSL 3.0, can be hidden entirely by defining |
17 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
18 | L<openssl_user_macros(7)>: | |
19 | ||
2186cd8e | 20 | int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, |
f0e4a860 | 21 | const unsigned char *f, int fl); |
2186cd8e UM |
22 | |
23 | int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, | |
f0e4a860 | 24 | const unsigned char *f, int fl, int rsa_len); |
2186cd8e UM |
25 | |
26 | int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, | |
f0e4a860 | 27 | const unsigned char *f, int fl); |
2186cd8e UM |
28 | |
29 | int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, | |
f0e4a860 | 30 | const unsigned char *f, int fl, int rsa_len); |
2186cd8e UM |
31 | |
32 | int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, | |
f0e4a860 BE |
33 | const unsigned char *f, int fl, |
34 | const unsigned char *p, int pl); | |
2186cd8e UM |
35 | |
36 | int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, | |
f0e4a860 BE |
37 | const unsigned char *f, int fl, int rsa_len, |
38 | const unsigned char *p, int pl); | |
39 | ||
40 | int RSA_padding_add_PKCS1_OAEP_mgf1(unsigned char *to, int tlen, | |
41 | const unsigned char *f, int fl, | |
42 | const unsigned char *p, int pl, | |
43 | const EVP_MD *md, const EVP_MD *mgf1md); | |
44 | ||
45 | int RSA_padding_check_PKCS1_OAEP_mgf1(unsigned char *to, int tlen, | |
46 | const unsigned char *f, int fl, int rsa_len, | |
47 | const unsigned char *p, int pl, | |
48 | const EVP_MD *md, const EVP_MD *mgf1md); | |
2186cd8e | 49 | |
2186cd8e | 50 | int RSA_padding_add_none(unsigned char *to, int tlen, |
f0e4a860 | 51 | const unsigned char *f, int fl); |
2186cd8e UM |
52 | |
53 | int RSA_padding_check_none(unsigned char *to, int tlen, | |
f0e4a860 | 54 | const unsigned char *f, int fl, int rsa_len); |
2186cd8e UM |
55 | |
56 | =head1 DESCRIPTION | |
57 | ||
4fd8a3e1 P |
58 | All of the functions described on this page are deprecated. |
59 | Applications should instead use the EVP PKEY APIs. | |
60 | ||
2186cd8e | 61 | The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, |
036c8d7e UM |
62 | decrypt, sign and verify functions. Normally they should not be called |
63 | from application programs. | |
2186cd8e | 64 | |
036c8d7e | 65 | However, they can also be called directly to implement padding for other |
2186cd8e UM |
66 | asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and |
67 | RSA_padding_check_PKCS1_OAEP() may be used in an application combined | |
68 | with B<RSA_NO_PADDING> in order to implement OAEP with an encoding | |
69 | parameter. | |
70 | ||
71 | RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into | |
72 | B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl> | |
73 | does not meet the size requirements of the encoding method. | |
74 | ||
75 | The following encoding methods are implemented: | |
76 | ||
77 | =over 4 | |
78 | ||
79 | =item PKCS1_type_1 | |
80 | ||
81 | PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures | |
82 | ||
83 | =item PKCS1_type_2 | |
84 | ||
85 | PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) | |
86 | ||
87 | =item PKCS1_OAEP | |
88 | ||
036c8d7e | 89 | PKCS #1 v2.0 EME-OAEP |
2186cd8e | 90 | |
2186cd8e UM |
91 | =item none |
92 | ||
93 | simply copy the data | |
94 | ||
95 | =back | |
96 | ||
97 | The random number generator must be seeded prior to calling | |
98 | RSA_padding_add_xxx(). | |
262c0088 DMSP |
99 | If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to |
100 | external circumstances (see L<RAND(7)>), the operation will fail. | |
2186cd8e UM |
101 | |
102 | RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain | |
103 | a valid encoding for a B<rsa_len> byte RSA key in the respective | |
261b5d96 UM |
104 | encoding method and stores the recovered data of at most B<tlen> bytes |
105 | (for B<RSA_NO_PADDING>: of size B<tlen>) | |
2186cd8e UM |
106 | at B<to>. |
107 | ||
108 | For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter | |
109 | of length B<pl>. B<p> may be B<NULL> if B<pl> is 0. | |
110 | ||
f0e4a860 BE |
111 | For RSA_padding_xxx_OAEP_mgf1(), B<md> points to the md hash, |
112 | if B<md> is B<NULL> that means md=sha1, and B<mgf1md> points to | |
113 | the mgf1 hash, if B<mgf1md> is B<NULL> that means mgf1md=md. | |
114 | ||
2186cd8e UM |
115 | =head1 RETURN VALUES |
116 | ||
117 | The RSA_padding_add_xxx() functions return 1 on success, 0 on error. | |
118 | The RSA_padding_check_xxx() functions return the length of the | |
119 | recovered data, -1 on error. Error codes can be obtained by calling | |
9b86974e | 120 | L<ERR_get_error(3)>. |
2186cd8e | 121 | |
5e0d9c86 | 122 | =head1 WARNINGS |
1e3f62a3 | 123 | |
f0e4a860 | 124 | The result of RSA_padding_check_PKCS1_type_2() is a very sensitive |
1e3f62a3 EK |
125 | information which can potentially be used to mount a Bleichenbacher |
126 | padding oracle attack. This is an inherent weakness in the PKCS #1 | |
f0e4a860 BE |
127 | v1.5 padding design. Prefer PKCS1_OAEP padding. If that is not |
128 | possible, the result of RSA_padding_check_PKCS1_type_2() should be | |
129 | checked in constant time if it matches the expected length of the | |
130 | plaintext and additionally some application specific consistency | |
131 | checks on the plaintext need to be performed in constant time. | |
132 | If the plaintext is rejected it must be kept secret which of the | |
133 | checks caused the application to reject the message. | |
134 | Do not remove the zero-padding from the decrypted raw RSA data | |
135 | which was computed by RSA_private_decrypt() with B<RSA_NO_PADDING>, | |
136 | as this would create a small timing side channel which could be | |
137 | used to mount a Bleichenbacher attack against any padding mode | |
138 | including PKCS1_OAEP. | |
1e3f62a3 | 139 | |
2186cd8e UM |
140 | =head1 SEE ALSO |
141 | ||
9b86974e RS |
142 | L<RSA_public_encrypt(3)>, |
143 | L<RSA_private_decrypt(3)>, | |
262c0088 DMSP |
144 | L<RSA_sign(3)>, L<RSA_verify(3)>, |
145 | L<RAND(7)> | |
2186cd8e | 146 | |
4fd8a3e1 P |
147 | =head1 HISTORY |
148 | ||
149 | All of these functions were deprecated in OpenSSL 3.0. | |
150 | ||
e2f92610 RS |
151 | =head1 COPYRIGHT |
152 | ||
8020d79b | 153 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 154 | |
4746f25a | 155 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
156 | this file except in compliance with the License. You can obtain a copy |
157 | in the file LICENSE in the source distribution or at | |
158 | L<https://www.openssl.org/source/license.html>. | |
159 | ||
160 | =cut |