]>
Commit | Line | Data |
---|---|---|
2186cd8e UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/rsa.h> | |
10 | ||
b89fdeb2 | 11 | int RSA_public_encrypt(int flen, const unsigned char *from, |
e9b77246 | 12 | unsigned char *to, RSA *rsa, int padding); |
2186cd8e | 13 | |
b89fdeb2 | 14 | int RSA_private_decrypt(int flen, const unsigned char *from, |
e9b77246 | 15 | unsigned char *to, RSA *rsa, int padding); |
2186cd8e UM |
16 | |
17 | =head1 DESCRIPTION | |
18 | ||
19 | RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a | |
20 | session key) using the public key B<rsa> and stores the ciphertext in | |
4101054a | 21 | B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory. |
2186cd8e UM |
22 | |
23 | B<padding> denotes one of the following modes: | |
24 | ||
25 | =over 4 | |
26 | ||
27 | =item RSA_PKCS1_PADDING | |
28 | ||
29 | PKCS #1 v1.5 padding. This currently is the most widely used mode. | |
b89fdeb2 BE |
30 | However, it is highly recommended to use RSA_PKCS1_OAEP_PADDING in |
31 | new applications. SEE WARNING BELOW. | |
2186cd8e UM |
32 | |
33 | =item RSA_PKCS1_OAEP_PADDING | |
34 | ||
35 | EME-OAEP as defined in PKCS #1 v2.0 with SHA-1, MGF1 and an empty | |
36 | encoding parameter. This mode is recommended for all new applications. | |
37 | ||
38 | =item RSA_SSLV23_PADDING | |
39 | ||
40 | PKCS #1 v1.5 padding with an SSL-specific modification that denotes | |
41 | that the server is SSL3 capable. | |
42 | ||
43 | =item RSA_NO_PADDING | |
44 | ||
45 | Raw RSA encryption. This mode should I<only> be used to implement | |
46 | cryptographically sound padding modes in the application code. | |
47 | Encrypting user data directly with RSA is insecure. | |
48 | ||
49 | =back | |
50 | ||
b89fdeb2 BE |
51 | B<flen> must not be more than RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5 |
52 | based padding modes, not more than RSA_size(B<rsa>) - 42 for | |
f46e76ef | 53 | RSA_PKCS1_OAEP_PADDING and exactly RSA_size(B<rsa>) for RSA_NO_PADDING. |
b89fdeb2 BE |
54 | When a padding mode other than RSA_NO_PADDING is in use, then |
55 | RSA_public_encrypt() will include some random bytes into the ciphertext | |
56 | and therefore the ciphertext will be different each time, even if the | |
57 | plaintext and the public key are exactly identical. | |
58 | The returned ciphertext in B<to> will always be zero padded to exactly | |
59 | RSA_size(B<rsa>) bytes. | |
60 | B<to> and B<from> may overlap. | |
2186cd8e UM |
61 | |
62 | RSA_private_decrypt() decrypts the B<flen> bytes at B<from> using the | |
b89fdeb2 BE |
63 | private key B<rsa> and stores the plaintext in B<to>. B<flen> should |
64 | be equal to RSA_size(B<rsa>) but may be smaller, when leading zero | |
65 | bytes are in the ciphertext. Those are not important and may be removed, | |
66 | but RSA_public_encrypt() does not do that. B<to> must point | |
67 | to a memory section large enough to hold the maximal possible decrypted | |
68 | data (which is equal to RSA_size(B<rsa>) for RSA_NO_PADDING, | |
69 | RSA_size(B<rsa>) - 11 for the PKCS #1 v1.5 based padding modes and | |
70 | RSA_size(B<rsa>) - 42 for RSA_PKCS1_OAEP_PADDING). | |
71 | B<padding> is the padding mode that was used to encrypt the data. | |
72 | B<to> and B<from> may overlap. | |
2186cd8e UM |
73 | |
74 | =head1 RETURN VALUES | |
75 | ||
76 | RSA_public_encrypt() returns the size of the encrypted data (i.e., | |
4101054a | 77 | RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the |
b89fdeb2 BE |
78 | recovered plaintext. A return value of 0 is not an error and |
79 | means only that the plaintext was empty. | |
2186cd8e UM |
80 | |
81 | On error, -1 is returned; the error codes can be | |
9b86974e | 82 | obtained by L<ERR_get_error(3)>. |
2186cd8e | 83 | |
1e3f62a3 EK |
84 | =head1 WARNING |
85 | ||
86 | Decryption failures in the RSA_PKCS1_PADDING mode leak information | |
87 | which can potentially be used to mount a Bleichenbacher padding oracle | |
88 | attack. This is an inherent weakness in the PKCS #1 v1.5 padding | |
89 | design. Prefer RSA_PKCS1_OAEP_PADDING. | |
90 | ||
2186cd8e UM |
91 | =head1 CONFORMING TO |
92 | ||
93 | SSL, PKCS #1 v2.0 | |
94 | ||
95 | =head1 SEE ALSO | |
96 | ||
b97fdb57 | 97 | L<ERR_get_error(3)>, L<RAND_bytes(3)>, |
9b86974e | 98 | L<RSA_size(3)> |
2186cd8e | 99 | |
e2f92610 RS |
100 | =head1 COPYRIGHT |
101 | ||
b89fdeb2 | 102 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 103 | |
4746f25a | 104 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
105 | this file except in compliance with the License. You can obtain a copy |
106 | in the file LICENSE in the source distribution or at | |
107 | L<https://www.openssl.org/source/license.html>. | |
108 | ||
109 | =cut |