pyhanko.sign.validation.status module

class pyhanko.sign.validation.status.SignatureStatus(intact: bool, valid: bool, trust_problem_indic: Optional[AdESSubIndic], signing_cert: Certificate, pkcs7_signature_mechanism: str, md_algorithm: str, validation_path: ValidationPath)

Bases: object

Class describing the validity of a (general) CMS signature.

intact: bool: Reports whether the signature is intact, i.e. whether the hash of the message content (which may or may not be embedded inside the CMS object itself) matches the hash value that was signed.

valid: bool: Reports whether the signature is valid, i.e. whether the hash’s signature actually validates.

trust_problem_indic: Optional[AdESSubIndic]: If not None, provides the AdES subindication indication what went wrong when validating the signer’s certificate.

signing_cert: Certificate: Contains the certificate of the signer, as embedded in the CMS object.

pkcs7_signature_mechanism: str: CMS signature mechanism used.

md_algorithm: str: Message digest algorithm used.

validation_path: ValidationPath: Validation path providing a valid chain of trust from the signer’s certificate to a trusted root certificate.

key_usage: ClassVar[Set[str]] = {'non_repudiation'}: Class property indicating which key usages are accepted on the signer’s certificate. The default is non_repudiation only.

extd_key_usage: ClassVar[Optional[Set[str]]] = None

Class property indicating which extended key usage key purposes are accepted to be present on the signer’s certificate.

See KeyUsageConstraints.extd_key_usage.

summary_fields()

property revoked: bool: Reports whether the signer’s certificate has been revoked or not. If this field is True, then obviously trusted will be False.

property trusted: bool: Reports whether the signer’s certificate is trusted w.r.t. the currently relevant validation context and key usage requirements.

summary(delimiter=','): Provide a textual but machine-parsable summary of the validity.

async classmethod validate_cert_usage(validator: CertificateValidator, key_usage_settings: Optional[KeyUsageConstraints] = None)

class pyhanko.sign.validation.status.TimestampSignatureStatus(intact: bool, valid: bool, trust_problem_indic: Optional[AdESSubIndic], signing_cert: Certificate, pkcs7_signature_mechanism: str, md_algorithm: str, validation_path: ValidationPath, timestamp: datetime)

Bases: SignatureStatus

Signature status class used when validating timestamp tokens.

key_usage: ClassVar[Set[str]] = {}: There are no (non-extended) key usage requirements for TSA certificates.

extd_key_usage: ClassVar[Optional[Set[str]]] = {'time_stamping'}: TSA certificates must have the time_stamping extended key usage extension (OID 1.3.6.1.5.5.7.3.8).

timestamp: datetime: Value of the timestamp token as a datetime object.

describe_timestamp_trust()

class pyhanko.sign.validation.status.X509AttributeInfo(attr_type: AttCertAttributeType, attr_values: Iterable[Asn1Value])

Bases: object

Info on an X.509 attribute.

attr_type: AttCertAttributeType: The certified attribute’s type.

attr_values: Iterable[Asn1Value]: The certified attribute’s values.

class pyhanko.sign.validation.status.CertifiedAttributeInfo(attr_type: AttCertAttributeType, attr_values: Iterable[Asn1Value], validation_results: Iterable[ACValidationResult])

Bases: X509AttributeInfo

Info on a certified attribute, including AC validation results.

validation_results: Iterable[ACValidationResult]: The validation details for the attribute in question (possibly several if values for the same attribute were sourced from several different ACs).

class pyhanko.sign.validation.status.ClaimedAttributes

Bases: object

Container class for extracted information on attributes asserted by a signer without an attribute certificate.

classmethod from_iterable(attrs: Iterable[AttCertAttribute], parse_error_fatal=False)

class pyhanko.sign.validation.status.CertifiedAttributes

Bases: object

Container class for extracted attribute certificate information.

classmethod from_results(results: Iterable[ACValidationResult], parse_error_fatal=False)

class pyhanko.sign.validation.status.CAdESSignerAttributeAssertions(claimed_attrs: ClaimedAttributes, certified_attrs: Optional[CertifiedAttributes] = None, ac_validation_errs: Optional[Collection[Union[PathValidationError, PathBuildingError]]] = None, unknown_attrs_present: bool = False)

