{"id":4469,"library":"certvalidator","title":"X.509 Certificate and Path Validator","description":"certvalidator is a Python library for validating X.509 certificates and certificate paths according to RFC 5280. It provides robust tools for checking certificate validity, revocation status (CRL and OCSP), and trust chains. The current version is 0.11.1, and it typically sees updates every few months for minor versions, with occasional major version bumps.","status":"active","version":"0.11.1","language":"en","source_language":"en","source_url":"https://github.com/wbond/certvalidator","tags":["security","ssl","tls","x509","certificate","validation"],"install":[{"cmd":"pip install certvalidator","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Low-level ASN.1 parsing and serialization for certificates.","package":"asn1crypto","optional":false},{"reason":"Cryptographic operations like hashing and signature verification, and TLS socket functionality.","package":"oscrypto","optional":false},{"reason":"Provides additional cryptographic primitives for certificate parsing and validation.","package":"pyca-cryptography","optional":false},{"reason":"Internationalized Domain Names in Applications (IDNA) support for hostname validation.","package":"idna","optional":false},{"reason":"HTTP client for fetching CRLs and OCSP responses.","package":"urllib3","optional":false},{"reason":"HTTP client, often used for fetching CRLs and OCSP responses indirectly via urllib3.","package":"requests","optional":false}],"imports":[{"symbol":"CertificateValidator","correct":"from certvalidator import CertificateValidator"},{"symbol":"TrustStore","correct":"from certvalidator.stores import TrustStore"},{"symbol":"errors","correct":"from certvalidator import errors"}],"quickstart":{"code":"from datetime import datetime\nfrom oscrypto import tls\nfrom certvalidator import CertificateValidator, errors\nfrom certvalidator.stores import TrustStore\n\n# Target host and port for certificate retrieval\nhostname = \"google.com\"\nport = 443\n\ntry:\n    # Step 1: Obtain the end-entity (leaf) certificate and its chain from a TLS server.\n    # oscrypto.tls.TLSSocket provides the full chain (peer_certificate and intermediate_certificates).\n    # This establishes a connection to fetch the server's certificate chain.\n    connection = tls.TLSSocket(hostname, port, timeout=5)\n    \n    # The attributes are oscrypto.asymmetric.Certificate objects; dump() gets their DER bytes.\n    leaf_cert_der = connection.peer_certificate.dump()\n    intermediate_certs_der = [c.dump() for c in connection.intermediate_certificates]\n    \n    connection.close() # Close the connection once certs are retrieved\n\n    # Step 2: Prepare the trust anchors (root CAs).\n    # TrustStore() by default loads system-wide trust anchors (e.g., from OS certificate store).\n    # For custom roots, use: SimpleTrustStore([root_ca_der_bytes, ...]).\n    trust_store = TrustStore()\n\n    # Step 3: Create a CertificateValidator instance.\n    # Arguments: leaf certificate, list of intermediate certificates, and the trust store.\n    validator = CertificateValidator(\n        leaf_cert_der,\n        intermediate_certs_der,\n        trust_store=trust_store\n    )\n\n    # Step 4: Perform validation for a specific purpose (e.g., TLS server certificate).\n    # validate_tls_server verifies hostname, key usage, validity period, and revocation status.\n    # validation_time is optional, defaults to datetime.utcnow().\n    validation_path = validator.validate_tls_server(hostname, validation_time=datetime.utcnow())\n    \n    print(f\"Certificate for {hostname} is valid.\")\n    print(\"Validated path:\")\n    for cert_in_path in validation_path:\n        print(f\"  - Subject: {cert_in_path.subject.human_friendly}\")\n        print(f\"    Issuer: {cert_in_path.issuer.human_friendly}\")\n\nexcept errors.PathValidationError as e:\n    print(f\"Certificate validation failed for {hostname}: {e}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure network connectivity and that 'oscrypto' and 'certvalidator' are installed.\")","lang":"python","description":"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`."},"warnings":[{"fix":"Convert `float` timestamps to `datetime.datetime` objects using `datetime.fromtimestamp(timestamp_float)`.","message":"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.","severity":"breaking","affected_versions":"<0.6.0"},{"fix":"Instantiate `RevocationChecker` objects (e.g., `CRLChecker()`, `OCSPChecker()`) and pass them as a list to the `revocation_checkers` argument of `CertificateValidator`.","message":"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.","severity":"breaking","affected_versions":"<0.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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)`.","severity":"gotcha","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}