pyhanko.sign.signers.pdf_signer module

This module implements support for PDF-specific signing functionality.

class pyhanko.sign.signers.pdf_signer.PdfSignatureMetadata(field_name: ~typing.Optional[str] = None, md_algorithm: ~typing.Optional[str] = None, location: ~typing.Optional[str] = None, reason: ~typing.Optional[str] = None, name: ~typing.Optional[str] = None, app_build_props: ~typing.Optional[~pyhanko.sign.signers.pdf_byterange.BuildProps] = None, certify: bool = False, subfilter: ~typing.Optional[~pyhanko.sign.fields.SigSeedSubFilter] = None, embed_validation_info: bool = False, use_pades_lta: bool = False, timestamp_field_name: ~typing.Optional[str] = None, validation_context: ~typing.Optional[~pyhanko_certvalidator.context.ValidationContext] = None, docmdp_permissions: ~pyhanko.sign.fields.MDPPerm = MDPPerm.FILL_FORMS, signer_key_usage: ~typing.Set[str] = <factory>, cades_signed_attr_spec: ~typing.Optional[~pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None, dss_settings: ~pyhanko.sign.signers.pdf_signer.DSSContentSettings = DSSContentSettings(include_vri=True, skip_if_unneeded=True, placement=<SigDSSPlacementPreference.TOGETHER_WITH_NEXT_TS: 3>, next_ts_settings=None), tight_size_estimates: bool = False, ac_validation_context: ~typing.Optional[~pyhanko_certvalidator.context.ValidationContext] = None)

Bases: object

Specification for a PDF signature.

field_name: Optional[str] = None

The name of the form field to contain the signature. If there is only one available signature field, the name may be inferred.

md_algorithm: Optional[str] = None

The name of the digest algorithm to use. It should be supported by pyca/cryptography.

If None, select_suitable_signing_md() will be invoked to generate a suitable default, unless a seed value dictionary happens to be available.

location: Optional[str] = None

Location of signing.

reason: Optional[str] = None

Reason for signing (textual).

name: Optional[str] = None

Name of the signer. This value is usually not necessary to set, since it should appear on the signer’s certificate, but there are cases where it might be useful to specify it here (e.g. in situations where signing is delegated to a trusted third party).

app_build_props: Optional[BuildProps] = None

Properties of the application that created the signature.

If specified, this data will be recorded in the Prop_Build dictionary of the signature.

certify: bool = False

Sign with an author (certification) signature, as opposed to an approval signature. A document can contain at most one such signature, and it must be the first one.

subfilter: Optional[SigSeedSubFilter] = None

Signature subfilter to use.

This should be one of ADOBE_PKCS7_DETACHED or PADES. If not specified, the value may be inferred from the signature field’s seed value dictionary. Failing that, ADOBE_PKCS7_DETACHED is used as the default value.

embed_validation_info: bool = False

Flag indicating whether validation info (OCSP responses and/or CRLs) should be embedded or not. This is necessary to be able to validate signatures long after they have been made. This flag requires validation_context to be set.

The precise manner in which the validation info is embedded depends on the (effective) value of subfilter:

  • With ADOBE_PKCS7_DETACHED, the validation information will be embedded inside the CMS object containing the signature.

  • With PADES, the validation information will be embedded into the document security store (DSS).

use_pades_lta: bool = False

If True, the signer will append an additional document timestamp after writing the signature’s validation information to the document security store (DSS). This flag is only meaningful if subfilter is PADES.

The PAdES B-LTA profile solves the long-term validation problem by adding a timestamp chain to the document after the regular signatures, which is updated with new timestamps at regular intervals. This provides an audit trail that ensures the long-term integrity of the validation information in the DSS, since OCSP responses and CRLs also have a finite lifetime.

See also PdfTimeStamper.update_archival_timestamp_chain().

timestamp_field_name: Optional[str] = None

Name of the timestamp field created when use_pades_lta is True. If not specified, a unique name will be generated using uuid.

validation_context: Optional[ValidationContext] = None

The validation context to use when validating signatures. If provided, the signer’s certificate and any timestamp certificates will be validated before signing.

This parameter is mandatory when embed_validation_info is True.

docmdp_permissions: MDPPerm = 2

Indicates the document modification policy that will be in force after this signature is created. Only relevant for certification signatures or signatures that apply locking.

Warning

For non-certification signatures, this is only explicitly allowed since PDF 2.0 (ISO 32000-2), so older software may not respect this setting on approval signatures.

signer_key_usage: Set[str]

Key usage extensions required for the signer’s certificate. Defaults to non_repudiation only, but sometimes digital_signature or a combination of both may be more appropriate. See x509.KeyUsage for a complete list.

Only relevant if a validation context is also provided.

cades_signed_attr_spec: Optional[CAdESSignedAttrSpec] = None

New in version 0.5.0.

Specification for CAdES-specific attributes.

dss_settings: DSSContentSettings = DSSContentSettings(include_vri=True, skip_if_unneeded=True, placement=<SigDSSPlacementPreference.TOGETHER_WITH_NEXT_TS: 3>, next_ts_settings=None)

New in version 0.8.0.

DSS output settings. See DSSContentSettings.

tight_size_estimates: bool = False

New in version 0.8.0.

When estimating the size of a signature container, do not add safety margins.

Note

This should be OK if the entire CMS object is produced by pyHanko, and the signing scheme produces signatures of a fixed size. However, if the signature container includes unsigned attributes such as signature timestamps, the size of the signature is never entirely predictable.

ac_validation_context: Optional[ValidationContext] = None

New in version 0.11.0.

Validation context for attribute certificates

class pyhanko.sign.signers.pdf_signer.DSSContentSettings(include_vri: bool = True, skip_if_unneeded: bool = True, placement: SigDSSPlacementPreference = SigDSSPlacementPreference.TOGETHER_WITH_NEXT_TS, next_ts_settings: Optional[TimestampDSSContentSettings] = None)

Bases: GeneralDSSContentSettings

New in version 0.8.0.

Settings for a DSS update with validation information for a signature.

placement: SigDSSPlacementPreference = 3

Preference for where to perform a DSS update with validation information for a specific signature. See SigDSSPlacementPreference.

The default is SigDSSPlacementPreference.TOGETHER_WITH_NEXT_TS.

next_ts_settings: Optional[TimestampDSSContentSettings] = None

Explicit settings for DSS updates pertaining to a document timestamp added as part of the same signing workflow, if applicable.

If None, a default will be generated based on the values of this settings object.

Note

When consuming DSSContentSettings objects, you should call get_settings_for_ts() instead of relying on the value of this field.

get_settings_for_ts() TimestampDSSContentSettings

Retrieve DSS update settings for document timestamps that are part of our signing workflow, if there are any.

assert_viable()

Check settings for consistency, and raise SigningError otherwise.

class pyhanko.sign.signers.pdf_signer.TimestampDSSContentSettings(include_vri: bool = True, skip_if_unneeded: bool = True, update_before_ts: bool = False)

Bases: GeneralDSSContentSettings

New in version 0.8.0.

Settings for a DSS update with validation information for a document timestamp.

Note

In most workflows, adding a document timestamp doesn’t trigger any DSS updates beyond VRI additions, because the same TSA is used for signature timestamps and for document timestamps.

update_before_ts: bool = False

Perform DSS update before creating the timestamp, instead of after.

Warning

This setting can only be used if include_vri is False.

assert_viable()

Check settings for consistency, and raise SigningError otherwise.

class pyhanko.sign.signers.pdf_signer.GeneralDSSContentSettings(include_vri: bool = True, skip_if_unneeded: bool = True)

Bases: object

New in version 0.8.0.

Settings that govern DSS creation and updating in general.

include_vri: bool = True

Flag to control whether to create and update entries in the VRI dictionary. The default is to always update the VRI dictionary.

Note

The VRI dictionary is a relic of the past that is effectively deprecated in the current PAdES standards, and most modern validators don’t rely on it being there.

That said, there’s no real harm in creating these entries, other than that it occasionally forces DSS updates where none would otherwise be necessary, and that it prevents the DSS from being updated prior to signing (as opposed to after signing).

skip_if_unneeded: bool = True

Do not perform a write if updating the DSS would not add any new information.

Note

This setting is only used if the DSS update would happen in its own revision.

class pyhanko.sign.signers.pdf_signer.SigDSSPlacementPreference(value)

Bases: Enum

New in version 0.8.0.

Preference for where to perform a DSS update with validation information for a specific signature.

TOGETHER_WITH_SIGNATURE = 1

Update the DSS in the revision that contains the signature. Doing so can be useful to create a PAdES-B-LT signature in a single revision. Such signatures can be processed by a validator that isn’t capable of incremental update analysis.

Warning

This setting can only be used if include_vri is False.

SEPARATE_REVISION = 2

Always perform the DSS update in a separate revision, after the signature, but before any timestamps are added.

Note

This is the old default behaviour.

TOGETHER_WITH_NEXT_TS = 3

If the signing workflow includes a document timestamp after the signature, update the DSS in the same revision as the timestamp. In the absence of document timestamps, this is equivalent to SEPARATE_REVISION.

Warning

This option controls the addition of validation info for the signature and its associated signature timestamp, not the validation info for the document timestamp itself. See DSSContentSettings.next_ts_settings.

In most practical situations, the distinction is only relevant in interrupted signing workflows (see Interrupted signing), where the lifecycle of the validation context is out of pyHanko’s hands.

class pyhanko.sign.signers.pdf_signer.PdfTimeStamper(timestamper: TimeStamper, field_name: Optional[str] = None, invis_settings: InvisSigSettings = InvisSigSettings(set_print_flag=True, set_hidden_flag=False, box_out_of_bounds=False), readable_field_name: str = 'Timestamp')

Bases: object

Class to encapsulate the process of appending document timestamps to PDF files.

property field_name: str

Retrieve or generate the field name for the signature field to contain the document timestamp.

Returns

The field name, as a (Python) string.

timestamp_pdf(pdf_out: IncrementalPdfFileWriter, md_algorithm, validation_context=None, bytes_reserved=None, validation_paths=None, timestamper: Optional[TimeStamper] = None, *, in_place=False, output=None, dss_settings: TimestampDSSContentSettings = TimestampDSSContentSettings(include_vri=True, skip_if_unneeded=True, update_before_ts=False), chunk_size=4096, tight_size_estimates: bool = False)

Changed in version 0.9.0: Wrapper around async_timestamp_pdf().

Timestamp the contents of pdf_out. Note that pdf_out should not be written to after this operation.

Parameters
  • pdf_out – An IncrementalPdfFileWriter.

  • md_algorithm – The hash algorithm to use when computing message digests.

  • validation_context – The pyhanko_certvalidator.ValidationContext against which the TSA response should be validated. This validation context will also be used to update the DSS.

  • bytes_reserved

    Bytes to reserve for the CMS object in the PDF file. If not specified, make an estimate based on a dummy signature.

    Warning

    Since the CMS object is written to the output file as a hexadecimal string, you should request twice the (estimated) number of bytes in the DER-encoded version of the CMS object.

  • validation_paths – If the validation path(s) for the TSA’s certificate are already known, you can pass them using this parameter to avoid having to run the validation logic again.

  • timestamper – Override the default TimeStamper associated with this PdfTimeStamper.

  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

  • dss_settings – DSS output settings. See TimestampDSSContentSettings.

  • tight_size_estimates

    When estimating the size of a document timestamp container, do not add safety margins.

    Note

    External TSAs cannot be relied upon to always produce the exact same output length, which makes this option risky to use.

Returns

The output stream containing the signed output.

async async_timestamp_pdf(pdf_out: IncrementalPdfFileWriter, md_algorithm, validation_context=None, bytes_reserved=None, validation_paths=None, timestamper: Optional[TimeStamper] = None, *, in_place=False, output=None, dss_settings: TimestampDSSContentSettings = TimestampDSSContentSettings(include_vri=True, skip_if_unneeded=True, update_before_ts=False), chunk_size=4096, tight_size_estimates: bool = False, embed_roots: bool = True)

New in version 0.9.0.

Timestamp the contents of pdf_out. Note that pdf_out should not be written to after this operation.

Parameters
  • pdf_out – An IncrementalPdfFileWriter.

  • md_algorithm – The hash algorithm to use when computing message digests.

  • validation_context – The pyhanko_certvalidator.ValidationContext against which the TSA response should be validated. This validation context will also be used to update the DSS.

  • bytes_reserved

    Bytes to reserve for the CMS object in the PDF file. If not specified, make an estimate based on a dummy signature.

    Warning

    Since the CMS object is written to the output file as a hexadecimal string, you should request twice the (estimated) number of bytes in the DER-encoded version of the CMS object.

  • validation_paths – If the validation path(s) for the TSA’s certificate are already known, you can pass them using this parameter to avoid having to run the validation logic again.

  • timestamper – Override the default TimeStamper associated with this PdfTimeStamper.

  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

  • dss_settings – DSS output settings. See TimestampDSSContentSettings.

  • tight_size_estimates

    When estimating the size of a document timestamp container, do not add safety margins.

    Note

    External TSAs cannot be relied upon to always produce the exact same output length, which makes this option risky to use.

  • embed_roots

    Option that controls whether the root certificate of each validation path should be embedded into the DSS. The default is True.

    Note

    Trust roots are configured by the validator, so embedding them typically does nothing in a typical validation process. Therefore they can be safely omitted in most cases. Nonetheless, embedding the roots can be useful for documentation purposes.

Returns

The output stream containing the signed output.

update_archival_timestamp_chain(reader: PdfFileReader, validation_context, in_place=True, output=None, chunk_size=4096, default_md_algorithm='sha256')

Changed in version 0.9.0: Wrapper around async_update_archival_timestamp_chain().

Validate the last timestamp in the timestamp chain on a PDF file, and write an updated version to an output stream.

Parameters
  • reader – A PdfReader encapsulating the input file.

  • validation_contextpyhanko_certvalidator.ValidationContext object to validate the last timestamp.

  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

  • default_md_algorithm – Message digest to use if there are no preceding timestamps in the file.

Returns

The output stream containing the signed output.

async async_update_archival_timestamp_chain(reader: PdfFileReader, validation_context, in_place=True, output=None, chunk_size=4096, default_md_algorithm='sha256', embed_roots: bool = True)

New in version 0.9.0.

Validate the last timestamp in the timestamp chain on a PDF file, and write an updated version to an output stream.

Parameters
  • reader – A PdfReader encapsulating the input file.

  • validation_contextpyhanko_certvalidator.ValidationContext object to validate the last timestamp.

  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

  • default_md_algorithm – Message digest to use if there are no preceding timestamps in the file.

  • embed_roots

    Option that controls whether the root certificate of each validation path should be embedded into the DSS. The default is True.

    Note

    Trust roots are configured by the validator, so embedding them typically does nothing in a typical validation process. Therefore they can be safely omitted in most cases. Nonetheless, embedding the roots can be useful for documentation purposes.

Returns

The output stream containing the signed output.

class pyhanko.sign.signers.pdf_signer.PdfSigner(signature_meta: PdfSignatureMetadata, signer: Signer, *, timestamper: Optional[TimeStamper] = None, stamp_style: Optional[BaseStampStyle] = None, new_field_spec: Optional[SigFieldSpec] = None)

Bases: object

Class to handle PDF signatures in general.

Parameters
  • signature_meta – The specification of the signature to add.

  • signerSigner object to use to produce the signature object.

  • timestamperTimeStamper object to use to produce any time stamp tokens that might be required.

  • stamp_style – Stamp style specification to determine the visible style of the signature, typically an object of type TextStampStyle or QRStampStyle. Defaults to constants.DEFAULT_SIGNING_STAMP_STYLE.

  • new_field_spec – If a new field is to be created, this parameter allows the caller to specify the field’s properties in the form of a SigFieldSpec. This parameter is only meaningful if existing_fields_only is False.

property default_md_for_signer: Optional[str]

Name of the default message digest algorithm for this signer, if there is one. This method will try the md_algorithm attribute on the signer’s signature_meta, or try to retrieve the digest algorithm associated with the underlying Signer.

Returns

The name of the message digest algorithm, or None.

register_extensions(pdf_out: BasePdfFileWriter, *, md_algorithm: str)
init_signing_session(pdf_out: BasePdfFileWriter, existing_fields_only=False) PdfSigningSession

Initialise a signing session with this PdfSigner for a specified PDF file writer.

This step in the signing process handles all field-level operations prior to signing: it creates the target form field if necessary, and makes sure the seed value dictionary gets processed.

See also digest_doc_for_signing() and sign_pdf().

Parameters
  • pdf_out – The writer containing the PDF file to be signed.

  • existing_fields_only – If True, never create a new empty signature field to contain the signature. If False, a new field may be created if no field matching field_name exists.

Returns

A PdfSigningSession object modelling the signing session in its post-setup stage.

digest_doc_for_signing(pdf_out: BasePdfFileWriter, existing_fields_only=False, bytes_reserved=None, *, appearance_text_params=None, in_place=False, output=None, chunk_size=4096) Tuple[PreparedByteRangeDigest, PdfTBSDocument, IO]

Deprecated since version 0.9.0: Use async_digest_doc_for_signing() instead.

Set up all stages of the signing process up to and including the point where the signature placeholder is allocated, and the document’s /ByteRange digest is computed.

See sign_pdf() for a less granular, more high-level approach.

Note

This method is useful in remote signing scenarios, where you might want to free up resources while waiting for the remote signer to respond. The PreparedByteRangeDigest object returned allows you to keep track of the required state to fill the signature container at some later point in time.

Parameters
  • pdf_out – A PDF file writer (usually an IncrementalPdfFileWriter) containing the data to sign.

  • existing_fields_only – If True, never create a new empty signature field to contain the signature. If False, a new field may be created if no field matching field_name exists.

  • bytes_reserved

    Bytes to reserve for the CMS object in the PDF file. If not specified, make an estimate based on a dummy signature.

    Warning

    Since the CMS object is written to the output file as a hexadecimal string, you should request twice the (estimated) number of bytes in the DER-encoded version of the CMS object.

  • appearance_text_params – Dictionary with text parameters that will be passed to the signature appearance constructor (if applicable).

  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

Returns

A tuple containing a PreparedByteRangeDigest object, a PdfTBSDocument object and an output handle to which the document in its current state has been written.

async async_digest_doc_for_signing(pdf_out: BasePdfFileWriter, existing_fields_only=False, bytes_reserved=None, *, appearance_text_params=None, in_place=False, output=None, chunk_size=4096) Tuple[PreparedByteRangeDigest, PdfTBSDocument, IO]

New in version 0.9.0.

Set up all stages of the signing process up to and including the point where the signature placeholder is allocated, and the document’s /ByteRange digest is computed.

See sign_pdf() for a less granular, more high-level approach.

Note

This method is useful in remote signing scenarios, where you might want to free up resources while waiting for the remote signer to respond. The PreparedByteRangeDigest object returned allows you to keep track of the required state to fill the signature container at some later point in time.

Parameters
  • pdf_out – A PDF file writer (usually an IncrementalPdfFileWriter) containing the data to sign.

  • existing_fields_only – If True, never create a new empty signature field to contain the signature. If False, a new field may be created if no field matching field_name exists.

  • bytes_reserved

    Bytes to reserve for the CMS object in the PDF file. If not specified, make an estimate based on a dummy signature.

    Warning

    Since the CMS object is written to the output file as a hexadecimal string, you should request twice the (estimated) number of bytes in the DER-encoded version of the CMS object.

  • appearance_text_params – Dictionary with text parameters that will be passed to the signature appearance constructor (if applicable).

  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

Returns

A tuple containing a PreparedByteRangeDigest object, a PdfTBSDocument object and an output handle to which the document in its current state has been written.

sign_pdf(pdf_out: BasePdfFileWriter, existing_fields_only=False, bytes_reserved=None, *, appearance_text_params=None, in_place=False, output=None, chunk_size=4096)

Changed in version 0.9.0: Wrapper around async_sign_pdf().

Sign a PDF file using the provided output writer.

Parameters
  • pdf_out – A PDF file writer (usually an IncrementalPdfFileWriter) containing the data to sign.

  • existing_fields_only – If True, never create a new empty signature field to contain the signature. If False, a new field may be created if no field matching field_name exists.

  • bytes_reserved – Bytes to reserve for the CMS object in the PDF file. If not specified, make an estimate based on a dummy signature.

  • appearance_text_params – Dictionary with text parameters that will be passed to the signature appearance constructor (if applicable).

  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

Returns

The output stream containing the signed data.

async async_sign_pdf(pdf_out: BasePdfFileWriter, existing_fields_only=False, bytes_reserved=None, *, appearance_text_params=None, in_place=False, output=None, chunk_size=4096)

New in version 0.9.0.

Sign a PDF file using the provided output writer.

Parameters
  • pdf_out – A PDF file writer (usually an IncrementalPdfFileWriter) containing the data to sign.

  • existing_fields_only – If True, never create a new empty signature field to contain the signature. If False, a new field may be created if no field matching field_name exists.

  • bytes_reserved – Bytes to reserve for the CMS object in the PDF file. If not specified, make an estimate based on a dummy signature.

  • appearance_text_params – Dictionary with text parameters that will be passed to the signature appearance constructor (if applicable).

  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

Returns

The output stream containing the signed data.

class pyhanko.sign.signers.pdf_signer.PdfSigningSession(pdf_signer: PdfSigner, pdf_out: BasePdfFileWriter, cms_writer, sig_field, md_algorithm: str, timestamper: TimeStamper, subfilter: SigSeedSubFilter, system_time: Optional[datetime] = None, sv_spec: Optional[SigSeedValueSpec] = None)

Bases: object

New in version 0.7.0.

Class modelling a PDF signing session in its initial state.

The __init__ method is internal API, get an instance using PdfSigner.init_signing_session().

async perform_presign_validation(pdf_out: Optional[BasePdfFileWriter] = None) Optional[PreSignValidationStatus]

Perform certificate validation checks for the signer’s certificate, including any necessary revocation checks.

This function will also attempt to validate & collect revocation information for the relevant TSA (by requesting a dummy timestamp).

Parameters

pdf_out – Current PDF writer. Technically optional; only used to look for the end of the timestamp chain in the previous revision when producing a PAdES-LTA signature in a document that is already signed (to ensure that the timestamp chain is uninterrupted).

Returns

A PreSignValidationStatus object, or None if there is no validation context available.

async estimate_signature_container_size(validation_info: PreSignValidationStatus, tight=False)
prepare_tbs_document(validation_info: PreSignValidationStatus, bytes_reserved, appearance_text_params=None) PdfTBSDocument

Set up the signature appearance (if necessary) and signature dictionary in the PDF file, to put the document in its final pre-signing state.

Parameters
  • validation_info – Validation information collected prior to signing.

  • bytes_reserved – Bytes to reserve for the signature container.

  • appearance_text_params – Optional text parameters for the signature appearance content.

Returns

A PdfTBSDocument describing the document in its final pre-signing state.

class pyhanko.sign.signers.pdf_signer.PdfTBSDocument(cms_writer, signer: Signer, md_algorithm: str, use_pades: bool, timestamper: Optional[TimeStamper] = None, post_sign_instructions: Optional[PostSignInstructions] = None, validation_context: Optional[ValidationContext] = None)

Bases: object

New in version 0.7.0.

A PDF document in its final pre-signing state.

The __init__ method is internal API, get an instance using PdfSigningSession.prepare_tbs_document(). Alternatively, use resume_signing() or finish_signing() to continue a previously interrupted signing process without instantiating a new PdfTBSDocument object.

digest_tbs_document(*, output: Optional[IO] = None, in_place: bool = False, chunk_size=4096) Tuple[PreparedByteRangeDigest, IO]

Write the document to an output stream and compute the digest, while keeping track of the (future) location of the signature contents in the output stream.

The digest can then be passed to the next part of the signing pipeline.

Warning

This method can only be called once.

Parameters
  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

Returns

A tuple containing a PreparedByteRangeDigest and the output stream to which the output was written.

async perform_signature(document_digest: bytes, pdf_cms_signed_attrs: PdfCMSSignedAttributes) PdfPostSignatureDocument

Perform the relevant cryptographic signing operations on the document digest, and write the resulting CMS object to the appropriate location in the output stream.

Warning

This method can only be called once, and must be invoked after digest_tbs_document().

Parameters
  • document_digest – Digest of the document, as computed over the relevant /ByteRange.

  • pdf_cms_signed_attrs – Description of the signed attributes to include.

Returns

A PdfPostSignatureDocument object.

classmethod resume_signing(output: IO, prepared_digest: PreparedByteRangeDigest, signature_cms: Union[bytes, ContentInfo], post_sign_instr: Optional[PostSignInstructions] = None, validation_context: Optional[ValidationContext] = None) PdfPostSignatureDocument

Resume signing after obtaining a CMS object from an external source.

This is a class method; it doesn’t require a PdfTBSDocument instance. Contrast with perform_signature().

Parameters
  • output – Output stream housing the document in its final pre-signing state. This stream must at least be writable and seekable, and also readable if post-signature processing is required.

  • prepared_digest – The prepared digest returned by a prior call to digest_tbs_document().

  • signature_cms – CMS object to embed in the signature dictionary.

  • post_sign_instr – Instructions for post-signing processing (DSS updates and document timestamps).

  • validation_context – Validation context to use in post-signing operations. This is mainly intended for TSA certificate validation, but it can also contain additional validation data to embed in the DSS.

Returns

A PdfPostSignatureDocument.

classmethod finish_signing(output: IO, prepared_digest: PreparedByteRangeDigest, signature_cms: Union[bytes, ContentInfo], post_sign_instr: Optional[PostSignInstructions] = None, validation_context: Optional[ValidationContext] = None, chunk_size=4096)

Finish signing after obtaining a CMS object from an external source, and perform any required post-signature processing.

This is a class method; it doesn’t require a PdfTBSDocument instance. Contrast with perform_signature().

Parameters
  • output – Output stream housing the document in its final pre-signing state.

  • prepared_digest – The prepared digest returned by a prior call to digest_tbs_document().

  • signature_cms – CMS object to embed in the signature dictionary.

  • post_sign_instr – Instructions for post-signing processing (DSS updates and document timestamps).

  • validation_context – Validation context to use in post-signing operations. This is mainly intended for TSA certificate validation, but it can also contain additional validation data to embed in the DSS.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

async classmethod async_finish_signing(output: IO, prepared_digest: PreparedByteRangeDigest, signature_cms: Union[bytes, ContentInfo], post_sign_instr: Optional[PostSignInstructions] = None, validation_context: Optional[ValidationContext] = None, chunk_size=4096)

Finish signing after obtaining a CMS object from an external source, and perform any required post-signature processing.

This is a class method; it doesn’t require a PdfTBSDocument instance. Contrast with perform_signature().

Parameters
  • output – Output stream housing the document in its final pre-signing state.

  • prepared_digest – The prepared digest returned by a prior call to digest_tbs_document().

  • signature_cms – CMS object to embed in the signature dictionary.

  • post_sign_instr – Instructions for post-signing processing (DSS updates and document timestamps).

  • validation_context – Validation context to use in post-signing operations. This is mainly intended for TSA certificate validation, but it can also contain additional validation data to embed in the DSS.

  • chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support memoryview.

class pyhanko.sign.signers.pdf_signer.PdfPostSignatureDocument(sig_contents: bytes, post_sign_instr: Optional[PostSignInstructions] = None, validation_context: Optional[ValidationContext] = None)

Bases: object

New in version 0.7.0.

Represents the final phase of the PDF signing process

async post_signature_processing(output: IO, chunk_size=4096)

Handle DSS updates and LTA timestamps, if applicable.

Parameters
  • output – I/O buffer containing the signed document. Must support reading, writing and seeking.

  • chunk_size – Chunk size to use for I/O operations that do not support the buffer protocol.

class pyhanko.sign.signers.pdf_signer.PreSignValidationStatus(signer_path: ValidationPath, validation_paths: List[ValidationPath], ts_validation_paths: Optional[List[ValidationPath]] = None, adobe_revinfo_attr: Optional[RevocationInfoArchival] = None, ocsps_to_embed: Optional[List[OCSPResponse]] = None, crls_to_embed: Optional[List[CertificateList]] = None, ac_validation_paths: Optional[List[ValidationPath]] = None)

Bases: object

New in version 0.7.0.

Container for validation data collected prior to creating a signature, e.g. for later inclusion in a document’s DSS, or as a signed attribute on the signature.

signer_path: ValidationPath

Validation path for the signer’s certificate.

validation_paths: List[ValidationPath]

List of other relevant validation paths.

ts_validation_paths: Optional[List[ValidationPath]] = None

List of validation paths relevant for embedded timestamps.

adobe_revinfo_attr: Optional[RevocationInfoArchival] = None

Preformatted revocation info attribute to include, if requested by the settings.

ocsps_to_embed: List[OCSPResponse] = None

List of OCSP responses collected so far.

crls_to_embed: List[CertificateList] = None

List of CRLS collected so far.

ac_validation_paths: Optional[List[ValidationPath]] = None

List of validation paths relevant for embedded attribute certificates.

class pyhanko.sign.signers.pdf_signer.PostSignInstructions(validation_info: ~pyhanko.sign.signers.pdf_signer.PreSignValidationStatus, timestamper: ~typing.Optional[~pyhanko.sign.timestamps.api.TimeStamper] = None, timestamp_md_algorithm: ~typing.Optional[str] = None, timestamp_field_name: ~typing.Optional[str] = None, dss_settings: ~pyhanko.sign.signers.pdf_signer.DSSContentSettings = DSSContentSettings(include_vri=True, skip_if_unneeded=True, placement=<SigDSSPlacementPreference.TOGETHER_WITH_NEXT_TS: 3>, next_ts_settings=None), tight_size_estimates: bool = False, embed_roots: bool = True, file_credential: ~typing.Optional[~pyhanko.pdf_utils.crypt.cred_ser.SerialisedCredential] = None)

Bases: object

New in version 0.7.0.

Container class housing instructions for incremental updates to the document after the signature has been put in place. Necessary for PAdES-LT and PAdES-LTA workflows.

validation_info: PreSignValidationStatus

Validation information to embed in the DSS (if not already present).

timestamper: Optional[TimeStamper] = None

Timestamper to use for produce document timestamps. If None, no timestamp will be added.

timestamp_md_algorithm: Optional[str] = None

Digest algorithm to use when producing timestamps. Defaults to DEFAULT_MD.

timestamp_field_name: Optional[str] = None

Name of the timestamp field to use. If not specified, a field name will be generated.

dss_settings: DSSContentSettings = DSSContentSettings(include_vri=True, skip_if_unneeded=True, placement=<SigDSSPlacementPreference.TOGETHER_WITH_NEXT_TS: 3>, next_ts_settings=None)

New in version 0.8.0.

Settings to fine-tune DSS generation.

tight_size_estimates: bool = False

New in version 0.8.0.

When estimating the size of a document timestamp container, do not add safety margins.

Note

External TSAs cannot be relied upon to always produce the exact same output length, which makes this option risky to use.

embed_roots: bool = True

New in version 0.9.0.

Option that controls whether the root certificate of each validation path should be embedded into the DSS. The default is True.

Note

Trust roots are configured by the validator, so embedding them typically does nothing in a typical validation process. Therefore they can be safely omitted in most cases. Nonetheless, embedding the roots can be useful for documentation purposes.

Note

This setting is not part of DSSContentSettings because its value is taken from the corresponding property on the Signer involved, not from the initial configuration.

file_credential: Optional[SerialisedCredential] = None

New in version 0.13.0.

Serialised file credential, to update encrypted files.