sslcontext

Client certificates whose private keys never leave the OS keystore, in a plain ssl.SSLContext. sslcontext signs TLS handshakes through Windows CNG, the macOS Keychain or a PKCS#11 token (smart cards included), so every library that accepts an ssl_context gets mutual TLS with no patching, no temporary key files and no compiled extension; system_context() also picks the certificate as the browser would. Documentation: https://jose-pr.github.io/sslcontext/.

Features

• Keystore identities in stdlib ssl — non-exportable and smart-card keys work, because the key is used through the keystore, never copied.
• Pure Python — ctypes over the OpenSSL that Python itself loaded: an OpenSSL 3 provider on modern builds, an OpenSSL 1.1 engine on older ones.
• In-memory credentials — load PEM or PKCS#12 bytes into a context without writing a key to disk.
• Never blocks on a PIN — PINs and passwords come from a value or a callback you write; with none, operations fail at once. Keystore dialogs and PIN pads are opt-in.
• The system's context — system_context(): the OS verifies servers (truststore) and, when a server asks, the client certificate is chosen as the browser would: from the system's keystores, matching the CAs the server names, following Edge's and Chrome's AutoSelectCertificateForUrls policy, your rules or your callback, and never blocking.
• One context builder — create_context() for the verify/cafile/capath combinations every HTTP client reimplements.

Keystores

Installation

pip install sslcontext

Quick start

Behave like the system's browser: the OS verifies the server, and when a server asks for a client certificate the matching one is chosen from the system's keystores. Build it once and share it:

import urllib.request
import sslcontext

ctx = sslcontext.system_context()
urllib.request.urlopen("https://intranet.example.com/", context=ctx)

A client certificate and key, from files, PEM text, bytes, pathlib paths or cryptography objects alike:

import sslcontext

ctx = sslcontext.create_context(ca="ca.pem", certificate="client.pem", key=key_pem)

Use a certificate from the Windows store whose key cannot be exported:

import urllib.request
import sslcontext
from sslcontext.backends import CNGBackend

ctx = sslcontext.create_context()
sslcontext.load_identity(ctx, CNGBackend().find_identity(subject="alice"))
urllib.request.urlopen("https://mtls.example.com/", context=ctx)

Use a smart card through its PKCS#11 module. The PIN callback decides how the PIN is obtained; with no PIN, signing fails instead of waiting:

from getpass import getpass
from sslcontext.backends import PKCS11Backend

def pin(request: sslcontext.PinRequest):
    if request.purpose == "list":
        return None  # list without logging in
    return getpass(f"PIN for {request.token}: ")

card = PKCS11Backend(pin=pin)
sslcontext.load_identity(ctx, card.find_identity(subject="alice"))

API overview

Command line

pip install "sslcontext[cli]" adds sslcontext: sslcontext list shows the client certificates the system's keystores hold, and sslcontext probe https://intranet.example/ shows what a server asks for and which certificate answers it.

Development

dotagents pyvenv && dotagents pyvenv 3.9
.pyvenv/<tag>/Scripts/python -m pip install -e ".[dev]"
.pyvenv/<tag>/Scripts/python -m pytest -q -rs

Releasing

This project follows Semantic Versioning and keeps a CHANGELOG.md. Pushing a tag matching v* triggers the release workflow: test gate → build (checking the tag names the version built) → a strict docs build as a gate → GitHub release → publish. The release workflow never deploys the docs site itself: for a final release its last job dispatches the docs workflow at the tag, which owns every Pages deploy.

License

MIT — see LICENSE.