5. Usage — Python-RSA 4.8 documentation (2024)

Important

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

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() andrsa.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)

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

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 messagethat only Bob can read.

1. Bob generates a key pair, and gives the public key to Alice. This isdone 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 moduleonly operates on bytes, and not on strings, so this step isnecessary.

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

3. Alice encrypts the message using Bob’s public key, and sends theencrypted 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 isthe only one who can read the message. Bob does not know for surethat 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 coupleof bytes are lost on random padding, and the rest is available for themessage itself. For example, a 512-bit key can encode a 53-bytemessage (512 bit = 64 bytes, 11 bytes are used for random padding andother stuff). See Working with big files for information on how to work withlarger files.

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

5.3. Signing and verification¶

You can create a detached signature for a message using thersa.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 alsopossible, check the rsa.sign() function documentation fordetails. 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 aprivate 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 returnsthe 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 arsa.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

Instead of a message you can also call rsa.sign() andrsa.verify() with a file-like object. If themessage 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 coupleof bytes are lost on random padding, and the rest is available for themessage itself. For example, a 512-bit key can encode a 53-bytemessage (512 bit = 64 bytes, 11 bytes are used for random padding andother stuff).