pyhanko_certvalidator.revinfo package
Submodules
pyhanko_certvalidator.revinfo.archival module
- class pyhanko_certvalidator.revinfo.archival.RevinfoUsabilityRating(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
Enum
Description of whether a piece of revocation information is considered usable in the circumstances provided.
- OK = 1
The revocation information is usable.
- STALE = 2
The revocation information is stale/too old.
- TOO_NEW = 3
The revocation information is too recent.
Note
This is never an issue in the AdES validation model.
- UNCLEAR = 4
The usability of the revocation information could not be assessed unambiguously.
- property usable_ades: bool
Boolean indicating whether the assigned rating corresponds to a “fresh” judgment in AdES.
- class pyhanko_certvalidator.revinfo.archival.RevinfoUsability(rating: RevinfoUsabilityRating, last_usable_at: datetime | None = None)
Bases:
object
Usability rating and cutoff date for a particular piece of revocation information.
- rating: RevinfoUsabilityRating
The rating assigned.
- last_usable_at: datetime | None = None
The last date at which the revocation information could have been considered usable, if applicable.
- class pyhanko_certvalidator.revinfo.archival.RevinfoContainer
Bases:
IssuedItemContainer
,ABC
A container for a piece of revocation information.
- usable_at(policy: CertRevTrustPolicy, timing_params: ValidationTimingParams) RevinfoUsability
Assess the usability of the revocation information given a revocation information trust policy and timing parameters.
- Parameters:
policy – The revocation information trust policy.
timing_params – Timing-related information.
- Returns:
A
RevinfoUsability
judgment.
- property revinfo_sig_mechanism_used: SignedDigestAlgorithm | None
Extract the signature mechanism used to guarantee the authenticity of the revocation information, if applicable.
- class pyhanko_certvalidator.revinfo.archival.OCSPContainer(ocsp_response_data: OCSPResponse, index: int = 0)
Bases:
RevinfoContainer
Container for an OCSP response.
- ocsp_response_data: OCSPResponse
The OCSP response value.
- index: int = 0
The index of the
SingleResponse
payload in the original OCSP response object retrieved from the server, if applicable.
- classmethod load_multi(ocsp_response: OCSPResponse) List[OCSPContainer]
Turn an OCSP response object into one or more
OCSPContainer
objects. If aOCSPContainer
contains more than oneSingleResponse
, then the same OCSP response will be duplicated into multiple containers, each with a differentindex
value.- Parameters:
ocsp_response – An OCSP response.
- Returns:
A list of
OCSPContainer
objects, one for eachSingleResponse
value.
- property issuance_date: datetime | None
The issuance date of the item.
- usable_at(policy: CertRevTrustPolicy, timing_params: ValidationTimingParams) RevinfoUsability
Assess the usability of the revocation information given a revocation information trust policy and timing parameters.
- Parameters:
policy – The revocation information trust policy.
timing_params – Timing-related information.
- Returns:
A
RevinfoUsability
judgment.
- extract_basic_ocsp_response() BasicOCSPResponse | None
Extract the
BasicOCSPResponse
, assuming there is one (i.e. the OCSP response is a standard, non-error response).
- extract_single_response() SingleResponse | None
Extract the unique
SingleResponse
value identified by the index.
- property revinfo_sig_mechanism_used: SignedDigestAlgorithm | None
Extract the signature mechanism used to guarantee the authenticity of the revocation information, if applicable.
- class pyhanko_certvalidator.revinfo.archival.CRLContainer(crl_data: CertificateList)
Bases:
RevinfoContainer
Container for a certificate revocation list (CRL).
- crl_data: CertificateList
The CRL data.
- usable_at(policy: CertRevTrustPolicy, timing_params: ValidationTimingParams) RevinfoUsability
Assess the usability of the revocation information given a revocation information trust policy and timing parameters.
- Parameters:
policy – The revocation information trust policy.
timing_params – Timing-related information.
- Returns:
A
RevinfoUsability
judgment.
- property issuance_date: datetime | None
The issuance date of the item.
- property revinfo_sig_mechanism_used: SignedDigestAlgorithm
Extract the signature mechanism used to guarantee the authenticity of the revocation information, if applicable.
- pyhanko_certvalidator.revinfo.archival.sort_freshest_first(lst: Iterable[RevInfoType]) List[RevInfoType]
Sort a list of revocation information containers in freshest-first order.
Revocation information that does not have a well-defined issuance date will be grouped at the end.
- Parameters:
lst – A list of
RevinfoContainer
objects of the same type.- Returns:
The same list sorted from fresh to stale.
- pyhanko_certvalidator.revinfo.archival.process_legacy_crl_input(crls: Iterable[bytes | CertificateList | CRLContainer]) List[CRLContainer]
Internal function to process legacy CRL data into one or more
CRLContainer
.- Parameters:
crls – Legacy CRL input data.
- Returns:
A list of
CRLContainer
objects.
- pyhanko_certvalidator.revinfo.archival.process_legacy_ocsp_input(ocsps: Iterable[bytes | OCSPResponse | OCSPContainer]) List[OCSPContainer]
Internal function to process legacy OCSP data into one or more
OCSPContainer
.- Parameters:
ocsps – Legacy OCSP input data.
- Returns:
A list of
OCSPContainer
objects.
pyhanko_certvalidator.revinfo.constants module
pyhanko_certvalidator.revinfo.manager module
- class pyhanko_certvalidator.revinfo.manager.RevinfoManager(certificate_registry: CertificateRegistry, poe_manager: POEManager, crls: Iterable[CRLContainer], ocsps: Iterable[OCSPContainer], assertions: Iterable[NonRevokedStatusAssertion] = (), fetchers: Fetchers | None = None)
Bases:
object
Added in version 0.20.0.
Class to manage and potentially fetch revocation information.
- Parameters:
certificate_registry – The associated certificate registry.
poe_manager – The proof-of-existence (POE) data manager.
crls – CRL data.
ocsps – OCSP response data.
fetchers – Fetchers for collecting revocation information. If
None
, no fetching will be performed.
- property poe_manager: POEManager
The proof-of-existence (POE) data manager.
- property certificate_registry: CertificateRegistry
The associated certificate registry.
- property fetching_allowed: bool
Boolean indicating whether fetching is allowed.
- 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 new_revocation_certs: List[Certificate]
A list of newly-fetched
x509.Certificate
objects that were obtained from OCSP responses and CRLs
- record_crl_issuer(certificate_list, cert)
Records the certificate that issued a certificate list. Used to reduce processing code when dealing with self-issued certificates and multiple CRLs.
- Parameters:
certificate_list – An ans1crypto.crl.CertificateList object
cert – An ans1crypto.x509.Certificate object
- check_crl_issuer(certificate_list) Certificate | None
Checks to see if the certificate that signed a certificate list has been found
- Parameters:
certificate_list – An ans1crypto.crl.CertificateList object
- Returns:
None if not found, or an asn1crypto.x509.Certificate object of the issuer
- async async_retrieve_crls(cert) List[CRLContainer]
Added in version 0.20.0.
- Parameters:
cert – An asn1crypto.x509.Certificate object
- Returns:
A list of
CRLContainer
objects
- async async_retrieve_ocsps(cert, authority: Authority) List[OCSPContainer]
Added in version 0.20.0.
- Parameters:
cert – An asn1crypto.x509.Certificate object
authority – The issuing authority for the certificate
- Returns:
A list of
OCSPContainer
objects
- evict_ocsps(hashes_to_evict: Set[bytes])
Internal API to eliminate local OCSP records from consideration.
- Parameters:
hashes_to_evict – A collection of OCSP response hashes; see
digest_for_poe()
.
- evict_crls(hashes_to_evict: Set[bytes])
Internal API to eliminate local CRLs from consideration.
- Parameters:
hashes_to_evict – A collection of CRL hashes; see
digest_for_poe()
.
- check_asserted_unrevoked(cert: Certificate, at: datetime) bool
pyhanko_certvalidator.revinfo.validate_crl module
- class pyhanko_certvalidator.revinfo.validate_crl.CRLWithPaths(crl: CRLContainer, paths: List[ValidationPath])
Bases:
object
A CRL with a number of candidate paths
- crl: CRLContainer
- paths: List[ValidationPath]
- async pyhanko_certvalidator.revinfo.validate_crl.verify_crl(cert: Certificate | AttributeCertificateV2, path: ValidationPath, validation_context: ValidationContext, use_deltas=True, proc_state: ValProcState | None = None)
Verifies a certificate against a list of CRLs, checking to make sure the certificate has not been revoked. Uses the algorithm from https://tools.ietf.org/html/rfc5280#section-6.3 as a basis, but the implementation differs to allow CRLs from unrecorded locations.
- Parameters:
cert – An asn1crypto.x509.Certificate or asn1crypto.cms.AttributeCertificateV2 object to check for in the CRLs
path – A pyhanko_certvalidator.path.ValidationPath object of the cert’s validation path, or in the case of an AC, the AA’s validation path.
validation_context – A pyhanko_certvalidator.context.ValidationContext object to use for caching validation information
use_deltas – A boolean indicating if delta CRLs should be used
proc_state – Internal state for error reporting and policy application decisions.
- Raises:
pyhanko_certvalidator.errors.CRLNoMatchesError - when none of the CRLs match the certificate pyhanko_certvalidator.errors.CRLValidationError - when any error occurs trying to verify the CertificateList pyhanko_certvalidator.errors.RevokedError - when the CRL indicates the certificate has been revoked
- class pyhanko_certvalidator.revinfo.validate_crl.ProvisionalCRLTrust(path: ValidationPath, delta: CRLContainer | None)
Bases:
object
A provisional CRL path, together with an optional delta CRL that may be relevant.
- path: ValidationPath
A provisional validation path for the CRL. Requires path validation.
- delta: CRLContainer | None
A delta CRL that may be relevant to the parent CRL for which the path was put together.
- class pyhanko_certvalidator.revinfo.validate_crl.CRLOfInterest(crl: CRLContainer, prov_paths: List[ProvisionalCRLTrust], is_indirect: bool, crl_authority_name: Name)
Bases:
object
A CRL of interest.
- crl: CRLContainer
The CRL data, packaged in a revocation info container.
- prov_paths: List[ProvisionalCRLTrust]
Candidate validation paths for the CRL, together with relevant delta CRLs, if appropriate.
- is_indirect: bool
Boolean indicating whether the CRL is an indirect one.
- crl_authority_name: Name
Distinguished name for the authority for which the CRL controls revocation.
- class pyhanko_certvalidator.revinfo.validate_crl.CRLCollectionResult(crls: List[CRLOfInterest], failure_msgs: List[str])
Bases:
object
The result of a CRL collection operation for AdES point-in-time validation purposes.
- crls: List[CRLOfInterest]
List of potentially relevant CRLs.
- failure_msgs: List[str]
List of failure messages, for error reporting purposes.
- async pyhanko_certvalidator.revinfo.validate_crl.collect_relevant_crls_with_paths(cert: Certificate | AttributeCertificateV2, path: ValidationPath, revinfo_manager: RevinfoManager, control_time: datetime, use_deltas=True, proc_state: ValProcState | None = None) CRLCollectionResult
Collect potentially relevant CRLs with the associated validation paths. Will not perform actual path validation.
- Parameters:
cert – The certificate under scrutiny.
path – The path currently being evaluated.
revinfo_manager – The revocation info manager.
control_time – The control time before which the validation info should have been issued.
use_deltas – Whether to include delta CRLs.
proc_state – The state of any prior validation process.
- Returns:
- pyhanko_certvalidator.revinfo.validate_crl.find_cert_in_list(cert: Certificate | AttributeCertificateV2, cert_issuer_name: Name, certificate_list: CertificateList, crl_authority_name: Name)
Looks for a cert in the list of revoked certificates
- Parameters:
cert – An asn1crypto.x509.Certificate object of the cert being checked, or an asn1crypto.cms.AttributeCertificateV2 object in the case of an attribute certificate.
cert_issuer_name – The certificate issuer’s distinguished name
certificate_list – An ans1crypto.crl.CertificateList object to look in for the cert
crl_authority_name – The distinguished name of the default authority for which the CRL issues certificates.
- Returns:
A tuple of (None, None) if not present, otherwise a tuple of (asn1crypto.x509.Time object, asn1crypto.crl.CRLReason object) representing the date/time the object was revoked and why
pyhanko_certvalidator.revinfo.validate_ocsp module
- async pyhanko_certvalidator.revinfo.validate_ocsp.verify_ocsp_response(cert: Certificate | AttributeCertificateV2, path: ValidationPath, validation_context: ValidationContext, proc_state: ValProcState | None = None)
Verifies an OCSP response, checking to make sure the certificate has not been revoked. Fulfills the requirements of https://tools.ietf.org/html/rfc6960#section-3.2.
- Parameters:
cert – An asn1cyrpto.x509.Certificate object or an asn1crypto.cms.AttributeCertificateV2 object to verify the OCSP response for
path – A pyhanko_certvalidator.path.ValidationPath object of the cert’s validation path, or in the case of an AC, the AA’s validation path.
validation_context – A pyhanko_certvalidator.context.ValidationContext object to use for caching validation information
proc_state – Internal state for error reporting and policy application decisions.
- Raises:
pyhanko_certvalidator.errors.OCSPNoMatchesError - when none of the OCSP responses match the certificate pyhanko_certvalidator.errors.OCSPValidationIndeterminateError - when the OCSP response could not be verified pyhanko_certvalidator.errors.RevokedError - when the OCSP response indicates the certificate has been revoked
- class pyhanko_certvalidator.revinfo.validate_ocsp.OCSPResponseOfInterest(ocsp_response: pyhanko_certvalidator.revinfo.archival.OCSPContainer, prov_path: pyhanko_certvalidator.path.ValidationPath)
Bases:
object
- ocsp_response: OCSPContainer
- prov_path: ValidationPath
- class pyhanko_certvalidator.revinfo.validate_ocsp.OCSPCollectionResult(responses: List[OCSPResponseOfInterest], failure_msgs: List[str])
Bases:
object
The result of an OCSP collection operation for AdES point-in-time validation purposes.
- responses: List[OCSPResponseOfInterest]
List of potentially relevant OCSP responses.
- failure_msgs: List[str]
List of failure messages, for error reporting purposes.
- async pyhanko_certvalidator.revinfo.validate_ocsp.collect_relevant_responses_with_paths(cert: Certificate | AttributeCertificateV2, path: ValidationPath, revinfo_manager: RevinfoManager, control_time: datetime, proc_state: ValProcState | None = None) OCSPCollectionResult
Collect potentially relevant OCSP responses with the associated validation paths. Will not perform actual path validation.
- Parameters:
cert – The certificate under scrutiny.
path – The path currently being evaluated.
revinfo_manager – The revocation info manager.
control_time – The control time before which the validation info should have been issued.
proc_state – The state of any prior validation process.
- Returns: