pyhanko.sign.signers module

class pyhanko.sign.signers.PdfSignatureMetadata(field_name: Optional[str] = None, md_algorithm: Optional[str] = None, location: Optional[str] = None, reason: Optional[str] = None, name: Optional[str] = None, certify: bool = False, subfilter: Optional[pyhanko.sign.fields.SigSeedSubFilter] = None, embed_validation_info: bool = False, use_pades_lta: bool = False, timestamp_field_name: Optional[str] = None, validation_context: Optional[certvalidator.context.ValidationContext] = None, docmdp_permissions: pyhanko.sign.fields.MDPPerm = <MDPPerm.FILL_FORMS: 2>, signer_key_usage: Set[str] = <factory>, cades_signed_attr_spec: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None)

Bases: object

Specification for a PDF signature.

field_name: 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: str = None

The name of the digest algorithm to use. It should be supported by hashlib.

If None, this will ordinarily default to the value of DEFAULT_MD, unless a seed value dictionary and/or a prior certification signature happen to be available.

location: str = None

Location of signing.

reason: str = None

Reason for signing (textual).

name: 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: pyhanko.sign.fields.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: 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: certvalidator.context.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: pyhanko.sign.fields.MDPPerm = 2

Indicates the document modification policy that will be in force after this signature is created.

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[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None

New in version 0.5.0.

Specification for CAdES-specific attributes.

class pyhanko.sign.signers.Signer(prefer_pss=False)

Bases: object

Abstract signer object that is agnostic as to where the cryptographic operations actually happen.

As of now, pyHanko provides two implementations:

  • SimpleSigner implements the easy case where all the key material can be loaded into memory.

  • PKCS11Signer implements a signer that is capable of interfacing with a PKCS11 device (see also BEIDSigner).

signing_cert: asn1crypto.x509.Certificate

The certificate that will be used to create the signature.

cert_registry: pyhanko.sign.general.CertificateStore

Collection of certificates associated with this signer. Note that this is simply a bookkeeping tool; in particular it doesn’t care about trust.

signature_mechanism: asn1crypto.algos.SignedDigestAlgorithm = None

The (cryptographic) signature mechanism to use.

get_signature_mechanism(digest_algorithm)

Get the signature mechanism for this signer to use. If signature_mechanism is set, it will be used. Otherwise, this method will attempt to put together a default based on mechanism used in the signer’s certificate.

Parameters

digest_algorithm – Digest algorithm to use as part of the signature mechanism. Only used if a signature mechanism object has to be put together on-the-fly, and the digest algorithm could not be inferred from the signer’s certificate.

Returns

A SignedDigestAlgorithm object.

sign_raw(data: bytes, digest_algorithm: str, dry_run=False)bytes

Compute the raw cryptographic signature of the data provided, hashed using the digest algorithm provided.

Parameters
  • data – Data to sign.

  • digest_algorithm

    Digest algorithm to use.

    Warning

    If signature_mechanism also specifies a digest, they should match.

  • dry_run – Do not actually create a signature, but merely output placeholder bytes that would suffice to contain an actual signature.

Returns

Signature bytes.

property subject_name
Returns

The subject’s common name as a string, extracted from signing_cert.

static format_revinfo(ocsp_responses: Optional[list] = None, crls: Optional[list] = None)

Format Adobe-style revocation information for inclusion into a CMS object.

Parameters
  • ocsp_responses – A list of OCSP responses to include.

  • crls – A list of CRLs to include.

Returns

A CMS attribute containing the relevant data.

signed_attrs(data_digest: bytes, digest_algorithm: str, timestamp: Optional[datetime.datetime] = None, revocation_info=None, use_pades=False, cades_meta: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None, timestamper=None, dry_run=False)

Changed in version 0.4.0: Added positional digest_algorithm parameter _(breaking change)_.

Changed in version 0.5.0: Added dry_run, timestamper and cades_meta parameters.

Format the signed attributes for a CMS signature.

Parameters
  • data_digest – Raw digest of the data to be signed.

  • digest_algorithm

    New in version 0.4.0.

    Name of the digest algorithm used to compute the digest.

  • timestamp – Current timestamp (ignored when use_pades is True).

  • revocation_info – Revocation information to embed; this should be the output of a call to Signer.format_revinfo() or None (ignored when use_pades is True).

  • use_pades – Respect PAdES requirements.

  • dry_run

    New in version 0.5.0.

    Flag indicating “dry run” mode. If True, only the approximate size of the output matters, so cryptographic operations can be replaced by placeholders.

  • timestamper

    New in version 0.5.0.

    Timestamper to use when creating timestamp tokens.

  • cades_meta

    New in version 0.5.0.

    Specification for CAdES-specific attributes.

Returns

An asn1crypto.cms.CMSAttributes object.

unsigned_attrs(digest_algorithm, signature: bytes, timestamper=None, dry_run=False)Optional[asn1crypto.cms.CMSAttributes]

Compute the unsigned attributes to embed into the CMS object. This function is called after signing the hash of the signed attributes (see signed_attrs()).

By default, this method only handles timestamp requests, but other functionality may be added by subclasses

If this method returns None, no unsigned attributes will be embedded.

Parameters
  • digest_algorithm – Digest algorithm used to hash the signed attributes.

  • signature – Signature of the signed attribute hash.

  • timestamper – Timestamp supplier to use.

  • dry_run – Flag indicating “dry run” mode. If True, only the approximate size of the output matters, so cryptographic operations can be replaced by placeholders.

Returns

The unsigned attributes to add, or None.

signer_info(digest_algorithm: str, signed_attrs, signature)

Format the SignerInfo entry for a CMS signature.

Parameters
  • digest_algorithm – Digest algorithm to use.

  • signed_attrs – Signed attributes (see signed_attrs()).

  • signature – The raw signature to embed (see sign_raw()).

Returns

An asn1crypto.cms.SignerInfo object.

sign(data_digest: bytes, digest_algorithm: str, timestamp: Optional[datetime.datetime] = None, dry_run=False, revocation_info=None, use_pades=False, timestamper=None, cades_signed_attr_meta: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None)asn1crypto.cms.ContentInfo

Produce a detached CMS signature from a raw data digest.

Parameters
  • data_digest – Digest of the actual content being signed.

  • digest_algorithm – Digest algorithm to use. This should be the same digest method as the one used to hash the (external) content.

  • timestamp – Current timestamp (ignored when use_pades is True).

  • dry_run

    If True, the actual signing step will be replaced with a placeholder.

    In a PDF signing context, this is necessary to estimate the size of the signature container before computing the actual digest of the document.

  • revocation_info – Revocation information to embed; this should be the output of a call to Signer.format_revinfo() (ignored when use_pades is True).

  • use_pades – Respect PAdES requirements.

  • timestamper

    TimeStamper used to obtain a trusted timestamp token that can be embedded into the signature container.

    Note

    If dry_run is true, the timestamper’s dummy_response() method will be called to obtain a placeholder token. Note that with a standard HTTPTimeStamper, this might still hit the timestamping server (in order to produce a realistic size estimate), but the dummy response will be cached.

  • cades_signed_attr_meta

    New in version 0.5.0.

    Specification for CAdES-specific attributes.

Returns

An ContentInfo object.

class pyhanko.sign.signers.SimpleSigner(signing_cert: asn1crypto.x509.Certificate, signing_key: asn1crypto.keys.PrivateKeyInfo, cert_registry: pyhanko.sign.general.CertificateStore, signature_mechanism: Optional[asn1crypto.algos.SignedDigestAlgorithm] = None, prefer_pss=False)

Bases: pyhanko.sign.signers.Signer

Simple signer implementation where the key material is available in local memory.

signing_key: asn1crypto.keys.PrivateKeyInfo

Private key associated with the certificate in signing_cert.

sign_raw(data: bytes, digest_algorithm: str, dry_run=False)bytes

Compute the raw cryptographic signature of the data provided, hashed using the digest algorithm provided.

Parameters
  • data – Data to sign.

  • digest_algorithm

    Digest algorithm to use.

    Warning

    If signature_mechanism also specifies a digest, they should match.

  • dry_run – Do not actually create a signature, but merely output placeholder bytes that would suffice to contain an actual signature.

Returns

Signature bytes.

classmethod load_pkcs12(pfx_file, ca_chain_files=None, passphrase=None, signature_mechanism=None, prefer_pss=False)

Load certificates and key material from a PCKS#12 archive (usually .pfx or .p12 files).

Parameters
  • pfx_file – Path to the PKCS#12 archive.

  • ca_chain_files – Path to (PEM/DER) files containing other relevant certificates not included in the PKCS#12 file.

  • passphrase – Passphrase to decrypt the PKCS#12 archive, if required.

  • signature_mechanism – Override the signature mechanism to use.

  • prefer_pss – Prefer PSS signature mechanism over RSA PKCS#1 v1.5 if there’s a choice.

Returns

A SimpleSigner object initialised with key material loaded from the PKCS#12 file provided.

classmethod load(key_file, cert_file, ca_chain_files=None, key_passphrase=None, other_certs=None, signature_mechanism=None, prefer_pss=False)

Load certificates and key material from PEM/DER files.

Parameters
  • key_file – File containing the signer’s private key.

  • cert_file – File containing the signer’s certificate.

  • ca_chain_files – File containing other relevant certificates.

  • key_passphrase – Passphrase to decrypt the private key (if required).

  • other_certs – Other relevant certificates, specified as a list of asn1crypto.x509.Certificate objects.

  • signature_mechanism – Override the signature mechanism to use.

  • prefer_pss – Prefer PSS signature mechanism over RSA PKCS#1 v1.5 if there’s a choice.

Returns

A SimpleSigner object initialised with key material loaded from the files provided.

class pyhanko.sign.signers.PdfTimeStamper(timestamper: pyhanko.sign.timestamps.TimeStamper)

Bases: object

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

generate_timestamp_field_name()str

Generate a unique name for a document timestamp field using uuid.

Returns

The field name, as a (Python) string.

timestamp_pdf(pdf_out: pyhanko.pdf_utils.incremental_writer.IncrementalPdfFileWriter, md_algorithm, validation_context, bytes_reserved=None, validation_paths=None, timestamper: Optional[pyhanko.sign.timestamps.TimeStamper] = None, *, in_place=False, output=None, chunk_size=4096)

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 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.

  • 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. Default is 4096.

Returns

The output stream containing the signed output.

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

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_contextcertvalidator.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 is 4096.

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

Returns

The output stream containing the signed output.

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

Bases: pyhanko.sign.signers.PdfTimeStamper

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 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.

generate_timestamp_field_name()str

Look up the timestamp field name in the PdfSignatureMetadata object associated with this PdfSigner. If not specified, generate a unique field name using uuid.

Returns

The field name, as a (Python) string.

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

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. Default is 4096.

Returns

The output stream containing the signed data.

class pyhanko.sign.signers.PdfCMSEmbedder(new_field_spec: Optional[pyhanko.sign.fields.SigFieldSpec] = None)

Bases: object

Low-level class that handles embedding CMS objects into PDF signature fields.

It also takes care of appearance generation and DocMDP configuration, but does not otherwise offer any of the conveniences of PdfSigner.

Parameters

new_field_specSigFieldSpec to use when creating new fields on-the-fly.

write_cms(field_name: str, writer: pyhanko.pdf_utils.writer.BasePdfFileWriter, existing_fields_only=False)

This method returns a generator coroutine that controls the process of embedding CMS data into a PDF signature field. Can be used for both timestamps and regular signatures.

Danger

This is a very low-level interface that performs virtually no error checking, and is intended to be used in situations where the construction of the CMS object to be embedded is not under the caller’s control (e.g. a remote signer that produces full-fledged CMS objects).

In almost every other case, you’re better of using PdfSigner instead, with a custom Signer implementation to handle the cryptographic operations if necessary.

The coroutine follows the following specific protocol.

  1. First, it retrieves or creates the signature field to embed the CMS object in, and yields a reference to said field.

  2. The caller should then send in a SigObjSetup object, which is subsequently processed by the coroutine. For convenience, the coroutine will then yield a reference to the signature dictionary (as embedded in the PDF writer).

  3. Next, the caller should send a SigIOSetup object, describing how the resulting document should be hashed and written to the output. The coroutine will write the entire document with a placeholder region reserved for the signature, compute the document’s hash and yield it to the caller.

    From this point onwards, no objects may be changed or added to the IncrementalPdfFileWriter currently in use.

  4. Finally, the caller should pass in a CMS object to place inside the signature dictionary. The CMS object can be supplied as a raw bytes object, or an asn1crypto-style object. The coroutine’s final yield is a tuple output, sig_contents, where output is the output stream used, and sig_contents is the value of the signature dictionary’s /Contents entry, given as a hexadecimal string.

Caution

It is the caller’s own responsibility to ensure that enough room is available in the placeholder signature object to contain the final CMS object.

Parameters
  • field_name – The name of the field to fill in. This should be a field of type /Sig.

  • writer – An IncrementalPdfFileWriter containing the document 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.

Returns

A generator coroutine implementing the protocol described above.

class pyhanko.sign.signers.SigObjSetup(sig_placeholder: pyhanko.sign.signers.PdfSignedData, mdp_setup: Optional[pyhanko.sign.signers.SigMDPSetup] = None, appearance_setup: Optional[pyhanko.sign.signers.SigAppearanceSetup] = None)

Bases: object

Describes the signature dictionary to be embedded as the form field’s value.

sig_placeholder: pyhanko.sign.signers.PdfSignedData

Bare-bones placeholder object, usually of type SignatureObject or DocumentTimestamp.

In particular, this determines the number of bytes to allocate for the CMS object.

mdp_setup: Optional[pyhanko.sign.signers.SigMDPSetup] = None

Optional DocMDP settings, see SigMDPSetup.

appearance_setup: Optional[pyhanko.sign.signers.SigAppearanceSetup] = None

Optional appearance settings, see SigAppearanceSetup.

class pyhanko.sign.signers.SigAppearanceSetup(style: pyhanko.stamp.TextStampStyle, timestamp: datetime.datetime, name: str, text_params: Optional[dict] = None)

Bases: object

Signature appearance configuration.

Part of the low-level PdfCMSEmbedder API, see SigObjSetup.

style: pyhanko.stamp.TextStampStyle

Stamp style to use to generate the appearance.

timestamp: datetime.datetime

Timestamp to show in the signature appearance.

name: str

Signer name to show in the signature appearance.

text_params: dict = None

Additional text interpolation parameters to pass to the underlying stamp style.

class pyhanko.sign.signers.SigMDPSetup(md_algorithm: str, certify: bool = False, field_lock: Union[pyhanko.sign.fields.FieldMDPSpec, NoneType] = None, docmdp_perms: Union[pyhanko.sign.fields.MDPPerm, NoneType] = None)

Bases: object

md_algorithm: str

Message digest algorithm to write into the signature reference dictionary, if one is written at all.

Warning

It is the caller’s responsibility to make sure that this value agrees with the value embedded into the CMS object, and with the algorithm used to hash the document. The low-level PdfCMSEmbedder API will simply take it at face value.

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.

field_lock: Optional[pyhanko.sign.fields.FieldMDPSpec] = None

Field lock information to write to the signature reference dictionary.

docmdp_perms: Optional[pyhanko.sign.fields.MDPPerm] = None

DocMDP permissions to write to the signature reference dictionary.

class pyhanko.sign.signers.PdfByteRangeDigest(data_key='/Contents', *, bytes_reserved=None)

Bases: pyhanko.pdf_utils.generic.DictionaryObject

fill(writer: pyhanko.pdf_utils.writer.BasePdfFileWriter, md_algorithm, in_place=False, output=None, chunk_size=4096)

Generator coroutine that handles the document hash computation and the actual filling of the placeholder data.

This is internal API; you should use use PdfSigner wherever possible. If you really need fine-grained control, use PdfCMSEmbedder instead.

class pyhanko.sign.signers.PdfSignedData(obj_type, subfilter: pyhanko.sign.fields.SigSeedSubFilter = <SigSeedSubFilter.ADOBE_PKCS7_DETACHED: '/adbe.pkcs7.detached'>, timestamp: Optional[datetime.datetime] = None, bytes_reserved=None)

Bases: pyhanko.sign.signers.PdfByteRangeDigest

Generic class to model signature dictionaries in a PDF file. See also SignatureObject and DocumentTimestamp.

Parameters
  • obj_type – The type of signature object.

  • subfilter – See SigSeedSubFilter.

  • timestamp – The timestamp to embed into the /M entry.

  • bytes_reserved

    The number of bytes to reserve for the signature. Defaults to 16 KiB.

    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.

class pyhanko.sign.signers.SignatureObject(timestamp: Optional[datetime.datetime] = None, subfilter: pyhanko.sign.fields.SigSeedSubFilter = <SigSeedSubFilter.ADOBE_PKCS7_DETACHED: '/adbe.pkcs7.detached'>, name=None, location=None, reason=None, bytes_reserved=None)

Bases: pyhanko.sign.signers.PdfSignedData

Class modelling a (placeholder for) a regular PDF signature.

Parameters
  • timestamp – The (optional) timestamp to embed into the /M entry.

  • subfilter – See SigSeedSubFilter.

  • bytes_reserved

    The number of bytes to reserve for the signature. Defaults to 16 KiB.

    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.

  • name – Signer name. You probably want to leave this blank, viewers should default to the signer’s subject name.

  • location – Optional signing location.

  • reason – Optional signing reason. May be restricted by seed values.

class pyhanko.sign.signers.DocumentTimestamp(bytes_reserved=None)

Bases: pyhanko.sign.signers.PdfSignedData

Class modelling a (placeholder for) a regular PDF signature.

Parameters

bytes_reserved

The number of bytes to reserve for the signature. Defaults to 16 KiB.

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.

class pyhanko.sign.signers.SigIOSetup(md_algorithm: str, in_place: bool = False, chunk_size: int = 4096, output: Optional[io.BufferedIOBase] = None)

Bases: object

I/O settings for writing signed PDF documents.

Objects of this type are used in the penultimate phase of the PdfCMSEmbedder protocol.

md_algorithm: str

Message digest algorithm to use to compute the document hash. It should be supported by hashlib.

Warning

This is also the message digest algorithm that should appear in the corresponding signerInfo entry in the CMS object that ends up being embedded in the signature field.

in_place: bool = False

Sign the input in-place. If False, write output to a BytesIO object, or output if the latter is not None.

chunk_size: int = 4096

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 is 4096.

output: Optional[io.BufferedIOBase] = None

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

pyhanko.sign.signers.sign_pdf(pdf_out: pyhanko.pdf_utils.writer.BasePdfFileWriter, signature_meta: pyhanko.sign.signers.PdfSignatureMetadata, signer: pyhanko.sign.signers.Signer, timestamper: Optional[pyhanko.sign.timestamps.TimeStamper] = None, new_field_spec: Optional[pyhanko.sign.fields.SigFieldSpec] = None, existing_fields_only=False, bytes_reserved=None, in_place=False, output=None)

Thin convenience wrapper around PdfSigner.sign_pdf().

Parameters
  • pdf_out – An IncrementalPdfFileWriter.

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

  • 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.

  • in_place – Sign the input in-place. If False, write output to a BytesIO object.

  • 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.

  • 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.

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

Returns

The output stream containing the signed output.

pyhanko.sign.signers.load_certs_from_pemder(cert_files)

A convenience function to load PEM/DER-encoded certificates from files.

Parameters

cert_files – An iterable of file names.

Returns

A generator producing asn1crypto.x509.Certificate objects.

pyhanko.sign.signers.DEFAULT_MD = 'sha256'

Default message digest algorithm used when computing digests for use in signatures.

pyhanko.sign.signers.DEFAULT_SIGNING_STAMP_STYLE = TextStampStyle(text_box_style=TextBoxStyle(font=<pyhanko.pdf_utils.font.SimpleFontEngine object>, font_size=10, leading=None, text_sep=10, border_width=0, vertical_center=True), border_width=3, stamp_text='Digitally signed by %(signer)s.\nTimestamp: %(ts)s.', timestamp_format='%Y-%m-%d %H:%M:%S %Z', background=<pyhanko.pdf_utils.content.RawContent object>, background_opacity=0.6)

Default stamp style used for visible signatures.