pyhanko.sign.validation.pdf_embedded module

class pyhanko.sign.validation.pdf_embedded.EmbeddedPdfSignature(reader: pyhanko.pdf_utils.reader.PdfFileReader, sig_field: pyhanko.pdf_utils.generic.DictionaryObject, fq_name: str)

Bases: object

Class modelling a signature embedded in a PDF document.

sig_object: pyhanko.pdf_utils.generic.DictionaryObject

The signature dictionary.

sig_field: pyhanko.pdf_utils.generic.DictionaryObject

The field dictionary of the form field containing the signature.

signed_data: asn1crypto.cms.SignedData

CMS signed data in the signature.

property embedded_attr_certs: List[asn1crypto.cms.AttributeCertificateV2]

Embedded attribute certificates.

property other_embedded_certs: List[asn1crypto.x509.Certificate]

Embedded X.509 certificates, excluding than that of the signer.

property signer_cert: asn1crypto.x509.Certificate

Certificate of the signer.

property sig_object_type: pyhanko.pdf_utils.generic.NameObject

Returns the type of the embedded signature object. For ordinary signatures, this will be /Sig. In the case of a document timestamp, /DocTimeStamp is returned.

Returns

A PDF name object describing the type of signature.

property field_name
Returns

Name of the signature field.

property self_reported_timestamp: Optional[datetime.datetime]
Returns

The signing time as reported by the signer, if embedded in the signature’s signed attributes.

property attached_timestamp_data: Optional[asn1crypto.cms.SignedData]
Returns

The signed data component of the timestamp token embedded in this signature, if present.

compute_integrity_info(diff_policy=None, skip_diff=False)

Compute the various integrity indicators of this signature.

Parameters
  • diff_policy – Policy to evaluate potential incremental updates that were appended to the signed revision of the document. Defaults to DEFAULT_DIFF_POLICY.

  • skip_diff – If True, skip the difference analysis step entirely.

summarise_integrity_info() dict

Compile the integrity information for this signature into a dictionary that can later be passed to PdfSignatureStatus as kwargs.

This method is only available after calling EmbeddedPdfSignature.compute_integrity_info().

property seed_value_spec: Optional[pyhanko.sign.fields.SigSeedValueSpec]
property docmdp_level: Optional[pyhanko.sign.fields.MDPPerm]
Returns

The document modification policy required by this signature or its Lock dictionary.

Warning

This does not take into account the DocMDP requirements of earlier signatures (if present).

The specification forbids signing with a more lenient DocMDP than the one currently in force, so this should not happen in a compliant document. That being said, any potential violations will still invalidate the earlier signature with the stricter DocMDP policy.

property fieldmdp: Optional[pyhanko.sign.fields.FieldMDPSpec]
Returns

Read the field locking policy of this signature, if applicable. See also FieldMDPSpec.

compute_digest() bytes

Compute the /ByteRange digest of this signature. The result will be cached.

Returns

The digest value.

compute_tst_digest() Optional[bytes]

Compute the digest of the signature needed to validate its timestamp token (if present).

Warning

This computation is only relevant for timestamp tokens embedded inside a regular signature. If the signature in question is a document timestamp (where the entire signature object is a timestamp token), this method does not apply.

Returns

The digest value, or None if there is no timestamp token.

evaluate_signature_coverage() pyhanko.sign.validation.status.SignatureCoverageLevel

Internal method used to evaluate the coverage level of a signature.

Returns

The coverage level of the signature.

evaluate_modifications(diff_policy: pyhanko.sign.diff_analysis.policy_api.DiffPolicy) Union[pyhanko.sign.diff_analysis.policy_api.DiffResult, pyhanko.sign.diff_analysis.policy_api.SuspiciousModification]

Internal method used to evaluate the modification level of a signature.

class pyhanko.sign.validation.pdf_embedded.DocMDPInfo(permission, author_sig)

Bases: tuple

Encodes certification information for a signed document, consisting of a reference to the author signature, together with the associated DocMDP policy.

property author_sig

Alias for field number 1

property permission

Alias for field number 0

pyhanko.sign.validation.pdf_embedded.read_certification_data(reader: pyhanko.pdf_utils.reader.PdfFileReader) Optional[pyhanko.sign.validation.pdf_embedded.DocMDPInfo]

Read the certification information for a PDF document, if present.

Parameters

reader – Reader representing the input document.

Returns

A DocMDPInfo object containing the relevant data, or None.

async pyhanko.sign.validation.pdf_embedded.async_validate_pdf_signature(embedded_sig: pyhanko.sign.validation.pdf_embedded.EmbeddedPdfSignature, signer_validation_context: Optional[pyhanko_certvalidator.context.ValidationContext] = None, ts_validation_context: Optional[pyhanko_certvalidator.context.ValidationContext] = None, ac_validation_context: Optional[pyhanko_certvalidator.context.ValidationContext] = None, diff_policy: Optional[pyhanko.sign.diff_analysis.policy_api.DiffPolicy] = None, key_usage_settings: Optional[pyhanko.sign.validation.settings.KeyUsageConstraints] = None, skip_diff: bool = False) pyhanko.sign.validation.status.PdfSignatureStatus

New in version 0.9.0.

Validate a PDF signature.

Parameters
  • embedded_sig – Embedded signature to evaluate.

  • signer_validation_context – Validation context to use to validate the signature’s chain of trust.

  • ts_validation_context – Validation context to use to validate the timestamp’s chain of trust (defaults to signer_validation_context).

  • ac_validation_context

    Validation context to use to validate attribute certificates. If not supplied, no AC validation will be performed.

    Note

    RFC 5755 requires attribute authority trust roots to be specified explicitly; hence why there’s no default.

  • diff_policy – Policy to evaluate potential incremental updates that were appended to the signed revision of the document. Defaults to DEFAULT_DIFF_POLICY.

  • key_usage_settings – A KeyUsageConstraints object specifying which key usages must or must not be present in the signer’s certificate.

  • skip_diff – If True, skip the difference analysis step entirely.

Returns

The status of the PDF signature in question.

async pyhanko.sign.validation.pdf_embedded.async_validate_pdf_timestamp(embedded_sig: pyhanko.sign.validation.pdf_embedded.EmbeddedPdfSignature, validation_context: Optional[pyhanko_certvalidator.context.ValidationContext] = None, diff_policy: Optional[pyhanko.sign.diff_analysis.policy_api.DiffPolicy] = None, skip_diff: bool = False) pyhanko.sign.validation.status.DocumentTimestampStatus

New in version 0.9.0.

Validate a PDF document timestamp.

Parameters
  • embedded_sig – Embedded signature to evaluate.

  • validation_context – Validation context to use to validate the timestamp’s chain of trust.

  • diff_policy – Policy to evaluate potential incremental updates that were appended to the signed revision of the document. Defaults to DEFAULT_DIFF_POLICY.

  • skip_diff – If True, skip the difference analysis step entirely.

Returns

The status of the PDF timestamp in question.

pyhanko.sign.validation.pdf_embedded.report_seed_value_validation(embedded_sig: pyhanko.sign.validation.pdf_embedded.EmbeddedPdfSignature, validation_path: pyhanko_certvalidator.path.ValidationPath, timestamp_found: bool)

Internal API function to enforce seed value constraints (if present) and report on the result(s).

Parameters
  • embedded_sig – The embedded signature.

  • validation_path – The validation path for the signer’s certificate.

  • timestamp_found – Flag indicating whether a valid timestamp was found or not.

Returns

A status_kwargs dict.