X.509 Verification
Support for X.509 certificate verification, also known as path validation or chain building.
Note
While usable, these APIs should be considered unstable and not yet subject to our backwards compatibility policy.
Example usage, with certifi providing the root of trust:
>>> from cryptography.x509 import Certificate, DNSName, load_pem_x509_certificates
>>> from cryptography.x509.verification import PolicyBuilder, Store
>>> import certifi
>>> from datetime import datetime
>>> with open(certifi.where(), "rb") as pems:
... store = Store(load_pem_x509_certificates(pems.read()))
>>> builder = PolicyBuilder().store(store)
>>> builder = builder.time(verification_time)
>>> verifier = builder.build_server_verifier(DNSName("cryptography.io"))
>>> # NOTE: peer and untrusted_intermediates are Certificate and
>>> # list[Certificate] respectively, and should be loaded from the
>>> # application context that needs them verified, such as a
>>> # TLS socket.
>>> chain = verifier.verify(peer, untrusted_intermediates)
- class cryptography.x509.verification.Store(certs)
New in version 42.0.0.
A Store is an opaque set of public keys and subject identifiers that are considered trusted a priori. Stores are typically created from the host OS’s root of trust, from a well-known source such as a browser CA bundle, or from a small set of manually pre-trusted entities.
- Parameters:
certs – A list of one or more
cryptography.x509.Certificate
instances.
- class cryptography.x509.verification.Subject
New in version 42.0.0.
Type alias: A union of all subject types supported:
cryptography.x509.general_name.DNSName
,cryptography.x509.general_name.IPAddress
.
- class cryptography.x509.verification.ServerVerifier
New in version 42.0.0.
A ServerVerifier verifies server certificates.
It contains and describes various pieces of configurable path validation logic, such as which subject to expect, how deep prospective validation chains may go, which signature algorithms are allowed, and so forth.
ServerVerifier instances cannot be constructed directly;
PolicyBuilder
must be used.- validation_time
- Type:
The verifier’s validation time.
- verify(leaf, intermediates)
Performs path validation on
leaf
, returning a valid path if one exists. The path is returned in leaf-first order: the first member isleaf
, followed by the intermediates used (if any), followed by a member of thestore
.- Parameters:
leaf – The leaf
Certificate
to validateintermediates – A
list
of intermediateCertificate
to attempt to use
- Returns:
A list containing a valid chain from
leaf
to a member ofServerVerifier.store
.- Raises:
VerificationError – If a valid chain cannot be constructed
- class cryptography.x509.verification.VerificationError
New in version 42.0.0.
The error raised when path validation fails.
- class cryptography.x509.verification.PolicyBuilder[source]
New in version 42.0.0.
A PolicyBuilder provides a builder-style interface for constructing a Verifier.
- time(new_time)
Sets the verifier’s verification time.
If not called explicitly, this is set to
datetime.datetime.now()
whenbuild_server_verifier()
is called.- Parameters:
new_time – The
datetime.datetime
to use in the verifier- Returns:
A new instance of
PolicyBuilder
- store(new_store)
Sets the verifier’s trust store.
- Parameters:
new_store – The
Store
to use in the verifier- Returns:
A new instance of
PolicyBuilder
- max_chain_depth(new_max_chain_depth)
Sets the verifier’s maximum chain building depth.
This depth behaves tracks the length of the intermediate CA chain: a maximum depth of zero means that the leaf must be directly issued by a member of the store, a depth of one means no more than one intermediate CA, and so forth. Note that self-issued intermediates don’t count against the chain depth, per RFC 5280.
- Parameters:
new_max_chain_depth – The maximum depth to allow in the verifier
- Returns:
A new instance of
PolicyBuilder
- build_server_verifier(subject)
Builds a verifier for verifying server certificates.
- Parameters:
subject – A
Subject
to use in the verifier- Returns:
An instance of
ServerVerifier