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 45.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.
Changed in version 45.0.0:
verification_time
andmax_chain_depth
were deprecated and will be removed in version 46.0.0. The newpolicy
property should be used to access these values instead.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.- policy
- Type:
The policy used by the verifier. Can be used to access verification time, maximum chain depth, etc.
- 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 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.
Changed in version 45.0.0:
subject
,verification_time
andmax_chain_depth
were deprecated and will be removed in version 46.0.0. The newpolicy
property should be used to access these values instead.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.- policy
- Type:
The policy used by the verifier. Can be used to access verification time, maximum chain depth, etc.
- 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
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()
whenbuild_server_verifier()
orbuild_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
- extension_policies(new_ee_policy, new_ca_policy)
Added in version 45.0.0.
Sets the EE and CA extension policies for the verifier. The default policies used are those returned by
ExtensionPolicy.webpki_defaults_ee()
andExtensionPolicy.webpki_defaults_ca()
.Warning
If the PolicyBuilder will be used to build a
ServerVerifier
, the EE extension policy must require theSubjectAlternativeName
extension to be present.- Parameters:
new_ca_policy (ExtensionPolicy) – The CA extension policy to use.
new_ee_policy (ExtensionPolicy) – The EE extension policy to use.
- 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
- class cryptography.x509.verification.ExtensionPolicy[source]
Added in version 45.0.0.
ExtensionPolicy provides a set of static methods to construct predefined extension policies, and a builder-style interface for modifying them.
Note
Calling any of the builder methods (
require_not_present()
,may_be_present()
, orrequire_present()
) multiple times with the same extension type will raise an exception.Note
Currently only the following extension types are supported in the ExtensionPolicy API:
AuthorityInformationAccess
,AuthorityKeyIdentifier
,SubjectKeyIdentifier
,KeyUsage
,SubjectAlternativeName
,BasicConstraints
,NameConstraints
,ExtendedKeyUsage
.- static permit_all()
Creates an ExtensionPolicy that does not put any constraints on a certificate’s extensions. This can serve as a base for a fully custom extension policy.
- Returns:
An instance of
ExtensionPolicy
- static webpki_defaults_ca()
Creates an ExtensionPolicy for CA certificates, based on CA/B Forum guidelines.
This is the default CA extension policy used by
PolicyBuilder
.- Returns:
An instance of
ExtensionPolicy
- static webpki_defaults_ee()
Creates an ExtensionPolicy for EE certificates, based on CA/B Forum guidelines.
This is the default EE extension policy used by
PolicyBuilder
.- Returns:
An instance of
ExtensionPolicy
- require_not_present(extension_type)
Specifies that the extension identified by extension_type must not be present (must be absent).
- Parameters:
extension_type (type[ExtensionType]) – The extension_type of the extension that must not be present.
- Returns:
An instance of
ExtensionPolicy
- may_be_present(extension_type, criticality, validator_cb)
Specifies that the extension identified by extension_type is optional. If it is present, it must conform to the given criticality constraint. An optional validator callback may be provided.
If a validator callback is provided, the callback will be invoked when
ClientVerifier.verify()
orServerVerifier.verify()
is called on a verifier that uses the extension policy. For details on the callback signature, seeMaybeExtensionValidatorCallback
.- Parameters:
extension_type (type[ExtensionType]) – A concrete class derived from
ExtensionType
indicating which extension may be present.criticality (Criticality) – The criticality of the extension
validator_cb (
MaybeExtensionValidatorCallback
or None) – An optional Python callback to validate the extension value. Must accept extensions of type extension_type.
- Returns:
An instance of
ExtensionPolicy
- require_present(extension_type, criticality, validator_cb)
Specifies that the extension identified by extension_type` must be present and conform to the given criticality constraint. An optional validator callback may be provided.
If a validator callback is provided, the callback will be invoked when
ClientVerifier.verify()
orServerVerifier.verify()
is called on a verifier that uses the extension policy. For details on the callback signature, seePresentExtensionValidatorCallback
.- Parameters:
extension_type (type[ExtensionType]) – A concrete class derived from
ExtensionType
indicating which extension is required to be present.criticality (Criticality) – The criticality of the extension
validator_cb (
PresentExtensionValidatorCallback
or None) – An optional Python callback to validate the extension value. Must accept extensions of type extension_type.
- Returns:
An instance of
ExtensionPolicy
- class cryptography.x509.verification.Criticality[source]
Added in version 45.0.0.
An enumeration of criticality constraints for certificate extensions.
- CRITICAL
The extension must be marked as critical.
- AGNOSTIC
The extension may be marked either as critical or non-critical.
- NON_CRITICAL
The extension must not be marked as critical.
- class cryptography.x509.verification.Policy[source]
Added in version 45.0.0.
Represents a policy for certificate verification. Passed to extension validator callbacks and accessible via
ClientVerifier
andServerVerifier
.- max_chain_depth
The maximum chain depth (as described in
PolicyBuilder.max_chain_depth()
).- Type:
- subject
The subject used during verification. Will be None if the verifier is a
ClientVerifier
.- Type:
x509.verification.Subject or None
- validation_time
The validation time.
- Type:
- extended_key_usage
The Extended Key Usage required by the policy.
- Type:
- type cryptography.x509.verification.MaybeExtensionValidatorCallback = Callable[[Policy, Certificate, ExtensionType | None], None]
Added in version 45.0.0.
A Python callback that validates an extension that may or may not be present. If the extension is not present, the callback will be invoked with ext set to None.
To fail the validation, the callback must raise an exception.
- Parameters:
policy (Policy) – The verification policy.
certificate (Certificate) – The certificate being verified.
extension (ExtensionType or None) – The extension value or None if the extension is not present.
- Returns:
An extension validator callback must return None. If the validation fails, the validator must raise an exception.
- type cryptography.x509.verification.PresentExtensionValidatorCallback = Callable[[Policy, Certificate, ExtensionType], None]
Added in version 45.0.0.
A Python callback that validates an extension that must be present.
To fail the validation, the callback must raise an exception.
- Parameters:
policy (Policy) – The verification policy.
certificate (Certificate) – The certificate being verified.
extension (ExtensionType) – The extension value.
- Returns:
An extension validator callback must return None. If the validation fails, the validator must raise an exception.