X.509 Path Validation

synta.x509 verifies RFC 5280 / CABF TLS server and client certificate chains.

import synta.x509 as x509

Classes

TrustStore

A set of trusted root CA certificates used as trust anchors for chain verification.

x509.TrustStore(ders: list[bytes])

Construct a TrustStore from a list of DER-encoded CA certificates.

CrlStore

A set of Certificate Revocation Lists for revocation checking.

x509.CrlStore(ders: list[bytes])

Construct a CrlStore from a list of DER-encoded CRLs.

VerificationPolicy

Policy parameters for chain verification.

x509.VerificationPolicy(
    server_names: list[str] | None = None,
    name_match: str = "any",
    validation_time: float | None = None,
    max_chain_depth: int | None = None,
    profile: str | None = None,
)

X509VerificationError

Raised on any chain or policy failure. Subclass of Exception.

try:
    x509.verify_server_certificate(...)
except x509.X509VerificationError as exc:
    print(f"verification failed: {exc}")

Functions

x509.verify_server_certificate(
    leaf: bytes | Certificate,
    intermediates: list[bytes | Certificate],
    store: TrustStore,
    policy: VerificationPolicy,
    crls: CrlStore | None = None,
) -> list[bytes]

Verify a TLS server certificate chain. Returns the verified chain as a list of DER-encoded certificates in order from trust anchor to leaf.

x509.verify_client_certificate(
    leaf: bytes | Certificate,
    intermediates: list[bytes | Certificate],
    store: TrustStore,
    policy: VerificationPolicy,
    crls: CrlStore | None = None,
) -> list[bytes]

Verify a TLS client certificate chain. Same return type as verify_server_certificate.

Usage

import synta
import synta.x509 as x509

# Load trust anchors from a PEM bundle
with open("roots.pem", "rb") as f:
    ders = synta.pem_to_der(f.read())
store = x509.TrustStore(ders)

# Verify a server certificate (single name)
with open("leaf.der", "rb") as f:
    leaf_der = f.read()
with open("intermediate.der", "rb") as f:
    intermediate_der = f.read()

policy = x509.VerificationPolicy(server_names=["example.com"])
chain  = x509.verify_server_certificate(leaf_der, [intermediate_der], store, policy)

for i, cert_der in enumerate(chain):
    cert = synta.Certificate.from_der(cert_der)
    role = "trust anchor" if i == 0 else ("leaf" if i == len(chain) - 1 else "CA")
    print(f"chain[{i}] ({role}): {cert.subject}")

# Multi-name any-match (cert must cover at least one name)
policy = x509.VerificationPolicy(
    server_names=["example.com", "www.example.com"],
    name_match="any",
)

# Multi-name all-match (cert must cover every name)
policy = x509.VerificationPolicy(
    server_names=["example.com", "api.example.com"],
    name_match="all",
)

# Error handling
try:
    chain = x509.verify_server_certificate(leaf_der, [], store, policy)
except x509.X509VerificationError as exc:
    print(f"verification failed: {exc}")

See also Certificate for verify_issued_by (single-issuer signature check without a full chain build) and Error Handling for the exception hierarchy.