5. 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.

5.1. Generating keys

You can use the rsa.newkeys() function to create a key pair:

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

Alternatively you can use rsa.PrivateKey.load_pkcs1() and 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)

5.1.1. Time to generate a key

Generating a key pair 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 Interoperability with OpenSSL for more information.

5.2. Encryption and decryption

To encrypt or decrypt a message, use rsa.encrypt() resp. rsa.decrypt(). Let’s say that Alice wants to send a message that only Bob can read.

  1. Bob generates a key pair, 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)

  2. 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')

  3. Alice encrypts the message using Bob’s public key, and sends the encrypted message.

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

  4. 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 Working with big files for information on how to work with larger files.

Altering the encrypted information will likely cause a rsa.pkcs1.DecryptionError. If you want to be sure, use 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 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.

5.2.1. Low-level operations

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

5.3. Signing and verification

You can create a detached signature for a message using the 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 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 rsa.compute_hash() function and then use the 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 rsa.verify() function. If the verification is successful, this function returns the hash algorithm used as a string:

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

Modify the message, and the signature is no longer valid and a 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 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 rsa.sign() and rsa.verify() with a 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)

5.4. 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).

5.4.1. 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:

  1. Generate a random key

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

  2. Use that key to encrypt the file with AES.

  3. Encrypt the AES key with RSA

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

  4. Send the encrypted file together with encrypted_aes_key

  5. 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.

5.4.2. 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.

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.