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