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