pyhanko_certvalidator package
Subpackages
- pyhanko_certvalidator.fetchers package
- Subpackages
- Submodules
- pyhanko_certvalidator.fetchers.api module
- pyhanko_certvalidator.fetchers.common_utils module
- Module contents
- pyhanko_certvalidator.ltv package
- Submodules
- pyhanko_certvalidator.ltv.ades_past module
- pyhanko_certvalidator.ltv.errors module
- pyhanko_certvalidator.ltv.poe module
- pyhanko_certvalidator.ltv.time_slide module
- pyhanko_certvalidator.ltv.types module
- Module contents
- pyhanko_certvalidator.revinfo package
- Submodules
- pyhanko_certvalidator.revinfo.archival module
- pyhanko_certvalidator.revinfo.constants module
- pyhanko_certvalidator.revinfo.manager module
RevinfoManager
RevinfoManager.poe_manager
RevinfoManager.certificate_registry
RevinfoManager.fetching_allowed
RevinfoManager.crls
RevinfoManager.ocsps
RevinfoManager.new_revocation_certs
RevinfoManager.record_crl_issuer()
RevinfoManager.check_crl_issuer()
RevinfoManager.async_retrieve_crls()
RevinfoManager.async_retrieve_ocsps()
RevinfoManager.evict_ocsps()
RevinfoManager.evict_crls()
RevinfoManager.check_asserted_unrevoked()
- pyhanko_certvalidator.revinfo.validate_crl module
- pyhanko_certvalidator.revinfo.validate_ocsp module
- Module contents
Submodules
pyhanko_certvalidator.asn1_types module
- class pyhanko_certvalidator.asn1_types.Target(name=None, value=None, **kwargs)
Bases:
Choice
- class pyhanko_certvalidator.asn1_types.TargetCert(value=None, default=None, **kwargs)
Bases:
Sequence
- class pyhanko_certvalidator.asn1_types.Targets(value=None, default=None, contents=None, spec=None, **kwargs)
Bases:
SequenceOf
- class pyhanko_certvalidator.asn1_types.SequenceOfTargets(value=None, default=None, contents=None, spec=None, **kwargs)
Bases:
SequenceOf
- class pyhanko_certvalidator.asn1_types.AttrSpec(value=None, default=None, contents=None, spec=None, **kwargs)
Bases:
SequenceOf
- class pyhanko_certvalidator.asn1_types.AAControls(value=None, default=None, **kwargs)
Bases:
Sequence
- accept(attr_id: AttCertAttributeType) bool
- classmethod read_extension_value(cert: Certificate) AAControls | None
pyhanko_certvalidator.context module
- class pyhanko_certvalidator.context.ACTargetDescription(validator_names: ~typing.List[~asn1crypto.x509.GeneralName] = <factory>, group_memberships: ~typing.List[~asn1crypto.x509.GeneralName] = <factory>)
Bases:
object
Value type to guide attribute certificate targeting checks, for attribute certificates that use the target information extension.
As stipulated in RFC 5755, an AC targeting check passes if the information in the relevant
AATargetDescription
matches at least oneTarget
in the AC’s target information extension.- validator_names: List[GeneralName]
The validating entity’s names.
This value is matched directly against any
Target``s that use the ``targetName
alternative.
- group_memberships: List[GeneralName]
The validating entity’s group memberships.
This value is matched against any
Target``s that use the ``targetGroup
alternative.
- class pyhanko_certvalidator.context.ValidationContext(trust_roots: Iterable[Certificate | TrustAnchor] | None = None, extra_trust_roots: Iterable[Certificate | TrustAnchor] | None = None, other_certs: Iterable[Certificate] | None = None, whitelisted_certs: Iterable[bytes | str] | None = None, moment: datetime | None = None, best_signature_time: datetime | None = None, allow_fetching: bool = False, crls: Iterable[bytes | CertificateList] | None = None, ocsps: Iterable[bytes | OCSPResponse] | None = None, revocation_mode: str = 'soft-fail', revinfo_policy: CertRevTrustPolicy | None = None, weak_hash_algos: Iterable[str] | None = None, time_tolerance: timedelta = datetime.timedelta(seconds=1), retroactive_revinfo: bool = False, fetcher_backend: FetcherBackend | None = None, acceptable_ac_targets: ACTargetDescription | None = None, poe_manager: POEManager | None = None, revinfo_manager: RevinfoManager | None = None, certificate_registry: CertificateRegistry | None = None, trust_manager: TrustManager | None = None, algorithm_usage_policy: AlgorithmUsagePolicy | None = None, fetchers: Fetchers | None = None)
Bases:
object
- property revinfo_manager: RevinfoManager
- property revinfo_policy: CertRevTrustPolicy
- property retroactive_revinfo: bool
- property time_tolerance: timedelta
- property moment: datetime
- property best_signature_time: datetime
- property fetching_allowed: bool
- property crls: List[CertificateList]
A list of all cached
crl.CertificateList
objects
- property ocsps: List[OCSPResponse]
A list of all cached
ocsp.OCSPResponse
objects
- property soft_fail_exceptions
A list of soft-fail exceptions that were ignored during checks
- is_whitelisted(cert)
Checks to see if a certificate has been whitelisted
- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
A bool - if the certificate is whitelisted
- async async_retrieve_crls(cert)
- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
A list of asn1crypto.crl.CertificateList objects
- retrieve_crls(cert)
Deprecated since version 0.17.0: Use
async_retrieve_crls()
instead.- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
A list of asn1crypto.crl.CertificateList objects
- async async_retrieve_ocsps(cert, issuer)
- Parameters:
cert – An asn1crypto.x509.Certificate object
issuer – An asn1crypto.x509.Certificate object of cert’s issuer
- Returns:
A list of asn1crypto.ocsp.OCSPResponse objects
- retrieve_ocsps(cert, issuer)
Deprecated since version 0.17.0: Use
async_retrieve_ocsps()
instead.- Parameters:
cert – An asn1crypto.x509.Certificate object
issuer – An asn1crypto.x509.Certificate object of cert’s issuer
- Returns:
A list of asn1crypto.ocsp.OCSPResponse objects
- record_validation(cert, path)
Records that a certificate has been validated, along with the path that was used for validation. This helps reduce duplicate work when validating a ceritifcate and related resources such as CRLs and OCSPs.
- Parameters:
cert – An ans1crypto.x509.Certificate object
path – A pyhanko_certvalidator.path.ValidationPath object
- check_validation(cert)
Checks to see if a certificate has been validated, and if so, returns the ValidationPath used to validate it.
- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
None if not validated, or a pyhanko_certvalidator.path.ValidationPath object of the validation path
- clear_validation(cert)
Clears the record that a certificate has been validated
- Parameters:
cert – An ans1crypto.x509.Certificate object
- property acceptable_ac_targets: ACTargetDescription | None
- class pyhanko_certvalidator.context.ValidationDataHandlers(revinfo_manager: RevinfoManager, poe_manager: POEManager, cert_registry: CertificateRegistry)
Bases:
object
Value class to hold ‘manager’/’registry’ objects. These are responsible for accumulating and exposing various data collections that are relevant for certificate validation.
- revinfo_manager: RevinfoManager
The revocation information manager.
- poe_manager: POEManager
The proof-of-existence record manager.
- cert_registry: CertificateRegistry
The certificate registry.
Note
The certificate registry is a trustless construct. It only holds certificates, but does mark them as trusted or store information related to how the certificates fit together.
- pyhanko_certvalidator.context.bootstrap_validation_data_handlers(fetchers: ~pyhanko_certvalidator.fetchers.api.Fetchers | ~pyhanko_certvalidator.fetchers.api.FetcherBackend | None = <pyhanko_certvalidator.fetchers.requests_fetchers.RequestsFetcherBackend object>, crls: ~typing.Iterable[~pyhanko_certvalidator.revinfo.archival.CRLContainer] = (), ocsps: ~typing.Iterable[~pyhanko_certvalidator.revinfo.archival.OCSPContainer] = (), certs: ~typing.Iterable[~asn1crypto.x509.Certificate] = (), poe_manager: ~pyhanko_certvalidator.ltv.poe.POEManager | None = None, nonrevoked_assertions: ~typing.Iterable[~pyhanko_certvalidator.policy_decl.NonRevokedStatusAssertion] = ()) ValidationDataHandlers
Simple bootstrapping method for a
ValidationDataHandlers
instance with reasonable defaults.- Parameters:
fetchers – Data fetcher implementation and/or backend to use. If
None
, remote fetching is disabled. Therequests
-based implementation is the default.crls – Initial collection of CRLs to feed to the revocation info manager.
ocsps – Initial collection of OCSP responses to feed to the revocation info manager.
certs – Initial collection of certificates to add to the certificate registry.
poe_manager – Explicit POE manager. Will instantiate an empty one if left unspecified.
nonrevoked_assertions – Assertions about the non-revoked status of certain certificates that will be taken as true by fiat.
- Returns:
A
ValidationDataHandlers
object.
- class pyhanko_certvalidator.context.CertValidationPolicySpec(trust_manager: ~pyhanko_certvalidator.registry.TrustManager, revinfo_policy: ~pyhanko_certvalidator.policy_decl.CertRevTrustPolicy, time_tolerance: ~datetime.timedelta = datetime.timedelta(seconds=1), acceptable_ac_targets: ~pyhanko_certvalidator.context.ACTargetDescription | None = None, algorithm_usage_policy: ~pyhanko_certvalidator.policy_decl.AlgorithmUsagePolicy | None = <pyhanko_certvalidator.policy_decl.DisallowWeakAlgorithmsPolicy object>, pkix_validation_params: ~pyhanko_certvalidator.policy_decl.PKIXValidationParams | None = None)
Bases:
object
Policy object describing how to validate certificates at a high level.
Note
A certificate validation policy differs from a validation context in that
ValidationContext
objects keep state as well. This is not the case for a certificate validation policy, which makes them suitable for reuse in complex validation workflows where the same policy needs to be applied independently in multiple steps.Warning
While a certification policy spec is intended to be stateless, some of its fields are abstract classes. As such, the true behaviour may depend on the underlying implementation.
- trust_manager: TrustManager
The trust manager that defines this policy’s trust anchors.
- revinfo_policy: CertRevTrustPolicy
The policy describing how to handle certificate revocation and associated revocation information.
- time_tolerance: timedelta = datetime.timedelta(seconds=1)
The time drift tolerated during validation. Defaults to one second.
- acceptable_ac_targets: ACTargetDescription | None = None
Targets to accept when evaluating the scope of an attribute certificate.
- algorithm_usage_policy: AlgorithmUsagePolicy | None = <pyhanko_certvalidator.policy_decl.DisallowWeakAlgorithmsPolicy object>
Policy on cryptographic algorithm usage. If left unspecified, a default will be used.
- pkix_validation_params: PKIXValidationParams | None = None
The PKIX validation parameters to use, as defined in RFC 5280.
- build_validation_context(timing_info: ValidationTimingInfo, handlers: ValidationDataHandlers | None) ValidationContext
Build a validation context from this policy, validation timing info and a set of validation data handlers.
- Parameters:
timing_info – Timing settings.
handlers – Optionally specify validation data handlers. A reasonable default will be supplied if absent.
- Returns:
A new
ValidationContext
reflecting the parameters.
pyhanko_certvalidator.errors module
- exception pyhanko_certvalidator.errors.PathError
Bases:
Exception
- exception pyhanko_certvalidator.errors.CertificateFetchError
Bases:
PathBuildingError
- exception pyhanko_certvalidator.errors.CRLValidationError
Bases:
Exception
- exception pyhanko_certvalidator.errors.CRLNoMatchesError
Bases:
CRLValidationError
- exception pyhanko_certvalidator.errors.CRLFetchError
Bases:
CRLValidationError
- exception pyhanko_certvalidator.errors.CRLValidationIndeterminateError(msg: str, failures: List[str], suspect_stale: datetime | None = None)
Bases:
CRLValidationError
- exception pyhanko_certvalidator.errors.OCSPValidationError
Bases:
Exception
- exception pyhanko_certvalidator.errors.OCSPNoMatchesError
Bases:
OCSPValidationError
- exception pyhanko_certvalidator.errors.OCSPValidationIndeterminateError(msg: str, failures: List[str], suspect_stale: datetime | None = None)
Bases:
OCSPValidationError
- exception pyhanko_certvalidator.errors.OCSPFetchError
Bases:
OCSPValidationError
- exception pyhanko_certvalidator.errors.ValidationError(message: str)
Bases:
Exception
- exception pyhanko_certvalidator.errors.PathValidationError(msg: str, *, proc_state: ValProcState)
Bases:
ValidationError
- classmethod from_state(msg: str, proc_state: ValProcState) TPathErr
- exception pyhanko_certvalidator.errors.RevokedError(msg, reason: CRLReason, revocation_dt: datetime, proc_state: ValProcState)
Bases:
PathValidationError
- classmethod format(reason: CRLReason, revocation_dt: datetime, revinfo_type: str, proc_state: ValProcState)
- exception pyhanko_certvalidator.errors.InsufficientRevinfoError(msg: str, *, proc_state: ValProcState)
Bases:
PathValidationError
- exception pyhanko_certvalidator.errors.StaleRevinfoError(msg: str, time_cutoff: datetime, proc_state: ValProcState)
Bases:
InsufficientRevinfoError
- classmethod format(msg: str, time_cutoff: datetime, proc_state: ValProcState)
- exception pyhanko_certvalidator.errors.InsufficientPOEError(msg: str, *, proc_state: ValProcState)
Bases:
PathValidationError
- exception pyhanko_certvalidator.errors.ExpiredError(msg, expired_dt: datetime, proc_state: ValProcState)
Bases:
PathValidationError
- classmethod format(*, expired_dt: datetime, proc_state: ValProcState)
- exception pyhanko_certvalidator.errors.NotYetValidError(msg, valid_from: datetime, proc_state: ValProcState)
Bases:
PathValidationError
- classmethod format(*, valid_from: datetime, proc_state: ValProcState)
- exception pyhanko_certvalidator.errors.InvalidCertificateError(message: str)
Bases:
ValidationError
- exception pyhanko_certvalidator.errors.DisallowedAlgorithmError(*args, banned_since: datetime | None = None, **kwargs)
Bases:
PathValidationError
- classmethod from_state(msg: str, proc_state: ValProcState, banned_since: datetime | None = None) DisallowedAlgorithmError
- exception pyhanko_certvalidator.errors.InvalidAttrCertificateError(message: str)
Bases:
InvalidCertificateError
- exception pyhanko_certvalidator.errors.PSSParameterMismatch
Bases:
InvalidSignature
Bases:
InvalidSignature
pyhanko_certvalidator.name_trees module
- exception pyhanko_certvalidator.name_trees.NameConstraintError
Bases:
ValueError
- pyhanko_certvalidator.name_trees.host_tree_contains(base_host: str, other_host: str) bool
- pyhanko_certvalidator.name_trees.uri_tree_contains(base: str, other: str) bool
- pyhanko_certvalidator.name_trees.dns_tree_contains(base: str, other: str)
- pyhanko_certvalidator.name_trees.email_tree_contains(base: str, other: str)
- pyhanko_certvalidator.name_trees.dirname_tree_contains(base: Name, other: Name)
- class pyhanko_certvalidator.name_trees.GeneralNameType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
Enum
- OTHER_NAME = 1
- RFC822_NAME = 2
- DNS_NAME = 3
- X400_ADDRESS = 4
- DIRECTORY_NAME = 5
- EDI_PARTY_NAME = 6
- UNIFORM_RESOURCE_IDENTIFIER = 7
- IP_ADDRESS = 8
- REGISTERED_ID = 9
- property check_membership: Callable[[str | Name, str | Name], bool] | None
- classmethod from_choice(choice) GeneralNameType
- exception pyhanko_certvalidator.name_trees.UnsupportedNameTypeError(name_type: GeneralNameType)
Bases:
NotImplementedError
- class pyhanko_certvalidator.name_trees.NameSubtree(name_type: pyhanko_certvalidator.name_trees.GeneralNameType, tree_base: pyhanko_certvalidator.name_trees._StringOrName | None, min: int = 0, max: int | None = None)
Bases:
object
- name_type: GeneralNameType
- tree_base: _StringOrName | None
- min: int = 0
- max: int | None = None
- classmethod from_name(name_type: GeneralNameType, name: str | Name)
- classmethod from_general_subtree(subtree) NameSubtree
- classmethod universal_tree(name_type: GeneralNameType) NameSubtree
Tree that contains all names of a given type.
- Parameters:
name_type – The name type to use.
- Returns:
- pyhanko_certvalidator.name_trees.x509_names_to_subtrees(names: Iterable[Name]) Dict[GeneralNameType, Set[NameSubtree]]
- pyhanko_certvalidator.name_trees.process_general_subtrees(subtrees: GeneralSubtrees) Dict[GeneralNameType, Set[NameSubtree]]
- class pyhanko_certvalidator.name_trees.NameConstraintValidationResult(failing_name_type: GeneralNameType | None = None, failing_name: str | Name | None = None)
Bases:
object
- property error_message
- class pyhanko_certvalidator.name_trees.PermittedSubtrees(initial_permitted_subtrees: Dict[GeneralNameType, Set[NameSubtree]])
Bases:
object
- intersect_with(trees: Dict[GeneralNameType, Set[NameSubtree]])
- accept_name(name_type: GeneralNameType, name) bool
- accept_cert(cert: Certificate) NameConstraintValidationResult
- class pyhanko_certvalidator.name_trees.ExcludedSubtrees(initial_excluded_subtrees: Dict[GeneralNameType, Set[NameSubtree]])
Bases:
object
- union_with(trees: Dict[GeneralNameType, Set[NameSubtree]])
- reject_name(name_type: GeneralNameType, name) bool
- accept_cert(cert: Certificate) NameConstraintValidationResult
- pyhanko_certvalidator.name_trees.default_permitted_subtrees() Dict[GeneralNameType, Set[NameSubtree]]
- pyhanko_certvalidator.name_trees.default_excluded_subtrees() Dict[GeneralNameType, Set[NameSubtree]]
pyhanko_certvalidator.path module
- class pyhanko_certvalidator.path.QualifiedPolicy(issuer_domain_policy_id: str, user_domain_policy_id: str, qualifiers: frozenset)
Bases:
object
- issuer_domain_policy_id: str
Policy OID in the issuer domain (i.e. as listed on the certificate).
- user_domain_policy_id: str
Policy OID of the equivalent policy in the user domain.
- qualifiers: frozenset
Set of x509.PolicyQualifierInfo objects.
- class pyhanko_certvalidator.path.ValidationPath(trust_anchor: TrustAnchor, interm: Iterable[Certificate], leaf: Certificate | AttributeCertificateV2 | None)
Bases:
object
Represents a path going towards an end-entity certificate or attribute certificate.
- property trust_anchor: TrustAnchor
- property first
Returns the current beginning of the path - for a path to be complete, this certificate should be a trust root
Warning
This is a compatibility property, and will return the first non-root certificate if the trust root is not provisioned as a certificate. If you want the trust root itself (even when it doesn’t have a certificate), use
trust_anchor
.- Returns:
The first asn1crypto.x509.Certificate object in the path
- property leaf: Certificate | AttributeCertificateV2 | None
Returns the current leaf certificate (AC or public-key). The trust root’s certificate will be returned if there is one and there are no other certificates in the path.
If the trust root is certificate-less and there are no certificates, the result will be
None
.
- describe_leaf() str | None
- get_ee_cert_safe() Certificate | None
Returns the current leaf certificate if it is an X.509 public-key certificate, and
None
otherwise. :return:
- property last: Certificate
Returns the last certificate in the path if it is an X.509 public-key certificate, and throws an error otherwise.
- Returns:
The last asn1crypto.x509.Certificate object in the path
- iter_authorities() Iterable[Authority]
Iterate over all authorities in the path, including the trust root.
- find_issuing_authority(cert: Certificate | AttributeCertificateV2)
Return the issuer of the cert specified, as defined by this path
- Parameters:
cert – A certificate to get the issuer of
- Raises:
LookupError - when the issuer of the certificate could not be found
- Returns:
An asn1crypto.x509.Certificate object of the issuer
- truncate_to_and_append(cert: Certificate, new_leaf: Certificate | AttributeCertificateV2)
Remove all certificates in the path after the cert specified and return them in a new path.
Internal API.
- Parameters:
cert – An asn1crypto.x509.Certificate object to find
new_leaf – A new leaf certificate to append.
- Raises:
LookupError - when the certificate could not be found
- Returns:
The current ValidationPath object, for chaining
- truncate_to_issuer_and_append(cert: Certificate)
Remove all certificates in the path after the issuer of the cert specified, as defined by this path, and append a new one.
Internal API.
- Parameters:
cert – A new leaf certificate to append.
- Raises:
LookupError - when the issuer of the certificate could not be found
- Returns:
The current ValidationPath object, for chaining
- copy_and_append(cert: Certificate | AttributeCertificateV2)
- copy_and_drop_leaf() ValidationPath
Drop the leaf cert from this path and return a new path with the last intermediate certificate set as the leaf.
- qualified_policies() FrozenSet[QualifiedPolicy] | None
- aa_attr_in_scope(attr_id: AttCertAttributeType) bool
- property pkix_len
- iter_certs(include_root: bool) Iterator[Certificate]
Iterate over the certificates in the path.
- Parameters:
include_root – Include the root (if it is supplied as a certificate)
- Returns:
An iterator.
pyhanko_certvalidator.policy_decl module
New in version 0.20.0.
- class pyhanko_certvalidator.policy_decl.RevocationCheckingRule(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
Enum
Rules determining in what circumstances revocation data has to be checked, and what kind.
- CRL_REQUIRED = 'clrcheck'
Check CRLs.
- OCSP_REQUIRED = 'ocspcheck'
Check OCSP.
- CRL_AND_OCSP_REQUIRED = 'bothcheck'
Check CRL and OCSP.
- CRL_OR_OCSP_REQUIRED = 'eithercheck'
Check CRL or OCSP.
- NO_CHECK = 'nocheck'
Do not check.
- CHECK_IF_DECLARED = 'ifdeclaredcheck'
Check revocation information if declared in the certificate.
Warning
This is not an ESI check type, but is preserved for compatibility with the ‘hard-fail’ mode in certvalidator.
Note
In this mode, cached CRLs will _not_ be checked if the certificate does not list any distribution points.
- CHECK_IF_DECLARED_SOFT = 'ifdeclaredsoftcheck'
Check revocation information if declared in the certificate, but do not fail validation if the check fails.
Warning
This is not an ESI check type, but is preserved for compatibility with the ‘soft-fail’ mode in certvalidator.
Note
In this mode, cached CRLs will _not_ be checked if the certificate does not list any distribution points.
- property strict: bool
- property tolerant: bool
- property crl_mandatory: bool
- property crl_relevant: bool
- property ocsp_mandatory: bool
- property ocsp_relevant: bool
- class pyhanko_certvalidator.policy_decl.RevocationCheckingPolicy(ee_certificate_rule: RevocationCheckingRule, intermediate_ca_cert_rule: RevocationCheckingRule)
Bases:
object
Class describing a revocation checking policy based on the types defined in the ETSI TS 119 172 series.
- ee_certificate_rule: RevocationCheckingRule
Revocation rule applied to end-entity certificates.
- intermediate_ca_cert_rule: RevocationCheckingRule
Revocation rule applied to certificates further up the path.
- classmethod from_legacy(policy: str)
- property essential: bool
- class pyhanko_certvalidator.policy_decl.FreshnessReqType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
Enum
Freshness requirement type.
- DEFAULT = 1
The default freshness policy, i.e. the
certvalidator
legacy policy. This policy considers revocation info valid between itsthisUpdate
andnextUpdate
times, but not outside of that window.
- MAX_DIFF_REVOCATION_VALIDATION = 2
Freshness policy requiring that the validation time, if later than the issuance date of the revocation info, be sufficiently close to that issuance date.
- TIME_AFTER_SIGNATURE = 3
Freshness policy requiring that the revocation info be issued after a predetermined “cooldown period” after the certificate was used to produce a signature.
- class pyhanko_certvalidator.policy_decl.CertRevTrustPolicy(revocation_checking_policy: RevocationCheckingPolicy, freshness: timedelta | None = None, freshness_req_type: FreshnessReqType = FreshnessReqType.DEFAULT, expected_post_expiry_revinfo_time: timedelta | None = None, retroactive_revinfo: bool = False)
Bases:
object
Class describing conditions for trusting revocation info. Based on CertificateRevTrust in ETSI TS 119 172-3.
- revocation_checking_policy: RevocationCheckingPolicy
The revocation checking policy requirements.
- freshness: timedelta | None = None
Freshness interval. If not specified, this defaults to the distance between
thisUpdate
andnextUpdate
for the given piece of revocation information. If thenextUpdate
field is not present, then the effective default is 30 minutes.
- freshness_req_type: FreshnessReqType = 1
Controls whether the freshness requirement applies relatively to the signing time or to the validation time.
- expected_post_expiry_revinfo_time: timedelta | None = None
Duration for which the issuing CA is expected to supply status information after a certificate expires.
- retroactive_revinfo: bool = False
Treat revocation info as retroactively valid, i.e. ignore the
this_update
field in CRLs and OCSP responses. This parameter is not taken into account for freshness policies other thanFreshnessReqType.DEFAULT
, and isFalse
by default in those cases.Warning
Be careful with this option, since it will cause incorrect behaviour for CAs that make use of certificate holds or other reversible revocation methods.
- class pyhanko_certvalidator.policy_decl.PKIXValidationParams(user_initial_policy_set: frozenset = frozenset({'any_policy'}), initial_policy_mapping_inhibit: bool = False, initial_explicit_policy: bool = False, initial_any_policy_inhibit: bool = False, initial_permitted_subtrees: Dict[pyhanko_certvalidator.name_trees.GeneralNameType, Set[pyhanko_certvalidator.name_trees.NameSubtree]] | None = None, initial_excluded_subtrees: Dict[pyhanko_certvalidator.name_trees.GeneralNameType, Set[pyhanko_certvalidator.name_trees.NameSubtree]] | None = None)
Bases:
object
- user_initial_policy_set: frozenset = frozenset({'any_policy'})
Set of policies that the user is willing to accept. By default, any policy is acceptable.
When setting this parameter to a non-default value, you probably want to set
initial_explicit_policy
as well.Note
These are specified in the policy domain of the trust root(s), and subject to policy mapping by intermediate certificate authorities.
- initial_policy_mapping_inhibit: bool = False
Flag indicating whether policy mapping is forbidden along the entire certification chains. By default, policy mapping is permitted.
Note
Policy constraints on intermediate certificates may force policy mapping to be inhibited from some point onwards.
- initial_explicit_policy: bool = False
Flag indicating whether path validation must terminate with at least one permissible policy; see
user_initial_policy_set
. By default, no such requirement is imposed.Note
If
user_initial_policy_set
is set to its default value of{'any_policy'}
, the effect is that the path validation must accept at least one policy, without specifying which.Warning
Due to widespread mis-specification of policy extensions in the wild, many real-world certification chains terminate with an empty set (or rather, tree) of valid policies. Therefore, this flag is set to
False
by default.
- initial_any_policy_inhibit: bool = False
Flag indicating whether
anyPolicy
should be left unprocessed when it appears in a certificate. By default,anyPolicy
is always processed when it appears.
- initial_permitted_subtrees: Dict[GeneralNameType, Set[NameSubtree]] | None = None
Set of permitted subtrees for each name type, indicating restrictions to impose on subject names (and alternative names) in the certification path.
By default, all names are permitted. This behaviour can be modified by name constraints on intermediate CA certificates.
- initial_excluded_subtrees: Dict[GeneralNameType, Set[NameSubtree]] | None = None
Set of excluded subtrees for each name type, indicating restrictions to impose on subject names (and alternative names) in the certification path.
By default, no names are excluded. This behaviour can be modified by name constraints on intermediate CA certificates.
- merge(other: PKIXValidationParams) PKIXValidationParams
Combine the conditions of these PKIX validation params with another set of parameters, producing the most lenient set of parameters that is stricter than both inputs.
- Parameters:
other – Another set of PKIX validation parameters.
- Returns:
A combined set of PKIX validation parameters.
- class pyhanko_certvalidator.policy_decl.AlgorithmUsageConstraint(allowed: bool, not_allowed_after: datetime | None = None, failure_reason: str | None = None)
Bases:
object
Expression of a constraint on the usage of an algorithm (possibly with parameter choices).
- allowed: bool
Flag indicating whether the algorithm can be used.
- not_allowed_after: datetime | None = None
Date indicating when the algorithm became unavailable (given the relevant choice of parameters, if applicable).
- failure_reason: str | None = None
A human-readable description of the failure reason, if applicable.
- class pyhanko_certvalidator.policy_decl.AlgorithmUsagePolicy
Bases:
ABC
Abstract interface defining a usage policy for cryptographic algorithms.
- digest_algorithm_allowed(algo: DigestAlgorithm, moment: datetime | None) AlgorithmUsageConstraint
Determine if the indicated digest algorithm can be used at the point in time indicated.
- Parameters:
algo – A digest algorithm description in ASN.1 form.
moment – The point in time at which the algorithm should be usable. If
None
, then the returned judgment applies at all times.
- Returns:
A
AlgorithmUsageConstraint
expressing the judgment.
- signature_algorithm_allowed(algo: SignedDigestAlgorithm, moment: datetime | None, public_key: PublicKeyInfo | None) AlgorithmUsageConstraint
Determine if the indicated signature algorithm (including the associated digest function and any parameters, if applicable) can be used at the point in time indicated.
- Parameters:
algo – A signature mechanism description in ASN.1 form.
moment – The point in time at which the algorithm should be usable. If
None
, then the returned judgment applies at all times.public_key –
The public key associated with the operation, if available.
Note
This parameter can be used to enforce key size limits or to filter out keys with known structural weaknesses.
- Returns:
A
AlgorithmUsageConstraint
expressing the judgment.
- class pyhanko_certvalidator.policy_decl.DisallowWeakAlgorithmsPolicy(weak_hash_algos=frozenset({'md2', 'md5', 'sha1'}), weak_signature_algos=frozenset({}), rsa_key_size_threshold=2048, dsa_key_size_threshold=3192)
Bases:
AlgorithmUsagePolicy
Primitive usage policy that forbids a list of user-specified “weak” algorithms and allows everything else. It also ignores the time parameter completely.
Note
This denial-based strategy is supplied to provide a backwards-compatible default. In many scenarios, an explicit allow-based strategy is more appropriate. Users with specific security requirements are encouraged to implement
AlgorithmUsagePolicy
themselves.- Parameters:
weak_hash_algos – The list of digest algorithms considered weak. Defaults to
DEFAULT_WEAK_HASH_ALGOS
.weak_signature_algos – The list of digest algorithms considered weak. Defaults to the empty set.
rsa_key_size_threshold – The key length threshold for RSA keys, in bits.
dsa_key_size_threshold – The key length threshold for DSA keys, in bits.
- digest_algorithm_allowed(algo: DigestAlgorithm, moment: datetime | None) AlgorithmUsageConstraint
Determine if the indicated digest algorithm can be used at the point in time indicated.
- Parameters:
algo – A digest algorithm description in ASN.1 form.
moment – The point in time at which the algorithm should be usable. If
None
, then the returned judgment applies at all times.
- Returns:
A
AlgorithmUsageConstraint
expressing the judgment.
- signature_algorithm_allowed(algo: SignedDigestAlgorithm, moment: datetime | None, public_key: PublicKeyInfo | None) AlgorithmUsageConstraint
Determine if the indicated signature algorithm (including the associated digest function and any parameters, if applicable) can be used at the point in time indicated.
- Parameters:
algo – A signature mechanism description in ASN.1 form.
moment – The point in time at which the algorithm should be usable. If
None
, then the returned judgment applies at all times.public_key –
The public key associated with the operation, if available.
Note
This parameter can be used to enforce key size limits or to filter out keys with known structural weaknesses.
- Returns:
A
AlgorithmUsageConstraint
expressing the judgment.
- class pyhanko_certvalidator.policy_decl.AcceptAllAlgorithms
Bases:
AlgorithmUsagePolicy
- digest_algorithm_allowed(algo: DigestAlgorithm, moment: datetime | None) AlgorithmUsageConstraint
Determine if the indicated digest algorithm can be used at the point in time indicated.
- Parameters:
algo – A digest algorithm description in ASN.1 form.
moment – The point in time at which the algorithm should be usable. If
None
, then the returned judgment applies at all times.
- Returns:
A
AlgorithmUsageConstraint
expressing the judgment.
- signature_algorithm_allowed(algo: SignedDigestAlgorithm, moment: datetime | None, public_key: PublicKeyInfo | None) AlgorithmUsageConstraint
Determine if the indicated signature algorithm (including the associated digest function and any parameters, if applicable) can be used at the point in time indicated.
- Parameters:
algo – A signature mechanism description in ASN.1 form.
moment – The point in time at which the algorithm should be usable. If
None
, then the returned judgment applies at all times.public_key –
The public key associated with the operation, if available.
Note
This parameter can be used to enforce key size limits or to filter out keys with known structural weaknesses.
- Returns:
A
AlgorithmUsageConstraint
expressing the judgment.
- class pyhanko_certvalidator.policy_decl.NonRevokedStatusAssertion(cert_sha256: bytes, at: datetime)
Bases:
object
Assert that a certificate was not revoked at some given date.
- cert_sha256: bytes
SHA-256 hash of the certificate.
- at: datetime
Moment in time at which the assertion is to be considered valid.
- pyhanko_certvalidator.policy_decl.DEFAULT_WEAK_HASH_ALGOS = frozenset({'md2', 'md5', 'sha1'})
Digest algorithms considered weak by default.
- pyhanko_certvalidator.policy_decl.REQUIRE_REVINFO = RevocationCheckingPolicy(ee_certificate_rule=<RevocationCheckingRule.CRL_OR_OCSP_REQUIRED: 'eithercheck'>, intermediate_ca_cert_rule=<RevocationCheckingRule.CRL_OR_OCSP_REQUIRED: 'eithercheck'>)
Policy indicating that revocation information is always required, but either OCSP or CRL-based revocation information is OK.
- pyhanko_certvalidator.policy_decl.NO_REVOCATION = RevocationCheckingPolicy(ee_certificate_rule=<RevocationCheckingRule.NO_CHECK: 'nocheck'>, intermediate_ca_cert_rule=<RevocationCheckingRule.NO_CHECK: 'nocheck'>)
Policy indicating that revocation information is never required.
pyhanko_certvalidator.policy_tree module
- pyhanko_certvalidator.policy_tree.update_policy_tree(certificate_policies, valid_policy_tree: PolicyTreeRoot, depth: int, any_policy_uninhibited: bool) PolicyTreeRoot | None
Internal method to update the policy tree during RFC 5280 validation.
- pyhanko_certvalidator.policy_tree.enumerate_policy_mappings(mappings: Iterable[PolicyMapping], proc_state: ValProcState)
Internal function to process policy mapping extension values into a Python dictionary mapping issuer domain policies to the corresponding policies in the subject policy domain.
- pyhanko_certvalidator.policy_tree.apply_policy_mapping(policy_map, valid_policy_tree, depth: int, policy_mapping_uninhibited: bool)
Internal function to apply the policy mapping to the current policy tree in accordance with the algorithm in RFC 5280.
- pyhanko_certvalidator.policy_tree.prune_unacceptable_policies(path_length, valid_policy_tree, acceptable_policies) PolicyTreeRoot | None
- class pyhanko_certvalidator.policy_tree.PolicyTreeRoot
Bases:
object
A generic policy tree node, used for the root node in the tree
- classmethod init_policy_tree(valid_policy, qualifier_set, expected_policy_set)
Accepts values for a PolicyTreeNode that will be created at depth 0
- Parameters:
valid_policy – A unicode string of a policy name or OID
qualifier_set – An instance of asn1crypto.x509.PolicyQualifierInfos
expected_policy_set – A set of unicode strings containing policy names or OIDs
- add_child(valid_policy, qualifier_set, expected_policy_set)
Creates a new PolicyTreeNode as a child of this node
- Parameters:
valid_policy – A unicode string of a policy name or OID
qualifier_set – An instance of asn1crypto.x509.PolicyQualifierInfos
expected_policy_set – A set of unicode strings containing policy names or OIDs
- remove_child(child)
Removes a child from this node
- Parameters:
child – An instance of PolicyTreeNode
- at_depth(depth) Iterable[PolicyTreeNode]
Returns a generator yielding all nodes in the tree at a specific depth
- Parameters:
depth – An integer >= 0 of the depth of nodes to yield
- Returns:
A generator yielding PolicyTreeNode objects
- walk_up(depth)
Returns a generator yielding all nodes in the tree at a specific depth, or above. Yields nodes starting with leaves and traversing up to the root.
- Parameters:
depth – An integer >= 0 of the depth of nodes to walk up from
- Returns:
A generator yielding PolicyTreeNode objects
- nodes_in_current_domain() Iterable[PolicyTreeNode]
Returns a generator yielding all nodes in the tree that are children of an
any_policy
node.
- class pyhanko_certvalidator.policy_tree.PolicyTreeNode(valid_policy: str, qualifier_set: PolicyQualifierInfos, expected_policy_set: Set[str])
Bases:
PolicyTreeRoot
A policy tree node that is used for all nodes but the root
- path_to_root()
pyhanko_certvalidator.registry module
- class pyhanko_certvalidator.registry.CertificateCollection
Bases:
ABC
Abstract base class for read-only access to a collection of certificates.
- retrieve_by_key_identifier(key_identifier: bytes)
Retrieves a cert via its key identifier
- Parameters:
key_identifier – A byte string of the key identifier
- Returns:
None or an asn1crypto.x509.Certificate object
- retrieve_many_by_key_identifier(key_identifier: bytes)
Retrieves possibly multiple certs via the corresponding key identifiers
- Parameters:
key_identifier – A byte string of the key identifier
- Returns:
A list of asn1crypto.x509.Certificate objects
- retrieve_by_name(name: Name)
Retrieves a list certs via their subject name
- Parameters:
name – An asn1crypto.x509.Name object
- Returns:
A list of asn1crypto.x509.Certificate objects
- retrieve_by_issuer_serial(issuer_serial)
Retrieve a certificate by its
issuer_serial
value.- Parameters:
issuer_serial – The
issuer_serial
value of the certificate.- Returns:
The certificate corresponding to the
issuer_serial
key passed in.- Returns:
None or an asn1crypto.x509.Certificate object
- class pyhanko_certvalidator.registry.CertificateStore
Bases:
CertificateCollection
,ABC
- register(cert: Certificate) bool
Register a single certificate.
- Parameters:
cert – Certificate to add.
- Returns:
True
if the certificate was added,False
if it already existed in this store.
- register_multiple(certs: Iterable[Certificate])
Register multiple certificates.
- Parameters:
certs – Certificates to register.
- Returns:
True
if at least one certificate was added,False
if all certificates already existed in this store.
- class pyhanko_certvalidator.registry.SimpleCertificateStore
Bases:
CertificateStore
Simple trustless certificate store.
- classmethod from_certs(certs)
- register(cert: Certificate) bool
Register a single certificate.
- Parameters:
cert – Certificate to add.
- Returns:
True
if the certificate was added,False
if it already existed in this store.
- retrieve_many_by_key_identifier(key_identifier: bytes)
Retrieves possibly multiple certs via the corresponding key identifiers
- Parameters:
key_identifier – A byte string of the key identifier
- Returns:
A list of asn1crypto.x509.Certificate objects
- retrieve_by_name(name: Name)
Retrieves a list certs via their subject name
- Parameters:
name – An asn1crypto.x509.Name object
- Returns:
A list of asn1crypto.x509.Certificate objects
- retrieve_by_issuer_serial(issuer_serial)
Retrieve a certificate by its
issuer_serial
value.- Parameters:
issuer_serial – The
issuer_serial
value of the certificate.- Returns:
The certificate corresponding to the
issuer_serial
key passed in.- Returns:
None or an asn1crypto.x509.Certificate object
- class pyhanko_certvalidator.registry.TrustManager
Bases:
object
Abstract trust manager API.
- is_root(cert: Certificate) bool
Checks if a certificate is in the list of trust roots in this registry
- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
A boolean - if the certificate is in the CA list
- find_potential_issuers(cert: Certificate) Iterator[TrustAnchor]
Find potential issuers that might have (directly) issued a particular certificate.
- Parameters:
cert – Issued certificate.
- Returns:
An iterator with potentially relevant trust anchors.
- class pyhanko_certvalidator.registry.SimpleTrustManager
Bases:
TrustManager
Trust manager backed by a list of trust roots, possibly in addition to the system trust list.
- classmethod build(trust_roots: Iterable[Certificate | TrustAnchor] | None = None, extra_trust_roots: Iterable[Certificate | TrustAnchor] | None = None) SimpleTrustManager
- Parameters:
trust_roots – If the operating system’s trust list should not be used, instead pass a list of asn1crypto.x509.Certificate objects. These certificates will be used as the trust roots for the path being built.
extra_trust_roots – If the operating system’s trust list should be used, but augmented with one or more extra certificates. This should be a list of asn1crypto.x509.Certificate objects.
- Returns:
- is_root(cert: Certificate)
Checks if a certificate is in the list of trust roots in this registry
- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
A boolean - if the certificate is in the CA list
- iter_certs() Iterator[Certificate]
- find_potential_issuers(cert: Certificate) Iterator[TrustAnchor]
Find potential issuers that might have (directly) issued a particular certificate.
- Parameters:
cert – Issued certificate.
- Returns:
An iterator with potentially relevant trust anchors.
- class pyhanko_certvalidator.registry.CertificateRegistry(*, cert_fetcher: CertificateFetcher | None = None)
Bases:
SimpleCertificateStore
Contains certificate lists used to build validation paths, and is also capable of fetching missing certificates if a certificate fetcher is supplied.
- classmethod build(certs: Iterable[Certificate] = (), *, cert_fetcher: CertificateFetcher | None = None)
Convenience method to set up a certificate registry and import certs into it.
- Parameters:
certs – Initial list of certificates to import.
cert_fetcher – Certificate fetcher to handle retrieval of missing certificates (in situations where that is possible).
- Returns:
A populated certificate registry.
- retrieve_by_name(name: Name, first_certificate: Certificate | None = None)
Retrieves a list certs via their subject name
- Parameters:
name – An asn1crypto.x509.Name object
first_certificate – An asn1crypto.x509.Certificate object that if found, should be placed first in the result list
- Returns:
A list of asn1crypto.x509.Certificate objects
- find_potential_issuers(cert: Certificate, trust_manager: TrustManager) Iterator[TrustAnchor | Certificate]
- async fetch_missing_potential_issuers(cert: Certificate)
- class pyhanko_certvalidator.registry.PathBuilder(trust_manager: TrustManager, registry: CertificateRegistry)
Bases:
object
Class to handle path building.
- build_paths(end_entity_cert)
Builds a list of ValidationPath objects from a certificate in the operating system trust store to the end-entity certificate
Note
This is a synchronous equivalent of
async_build_paths()
that calls the latter in a new event loop. As such, it can’t be used from within asynchronous code.- Parameters:
end_entity_cert – A byte string of a DER or PEM-encoded X.509 certificate, or an instance of asn1crypto.x509.Certificate
- Returns:
A list of pyhanko_certvalidator.path.ValidationPath objects that represent the possible paths from the end-entity certificate to one of the CA certs.
- async async_build_paths(end_entity_cert: Certificate)
Builds a list of ValidationPath objects from a certificate in the operating system trust store to the end-entity certificate, returning all paths in a single list.
- Parameters:
end_entity_cert – A byte string of a DER or PEM-encoded X.509 certificate, or an instance of asn1crypto.x509.Certificate
- Returns:
A list of pyhanko_certvalidator.path.ValidationPath objects that represent the possible paths from the end-entity certificate to one of the CA certs.
- async_build_paths_lazy(end_entity_cert: Certificate) CancelableAsyncIterator[ValidationPath]
Builds a list of ValidationPath objects from a certificate in the operating system trust store to the end-entity certificate, and emit them as an asynchronous generator.
- Parameters:
end_entity_cert – A byte string of a DER or PEM-encoded X.509 certificate, or an instance of asn1crypto.x509.Certificate
- Returns:
An asynchronous iterator that yields pyhanko_certvalidator.path.ValidationPath objects that represent the possible paths from the end-entity certificate to one of the CA certs, and raises PathBuildingError if no paths could be built
- class pyhanko_certvalidator.registry.LazyPathIterator(walker: _PathWalker, cert: Certificate)
Bases:
CancelableAsyncIterator
[ValidationPath
]- async cancel()
- class pyhanko_certvalidator.registry.LayeredCertificateStore(stores: List[CertificateCollection])
Bases:
CertificateCollection
Trustless certificate store that looks up certificates in other stores in a specific order.
- retrieve_many_by_key_identifier(key_identifier: bytes)
Retrieves possibly multiple certs via the corresponding key identifiers
- Parameters:
key_identifier – A byte string of the key identifier
- Returns:
A list of asn1crypto.x509.Certificate objects
- retrieve_by_name(name: Name)
Retrieves a list certs via their subject name
- Parameters:
name – An asn1crypto.x509.Name object
- Returns:
A list of asn1crypto.x509.Certificate objects
- retrieve_by_issuer_serial(issuer_serial)
Retrieve a certificate by its
issuer_serial
value.- Parameters:
issuer_serial – The
issuer_serial
value of the certificate.- Returns:
The certificate corresponding to the
issuer_serial
key passed in.- Returns:
None or an asn1crypto.x509.Certificate object
pyhanko_certvalidator.util module
- pyhanko_certvalidator.util.extract_dir_name(names: GeneralNames, err_msg_prefix: str) Name
- pyhanko_certvalidator.util.extract_ac_issuer_dir_name(attr_cert: AttributeCertificateV2) Name
- pyhanko_certvalidator.util.get_issuer_dn(cert: Certificate | AttributeCertificateV2) Name
- pyhanko_certvalidator.util.issuer_serial(cert: Certificate | AttributeCertificateV2) bytes
- pyhanko_certvalidator.util.get_ac_extension_value(attr_cert: AttributeCertificateV2, ext_name: str)
- pyhanko_certvalidator.util.get_relevant_crl_dps(cert: Certificate | AttributeCertificateV2, *, use_deltas) List[DistributionPoint]
- pyhanko_certvalidator.util.get_ocsp_urls(cert: Certificate | AttributeCertificateV2)
- pyhanko_certvalidator.util.get_declared_revinfo(cert: Certificate | AttributeCertificateV2)
- pyhanko_certvalidator.util.validate_sig(signature: bytes, signed_data: bytes, public_key_info: PublicKeyInfo, sig_algo: str, hash_algo: str, parameters=None)
pyhanko_certvalidator.validate module
- pyhanko_certvalidator.validate.validate_path(validation_context, path, parameters: PKIXValidationParams | None = None)
Validates the path using the algorithm from https://tools.ietf.org/html/rfc5280#section-6.1.
Critical extensions on the end-entity certificate are not validated and are left up to the consuming application to process and/or fail on.
Note
This is a synchronous equivalent of
async_validate_path()
that calls the latter in a new event loop. As such, it can’t be used from within asynchronous code.- Parameters:
validation_context – A pyhanko_certvalidator.context.ValidationContext object to use for configuring validation behavior
path – A pyhanko_certvalidator.path.ValidationPath object of the path to validate
parameters – Additional input parameters to the PKIX validation algorithm. These are not used when validating CRLs and OCSP responses.
- Raises:
pyhanko_certvalidator.errors.PathValidationError - when an error occurs validating the path pyhanko_certvalidator.errors.RevokedError - when the certificate or another certificate in its path has been revoked
- Returns:
The final certificate in the path - an instance of asn1crypto.x509.Certificate
- async pyhanko_certvalidator.validate.async_validate_path(validation_context: ValidationContext, path: ValidationPath, parameters: PKIXValidationParams | None = None)
Validates the path using the algorithm from https://tools.ietf.org/html/rfc5280#section-6.1.
Critical extensions on the end-entity certificate are not validated and are left up to the consuming application to process and/or fail on.
- Parameters:
validation_context – A pyhanko_certvalidator.context.ValidationContext object to use for configuring validation behavior
path – A pyhanko_certvalidator.path.ValidationPath object of the path to validate
parameters – Additional input parameters to the PKIX validation algorithm. These are not used when validating CRLs and OCSP responses.
- Raises:
pyhanko_certvalidator.errors.PathValidationError - when an error occurs validating the path pyhanko_certvalidator.errors.RevokedError - when the certificate or another certificate in its path has been revoked
- Returns:
The final certificate in the path - an instance of asn1crypto.x509.Certificate
- pyhanko_certvalidator.validate.validate_tls_hostname(validation_context: ValidationContext, cert: Certificate, hostname: str)
Validates the end-entity certificate from a pyhanko_certvalidator.path.ValidationPath object to ensure that the certificate is valid for the hostname provided and that the certificate is valid for the purpose of a TLS connection.
THE CERTIFICATE PATH MUST BE VALIDATED SEPARATELY VIA validate_path()!
- Parameters:
validation_context – A pyhanko_certvalidator.context.ValidationContext object to use for configuring validation behavior
cert – An asn1crypto.x509.Certificate object returned from validate_path()
hostname – A unicode string of the TLS server hostname
- Raises:
pyhanko_certvalidator.errors.InvalidCertificateError - when the certificate is not valid for TLS or the hostname
- pyhanko_certvalidator.validate.validate_usage(validation_context: ValidationContext, cert: Certificate, key_usage: Set[str], extended_key_usage: Set[str], extended_optional: bool)
Validates the end-entity certificate from a pyhanko_certvalidator.path.ValidationPath object to ensure that the certificate is valid for the key usage and extended key usage purposes specified.
THE CERTIFICATE PATH MUST BE VALIDATED SEPARATELY VIA validate_path()!
- Parameters:
validation_context – A pyhanko_certvalidator.context.ValidationContext object to use for configuring validation behavior
cert – An asn1crypto.x509.Certificate object returned from validate_path()
key_usage – A set of unicode strings of the required key usage purposes
extended_key_usage – A set of unicode strings of the required extended key usage purposes
extended_optional – A bool - if the extended_key_usage extension may be omitted and still considered valid
- Raises:
pyhanko_certvalidator.errors.InvalidCertificateError - when the certificate is not valid for the usages specified
- pyhanko_certvalidator.validate.validate_aa_usage(validation_context: ValidationContext, cert: Certificate, extended_key_usage: Set[str] | None = None)
Validate AA certificate profile conditions in RFC 5755 § 4.5
- Parameters:
validation_context –
cert –
extended_key_usage –
- Returns:
- pyhanko_certvalidator.validate.check_ac_holder_match(holder_cert: Certificate, holder: Holder)
Match a candidate holder certificate against the holder entry of an attribute certificate.
- Parameters:
holder_cert – Candidate holder certificate.
holder – Holder value to match against.
- Returns:
Return the parts of the holder entry that mismatched as a set. Possible values are ‘base_certificate_id’, ‘entity_name’ and ‘object_digest_info’. If the returned set is empty, all entries in the holder entry matched the information in the certificate.
- class pyhanko_certvalidator.validate.ACValidationResult(attr_cert: AttributeCertificateV2, aa_cert: Certificate, aa_path: ValidationPath, approved_attributes: Dict[str, AttCertAttribute])
Bases:
object
The result of a successful attribute certificate validation.
- attr_cert: AttributeCertificateV2
The attribute certificate that was validated.
- aa_cert: Certificate
The attribute authority that issued the certificate.
- aa_path: ValidationPath
The validation path of the attribute authority’s certificate.
- approved_attributes: Dict[str, AttCertAttribute]
Approved attributes in the attribute certificate, possibly filtered by AA controls.
- async pyhanko_certvalidator.validate.async_validate_ac(attr_cert: AttributeCertificateV2, validation_context: ValidationContext, aa_pkix_params: PKIXValidationParams = PKIXValidationParams(user_initial_policy_set=frozenset({'any_policy'}), initial_policy_mapping_inhibit=False, initial_explicit_policy=False, initial_any_policy_inhibit=False, initial_permitted_subtrees=None, initial_excluded_subtrees=None), holder_cert: Certificate | None = None) ACValidationResult
Validate an attribute certificate with respect to a given validation context.
- Parameters:
attr_cert – The attribute certificate to validate.
validation_context – The validation context to validate against.
aa_pkix_params – PKIX validation parameters to supply to the path validation algorithm applied to the attribute authority’s certificate.
holder_cert –
Certificate of the presumed holder to match against the AC’s holder entry. If not provided, the holder check is left to the caller to perform.
Note
This is a convenience option in case there’s only one reasonable candidate holder certificate (e.g. when the attribute certificates are part of a CMS SignedData value with only a single signer).
- Returns:
An
ACValidationResult
detailing the validation result, if successful.
- async pyhanko_certvalidator.validate.intl_validate_path(validation_context: ValidationContext, path: ValidationPath, proc_state: ValProcState, parameters: PKIXValidationParams | None = None)
Internal copy of validate_path() that allows overriding the name of the end-entity certificate as used in exception messages. This functionality is used during chain validation when dealing with indirect CRLs issuer or OCSP responder certificates.
- Parameters:
validation_context – A pyhanko_certvalidator.context.ValidationContext object to use for configuring validation behavior
path – A pyhanko_certvalidator.path.ValidationPath object of the path to validate
proc_state – Internal state for error reporting and policy application decisions.
parameters – Additional input parameters to the PKIX validation algorithm. These are not used when validating CRLs and OCSP responses.
- Returns:
The final certificate in the path - an instance of asn1crypto.x509.Certificate
pyhanko_certvalidator.version module
Module contents
- class pyhanko_certvalidator.CertificateValidator(end_entity_cert: Certificate, intermediate_certs: Iterable[Certificate] | None = None, validation_context: ValidationContext | None = None, pkix_params: PKIXValidationParams | None = None)
Bases:
object
- property certificate
- async async_validate_path() ValidationPath
Builds possible certificate paths and validates them until a valid one is found, or all fail.
- Raises:
pyhanko_certvalidator.errors.PathBuildingError - when an error occurs building the path pyhanko_certvalidator.errors.PathValidationError - when an error occurs validating the path pyhanko_certvalidator.errors.RevokedError - when the certificate or another certificate in its path has been revoked
- validate_usage(key_usage, extended_key_usage=None, extended_optional=False)
Validates the certificate path and that the certificate is valid for the key usage and extended key usage purposes specified.
Deprecated since version 0.17.0: Use
async_validate_usage()
instead.- Parameters:
key_usage –
A set of unicode strings of the required key usage purposes. Valid values include:
”digital_signature”
”non_repudiation”
”key_encipherment”
”data_encipherment”
”key_agreement”
”key_cert_sign”
”crl_sign”
”encipher_only”
”decipher_only”
extended_key_usage –
A set of unicode strings of the required extended key usage purposes. These must be either dotted number OIDs, or one of the following extended key usage purposes:
”server_auth”
”client_auth”
”code_signing”
”email_protection”
”ipsec_end_system”
”ipsec_tunnel”
”ipsec_user”
”time_stamping”
”ocsp_signing”
”wireless_access_points”
An example of a dotted number OID:
”1.3.6.1.5.5.7.3.1”
extended_optional – A bool - if the extended_key_usage extension may be ommited and still considered valid
- Raises:
pyhanko_certvalidator.errors.PathValidationError - when an error occurs validating the path pyhanko_certvalidator.errors.RevokedError - when the certificate or another certificate in its path has been revoked pyhanko_certvalidator.errors.InvalidCertificateError - when the certificate is not valid for the usages specified
- Returns:
A pyhanko_certvalidator.path.ValidationPath object of the validated certificate validation path
- async async_validate_usage(key_usage, extended_key_usage=None, extended_optional=False)
Validates the certificate path and that the certificate is valid for the key usage and extended key usage purposes specified.
- Parameters:
key_usage –
A set of unicode strings of the required key usage purposes. Valid values include:
”digital_signature”
”non_repudiation”
”key_encipherment”
”data_encipherment”
”key_agreement”
”key_cert_sign”
”crl_sign”
”encipher_only”
”decipher_only”
extended_key_usage –
A set of unicode strings of the required extended key usage purposes. These must be either dotted number OIDs, or one of the following extended key usage purposes:
”server_auth”
”client_auth”
”code_signing”
”email_protection”
”ipsec_end_system”
”ipsec_tunnel”
”ipsec_user”
”time_stamping”
”ocsp_signing”
”wireless_access_points”
An example of a dotted number OID:
”1.3.6.1.5.5.7.3.1”
extended_optional – A bool - if the extended_key_usage extension may be ommited and still considered valid
- Raises:
pyhanko_certvalidator.errors.PathValidationError - when an error occurs validating the path pyhanko_certvalidator.errors.RevokedError - when the certificate or another certificate in its path has been revoked pyhanko_certvalidator.errors.InvalidCertificateError - when the certificate is not valid for the usages specified
- Returns:
A pyhanko_certvalidator.path.ValidationPath object of the validated certificate validation path
- validate_tls(hostname)
Validates the certificate path, that the certificate is valid for the hostname provided and that the certificate is valid for the purpose of a TLS connection.
Deprecated since version 0.17.0: Use
async_validate_tls()
instead.- Parameters:
hostname – A unicode string of the TLS server hostname
- Raises:
pyhanko_certvalidator.errors.PathValidationError - when an error occurs validating the path pyhanko_certvalidator.errors.RevokedError - when the certificate or another certificate in its path has been revoked pyhanko_certvalidator.errors.InvalidCertificateError - when the certificate is not valid for TLS or the hostname
- Returns:
A pyhanko_certvalidator.path.ValidationPath object of the validated certificate validation path
- async async_validate_tls(hostname)
Validates the certificate path, that the certificate is valid for the hostname provided and that the certificate is valid for the purpose of a TLS connection.
- Parameters:
hostname – A unicode string of the TLS server hostname
- Raises:
pyhanko_certvalidator.errors.PathValidationError - when an error occurs validating the path pyhanko_certvalidator.errors.RevokedError - when the certificate or another certificate in its path has been revoked pyhanko_certvalidator.errors.InvalidCertificateError - when the certificate is not valid for TLS or the hostname
- Returns:
A pyhanko_certvalidator.path.ValidationPath object of the validated certificate validation path
- class pyhanko_certvalidator.ValidationContext(trust_roots: Iterable[Certificate | TrustAnchor] | None = None, extra_trust_roots: Iterable[Certificate | TrustAnchor] | None = None, other_certs: Iterable[Certificate] | None = None, whitelisted_certs: Iterable[bytes | str] | None = None, moment: datetime | None = None, best_signature_time: datetime | None = None, allow_fetching: bool = False, crls: Iterable[bytes | CertificateList] | None = None, ocsps: Iterable[bytes | OCSPResponse] | None = None, revocation_mode: str = 'soft-fail', revinfo_policy: CertRevTrustPolicy | None = None, weak_hash_algos: Iterable[str] | None = None, time_tolerance: timedelta = datetime.timedelta(seconds=1), retroactive_revinfo: bool = False, fetcher_backend: FetcherBackend | None = None, acceptable_ac_targets: ACTargetDescription | None = None, poe_manager: POEManager | None = None, revinfo_manager: RevinfoManager | None = None, certificate_registry: CertificateRegistry | None = None, trust_manager: TrustManager | None = None, algorithm_usage_policy: AlgorithmUsagePolicy | None = None, fetchers: Fetchers | None = None)
Bases:
object
- property revinfo_manager: RevinfoManager
- property revinfo_policy: CertRevTrustPolicy
- property retroactive_revinfo: bool
- property time_tolerance: timedelta
- property moment: datetime
- property best_signature_time: datetime
- property fetching_allowed: bool
- property crls: List[CertificateList]
A list of all cached
crl.CertificateList
objects
- property ocsps: List[OCSPResponse]
A list of all cached
ocsp.OCSPResponse
objects
- property soft_fail_exceptions
A list of soft-fail exceptions that were ignored during checks
- is_whitelisted(cert)
Checks to see if a certificate has been whitelisted
- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
A bool - if the certificate is whitelisted
- async async_retrieve_crls(cert)
- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
A list of asn1crypto.crl.CertificateList objects
- retrieve_crls(cert)
Deprecated since version 0.17.0: Use
async_retrieve_crls()
instead.- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
A list of asn1crypto.crl.CertificateList objects
- async async_retrieve_ocsps(cert, issuer)
- Parameters:
cert – An asn1crypto.x509.Certificate object
issuer – An asn1crypto.x509.Certificate object of cert’s issuer
- Returns:
A list of asn1crypto.ocsp.OCSPResponse objects
- retrieve_ocsps(cert, issuer)
Deprecated since version 0.17.0: Use
async_retrieve_ocsps()
instead.- Parameters:
cert – An asn1crypto.x509.Certificate object
issuer – An asn1crypto.x509.Certificate object of cert’s issuer
- Returns:
A list of asn1crypto.ocsp.OCSPResponse objects
- record_validation(cert, path)
Records that a certificate has been validated, along with the path that was used for validation. This helps reduce duplicate work when validating a ceritifcate and related resources such as CRLs and OCSPs.
- Parameters:
cert – An ans1crypto.x509.Certificate object
path – A pyhanko_certvalidator.path.ValidationPath object
- check_validation(cert)
Checks to see if a certificate has been validated, and if so, returns the ValidationPath used to validate it.
- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
None if not validated, or a pyhanko_certvalidator.path.ValidationPath object of the validation path
- clear_validation(cert)
Clears the record that a certificate has been validated
- Parameters:
cert – An ans1crypto.x509.Certificate object
- property acceptable_ac_targets: ACTargetDescription | None
- class pyhanko_certvalidator.PKIXValidationParams(user_initial_policy_set: frozenset = frozenset({'any_policy'}), initial_policy_mapping_inhibit: bool = False, initial_explicit_policy: bool = False, initial_any_policy_inhibit: bool = False, initial_permitted_subtrees: Dict[pyhanko_certvalidator.name_trees.GeneralNameType, Set[pyhanko_certvalidator.name_trees.NameSubtree]] | None = None, initial_excluded_subtrees: Dict[pyhanko_certvalidator.name_trees.GeneralNameType, Set[pyhanko_certvalidator.name_trees.NameSubtree]] | None = None)
Bases:
object
- user_initial_policy_set: frozenset = frozenset({'any_policy'})
Set of policies that the user is willing to accept. By default, any policy is acceptable.
When setting this parameter to a non-default value, you probably want to set
initial_explicit_policy
as well.Note
These are specified in the policy domain of the trust root(s), and subject to policy mapping by intermediate certificate authorities.
- initial_policy_mapping_inhibit: bool = False
Flag indicating whether policy mapping is forbidden along the entire certification chains. By default, policy mapping is permitted.
Note
Policy constraints on intermediate certificates may force policy mapping to be inhibited from some point onwards.
- initial_explicit_policy: bool = False
Flag indicating whether path validation must terminate with at least one permissible policy; see
user_initial_policy_set
. By default, no such requirement is imposed.Note
If
user_initial_policy_set
is set to its default value of{'any_policy'}
, the effect is that the path validation must accept at least one policy, without specifying which.Warning
Due to widespread mis-specification of policy extensions in the wild, many real-world certification chains terminate with an empty set (or rather, tree) of valid policies. Therefore, this flag is set to
False
by default.
- initial_any_policy_inhibit: bool = False
Flag indicating whether
anyPolicy
should be left unprocessed when it appears in a certificate. By default,anyPolicy
is always processed when it appears.
- initial_permitted_subtrees: Dict[GeneralNameType, Set[NameSubtree]] | None = None
Set of permitted subtrees for each name type, indicating restrictions to impose on subject names (and alternative names) in the certification path.
By default, all names are permitted. This behaviour can be modified by name constraints on intermediate CA certificates.
- initial_excluded_subtrees: Dict[GeneralNameType, Set[NameSubtree]] | None = None
Set of excluded subtrees for each name type, indicating restrictions to impose on subject names (and alternative names) in the certification path.
By default, no names are excluded. This behaviour can be modified by name constraints on intermediate CA certificates.
- merge(other: PKIXValidationParams) PKIXValidationParams
Combine the conditions of these PKIX validation params with another set of parameters, producing the most lenient set of parameters that is stricter than both inputs.
- Parameters:
other – Another set of PKIX validation parameters.
- Returns:
A combined set of PKIX validation parameters.
- async pyhanko_certvalidator.find_valid_path(certificate: Certificate, paths: CancelableAsyncIterator[ValidationPath], validation_context: ValidationContext, pkix_validation_params: PKIXValidationParams | None = None)