diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/cli.rst | 55 | ||||
| -rw-r--r-- | doc/compatibility.rst | 6 | ||||
| -rw-r--r-- | doc/conf.py | 4 | ||||
| -rw-r--r-- | doc/installation.rst | 13 | ||||
| -rw-r--r-- | doc/reference.rst | 24 | ||||
| -rw-r--r-- | doc/upgrading.rst | 20 | ||||
| -rw-r--r-- | doc/usage.rst | 102 |
7 files changed, 74 insertions, 150 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..be4d295 100644 --- a/doc/compatibility.rst +++ b/doc/compatibility.rst @@ -16,7 +16,7 @@ Encryption: Signatures: PKCS#1 v1.5 using the following hash methods: - MD5, SHA-1, SHA-256, SHA-384, SHA-512 + MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 Private keys: PKCS#1 v1.5 in PEM and DER format, ASN.1 type RSAPrivateKey @@ -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/conf.py b/doc/conf.py index 95317b2..3331a86 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -28,7 +28,7 @@ import rsa # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', - 'sphinx.ext.coverage', 'sphinx.ext.pngmath'] + 'sphinx.ext.coverage'] # I would like to add 'sphinx.ext.viewcode', but it causes a UnicodeDecodeError @@ -46,7 +46,7 @@ master_doc = 'index' # General information about the project. project = u'Python-RSA' -copyright = u'2011-2016, Sybren A. Stüvel' +copyright = u'2011-2018, Sybren A. Stüvel' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/doc/installation.rst b/doc/installation.rst index 578dc86..32dc257 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -5,23 +5,18 @@ Installation can be done in various ways. The simplest form uses pip or easy_install. Either one will work:: pip install rsa - easy_install rsa -Depending on your system you may need to use ``sudo pip`` or ``sudo -easy_install``. +Depending on your system you may need to use ``sudo pip`` if you want to install +the library system-wide. Installation from source is also quite easy. Download the source and then type:: python setup.py install -or if that doesn't work:: - - sudo python setup.py install - The sources are tracked in our `Git repository`_ at -Github. It also hosts the `issue tracker`_. +GitHub. It also hosts the `issue tracker`_. .. _`Git repository`: https://github.com/sybrenstuvel/python-rsa.git .. _`issue tracker`: https://github.com/sybrenstuvel/python-rsa/issues @@ -49,7 +44,7 @@ pip to install the development requirements in a virtual environment:: Once these are installed, use Git_ to get a copy of the source:: - hg clone https://github.com/sybrenstuvel/python-rsa.git + git clone https://github.com/sybrenstuvel/python-rsa.git python setup.py develop .. _Git: https://git-scm.com/ diff --git a/doc/reference.rst b/doc/reference.rst index d1b0b6d..9da7c6b 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -15,6 +15,8 @@ Functions .. autofunction:: rsa.verify +.. autofunction:: rsa.find_signature_hash + .. autofunction:: rsa.newkeys(keysize) @@ -49,32 +51,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 +92,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..b1244d4 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -13,13 +13,13 @@ and a public key. The private key is called *private* for a reason. Never share this key with anyone. -The public key is used for encypting a message such that it can only +The public key is used for encrypting a message such that it can only be read by the owner of the private key. As such it's also referred to as the *encryption key*. Decrypting a message can only be done using the private key, hence it's also called the *decryption key*. The private key is used for signing a message. With this signature and -the public key, the receiver can verifying that a message was signed +the public key, the receiver can verify that a message was signed by the owner of the private key, and that the message was not modified after signing. @@ -90,32 +90,6 @@ generate them for you, then load them in your Python code. OpenSSL generates a 4096-bit key in 3.5 seconds on the same machine as used above. See :ref:`openssl` for more information. -Key size requirements ---------------------- - -Python-RSA version 3.0 introduced PKCS#1-style random padding. This -means that 11 bytes (88 bits) of your key are no longer usable for -encryption, so keys smaller than this are unusable. The larger the -key, the higher the security. - -Creating signatures also requires a key of a certain size, depending -on the used hash method: - -+-------------+-----------------------------------+ -| Hash method | Suggested minimum key size (bits) | -+=============+===================================+ -| MD5 | 360 | -+-------------+-----------------------------------+ -| SHA-1 | 368 | -+-------------+-----------------------------------+ -| SHA-256 | 496 | -+-------------+-----------------------------------+ -| SHA-384 | 624 | -+-------------+-----------------------------------+ -| SHA-512 | 752 | -+-------------+-----------------------------------+ - - Encryption and decryption ------------------------- @@ -198,11 +172,20 @@ 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. +It is possible to calculate the hash and signature in separate operations +(i.e for generating the hash on a client machine and then sign with a +private key on remote server). To hash a message use the :py:func:`rsa.compute_hash` +function and then use the :py:func:`rsa.sign_hash` function to sign the hash: + + >>> message = 'Go left at the blue tree' + >>> hash = rsa.compute_hash(message, 'SHA-1') + >>> signature = rsa.sign_hash(hash, privkey, 'SHA-1') + In order to verify the signature, use the :py:func:`rsa.verify` function. This function returns True if the verification is successful: @@ -285,7 +268,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 @@ -294,60 +277,11 @@ Only using Python-RSA: the VARBLOCK format 2. decrypt/encrypt_bigfile() does not use hybrid encryption (it uses plain RSA) and has no method for chaining, so block reordering is possible. - See `issue #19 on Github`_ for more information. + See `issue #19 on GitHub`_ for more information. .. _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. - +.. _issue #19 on GitHub: https://github.com/sybrenstuvel/python-rsa/issues/13 +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. |