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