Bases: object

Value type describing information extracted (and, if relevant, validated) from a signer-attrs-v2 signed attribute.

claimed_attrs: ClaimedAttributes: Attributes claimed by the signer without additional justification. May be empty.

certified_attrs: Optional[CertifiedAttributes] = None

Attributes claimed by the signer using an attribute certificate.

This field will only be populated if an attribute certificate validation context is available, otherwise its value will be None, even if there are no attribute certificates present.

ac_validation_errs: Optional[Collection[Union[PathValidationError, PathBuildingError]]] = None

Attribute certificate validation errors.

This field will only be populated if an attribute certificate validation context is available, otherwise its value will be None, even if there are no attribute certificates present.

unknown_attrs_present: bool = False

Records if the signer-attrs-v2 attribute contained certificate types or signed assertions that could not be processed.

This does not affect the validation process by default, but will trigger a warning.

property valid

class pyhanko.sign.validation.status.StandardCMSSignatureStatus(intact: bool, valid: bool, trust_problem_indic: Optional[AdESSubIndic], signing_cert: Certificate, pkcs7_signature_mechanism: str, md_algorithm: str, validation_path: ValidationPath, signer_reported_dt: Optional[datetime] = None, timestamp_validity: Optional[TimestampSignatureStatus] = None, content_timestamp_validity: Optional[TimestampSignatureStatus] = None, ac_attrs: Optional[CertifiedAttributes] = None, ac_validation_errs: Optional[Collection[Union[PathValidationError, PathBuildingError]]] = None, cades_signer_attrs: Optional[CAdESSignerAttributeAssertions] = None)

Bases: SignatureStatus

Status of a standard “end-entity” CMS signature, potentially with timing information embedded inside.

signer_reported_dt: Optional[datetime] = None

Signer-reported signing time, if present in the signature.

Generally speaking, this timestamp should not be taken as fact.

timestamp_validity: Optional[TimestampSignatureStatus] = None: Validation status of the signature timestamp token embedded in this signature, if present.

content_timestamp_validity: Optional[TimestampSignatureStatus] = None: Validation status of the content timestamp token embedded in this signature, if present.

ac_attrs: Optional[CertifiedAttributes] = None

Certified attributes sourced from valid attribute certificates embedded into the SignedData’s certificates field and the CAdES-style signer-attrs-v2 attribute (if present).

Will be None if no validation context for attribute certificate validation was provided.

Note

There is a semantic difference between attribute certificates extracted from the certificates field and those extracted from the signer-attrs-v2 attribute. In the former case, the ACs are not covered by the signature. However, a CAdES-style signer-attrs-v2 attribute is signed, so the signer is expected to have explicitly _acknowledged_ all attributes, in the AC. See also cades_signer_attrs.

ac_validation_errs: Optional[Collection[Union[PathValidationError, PathBuildingError]]] = None

Errors encountered while validating attribute certificates embedded into the SignedData’s certificates field and the CAdES-style signer-attrs-v2 attribute (if present).

Will be None if no validation context for attribute certificate validation was provided.

cades_signer_attrs: Optional[CAdESSignerAttributeAssertions] = None: Information extracted and validated from the signed signer-attrs-v2 attribute defined in CAdES.

property bottom_line: bool

Formulates a general judgment on the validity of this signature. This takes into account the cryptographic validity of the signature, the signature’s chain of trust and the validity of the timestamp token (if present).

Returns: True if all constraints are satisfied, False otherwise.

summary_fields()

pretty_print_details()

pretty_print_sections()

class pyhanko.sign.validation.status.SignatureCoverageLevel(value)

Bases: OrderedEnum

Indicate the extent to which a PDF signature (cryptographically) covers a document. Note that this does not pass judgment on whether uncovered updates are legitimate or not, but as a general rule, a legitimate signature will satisfy at least ENTIRE_REVISION.

UNCLEAR = 0: The signature’s coverage is unclear and/or disconnected. In standard PDF signatures, this is usually a bad sign.

