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