Skip to content

Commit 1d14c4e

Browse files
sybrenstuvelsybrenstuvel
committed
Updated documentation for removal of bigfile/VARBLOCK support.
1 parent 88927a9 commit 1d14c4e

5 files changed

Lines changed: 52 additions & 108 deletions

File tree

‎doc/cli.rst‎

Lines changed: 27 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -13,31 +13,30 @@ on how to use them. Here is a short overview:
1313
.. index:: pyrsa-verify, pyrsa-priv2pub, pyrsa-encrypt-bigfile
1414
.. index:: pyrsa-decrypt-bigfile, pyrsa-decrypt-bigfile
1515

16-
+-----------------------+--------------------------------------------------+-----------------------------------------+
17-
| Command | Usage | Core function |
18-
+=======================+==================================================+=========================================+
19-
| pyrsa-keygen | Generates a new RSA keypair in PEM or DER format | :py:func:`rsa.newkeys` |
20-
+-----------------------+--------------------------------------------------+-----------------------------------------+
21-
| pyrsa-encrypt | Encrypts a file. The file must be shorter than | :py:func:`rsa.encrypt` |
22-
| | the key length in order to be encrypted. | |
23-
+-----------------------+--------------------------------------------------+-----------------------------------------+
24-
| pyrsa-decrypt | Decrypts a file. | :py:func:`rsa.decrypt` |
25-
+-----------------------+--------------------------------------------------+-----------------------------------------+
26-
| pyrsa-sign | Signs a file, outputs the signature. | :py:func:`rsa.sign` |
27-
+-----------------------+--------------------------------------------------+-----------------------------------------+
28-
| pyrsa-verify | Verifies a signature. The result is written to | :py:func:`rsa.verify` |
29-
| | the console as well as returned in the exit | |
30-
| | status code. | |
31-
+-----------------------+--------------------------------------------------+-----------------------------------------+
32-
| pyrsa-priv2pub | Reads a private key and outputs the | \- |
33-
| | corresponding public key. | |
34-
+-----------------------+--------------------------------------------------+-----------------------------------------+
35-
| pyrsa-encrypt-bigfile | Encrypts a file to an encrypted VARBLOCK file. | :py:func:`rsa.bigfile.encrypt_bigfile` |
36-
| | The file can be larger than the key length, but | |
37-
| | the output file is only compatible with | |
38-
| | Python-RSA. | |
39-
+-----------------------+--------------------------------------------------+-----------------------------------------+
40-
| pyrsa-decrypt-bigfile | Decrypts an encrypted VARBLOCK file. | :py:func:`rsa.bigfile.encrypt_bigfile` |
41-
+-----------------------+--------------------------------------------------+-----------------------------------------+
42-
43-
16+
+-------------------------+--------------------------------------------------+-----------------------------------------+
17+
| Command | Usage | Core function |
18+
+=========================+==================================================+=========================================+
19+
| pyrsa-keygen | Generates a new RSA keypair in PEM or DER format | :py:func:`rsa.newkeys` |
20+
+-------------------------+--------------------------------------------------+-----------------------------------------+
21+
| pyrsa-encrypt | Encrypts a file. The file must be shorter than | :py:func:`rsa.encrypt` |
22+
| | the key length in order to be encrypted. | |
23+
+-------------------------+--------------------------------------------------+-----------------------------------------+
24+
| pyrsa-decrypt | Decrypts a file. | :py:func:`rsa.decrypt` |
25+
+-------------------------+--------------------------------------------------+-----------------------------------------+
26+
| pyrsa-sign | Signs a file, outputs the signature. | :py:func:`rsa.sign` |
27+
+-------------------------+--------------------------------------------------+-----------------------------------------+
28+
| pyrsa-verify | Verifies a signature. The result is written to | :py:func:`rsa.verify` |
29+
| | the console as well as returned in the exit | |
30+
| | status code. | |
31+
+-------------------------+--------------------------------------------------+-----------------------------------------+
32+
| pyrsa-priv2pub | Reads a private key and outputs the | \- |
33+
| | corresponding public key. | |
34+
+-------------------------+--------------------------------------------------+-----------------------------------------+
35+
| *pyrsa-encrypt-bigfile* | *Encrypts a file to an encrypted VARBLOCK file. | *Deprecated in Python-RSA 3.4 and |
36+
| | The file can be larger than the key length, but | removed from version 4.0.* |
37+
| | the output file is only compatible with | |
38+
| | Python-RSA.* | |
39+
+-------------------------+--------------------------------------------------+-----------------------------------------+
40+
| *pyrsa-decrypt-bigfile* | *Decrypts an encrypted VARBLOCK file.* | *Deprecated in Python-RSA 3.4 and |
41+
| | | removed from version 4.0.* |
42+
+-------------------------+--------------------------------------------------+-----------------------------------------+

