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)
>>> # See the documentation on `time` below for more details. If
>>> # significant time passes between creating a verifier and performing a
>>> # verification, you may encounter issues with certificate expiration.
>>> 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)

Added 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: Added 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.VerifiedClient

Added in version 43.0.0.

Changed in version 44.0.0: Made subjects optional with the addition of custom extension policies.

subjects

Type:: list of GeneralName or None

The subjects presented in the verified client’s Subject Alternative Name extension or None if the extension is not present.

chain

Type:: A list of Certificate, in leaf-first order

The chain of certificates that forms the valid chain to the client certificate.

class cryptography.x509.verification.ClientVerifier

Added in version 43.0.0.

A ClientVerifier verifies client certificates.

It contains and describes various pieces of configurable path validation logic, such as how deep prospective validation chains may go, which signature algorithms are allowed, and so forth.

ClientVerifier instances cannot be constructed directly; PolicyBuilder must be used.

validation_time

Type:: datetime.datetime

The verifier’s validation time.

max_chain_depth

Type:: int

The verifier’s maximum intermediate CA chain depth.

store

Type:: Store

The verifier’s trust store.

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 is leaf, followed by the intermediates used (if any), followed by a member of the store.

Parameters:

leaf – The leaf Certificate to validate
intermediates – A list of intermediate Certificate to attempt to use

Returns:

A new instance of VerifiedClient

Raises:

VerificationError – If a valid chain cannot be constructed
UnsupportedGeneralNameType – If a valid chain exists, but contains an unsupported general name type

class cryptography.x509.verification.ServerVerifier

Added 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.

subject

Type:: Subject

The verifier’s subject.

validation_time

Type:: datetime.datetime

The verifier’s validation time.

max_chain_depth

Type:: int

The verifier’s maximum intermediate CA chain depth.

store

Type:: Store

The verifier’s trust store.

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 is leaf, followed by the intermediates used (if any), followed by a member of the store.

Parameters:

leaf – The leaf Certificate to validate
intermediates – A list of intermediate Certificate to attempt to use

Returns:

A list containing a valid chain from leaf to a member of ServerVerifier.store.

Raises:

VerificationError – If a valid chain cannot be constructed

class cryptography.x509.verification.VerificationError: Added in version 42.0.0.

The error raised when path validation fails.

class cryptography.x509.verification.PolicyBuilder[source]

Added 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() when build_server_verifier() or build_client_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

build_client_verifier()

Added in version 43.0.0.

Builds a verifier for verifying client certificates.

Warning

This API is not suitable for website (i.e. server) certificate verification. You must use build_server_verifier() for server verification.

Returns:: An instance of ClientVerifier