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.
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 .
Rsa python private key
RSA is the most widespread and used public key algorithm. Its security is based on the difficulty of factoring large integers. The algorithm has withstood attacks for more than 30 years, and it is therefore considered reasonably secure for new designs.
The algorithm can be used for both confidentiality (encryption) and authentication (digital signature). It is worth noting that signing and decryption are significantly slower than verification and encryption.
The cryptographic strength is primarily linked to the length of the RSA modulus n. In 2017, a sufficient length is deemed to be 2048 bits. For more information, see the most recent ECRYPT report.
Both RSA ciphertexts and RSA signatures are as large as the RSA modulus n (256 bytes if n is 2048 bit long).
The module Crypto.PublicKey.RSA provides facilities for generating new RSA keys, reconstructing them from known components, exporting them, and importing them.
As an example, this is how you generate a new RSA key pair, save it in a file called mykey.pem , and then read it back:
>>> from Crypto.PublicKey import RSA >>> >>> key = RSA.generate(2048) >>> f = open('mykey.pem','wb') >>> f.write(key.export_key('PEM')) >>> f.close() . >>> f = open('mykey.pem','r') >>> key = RSA.import_key(f.read())
Class defining an actual RSA key. Do not instantiate directly. Use generate() , construct() or import_key() instead.
- n (integer) – RSA modulus
- e (integer) – RSA public exponent
- d (integer) – RSA private exponent
- p (integer) – First factor of the RSA modulus
- q (integer) – Second factor of the RSA modulus
- invp (integer) – Chinese remainder component ( \(p^ \text q\) )
- invq (integer) – Chinese remainder component ( \(q^ \text p\) )
- u (integer) – Same as invp
exportKey ( format = ‘PEM’ , passphrase = None , pkcs = 1 , protection = None , randfunc = None ) ¶
- format (string) – The format to use for wrapping the key:
- ’PEM’. (Default) Text encoding, done according to RFC1421/RFC1423.
- ’DER’. Binary encoding.
- ’OpenSSH’. Textual encoding, done according to OpenSSH specification. Only suitable for public keys (not private keys).
Note This parameter is ignored for a public key. For DER and PEM, an ASN.1 DER SubjectPublicKeyInfo structure is always used.
- A 16 byte Triple DES key is derived from the passphrase using Crypto.Protocol.KDF.PBKDF2() with 8 bytes salt, and 1 000 iterations of Crypto.Hash.HMAC .
- The private key is encrypted using CBC.
- The encrypted key is encoded according to PKCS#8.
Specifying a value for protection is only meaningful for PKCS#8 (that is, pkcs=8 ) and only if a pass phrase is present too.
The supported schemes for PKCS#8 are listed in the Crypto.IO.PKCS8 module (see wrap_algo parameter).
ValueError – when the format is unknown or when you try to encrypt a private key with DER format and PKCS#1.
If you don’t provide a pass phrase, the private key will be exported in the clear!
- format (string) – The format to use for wrapping the key:
- ’PEM’. (Default) Text encoding, done according to RFC1421/RFC1423.
- ’DER’. Binary encoding.
- ’OpenSSH’. Textual encoding, done according to OpenSSH specification. Only suitable for public keys (not private keys).
Note This parameter is ignored for a public key. For DER and PEM, an ASN.1 DER SubjectPublicKeyInfo structure is always used.
- A 16 byte Triple DES key is derived from the passphrase using Crypto.Protocol.KDF.PBKDF2() with 8 bytes salt, and 1 000 iterations of Crypto.Hash.HMAC .
- The private key is encrypted using CBC.
- The encrypted key is encoded according to PKCS#8.
Specifying a value for protection is only meaningful for PKCS#8 (that is, pkcs=8 ) and only if a pass phrase is present too.
The supported schemes for PKCS#8 are listed in the Crypto.IO.PKCS8 module (see wrap_algo parameter).
ValueError – when the format is unknown or when you try to encrypt a private key with DER format and PKCS#1.
If you don’t provide a pass phrase, the private key will be exported in the clear!
Whether this is an RSA private key
A matching RSA public key.
A matching RSA public key.
Size of the RSA modulus in bits
The minimal amount of bytes that can hold the RSA modulus
Crypto.PublicKey.RSA. construct ( rsa_components , consistency_check = True ) ¶
Construct an RSA key from a tuple of valid RSA components.
The modulus n must be the product of two primes. The public exponent e must be odd and larger than 1.
In case of a private key, the following equations must apply:
- rsa_components (tuple) – A tuple of integers, with at least 2 and no more than 6 items. The items come in the following order:
- RSA modulus n.
- Public exponent e.
- Private exponent d. Only required if the key is private.
- First factor of n (p). Optional, but the other factor q must also be present.
- Second factor of n (q). Optional.
- CRT coefficient q, that is \(p^ \textq\) . Optional.
ValueError – when the key being imported fails the most basic RSA validity checks.
Returns: An RSA key object ( RsaKey ).
Crypto.PublicKey.RSA. generate ( bits , randfunc = None , e = 65537 ) ¶
Create a new RSA key pair.
The algorithm closely follows NIST FIPS 186-4 in its sections B.3.1 and B.3.3. The modulus is the product of two non-strong probable primes. Each prime passes a suitable number of Miller-Rabin tests with random bases and a single Lucas test.
- bits (integer) – Key length, or size (in bits) of the RSA modulus. It must be at least 1024, but 2048 is recommended. The FIPS standard only defines 1024, 2048 and 3072.
- randfunc (callable) – Function that returns random bytes. The default is Crypto.Random.get_random_bytes() .
- e (integer) – Public RSA exponent. It must be an odd positive integer. It is typically a small number with very few ones in its binary representation. The FIPS standard requires the public exponent to be at least 65537 (the default).
Returns: an RSA key object ( RsaKey , with private key).
Crypto.PublicKey.RSA. import_key ( extern_key , passphrase = None ) ¶
Import an RSA key (public or private).
- extern_key (stringorbyte string) – The RSA key to import. The following formats are supported for an RSA public key:
- X.509 certificate (binary or PEM format)
- X.509 subjectPublicKeyInfo DER SEQUENCE (binary or PEM encoding)
- PKCS#1 RSAPublicKey DER SEQUENCE (binary or PEM encoding)
- An OpenSSH line (e.g. the content of ~/.ssh/id_ecdsa , ASCII)
The following formats are supported for an RSA private key:
- PKCS#1 RSAPrivateKey DER SEQUENCE (binary or PEM encoding)
- PKCS#8 PrivateKeyInfo or EncryptedPrivateKeyInfo DER SEQUENCE (binary or PEM encoding)
- OpenSSH (text format, introduced in OpenSSH 6.5)
For details about the PEM encoding, see RFC1421/RFC1423.
Returns: An RSA key object ( RsaKey ).
ValueError/IndexError/TypeError – When the given key cannot be parsed (possibly because the pass phrase is wrong).
Crypto.PublicKey.RSA. oid = ‘1.2.840.113549.1.1.1’ ¶
Object ID for the RSA encryption algorithm. This OID often indicates a generic RSA key, even when such key will be actually used for digital signatures.