]>
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, | |
8 | RSA_padding_add_SSLv23, RSA_padding_check_SSLv23, | |
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 | ||
16 | int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen, | |
e9b77246 | 17 | unsigned char *f, int fl); |
2186cd8e UM |
18 | |
19 | int RSA_padding_check_PKCS1_type_1(unsigned char *to, int tlen, | |
e9b77246 | 20 | unsigned char *f, int fl, int rsa_len); |
2186cd8e UM |
21 | |
22 | int RSA_padding_add_PKCS1_type_2(unsigned char *to, int tlen, | |
e9b77246 | 23 | unsigned char *f, int fl); |
2186cd8e UM |
24 | |
25 | int RSA_padding_check_PKCS1_type_2(unsigned char *to, int tlen, | |
e9b77246 | 26 | unsigned char *f, int fl, int rsa_len); |
2186cd8e UM |
27 | |
28 | int RSA_padding_add_PKCS1_OAEP(unsigned char *to, int tlen, | |
e9b77246 | 29 | unsigned char *f, int fl, unsigned char *p, int pl); |
2186cd8e UM |
30 | |
31 | int RSA_padding_check_PKCS1_OAEP(unsigned char *to, int tlen, | |
e9b77246 BB |
32 | unsigned char *f, int fl, int rsa_len, |
33 | unsigned char *p, int pl); | |
2186cd8e UM |
34 | |
35 | int RSA_padding_add_SSLv23(unsigned char *to, int tlen, | |
e9b77246 | 36 | unsigned char *f, int fl); |
2186cd8e UM |
37 | |
38 | int RSA_padding_check_SSLv23(unsigned char *to, int tlen, | |
e9b77246 | 39 | unsigned char *f, int fl, int rsa_len); |
2186cd8e UM |
40 | |
41 | int RSA_padding_add_none(unsigned char *to, int tlen, | |
e9b77246 | 42 | unsigned char *f, int fl); |
2186cd8e UM |
43 | |
44 | int RSA_padding_check_none(unsigned char *to, int tlen, | |
e9b77246 | 45 | unsigned char *f, int fl, int rsa_len); |
2186cd8e UM |
46 | |
47 | =head1 DESCRIPTION | |
48 | ||
49 | The RSA_padding_xxx_xxx() functions are called from the RSA encrypt, | |
036c8d7e UM |
50 | decrypt, sign and verify functions. Normally they should not be called |
51 | from application programs. | |
2186cd8e | 52 | |
036c8d7e | 53 | However, they can also be called directly to implement padding for other |
2186cd8e UM |
54 | asymmetric ciphers. RSA_padding_add_PKCS1_OAEP() and |
55 | RSA_padding_check_PKCS1_OAEP() may be used in an application combined | |
56 | with B<RSA_NO_PADDING> in order to implement OAEP with an encoding | |
57 | parameter. | |
58 | ||
59 | RSA_padding_add_xxx() encodes B<fl> bytes from B<f> so as to fit into | |
60 | B<tlen> bytes and stores the result at B<to>. An error occurs if B<fl> | |
61 | does not meet the size requirements of the encoding method. | |
62 | ||
63 | The following encoding methods are implemented: | |
64 | ||
65 | =over 4 | |
66 | ||
67 | =item PKCS1_type_1 | |
68 | ||
69 | PKCS #1 v2.0 EMSA-PKCS1-v1_5 (PKCS #1 v1.5 block type 1); used for signatures | |
70 | ||
71 | =item PKCS1_type_2 | |
72 | ||
73 | PKCS #1 v2.0 EME-PKCS1-v1_5 (PKCS #1 v1.5 block type 2) | |
74 | ||
75 | =item PKCS1_OAEP | |
76 | ||
036c8d7e | 77 | PKCS #1 v2.0 EME-OAEP |
2186cd8e UM |
78 | |
79 | =item SSLv23 | |
80 | ||
81 | PKCS #1 EME-PKCS1-v1_5 with SSL-specific modification | |
82 | ||
83 | =item none | |
84 | ||
85 | simply copy the data | |
86 | ||
87 | =back | |
88 | ||
89 | The random number generator must be seeded prior to calling | |
90 | RSA_padding_add_xxx(). | |
91 | ||
92 | RSA_padding_check_xxx() verifies that the B<fl> bytes at B<f> contain | |
93 | a valid encoding for a B<rsa_len> byte RSA key in the respective | |
261b5d96 UM |
94 | encoding method and stores the recovered data of at most B<tlen> bytes |
95 | (for B<RSA_NO_PADDING>: of size B<tlen>) | |
2186cd8e UM |
96 | at B<to>. |
97 | ||
98 | For RSA_padding_xxx_OAEP(), B<p> points to the encoding parameter | |
99 | of length B<pl>. B<p> may be B<NULL> if B<pl> is 0. | |
100 | ||
101 | =head1 RETURN VALUES | |
102 | ||
103 | The RSA_padding_add_xxx() functions return 1 on success, 0 on error. | |
104 | The RSA_padding_check_xxx() functions return the length of the | |
105 | recovered data, -1 on error. Error codes can be obtained by calling | |
9b86974e | 106 | L<ERR_get_error(3)>. |
2186cd8e | 107 | |
1e3f62a3 EK |
108 | =head1 WARNING |
109 | ||
110 | The RSA_padding_check_PKCS1_type_2() padding check leaks timing | |
111 | information which can potentially be used to mount a Bleichenbacher | |
112 | padding oracle attack. This is an inherent weakness in the PKCS #1 | |
e875b0cf AP |
113 | v1.5 padding design. Prefer PKCS1_OAEP padding. Otherwise it can |
114 | be recommended to pass zero-padded B<f>, so that B<fl> equals to | |
115 | B<rsa_len>, and if fixed by protocol, B<tlen> being set to the | |
116 | expected length. In such case leakage would be minimal, it would | |
117 | take attacker's ability to observe memory access pattern with byte | |
118 | granilarity as it occurs, post-factum timing analysis won't do. | |
1e3f62a3 | 119 | |
2186cd8e UM |
120 | =head1 SEE ALSO |
121 | ||
9b86974e RS |
122 | L<RSA_public_encrypt(3)>, |
123 | L<RSA_private_decrypt(3)>, | |
124 | L<RSA_sign(3)>, L<RSA_verify(3)> | |
2186cd8e | 125 | |
e2f92610 RS |
126 | =head1 COPYRIGHT |
127 | ||
128 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
129 | ||
4746f25a | 130 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
131 | this file except in compliance with the License. You can obtain a copy |
132 | in the file LICENSE in the source distribution or at | |
133 | L<https://www.openssl.org/source/license.html>. | |
134 | ||
135 | =cut |