pyhanko.sign.validation.ades module

This module contains a number of functions to handle AdES signature validation.

Danger

This API is incubating, and not all features of the spec have been fully implemented at this stage. There will be bugs, and API changes may still occur.

async pyhanko.sign.validation.ades.ades_basic_validation(signed_data: ~asn1crypto.cms.SignedData, validation_spec: ~pyhanko.sign.validation.policy_decl.SignatureValidationSpec, timing_info: ~typing.Optional[~pyhanko_certvalidator.ltv.types.ValidationTimingInfo] = None, raw_digest: ~typing.Optional[bytes] = None, validation_data_handlers: ~typing.Optional[~pyhanko_certvalidator.context.ValidationDataHandlers] = None, signature_not_before_time: ~typing.Optional[~datetime.datetime] = None, extra_status_kwargs: ~typing.Optional[~typing.Dict[str, ~typing.Any]] = None, status_cls: ~typing.Type[~pyhanko.sign.validation.ades.StatusType] = <class 'pyhanko.sign.validation.status.StandardCMSSignatureStatus'>) → AdESBasicValidationResult

Validate a CMS signature according to ETSI EN 319 102-1 § 5.3.

Parameters:

signed_data – The SignedData value.
validation_spec – Validation settings to apply.
raw_digest – The expected message digest attribute value.
timing_info – Data object describing the timing of the validation. Defaults to ValidationTimingInfo.now().
validation_data_handlers – Data handlers to manage validation data.
extra_status_kwargs – Extra keyword arguments to pass to the signature status object’s __init__ function.
status_cls – The class of the resulting status object in pyHanko’s internal validation API.
signature_not_before_time – Time when the signature was known _not_ to exist.

Returns:

A AdESBasicValidationResult.

async pyhanko.sign.validation.ades.ades_with_time_validation(signed_data: ~asn1crypto.cms.SignedData, validation_spec: ~pyhanko.sign.validation.policy_decl.SignatureValidationSpec, timing_info: ~typing.Optional[~pyhanko_certvalidator.ltv.types.ValidationTimingInfo] = None, raw_digest: ~typing.Optional[bytes] = None, validation_data_handlers: ~typing.Optional[~pyhanko_certvalidator.context.ValidationDataHandlers] = None, signature_not_before_time: ~typing.Optional[~datetime.datetime] = None, extra_status_kwargs: ~typing.Optional[~typing.Dict[str, ~typing.Any]] = None, status_cls: ~typing.Type[~pyhanko.sign.validation.ades.StatusType] = <class 'pyhanko.sign.validation.status.StandardCMSSignatureStatus'>) → AdESWithTimeValidationResult

Validate a CMS signature with time according to ETSI EN 319 102-1 § 5.5.

Parameters:

signed_data – The SignedData value.
validation_spec – Validation settings to apply.
raw_digest – The expected message digest attribute value.
timing_info – Data object describing the timing of the validation. Defaults to ValidationTimingInfo.now().
validation_data_handlers – Data handlers to manage validation data.
extra_status_kwargs – Extra keyword arguments to pass to the signature status object’s __init__ function.
status_cls – The class of the resulting status object in pyHanko’s internal validation API.
signature_not_before_time – Time when the signature was known _not_ to exist.

Returns:

A AdESBasicValidationResult.

async pyhanko.sign.validation.ades.ades_lta_validation(embedded_sig: EmbeddedPdfSignature, pdf_validation_spec: PdfSignatureValidationSpec, timing_info: Optional[ValidationTimingInfo] = None, signature_not_before_time: Optional[datetime] = None) → AdESLTAValidationResult

Validate a PAdES signature providing long-term availability and integrity of validation material. See ETSI EN 319 102-1, § 5.6.3.

For the purposes of PAdES validation, the chain of document time stamps in the document serves as the unique Evidence Record (ER).

Parameters:

embedded_sig – The PDF signature to validate.
pdf_validation_spec – PDF signature validation settings.
timing_info – Data object describing the timing of the validation. Defaults to ValidationTimingInfo.now().
signature_not_before_time – Time when the signature was known _not_ to exist.

Returns:

A validation result.

async pyhanko.sign.validation.ades.ades_timestamp_validation(tst_signed_data: ~asn1crypto.cms.SignedData, validation_spec: ~pyhanko.sign.validation.policy_decl.SignatureValidationSpec, expected_tst_imprint: bytes, timing_info: ~typing.Optional[~pyhanko_certvalidator.ltv.types.ValidationTimingInfo] = None, validation_data_handlers: ~typing.Optional[~pyhanko_certvalidator.context.ValidationDataHandlers] = None, extra_status_kwargs: ~typing.Optional[~typing.Dict[str, ~typing.Any]] = None, status_cls: ~typing.Type[~pyhanko.sign.validation.ades.StatusType] = <class 'pyhanko.sign.validation.status.TimestampSignatureStatus'>) → AdESBasicValidationResult

Validate a timestamp token according to ETSI EN 319 102-1 § 5.4.

Parameters:

tst_signed_data – The SignedData value of the timestamp.
validation_spec – Validation settings to apply.
expected_tst_imprint – The expected message imprint in the timestamp token.
timing_info – Data object describing the timing of the validation. Defaults to ValidationTimingInfo.now().
validation_data_handlers – Data handlers to manage validation data.
extra_status_kwargs – Extra keyword arguments to pass to the signature status object’s __init__ function.
status_cls – The class of the resulting status object in pyHanko’s internal validation API.

Returns:

A AdESBasicValidationResult.

class pyhanko.sign.validation.ades.AdESBasicValidationResult(ades_subindic: AdESSubIndic, api_status: Optional[StatusType], failure_msg: Optional[str])

Bases: object

Result of validation of basic signatures.

ETSI EN 319 102-1, § 5.3

ades_subindic: AdESSubIndic: AdES subindication.

api_status: Optional[StatusType]: A status descriptor object from pyHanko’s own validation API. Will be an instance of SignatureStatus or a subclass thereof.

failure_msg: Optional[str]: A string describing the reason why validation failed, if applicable.

class pyhanko.sign.validation.ades.AdESWithTimeValidationResult(ades_subindic: pyhanko.sign.ades.report.AdESSubIndic, api_status: Union[StatusType, NoneType], failure_msg: Union[str, NoneType], best_signature_time: datetime.datetime, signature_not_before_time: Union[datetime.datetime, NoneType])

Bases: AdESBasicValidationResult

best_signature_time: datetime

signature_not_before_time: Optional[datetime]

class pyhanko.sign.validation.ades.AdESLTAValidationResult(ades_subindic: AdESSubIndic, api_status: Optional[StatusType], failure_msg: Optional[str], best_signature_time: datetime, signature_not_before_time: Optional[datetime], oldest_evidence_record_timestamp: Optional[datetime], signature_timestamp_status: Optional[AdESBasicValidationResult])

Bases: AdESWithTimeValidationResult

Result of a PAdES validation for a signature providing long-term availability and integrity of validation material. See ETSI EN 319 102-1, § 5.6.3.

oldest_evidence_record_timestamp: Optional[datetime]: The oldest timestamp in the evidence record, after validation.

Note

For PAdES, this refers to the chain of document timestamp signatures after signing.

signature_timestamp_status: Optional[AdESBasicValidationResult]: The validation result for the signature time stamp, if applicable.