Trustme: TLS Certs for Testing

1.2.1 · active · verified Sun Apr 12

Trustme is a tiny Python package designed to generate fake (but technically real) TLS certificates for use in test suites. It provides a simple way to create a certificate authority (CA) and issue server certificates, which can then be used to configure SSL context objects for testing network clients and servers. The current version is 1.2.1, with releases typically tied to Python version support and bug fixes.

Warnings

breaking Support for older Python versions has been removed. Version 1.2.0 removed support for Python 3.8 and PyPy 3.9. Version 1.1.0 removed support for Python 3.7.
Fix: Ensure your project is running on Python 3.9+ (3.10+ recommended for full compatibility with latest versions) and update your Python environment if necessary.
deprecated The use of deprecated `pyOpenSSL` APIs has been updated to non-deprecated `cryptography` APIs in version 1.2.1. While `trustme` handles this internally, users relying on specific `pyOpenSSL` patterns for deeper integration might need to review their code if migrating from very old `trustme` versions or directly manipulating `pyOpenSSL` objects exposed by `trustme`.
Fix: Upgrade to `trustme` 1.2.1 or newer. Review any direct interactions with `pyOpenSSL` objects obtained from `trustme` to ensure compatibility with `cryptography`-backed APIs.
deprecated The `--common-name` option in the command-line interface (`python -m trustme`) is deprecated. Common Name (CN) is a legacy field for identifying certificates; modern TLS relies on Subject Alternative Names (SANs).
Fix: Prefer using the `--identities` option for specifying hostnames/IPs for certificates, as this properly populates Subject Alternative Names (SANs).
gotcha The `idna` library, a dependency of `trustme` (via `cryptography` or `pyOpenSSL`), was historically not always explicitly listed as a direct dependency in `trustme`'s `setup.py` or `pyproject.toml` for some package managers, leading to installation or runtime errors.
Fix: While this issue is likely resolved in modern `trustme` distributions, if you encounter `ModuleNotFoundError` for `idna`, explicitly install it: `pip install idna`.

Install

pip install -U trustme Install latest version

Imports

trustme
```
import trustme
```
CA
```
ca = trustme.CA()
```
Main class for creating a Certificate Authority.
LeafCert
```
server_cert = ca.issue_cert('hostname')
```
Class representing a issued certificate, typically obtained from a CA instance.

Quickstart

This quickstart demonstrates how to programmatically create a Certificate Authority (CA), issue a server certificate, and configure both server and client SSL contexts to use and trust these certificates. This setup is ideal for local testing of TLS-secured applications.

import trustme
import ssl

# 1. Create a fake Certificate Authority (CA)
ca = trustme.CA()

# 2. Issue a server certificate signed by the CA
#    The identities specify what hostnames/IPs the cert is valid for
server_cert = ca.issue_cert(b'localhost', '127.0.0.1', '::1', 'test-host.example.org')

# 3. Create an SSLContext for a server
server_context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
server_context.minimum_version = ssl.TLSVersion.TLSv1_2 # Ensure modern TLS

# 4. Configure the server_context to use the issued server certificate
server_cert.configure_cert(server_context)

# 5. Create an SSLContext for a client
client_context = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)
client_context.minimum_version = ssl.TLSVersion.TLSv1_2

# 6. Configure the client_context to trust the CA that signed the server cert
ca.configure_trust(client_context)

print("Certificates and SSL contexts configured successfully.")
# You can now use server_context and client_context in your server/client applications
# For example, with asyncio or trio for network communication.

view raw JSON →