crypto#

from mitm import crypto

Cryptography functionalities.

crypto.new_RSA()#

Generates an RSA pair.

This function is intended to be utilized with new_X509(). See function new_pair() to understand how to generate a valid RSA and X509 pair for SSL/TLS use.

Parameters:

bits (int) – Size of the RSA key. Defaults to 2048.

Return type:

PKey

crypto.new_X509(state_or_province_name, locality, organization_name, organization_unit_name, common_name, serial_number, time_not_before, time_not_after)#

Generates a non-signed X509 certificate.

This function is intended to be utilized with new_RSA(). See function new_pair() to understand how to generate a valid RSA and X509 pair for SSL/TLS use.

Parameters:

  • country_name (str) – Country name code. Defaults to US.

  • state_or_province_name (str) – State or province name. Defaults to New York.

  • locality (str) – Locality name. Can be any. Defaults to New York.

  • organization_name (str) – Name of the org generating the cert. Defaults to mitm.

  • organization_unit_name (str) – Name of the subunit of the org. Defaults to mitm.

  • common_name (str) – Server name protected by the SSL cert. Defaults to hostname.

  • serial_number (Optional[int]) – A unique serial number. Any number between 0 and 2^64-1. Defaults to random number.

  • time_not_before (int) – Time since cert is valid. 0 means now. Defaults to 0.

  • time_not_after (int) – Time when cert is no longer valid. Defaults to 5 years.

Return type:

X509

LRU_MAX_SIZE#

Max size of the LRU cache used by CertificateAuthority.new_context() method. Defaults to 1024.

Due to limitations of the Python’s SSL module we are unable to load certificates/keys from memory; on every request we must dump the generated cert/key to disk and pass the paths ssl.SSLContext.load_cert_chain() method. For a few requests this is not an issue, but for a large quantity of requests this is a significant performance hit.

To mitigate this issue we cache the generated SSLContext using lru_cache. LRU_MAX_SIZE defines the maximum number of cached ssl.SSLContexts that can be stored in memory at one time. This value can be modified by editing it _before_ CertificateAuthority is used elsewhere.

from mitm import MITM, CertificateAuthority, middleware, protocol, crypto
from pathlib import Path

# Updates the maximum size of the LRU cache.
crypto.LRU_MAX_SIZE = 2048

# Rest of the code goes here.
class CertificateAuthority[source]#

Certificate Authority interface.

__init__(key, cert)[source]#

Generates a certificate authority.

Parameters:

  • key (Optional[PKey]) – Private key of the CA. Generated if not provided.

  • cert (Optional[X509]) – Unsigned certificate of the CA. Generated if not provided.

classmethod init(path)[source]#

Helper init method to initialize or load a CA.

Parameters:

path (Path) – The path where mitm.pem and mitm.key are to be loaded/saved.

new_X509(host)[source]#

Generates a new certificate for the host.

Note

The hostname must be a valid IP address or a valid hostname.

Parameters:

host (str) – Hostname to generate the certificate for.

Return type:

Tuple[X509, PKey]

Returns:

A tuple of the certificate and private key.

new_context(host)[source]#

Generates a new SSLContext with the given X509 certificate and private key.

Parameters:

  • X509 – X509 certificate.

  • PKey – Private key.

Return type:

SSLContext

Returns:

The SSLContext with the certificate loaded.

save(cert_path, key_path)[source]#

Saves the certificate authority and its private key to disk.

Parameters:

  • cert_path (Union[Path, str]) – Path to the certificate file.

  • key_path (Union[Path, str]) – Path to the key file.

classmethod load(cert_path, key_path)[source]#

Loads the certificate authority and its private key from disk.

Parameters:

  • cert_path (Union[Path, str]) – Path to the certificate file.

  • key_path (Union[Path, str]) – Path to the key file.

Return type:

CertificateAuthority