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, 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).
- 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
orPADES
. 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 ifsubfilter
isPADES
.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.
- timestamp_field_name: Optional[str] = None
Name of the timestamp field created when
use_pades_lta
isTrue
. If not specified, a unique name will be generated usinguuid
.
- 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
isTrue
.
- 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 sometimesdigital_signature
or a combination of both may be more appropriate. Seex509.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 callget_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
isFalse
.
- 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
isFalse
.
- 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 thatpdf_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 thisPdfTimeStamper
.output – Write the output to the specified output stream. If
None
, write to a newBytesIO
object. Default isNone
.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 thatpdf_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 thisPdfTimeStamper
.output – Write the output to the specified output stream. If
None
, write to a newBytesIO
object. Default isNone
.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_context –
pyhanko_certvalidator.ValidationContext
object to validate the last timestamp.output – Write the output to the specified output stream. If
None
, write to a newBytesIO
object. Default isNone
.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_context –
pyhanko_certvalidator.ValidationContext
object to validate the last timestamp.output – Write the output to the specified output stream. If
None
, write to a newBytesIO
object. Default isNone
.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.
signer –
Signer
object to use to produce the signature object.timestamper –
TimeStamper
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
orQRStampStyle
. Defaults toconstants.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 ifexisting_fields_only
isFalse
.
- 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’ssignature_meta
, or try to retrieve the digest algorithm associated with the underlyingSigner
.- 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()
andsign_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. IfFalse
, a new field may be created if no field matchingfield_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. IfFalse
, a new field may be created if no field matchingfield_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 newBytesIO
object. Default isNone
.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, aPdfTBSDocument
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. IfFalse
, a new field may be created if no field matchingfield_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 newBytesIO
object. Default isNone
.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, aPdfTBSDocument
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. IfFalse
, a new field may be created if no field matchingfield_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 newBytesIO
object. Default isNone
.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. IfFalse
, a new field may be created if no field matchingfield_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 newBytesIO
object. Default isNone
.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 usingPdfSigner.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, orNone
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 usingPdfSigningSession.prepare_tbs_document()
. Alternatively, useresume_signing()
orfinish_signing()
to continue a previously interrupted signing process without instantiating a newPdfTBSDocument
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 newBytesIO
object. Default isNone
.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 withperform_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
- 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 withperform_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 withperform_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 theSigner
involved, not from the initial configuration.
- file_credential: Optional[SerialisedCredential] = None
New in version 0.13.0.
Serialised file credential, to update encrypted files.