X.509 Certificate and Path Validator

Warnings

• breaking Prior to 0.6.0, the `validation_time` parameter in `CertificateValidator` methods (e.g., `validate_tls_server`) expected a `float` (Unix timestamp). Since 0.6.0, it now exclusively accepts a `datetime.datetime` object.
  Fix: Convert `float` timestamps to `datetime.datetime` objects using `datetime.fromtimestamp(timestamp_float)`.
• breaking In version 0.7.0, the `RevocationChecker` functionality was refactored. It moved to its own class (`certvalidator.revocation_checker.RevocationChecker`), and the `CertificateValidator` constructor now expects a list of `RevocationChecker` instances via the `revocation_checkers` parameter, instead of direct arguments.
  Fix: Instantiate `RevocationChecker` objects (e.g., `CRLChecker()`, `OCSPChecker()`) and pass them as a list to the `revocation_checkers` argument of `CertificateValidator`.
• gotcha Validation will fail if the provided certificate chain (the `intermediate_certs_der` argument to `CertificateValidator`) is incomplete or incorrect, meaning the path from the end-entity certificate to a trusted root cannot be constructed. Always ensure you have the full chain from the server or source.
  Fix: When fetching certificates from a TLS server, use mechanisms that provide the full certificate chain (e.g., `oscrypto.tls.TLSSocket`'s `peer_certificate` and `intermediate_certificates`). If loading from files, ensure all intermediate certificates are present.
• gotcha Since version 0.5.0, `certvalidator` defaults to a 'hard-fail' policy for OCSP responses. If an OCSP response cannot be fetched or is invalid, validation will fail unless explicitly configured otherwise via `OCSPChecker(soft_fail=True)`.
  Fix: If you prefer 'soft-fail' behavior where unresolvable OCSP issues do not halt validation, instantiate `OCSPChecker(soft_fail=True)` and include it in your `revocation_checkers` list.

Install

• pip install certvalidator Install stable version

Imports

• CertificateValidator

  from certvalidator import CertificateValidator

• TrustStore

  from certvalidator.stores import TrustStore

• errors

  from certvalidator import errors

Quickstart

This quickstart demonstrates how to fetch a TLS server's certificate chain using `oscrypto`, load system trust anchors with `TrustStore`, and then validate the certificate path for a specific hostname using `CertificateValidator`.

from datetime import datetime
from oscrypto import tls
from certvalidator import CertificateValidator, errors
from certvalidator.stores import TrustStore

# Target host and port for certificate retrieval
hostname = "google.com"
port = 443

try:
    # Step 1: Obtain the end-entity (leaf) certificate and its chain from a TLS server.
    # oscrypto.tls.TLSSocket provides the full chain (peer_certificate and intermediate_certificates).
    # This establishes a connection to fetch the server's certificate chain.
    connection = tls.TLSSocket(hostname, port, timeout=5)
    
    # The attributes are oscrypto.asymmetric.Certificate objects; dump() gets their DER bytes.
    leaf_cert_der = connection.peer_certificate.dump()
    intermediate_certs_der = [c.dump() for c in connection.intermediate_certificates]
    
    connection.close() # Close the connection once certs are retrieved

    # Step 2: Prepare the trust anchors (root CAs).
    # TrustStore() by default loads system-wide trust anchors (e.g., from OS certificate store).
    # For custom roots, use: SimpleTrustStore([root_ca_der_bytes, ...]).
    trust_store = TrustStore()

    # Step 3: Create a CertificateValidator instance.
    # Arguments: leaf certificate, list of intermediate certificates, and the trust store.
    validator = CertificateValidator(
        leaf_cert_der,
        intermediate_certs_der,
        trust_store=trust_store
    )

    # Step 4: Perform validation for a specific purpose (e.g., TLS server certificate).
    # validate_tls_server verifies hostname, key usage, validity period, and revocation status.
    # validation_time is optional, defaults to datetime.utcnow().
    validation_path = validator.validate_tls_server(hostname, validation_time=datetime.utcnow())
    
    print(f"Certificate for {hostname} is valid.")
    print("Validated path:")
    for cert_in_path in validation_path:
        print(f"  - Subject: {cert_in_path.subject.human_friendly}")
        print(f"    Issuer: {cert_in_path.issuer.human_friendly}")

except errors.PathValidationError as e:
    print(f"Certificate validation failed for {hostname}: {e}")
except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure network connectivity and that 'oscrypto' and 'certvalidator' are installed.")