CONTIGUOUS_BLOCK_FROM_START = 1: The signature covers a contiguous block in the PDF file stretching from the first byte of the file to the last byte in the indicated /ByteRange. In other words, the only interruption in the byte range is fully occupied by the signature data itself.

ENTIRE_REVISION = 2: The signature covers the entire revision in which it occurs, but incremental updates may have been added later. This is not necessarily evidence of tampering. In particular, it is expected when a file contains multiple signatures. Nonetheless, caution is required.

ENTIRE_FILE = 3: The entire file is covered by the signature.

class pyhanko.sign.validation.status.ModificationInfo(coverage: pyhanko.sign.validation.status.SignatureCoverageLevel = None, diff_result: Union[pyhanko.sign.diff_analysis.policy_api.DiffResult, pyhanko.sign.diff_analysis.policy_api.SuspiciousModification, NoneType] = None)

Bases: object

coverage: SignatureCoverageLevel = None: Indicates how much of the document is covered by the signature.

diff_result: Optional[Union[DiffResult, SuspiciousModification]] = None

Result of the difference analysis run on the file:

If None, no difference analysis was run.
If the difference analysis was successful, this attribute will contain a DiffResult object.
If the difference analysis failed due to unforeseen or suspicious modifications, the SuspiciousModification exception thrown by the difference policy will be stored in this attribute.

property modification_level: Optional[ModificationLevel]

Indicates the degree to which the document was modified after the signature was applied.

Will be None if difference analysis results are not available; an instance of ModificationLevel otherwise.

class pyhanko.sign.validation.status.PdfSignatureStatus(intact: bool, valid: bool, trust_problem_indic: Optional[AdESSubIndic], signing_cert: Certificate, pkcs7_signature_mechanism: str, md_algorithm: str, validation_path: ValidationPath, signer_reported_dt: Optional[datetime] = None, timestamp_validity: Optional[TimestampSignatureStatus] = None, content_timestamp_validity: Optional[TimestampSignatureStatus] = None, ac_attrs: Optional[CertifiedAttributes] = None, ac_validation_errs: Optional[Collection[Union[PathValidationError, PathBuildingError]]] = None, cades_signer_attrs: Optional[CAdESSignerAttributeAssertions] = None, coverage: Optional[SignatureCoverageLevel] = None, diff_result: Optional[Union[DiffResult, SuspiciousModification]] = None, docmdp_ok: Optional[bool] = None, has_seed_values: bool = False, seed_value_constraint_error: Optional[SigSeedValueValidationError] = None)

Bases: ModificationInfo, StandardCMSSignatureStatus

Class to indicate the validation status of a PDF signature.

docmdp_ok: Optional[bool] = None

Indicates whether the signature’s modification_level is in line with the document signature policy in force.

If None, compliance could not be determined.

has_seed_values: bool = False: Records whether the signature form field has seed values.

seed_value_constraint_error: Optional[SigSeedValueValidationError] = None: Records the reason for failure if the signature field’s seed value constraints didn’t validate.

property bottom_line: bool

Formulates a general judgment on the validity of this signature. This takes into account the cryptographic validity of the signature, the signature’s chain of trust, compliance with the document modification policy, seed value constraint compliance and the validity of the timestamp token (if present).

Returns: True if all constraints are satisfied, False otherwise.

property seed_value_ok: bool: Indicates whether the signature satisfies all mandatory constraints in the seed value dictionary of the associated form field.

Warning

Currently, not all seed value entries are recognised by the signer and/or the validator, so this judgment may not be entirely accurate in some cases.

See SigSeedValueSpec.

summary_fields()

pretty_print_sections()

class pyhanko.sign.validation.status.DocumentTimestampStatus(intact: bool, valid: bool, trust_problem_indic: Optional[AdESSubIndic], signing_cert: Certificate, pkcs7_signature_mechanism: str, md_algorithm: str, validation_path: ValidationPath, timestamp: datetime, coverage: Optional[SignatureCoverageLevel] = None, diff_result: Optional[Union[DiffResult, SuspiciousModification]] = None)

Bases: ModificationInfo, TimestampSignatureStatus

Class to indicate the validation status of a PDF document timestamp.