From 1d14c4e6c6c78acb2af553cdbc4fe23fc72024b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= Date: Mon, 10 Apr 2017 11:31:09 +0200 Subject: Updated documentation for removal of bigfile/VARBLOCK support. --- doc/cli.rst | 55 +++++++++++++++++++++++------------------------ doc/compatibility.rst | 4 ++-- doc/reference.rst | 22 +------------------ doc/upgrading.rst | 20 ++++++++++++++--- doc/usage.rst | 59 +++++---------------------------------------------- 5 files changed, 52 insertions(+), 108 deletions(-) (limited to 'doc') 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 ` 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 -` 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. -- cgit v1.2.1