‎doc/compatibility.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,8 @@ Public keys:
2525
PKCS#1 v1.5 in PEM and DER format, ASN.1 type RSAPublicKey
2626

2727
:ref:`VARBLOCK <bigfiles>` encryption:
28-
Python-RSA only, not compatible with any other known application.
28+
Deprecated in Python-RSA 3.4 and removed from Python-RSA 4.0.
29+
Was Python-RSA only, not compatible with any other known application.
2930

3031
.. _openssl:
3132

@@ -59,4 +60,3 @@ PKCS#8 format you need an external tool such as OpenSSL::
5960
openssl rsa -in privatekey-pkcs8.pem -out privatekey.pem
6061

6162
You can then extract the corresponding public key as described above.
62-

‎doc/reference.rst‎

Lines changed: 1 addition & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -49,32 +49,13 @@ Exceptions
4949

5050
.. index:: VARBLOCK (file format)
5151

52-
Module: rsa.bigfile
53-
-------------------
54-
55-
.. warning::
56-
57-
The :py:mod:`rsa.bigfile` module is NOT recommended for general use, has been
58-
deprecated since Python-RSA 3.4, and will be removed in a future release. It's
59-
vulnerable to a number of attacks. See :ref:`bigfiles` for more information.
60-
61-
The :py:mod:`rsa.bigfile` module contains functions for encrypting and
62-
decrypting files that are larger than the RSA key. See
63-
:ref:`bigfiles` for more information.
64-
65-
.. autofunction:: rsa.bigfile.encrypt_bigfile
66-
67-
.. autofunction:: rsa.bigfile.decrypt_bigfile
68-
69-
.. _VARBLOCK:
70-
7152
The VARBLOCK file format
7253
++++++++++++++++++++++++
7354

7455
.. warning::
7556

7657
The VARBLOCK format is NOT recommended for general use, has been deprecated since
77-
Python-RSA 3.4, and will be removed in a future release. It's vulnerable to a
58+
Python-RSA 3.4, and was removed in version 4.0. It's vulnerable to a
7859
number of attacks. See :ref:`bigfiles` for more information.
7960

8061
The VARBLOCK file format allows us to encrypt files that are larger
@@ -109,4 +90,3 @@ the core of the entire library.
10990
.. autofunction:: rsa.core.encrypt_int
11091

11192
.. autofunction:: rsa.core.decrypt_int
112-

‎doc/upgrading.rst‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,22 @@
11
Upgrading from older versions
22
=============================
33

4+
From versions older than Python-RSA 4.0
5+
---------------------------------------
6+
7+
Support for the VARBLOCK/bigfile format has been dropped in version 4.0, after
8+
being deprecated for a year. There is no alternative implementation in
9+
Python-RSA 4.0. If you need this, or have ideas on how to do handle encryption
10+
of large files securely and in a compatible way with existing standards,
11+
`open a ticket to discuss this`_.
12+
13+
.. _open a ticket to discuss this:
14+
https://github.com/sybrenstuvel/python-rsa/issues/new
15+
16+
17+
From versions older than Python-RSA 3.4
18+
---------------------------------------
19+
420
Previous versions of Python-RSA were less secure than the current
521
version. In order to be able to gradually upgrade your software, those
622
old versions will be available until Python-RSA 4.0.
@@ -34,8 +50,7 @@ less secure code into your project.
3450

