Skip to content

mTLS Helpers

lacme.mtls

mTLS SSL context helpers.

Provides :func:server_ssl_context and :func:client_ssl_context for creating :class:ssl.SSLContext objects configured for mutual TLS. Also provides :func:write_pem_files and :func:pem_files for writing PEM data to secure temporary files (useful for uvicorn which only accepts file paths). Accepts PEM data as bytes or file paths as str/:class:~pathlib.Path.

PemInput module-attribute 

PemInput = bytes | str | Path

PEM data (bytes) or a file path (str or Path).

PemPaths dataclass

Paths to PEM files written by :func:write_pem_files.

as_uvicorn_kwargs 
as_uvicorn_kwargs() -> dict[str, str]

Return kwargs suitable for uvicorn.run().

When ca is set, includes ssl_ca_certs. To enforce mTLS (require client certificates), also pass ssl_cert_reqs=ssl.CERT_REQUIRED to uvicorn — it defaults to CERT_NONE even when ssl_ca_certs is provided.

client_ssl_context 

client_ssl_context(*, cert_pem: PemInput | None = None, key_pem: PemInput | None = None, ca_cert_pem: PemInput | None = None) -> ssl.SSLContext

Create a TLS client context for mTLS connections.

Parameters:

Name Type Description Default
cert_pem PemInput | None

Client certificate to present (PEM bytes or file path).

 None
key_pem PemInput | None

Client private key (PEM bytes or file path).

 None
ca_cert_pem PemInput | None

CA certificate for verifying the server (PEM bytes or file path). Overrides the system default trust store.

 None

Returns:

Name Type Description
Configured SSLContext

class:ssl.SSLContext with TLSv1.2 minimum.

pem_files 

pem_files(bundle: CertBundle, ca_pem: bytes | None = None, directory: Path | str | None = None) -> Generator[PemPaths, None, None]

Context manager: write PEM files and clean up on exit.

Usage::

with pem_files(bundle, ca_pem=ca.root_cert_pem) as paths:
    uvicorn.run("app:app", **paths.as_uvicorn_kwargs())
# temp files deleted automatically

server_ssl_context 

server_ssl_context(*, cert_pem: PemInput, key_pem: PemInput, ca_cert_pem: PemInput | None = None) -> ssl.SSLContext

Create a TLS server context, optionally requiring client certificates.

Parameters:

Name Type Description Default
cert_pem PemInput

Server certificate (PEM bytes or file path).

 required
key_pem PemInput

Server private key (PEM bytes or file path).

 required
ca_cert_pem PemInput | None

CA certificate for verifying clients (PEM bytes or file path). When provided, the context requires client certificates (CERT_REQUIRED).

 None

Returns:

Name Type Description
Configured SSLContext

class:ssl.SSLContext with TLSv1.2 minimum.

write_pem_files 

write_pem_files(bundle: CertBundle, ca_pem: bytes | None = None, directory: Path | str | None = None) -> PemPaths

Write certificate PEM data to secure temporary files.

Creates a directory with 0o700 permissions containing cert/CA files (0o644) and the private key (0o600). Useful for uvicorn and other servers that only accept file paths.

The caller is responsible for cleanup. For automatic cleanup, use :func:pem_files (context manager) instead.

Parameters:

Name Type Description Default
bundle CertBundle

Certificate bundle with fullchain_pem and key_pem.

 required
ca_pem bytes | None

Optional CA certificate PEM bytes.

 None
directory Path | str | None

Parent directory for the temp dir. Defaults to system temp.

 None

Returns:

Type Description
PemPaths

class:PemPaths with file paths.

write_pem_files_persistent 

write_pem_files_persistent(bundle: CertBundle, ca_pem: bytes | None = None, directory: Path | str | None = None) -> PemPaths

Like :func:write_pem_files but registers atexit cleanup.

Suitable for long-lived processes where a context manager is inconvenient (e.g., passing paths to uvicorn before app.run()).