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 a OCSPContainer contains more than one SingleResponse, then the same OCSP response will be duplicated into multiple containers, each with a different index value.

Parameters:

ocsp_response – An OCSP response.

Returns:

A list of OCSPContainer objects, one for each SingleResponse 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

New 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]

New 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]

New 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:

A CRLCollectionResult.

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:

A OCSPCollectionResult.

Module contents