Updated documentation for removal of bigfile/VARBLOCK support.
diff --git a/doc/cli.rst b/doc/cli.rst
index af2b5f1..30864d7 100644
--- a/doc/cli.rst
+++ b/doc/cli.rst
@@ -13,31 +13,30 @@
.. index:: pyrsa-verify, pyrsa-priv2pub, pyrsa-encrypt-bigfile
.. index:: pyrsa-decrypt-bigfile, pyrsa-decrypt-bigfile
-+-----------------------+--------------------------------------------------+-----------------------------------------+
-| Command | Usage | Core function |
-+=======================+==================================================+=========================================+
-| pyrsa-keygen | Generates a new RSA keypair in PEM or DER format | :py:func:`rsa.newkeys` |
-+-----------------------+--------------------------------------------------+-----------------------------------------+
-| pyrsa-encrypt | Encrypts a file. The file must be shorter than | :py:func:`rsa.encrypt` |
-| | the key length in order to be encrypted. | |
-+-----------------------+--------------------------------------------------+-----------------------------------------+
-| pyrsa-decrypt | Decrypts a file. | :py:func:`rsa.decrypt` |
-+-----------------------+--------------------------------------------------+-----------------------------------------+
-| pyrsa-sign | Signs a file, outputs the signature. | :py:func:`rsa.sign` |
-+-----------------------+--------------------------------------------------+-----------------------------------------+
-| pyrsa-verify | Verifies a signature. The result is written to | :py:func:`rsa.verify` |
-| | the console as well as returned in the exit | |
-| | status code. | |
-+-----------------------+--------------------------------------------------+-----------------------------------------+
-| pyrsa-priv2pub | Reads a private key and outputs the | \- |
-| | corresponding public key. | |
-+-----------------------+--------------------------------------------------+-----------------------------------------+
-| pyrsa-encrypt-bigfile | Encrypts a file to an encrypted VARBLOCK file. | :py:func:`rsa.bigfile.encrypt_bigfile` |
-| | The file can be larger than the key length, but | |
-| | the output file is only compatible with | |
-| | Python-RSA. | |
-+-----------------------+--------------------------------------------------+-----------------------------------------+
-| pyrsa-decrypt-bigfile | Decrypts an encrypted VARBLOCK file. | :py:func:`rsa.bigfile.encrypt_bigfile` |
-+-----------------------+--------------------------------------------------+-----------------------------------------+
-
-
++-------------------------+--------------------------------------------------+-----------------------------------------+
+| Command | Usage | Core function |
++=========================+==================================================+=========================================+
+| pyrsa-keygen | Generates a new RSA keypair in PEM or DER format | :py:func:`rsa.newkeys` |
++-------------------------+--------------------------------------------------+-----------------------------------------+
+| pyrsa-encrypt | Encrypts a file. The file must be shorter than | :py:func:`rsa.encrypt` |
+| | the key length in order to be encrypted. | |
++-------------------------+--------------------------------------------------+-----------------------------------------+
+| pyrsa-decrypt | Decrypts a file. | :py:func:`rsa.decrypt` |
++-------------------------+--------------------------------------------------+-----------------------------------------+
+| pyrsa-sign | Signs a file, outputs the signature. | :py:func:`rsa.sign` |
++-------------------------+--------------------------------------------------+-----------------------------------------+
+| pyrsa-verify | Verifies a signature. The result is written to | :py:func:`rsa.verify` |
+| | the console as well as returned in the exit | |
+| | status code. | |
++-------------------------+--------------------------------------------------+-----------------------------------------+
+| pyrsa-priv2pub | Reads a private key and outputs the | \- |
+| | corresponding public key. | |
++-------------------------+--------------------------------------------------+-----------------------------------------+
+| *pyrsa-encrypt-bigfile* | *Encrypts a file to an encrypted VARBLOCK file. | *Deprecated in Python-RSA 3.4 and |
+| | The file can be larger than the key length, but | removed from version 4.0.* |
+| | the output file is only compatible with | |
+| | Python-RSA.* | |
++-------------------------+--------------------------------------------------+-----------------------------------------+
+| *pyrsa-decrypt-bigfile* | *Decrypts an encrypted VARBLOCK file.* | *Deprecated in Python-RSA 3.4 and |
+| | | removed from version 4.0.* |
++-------------------------+--------------------------------------------------+-----------------------------------------+
diff --git a/doc/compatibility.rst b/doc/compatibility.rst
index aedfcb6..d6e1dc4 100644
--- a/doc/compatibility.rst
+++ b/doc/compatibility.rst
@@ -25,7 +25,8 @@
PKCS#1 v1.5 in PEM and DER format, ASN.1 type RSAPublicKey
:ref:`VARBLOCK <bigfiles>` encryption:
- Python-RSA only, not compatible with any other known application.
+ Deprecated in Python-RSA 3.4 and removed from Python-RSA 4.0.
+ Was Python-RSA only, not compatible with any other known application.
.. _openssl:
@@ -59,4 +60,3 @@
openssl rsa -in privatekey-pkcs8.pem -out privatekey.pem
You can then extract the corresponding public key as described above.
-
diff --git a/doc/reference.rst b/doc/reference.rst
index d1b0b6d..d81f742 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -49,32 +49,13 @@
.. index:: VARBLOCK (file format)
-Module: rsa.bigfile
--------------------
-
-.. warning::
-
- The :py:mod:`rsa.bigfile` module is NOT recommended for general use, has been
- deprecated since Python-RSA 3.4, and will be removed in a future release. It's
- vulnerable to a number of attacks. See :ref:`bigfiles` for more information.
-
-The :py:mod:`rsa.bigfile` module contains functions for encrypting and
-decrypting files that are larger than the RSA key. See
-:ref:`bigfiles` for more information.
-
-.. autofunction:: rsa.bigfile.encrypt_bigfile
-
-.. autofunction:: rsa.bigfile.decrypt_bigfile
-
-.. _VARBLOCK:
-
The VARBLOCK file format
++++++++++++++++++++++++
.. warning::
The VARBLOCK format is NOT recommended for general use, has been deprecated since
- Python-RSA 3.4, and will be removed in a future release. It's vulnerable to a
+ Python-RSA 3.4, and was removed in version 4.0. It's vulnerable to a
number of attacks. See :ref:`bigfiles` for more information.
The VARBLOCK file format allows us to encrypt files that are larger
@@ -109,4 +90,3 @@
.. autofunction:: rsa.core.encrypt_int
.. autofunction:: rsa.core.decrypt_int
-
diff --git a/doc/upgrading.rst b/doc/upgrading.rst
index 0ec18eb..3381baa 100644
--- a/doc/upgrading.rst
+++ b/doc/upgrading.rst
@@ -1,6 +1,22 @@
Upgrading from older versions
=============================
+From versions older than Python-RSA 4.0
+---------------------------------------
+
+Support for the VARBLOCK/bigfile format has been dropped in version 4.0, after
+being deprecated for a year. There is no alternative implementation in
+Python-RSA 4.0. If you need this, or have ideas on how to do handle encryption
+of large files securely and in a compatible way with existing standards,
+`open a ticket to discuss this`_.
+
+.. _open a ticket to discuss this:
+ https://github.com/sybrenstuvel/python-rsa/issues/new
+
+
+From versions older than Python-RSA 3.4
+---------------------------------------
+
Previous versions of Python-RSA were less secure than the current
version. In order to be able to gradually upgrade your software, those
old versions will be available until Python-RSA 4.0.
@@ -34,8 +50,7 @@
The random padding introduced in version 3.0 made things much more
secure, but also requires a larger key to encrypt the same message.
-You can either generate a new key with :py:func:`rsa.newkeys`, or use
-:py:func:`rsa.bigfile.encrypt_bigfile` to encrypt your files.
+
Converting keys
---------------
@@ -70,4 +85,3 @@
old_priv_key.update(old_pub_key)
priv_key = rsa.PrivateKey(**old_priv_key)
-
diff --git a/doc/usage.rst b/doc/usage.rst
index a3d128d..b4f8426 100644
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -198,7 +198,7 @@
>>> (pubkey, privkey) = rsa.newkeys(512)
>>> message = 'Go left at the blue tree'
>>> signature = rsa.sign(message, privkey, 'SHA-1')
-
+
This hashes the message using SHA-1. Other hash methods are also
possible, check the :py:func:`rsa.sign` function documentation for
details. The hash is then signed with the private key.
@@ -285,7 +285,7 @@
.. warning::
The VARBLOCK format is NOT recommended for general use, has been deprecated since
- Python-RSA 3.4, and will be removed in a future release. It's vulnerable to a
+ Python-RSA 3.4, and has been removed in version 4.0. It's vulnerable to a
number of attacks:
1. decrypt/encrypt_bigfile() does not implement `Authenticated encryption`_ nor
@@ -299,55 +299,6 @@
.. _Authenticated encryption: https://en.wikipedia.org/wiki/Authenticated_encryption
.. _issue #19 on Github: https://github.com/sybrenstuvel/python-rsa/issues/13
-
-As far as we know, there is no pure-Python AES encryption. Previous
-versions of Python-RSA included functionality to encrypt large files
-with just RSA, and so does this version. The format has been improved,
-though.
-
-Encrypting works as follows: the input file is split into blocks that
-are just large enough to encrypt with your RSA key. Every block is
-then encrypted using RSA, and the encrypted blocks are assembled into
-the output file. This file format is called the :ref:`VARBLOCK
-<VARBLOCK>` format.
-
-Decrypting works in reverse. The encrypted file is separated into
-encrypted blocks. Those are decrypted, and assembled into the original
-file.
-
-.. note::
-
- The file will get larger after encryption, as each encrypted block
- has 8 bytes of random padding and 3 more bytes of overhead.
-
-Since these encryption/decryption functions are potentially called on
-very large files, they use another approach. Where the regular
-functions store the message in memory in its entirety, these functions
-work on one block at the time. As a result, you should call them with
-:py:class:`file`-like objects as the parameters.
-
-Before using we of course need a keypair:
-
->>> import rsa
->>> (pub_key, priv_key) = rsa.newkeys(512)
-
-Encryption works on file handles using the
-:py:func:`rsa.bigfile.encrypt_bigfile` function:
-
->>> from rsa.bigfile import *
->>> with open('inputfile', 'rb') as infile, open('outputfile', 'wb') as outfile:
-... encrypt_bigfile(infile, outfile, pub_key)
-
-As does decryption using the :py:func:`rsa.bigfile.decrypt_bigfile`
-function:
-
->>> from rsa.bigfile import *
->>> with open('inputfile', 'rb') as infile, open('outputfile', 'wb') as outfile:
-... decrypt_bigfile(infile, outfile, priv_key)
-
-.. note::
-
- :py:func:`rsa.sign` and :py:func:`rsa.verify` work on arbitrarily
- long files, so they do not have a "bigfile" equivalent.
-
-
+As of Python-RSA version 4.0, the VARBLOCK format has been removed from the
+library. For now, this section is kept here to document the issues with that
+format, and ensure we don't do something like that again.