doc/usage.rst

.. _usage:

Usage
=====

This section describes the usage of the Python-RSA module.

Before you can use RSA you need keys. You will receive a private key
and a public key.

.. important::

    The private key is called *private* for a reason. Never share this
    key with anyone.

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 verify that a message was signed
by the owner of the private key, and that the message was not modified
after signing.


Generating keys
---------------

You can use the :py:func:`rsa.newkeys` function to create a keypair:

    >>> import rsa
    >>> (pubkey, privkey) = rsa.newkeys(512)

Alternatively you can use :py:meth:`rsa.PrivateKey.load_pkcs1` and
:py:meth:`rsa.PublicKey.load_pkcs1` to load keys from a file:

    >>> import rsa
    >>> with open('private.pem', mode='rb') as privatefile:
    ...     keydata = privatefile.read()
    >>> privkey = rsa.PrivateKey.load_pkcs1(keydata)


Time to generate a key
++++++++++++++++++++++

Generating a keypair may take a long time, depending on the number of
bits required. The number of bits determines the cryptographic
strength of the key, as well as the size of the message you can
encrypt. If you don't mind having a slightly smaller key than you
requested, you can pass ``accurate=False`` to speed up the key
generation process.

Another way to speed up the key generation process is to use multiple
processes in parallel to speed up the key generation. Use no more than
the number of processes that your machine can run in parallel; a
dual-core machine should use ``poolsize=2``; a quad-core
hyperthreading machine can run two threads on each core, and thus can
use ``poolsize=8``.

    >>> (pubkey, privkey) = rsa.newkeys(512, poolsize=8)

These are some average timings from my desktop machine (Linux 2.6,
2.93 GHz quad-core Intel Core i7, 16 GB RAM) using 64-bit CPython 2.7.
Since key generation is a random process, times may differ even on
similar hardware. On all tests, we used the default ``accurate=True``.

+----------------+------------------+------------------+
| Keysize (bits) | single process   | eight processes  |
+================+==================+==================+
| 128            | 0.01 sec.        | 0.01 sec.        |
+----------------+------------------+------------------+
| 256            | 0.03 sec.        | 0.02 sec.        |
+----------------+------------------+------------------+
| 384            | 0.09 sec.        | 0.04 sec.        |
+----------------+------------------+------------------+
| 512            | 0.11 sec.        | 0.07 sec.        |
+----------------+------------------+------------------+
| 1024           | 0.79 sec.        | 0.30 sec.        |
+----------------+------------------+------------------+
| 2048           | 6.55 sec.        | 1.60 sec.        |
+----------------+------------------+------------------+
| 3072           | 23.4 sec.        | 7.14 sec.        |
+----------------+------------------+------------------+
| 4096           | 72.0 sec.        | 24.4 sec.        |
+----------------+------------------+------------------+

If key generation is too slow for you, you could use OpenSSL to
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.


Encryption and decryption
-------------------------

To encrypt or decrypt a message, use :py:func:`rsa.encrypt` resp.
:py:func:`rsa.decrypt`. Let's say that Alice wants to send a message
that only Bob can read.

#. Bob generates a keypair, and gives the public key to Alice. This is
   done such that Alice knows for sure that the key is really Bob's
   (for example by handing over a USB stick that contains the key).

    >>> import rsa
    >>> (bob_pub, bob_priv) = rsa.newkeys(512)

#. Alice writes a message, and encodes it in UTF-8. The RSA module
   only operates on bytes, and not on strings, so this step is
   necessary.

    >>> message = 'hello Bob!'.encode('utf8')

#. Alice encrypts the message using Bob's public key, and sends the
   encrypted message.

    >>> import rsa
    >>> crypto = rsa.encrypt(message, bob_pub)

#. Bob receives the message, and decrypts it with his private key.

    >>> message = rsa.decrypt(crypto, bob_priv)
    >>> print(message.decode('utf8'))
    hello Bob!

Since Bob kept his private key *private*, Alice can be sure that he is
the only one who can read the message. Bob does *not* know for sure
that it was Alice that sent the message, since she didn't sign it.