3551
The random padding introduced in version 3.0 made things much more
3652
secure, but also requires a larger key to encrypt the same message.
37-
You can either generate a new key with :py:func:`rsa.newkeys`, or use
38-
:py:func:`rsa.bigfile.encrypt_bigfile` to encrypt your files.
53+
3954

4055
Converting keys
4156
---------------
@@ -70,4 +85,3 @@ older version of Python-RSA, use the following::
7085

7186
old_priv_key.update(old_pub_key)
7287
priv_key = rsa.PrivateKey(**old_priv_key)
73-

‎doc/usage.rst‎

Lines changed: 5 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,7 @@ You can create a detached signature for a message using the
198198
>>> (pubkey, privkey) = rsa.newkeys(512)
199199
>>> message = 'Go left at the blue tree'
200200
>>> signature = rsa.sign(message, privkey, 'SHA-1')
201-
201+
202202
This hashes the message using SHA-1. Other hash methods are also
203203
possible, check the :py:func:`rsa.sign` function documentation for
204204
details. The hash is then signed with the private key.
@@ -285,7 +285,7 @@ Only using Python-RSA: the VARBLOCK format
285285
.. warning::
286286

287287
The VARBLOCK format is NOT recommended for general use, has been deprecated since
288-
Python-RSA 3.4, and will be removed in a future release. It's vulnerable to a
288+
Python-RSA 3.4, and has been removed in version 4.0. It's vulnerable to a
289289
number of attacks:
290290

291291
1. decrypt/encrypt_bigfile() does not implement `Authenticated encryption`_ nor
@@ -299,55 +299,6 @@ Only using Python-RSA: the VARBLOCK format
299299
.. _Authenticated encryption: https://en.wikipedia.org/wiki/Authenticated_encryption
300300
.. _issue #19 on Github: https://github.com/sybrenstuvel/python-rsa/issues/13
301301

302-
303-
As far as we know, there is no pure-Python AES encryption. Previous
304-
versions of Python-RSA included functionality to encrypt large files
305-
with just RSA, and so does this version. The format has been improved,
306-
though.
307-
308-
Encrypting works as follows: the input file is split into blocks that
309-
are just large enough to encrypt with your RSA key. Every block is
310-
then encrypted using RSA, and the encrypted blocks are assembled into
311-
the output file. This file format is called the :ref:`VARBLOCK
312-
<VARBLOCK>` format.
313-
314-
Decrypting works in reverse. The encrypted file is separated into
315-
encrypted blocks. Those are decrypted, and assembled into the original
316-
file.
317-
318-
.. note::
319-
320-
The file will get larger after encryption, as each encrypted block
321-
has 8 bytes of random padding and 3 more bytes of overhead.
322-
323-
Since these encryption/decryption functions are potentially called on
324-
very large files, they use another approach. Where the regular
325-
functions store the message in memory in its entirety, these functions
326-
work on one block at the time. As a result, you should call them with
327-
:py:class:`file`-like objects as the parameters.
328-
329-
Before using we of course need a keypair:
330-
331-
>>> import rsa
332-
>>> (pub_key, priv_key) = rsa.newkeys(512)
333-
334-
Encryption works on file handles using the
335-
:py:func:`rsa.bigfile.encrypt_bigfile` function:
336-
337-
>>> from rsa.bigfile import *
338-
>>> with open('inputfile', 'rb') as infile, open('outputfile', 'wb') as outfile:
339-
... encrypt_bigfile(infile, outfile, pub_key)
340-
341-
As does decryption using the :py:func:`rsa.bigfile.decrypt_bigfile`
342-
function:
343-
344-
>>> from rsa.bigfile import *
345-
>>> with open('inputfile', 'rb') as infile, open('outputfile', 'wb') as outfile:
346-
... decrypt_bigfile(infile, outfile, priv_key)
347-
348-
.. note::
349-
350-
:py:func:`rsa.sign` and :py:func:`rsa.verify` work on arbitrarily
351-
long files, so they do not have a "bigfile" equivalent.
352-
353-
302+
As of Python-RSA version 4.0, the VARBLOCK format has been removed from the
303+
library. For now, this section is kept here to document the issues with that
304+
format, and ensure we don't do something like that again.

0 commit comments

Comments
 (0)