Updated documentation for removal of bigfile/VARBLOCK support.

5 files changed, 52 insertions, 108 deletions

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 @@ on how to use them. Here is a short overview:
 .. 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 @@ Public keys:
     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 @@ PKCS#8 format you need an external tool such as OpenSSL::
     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 @@ Exceptions
 
 .. 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 @@ the core of the entire library.
 .. 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 @@ less secure code into your project.
 
 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 @@ older version of Python-RSA, use the following::
 
     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 @@ You can create a detached signature for a message using the
     >>> (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 @@ Only using Python-RSA: the VARBLOCK 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 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 @@ Only using Python-RSA: the VARBLOCK format
 .. _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.