RSA can only encrypt messages that are smaller than the key. A couple
of bytes are lost on random padding, and the rest is available for the
message itself. For example, a 512-bit key can encode a 53-byte
message (512 bit = 64 bytes, 11 bytes are used for random padding and
other stuff). See :ref:`bigfiles` for information on how to work with
larger files.

Altering the encrypted information will *likely* cause a
:py:class:`rsa.pkcs1.DecryptionError`. If you want to be *sure*, use
:py:func:`rsa.sign`.

    >>> crypto = rsa.encrypt(b'hello', bob_pub)
    >>> crypto = crypto[:-1] + b'X' # change the last byte
    >>> rsa.decrypt(crypto, bob_priv)
    Traceback (most recent call last):
    ...
    rsa.pkcs1.DecryptionError: Decryption failed


.. warning::

    Never display the stack trace of a
    :py:class:`rsa.pkcs1.DecryptionError` exception. It shows where
    in the code the exception occurred, and thus leaks information
    about the key. It’s only a tiny bit of information, but every bit
    makes cracking the keys easier.

Low-level operations
++++++++++++++++++++

The core RSA algorithm operates on large integers. These operations
are considered low-level and are supported by the
:py:func:`rsa.core.encrypt_int` and :py:func:`rsa.core.decrypt_int`
functions.

Signing and verification
------------------------

You can create a detached signature for a message using the
:py:func:`rsa.sign` function:

    >>> (pubkey, privkey) = rsa.newkeys(512)
    >>> message = 'Go left at the blue tree'.encode()
    >>> 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'.encode()
    >>> 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:

    >>> message = 'Go left at the blue tree'.encode()
    >>> rsa.verify(message, signature, pubkey)
    True

Modify the message, and the signature is no longer valid and a
:py:class:`rsa.pkcs1.VerificationError` is thrown:

    >>> message = 'Go right at the blue tree'.encode()
    >>> rsa.verify(message, signature, pubkey)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "/home/sybren/workspace/python-rsa/rsa/pkcs1.py", line 289, in verify
        raise VerificationError('Verification failed')
    rsa.pkcs1.VerificationError: Verification failed

.. warning::

    Never display the stack trace of a
    :py:class:`rsa.pkcs1.VerificationError` exception. It shows where
    in the code the exception occurred, and thus leaks information
    about the key. It's only a tiny bit of information, but every bit
    makes cracking the keys easier.

Instead of a message you can also call :py:func:`rsa.sign` and
:py:func:`rsa.verify` with a :py:class:`file`-like object. If the
message object has a ``read(int)`` method it is assumed to be a file.
In that case the file is hashed in 1024-byte blocks at the time.

    >>> with open('somefile', 'rb') as msgfile:
    ...     signature = rsa.sign(msgfile, privkey, 'SHA-1')

    >>> with open('somefile', 'rb') as msgfile:
    ...     rsa.verify(msgfile, signature, pubkey)


.. _bigfiles:

Working with big files
----------------------

RSA can only encrypt messages that are smaller than the key. A couple
of bytes are lost on random padding, and the rest is available for the
message itself. For example, a 512-bit key can encode a 53-byte
message (512 bit = 64 bytes, 11 bytes are used for random padding and
other stuff).

How it usually works
++++++++++++++++++++

The most common way to use RSA with larger files uses a block cypher
like AES or DES3 to encrypt the file with a random key, then encrypt
the random key with RSA. You would send the encrypted file along with
the encrypted key to the recipient. The complete flow is:

#. Generate a random key

    >>> import rsa.randnum
    >>> aes_key = rsa.randnum.read_random_bits(128)

#. Use that key to encrypt the file with AES.
#. :py:func:`Encrypt <rsa.encrypt>` the AES key with RSA

    >>> encrypted_aes_key = rsa.encrypt(aes_key, public_rsa_key)

#. Send the encrypted file together with ``encrypted_aes_key``
#. The recipient now reverses this process to obtain the encrypted
   file.

.. note::

    The Python-RSA module does not contain functionality to do the AES
    encryption for you.

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 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
       uses MACs to verify messages before decrypting public key encrypted messages.

    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.

.. _Authenticated encryption: https://en.wikipedia.org/wiki/Authenticated_encryption
.. _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.