Package Cryptodome :: Package PublicKey :: Module RSA

Module RSA

RSA public-key cryptography algorithm (signature and encryption).

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 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 cryptograhic strength is primarily linked to the length of the modulus n. In 2012, a sufficient length is deemed to be 2048 bits. For more information, see the most recent ECRYPT report.

Both RSA ciphertext and RSA signature are as big as the modulus n (256 bytes if n is 2048 bit long).

This module provides facilities for generating fresh, new RSA keys, constructing them from known components, exporting them, and importing them.

>>> from Cryptodome.PublicKey import RSA
>>>
>>> key = RSA.generate(2048)
>>> f = open('mykey.pem','w')
>>> f.write(key.exportKey('PEM'))
>>> f.close()
...
>>> f = open('mykey.pem','r')
>>> key = RSA.import_key(f.read())

Even though you may choose to directly use the methods of an RSA key object to perform the primitive cryptographic operations (e.g. RsaKey._encrypt), it is recommended to use one of the standardized schemes instead (like Cryptodome.Cipher.PKCS1_v1_5 or Cryptodome.Signature.PKCS1_v1_5).

Classes
  RsaKey
Class defining an actual RSA key.
Functions
 
generate(bits, randfunc=None, e=65537)
Create a new RSA key.
 
construct(rsa_components, consistency_check=True)
Construct an RSA key from a tuple of valid RSA components.
 
import_key(extern_key, passphrase=None)
Import an RSA key (public or private half), encoded in standard form.
Variables
  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.
Function Details

generate(bits, randfunc=None, e=65537)

 

Create a new RSA key.

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.

Parameters:
  • bits (integer) - Key length, or size (in bits) of the RSA modulus. It must be at least 1024. The FIPS standard only defines 1024, 2048 and 3072.
  • randfunc (callable) - Function that returns random bytes. The default is Cryptodome.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).

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:

  • e != 1
  • p*q = n
  • e*d = 1 mod lcm[(p-1)(q-1)]
  • p*u = 1 mod q
Parameters:
  • rsa_components (tuple) - A tuple of long integers, with at least 2 and no more than 6 items. The items come in the following order:

    1. RSA modulus (n).
    2. Public exponent (e).
    3. Private exponent (d). Only required if the key is private.
    4. First factor of n (p). Optional, but factor q must also be present.
    5. Second factor of n (q). Optional.
    6. CRT coefficient, (1/p) mod q (u). Optional.
  • consistency_check (boolean) - If True, the library will verify that the provided components fulfil the main RSA properties.
Returns:
An RSA key object (RsaKey).
Raises:
  • ValueError - When the key being imported fails the most basic RSA validity checks.

import_key(extern_key, passphrase=None)

 

Import an RSA key (public or private half), encoded in standard form.

Parameters:
  • extern_key (string) - The RSA key to import, encoded as a byte string.

    An RSA public key can be in any of the following formats:

    • 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)
    • OpenSSH (textual public key only)

    An RSA private key can be in any of the following formats:

    • PKCS#1 RSAPrivateKey DER SEQUENCE (binary or PEM encoding)
    • PKCS#8 PrivateKeyInfo or EncryptedPrivateKeyInfo DER SEQUENCE (binary or PEM encoding)
    • OpenSSH (textual public key only)

    For details about the PEM encoding, see RFC1421/RFC1423.

    The private key may be encrypted by means of a certain pass phrase either at the PEM level or at the PKCS#8 level.

  • passphrase (string) - In case of an encrypted private key, this is the pass phrase from which the decryption key is derived.
Returns:
An RSA key object (RsaKey).
Raises:
  • ValueError/IndexError/TypeError - When the given key cannot be parsed (possibly because the pass phrase is wrong).