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_SSLv23, RSA_padding_check_SSLv23,
10RSA_padding_add_none, RSA_padding_check_none - asymmetric encryption
11padding
12
13=head1 SYNOPSIS
14
15 #include <openssl/rsa.h>
16
17 int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,
18                                  const unsigned char *f, int fl);
19
20 int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen,
21                                    const unsigned char *f, int fl, int rsa_len);
22
23 int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen,
24                                  const unsigned char *f, int fl);
25
26 int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen,
27                                    const unsigned char *f, int fl, int rsa_len);
28
29 int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen,
30                                const unsigned char *f, int fl,
31                                const unsigned char *p, int pl);
32
33 int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen,
34                                  const unsigned char *f, int fl, int rsa_len,
35                                  const unsigned char *p, int pl);
36
37 int RSA_padding_add_PKCS1_OAEP_mgf1(unsigned char *to, int tlen,
38                                     const unsigned char *f, int fl,
39                                     const unsigned char *p, int pl,
40                                     const EVP_MD *md, const EVP_MD *mgf1md);
41
42 int RSA_padding_check_PKCS1_OAEP_mgf1(unsigned char *to, int tlen,
43                                       const unsigned char *f, int fl, int rsa_len,
44                                       const unsigned char *p, int pl,
45                                       const EVP_MD *md, const EVP_MD *mgf1md);
46
47 int RSA_padding_add_SSLv23(unsigned char *to, int tlen,
48                            const unsigned char *f, int fl);
49
50 int RSA_padding_check_SSLv23(unsigned char *to, int tlen,
51                              const unsigned char *f, int fl, int rsa_len);
52
53 int RSA_padding_add_none(unsigned char *to, int tlen,
54                          const unsigned char *f, int fl);
55
56 int RSA_padding_check_none(unsigned char *to, int tlen,
57                            const unsigned char *f, int fl, int rsa_len);
58
59=head1 DESCRIPTION
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 SSLv23
92
93PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification
94
95=item none
96
97simply copy the data
98
99=back
100
101The random number generator must be seeded prior to calling
102RSA_padding_add_xxx().
103If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
104external circumstances (see L<RAND(7)>), the operation will fail.
105
106RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain
107a valid encoding for a B<rsa_len> byte RSA key in the respective
108encoding method and stores the recovered data of at most B<tlen> bytes
109(for B<RSA_NO_PADDING>: of size B<tlen>)
110at B<to>.
111
112For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter
113of length B<pl>. B<p> may be B<NULL> if B<pl> is 0.
114
115For RSA_padding_xxx_OAEP_mgf1(), B<md> points to the md hash,
116if B<md> is B<NULL> that means md=sha1, and B<mgf1md> points to
117the mgf1 hash, if B<mgf1md> is B<NULL> that means mgf1md=md.
118
119=head1 RETURN VALUES
120
121The RSA_padding_add_xxx() functions return 1 on success, 0 on error.
122The RSA_padding_check_xxx() functions return the length of the
123recovered data, -1 on error. Error codes can be obtained by calling
124L<ERR_get_error(3)>.
125
126=head1 WARNINGS
127
128The result of RSA_padding_check_PKCS1_type_2() is a very sensitive
129information which can potentially be used to mount a Bleichenbacher
130padding oracle attack. This is an inherent weakness in the PKCS #1
131v1.5 padding design. Prefer PKCS1_OAEP padding. If that is not
132possible, the result of RSA_padding_check_PKCS1_type_2() should be
133checked in constant time if it matches the expected length of the
134plaintext and additionally some application specific consistency
135checks on the plaintext need to be performed in constant time.
136If the plaintext is rejected it must be kept secret which of the
137checks caused the application to reject the message.
138Do not remove the zero-padding from the decrypted raw RSA data
139which was computed by RSA_private_decrypt() with B<RSA_NO_PADDING>,
140as this would create a small timing side channel which could be
141used to mount a Bleichenbacher attack against any padding mode
142including PKCS1_OAEP.
143
144=head1 SEE ALSO
145
146L<RSA_public_encrypt(3)>,
147L<RSA_private_decrypt(3)>,
148L<RSA_sign(3)>, L<RSA_verify(3)>,
149L<RAND(7)>
150
151=head1 COPYRIGHT
152
153Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
154
155Licensed under the OpenSSL license (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