pyhanko.sign package

Subpackages

Submodules

pyhanko.sign.attributes module

class pyhanko.sign.attributes.AdobeRevinfoProvider(value: RevocationInfoArchival)

Bases: CMSAttributeProvider

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

Parameters:

value – A (pre-formatted) RevocationInfoArchival object.

attribute_type: str = 'adobe_revocation_info_archival'

Name of the CMS attribute type this provider supplies. See cms.CMSAttributeType.

async build_attr_value(dry_run=False) → RevocationInfoArchival | None

Build the attribute value asynchronously.

Parameters:

dry_run – True if the signer is operating in dry-run (size estimation) mode.

Returns:

An attribute value appropriate for the attribute type.

class pyhanko.sign.attributes.CMSAlgorithmProtectionProvider(digest_algo: str, signature_algo: SignedDigestAlgorithm)

Bases: CMSAttributeProvider

attribute_type: str = 'cms_algorithm_protection'

Name of the CMS attribute type this provider supplies. See cms.CMSAttributeType.

async build_attr_value(dry_run=False) → CMSAlgorithmProtection

Build the attribute value asynchronously.

Parameters:

dry_run – True if the signer is operating in dry-run (size estimation) mode.

Returns:

An attribute value appropriate for the attribute type.

class pyhanko.sign.attributes.CMSAttributeProvider

Bases: object

Base class to provide asynchronous CMS attribute values.

attribute_type: str

Name of the CMS attribute type this provider supplies. See cms.CMSAttributeType.

async build_attr_value(dry_run=False)

Build the attribute value asynchronously.

Parameters:

dry_run – True if the signer is operating in dry-run (size estimation) mode.

Returns:

An attribute value appropriate for the attribute type.

async get_attribute(dry_run=False) → CMSAttribute | None
class pyhanko.sign.attributes.SignedAttributeProviderSpec

Bases: ABC

Added in version 0.14.0.

Interface for setting up signed attributes, independently of the Signer hierarchy.

signed_attr_providers(data_digest: bytes, digest_algorithm: str) → Iterable[CMSAttributeProvider]

Lazily set up signed attribute providers.

Parameters:

  • data_digest – The digest of the data to be signed.

  • digest_algorithm – The digest algorithm used.

class pyhanko.sign.attributes.SigningCertificateV2Provider(signing_cert: Certificate)

Bases: CMSAttributeProvider

Provide a value for the signing-certificate-v2 attribute.

Parameters:

signing_cert – Certificate containing the signer’s public key.

attribute_type: str = 'signing_certificate_v2'

Name of the CMS attribute type this provider supplies. See cms.CMSAttributeType.

async build_attr_value(dry_run=False) → SigningCertificateV2

Build the attribute value asynchronously.

Parameters:

dry_run – True if the signer is operating in dry-run (size estimation) mode.

Returns:

An attribute value appropriate for the attribute type.

class pyhanko.sign.attributes.SigningTimeProvider(timestamp: datetime)

Bases: CMSAttributeProvider

Provide a value for the signing-time attribute (i.e. an otherwise unauthenticated timestamp).

Parameters:

timestamp – Datetime object to include.

attribute_type: str = 'signing_time'

Name of the CMS attribute type this provider supplies. See cms.CMSAttributeType.

async build_attr_value(dry_run=False) → Time

Build the attribute value asynchronously.

Parameters:

dry_run – True if the signer is operating in dry-run (size estimation) mode.

Returns:

An attribute value appropriate for the attribute type.

class pyhanko.sign.attributes.TSTProvider(digest_algorithm: str, data_to_ts: bytes, timestamper: TimeStamper, attr_type: str = 'signature_time_stamp_token', prehashed=False)

Bases: CMSAttributeProvider

async build_attr_value(dry_run=False) → ContentInfo

Build the attribute value asynchronously.

Parameters:

dry_run – True if the signer is operating in dry-run (size estimation) mode.

Returns:

An attribute value appropriate for the attribute type.

class pyhanko.sign.attributes.UnsignedAttributeProviderSpec

Bases: ABC

Added in version 0.14.0.

Interface for setting up unsigned attributes, independently of the Signer hierarchy.

unsigned_attr_providers(signature: bytes, signed_attrs: CMSAttributes, digest_algorithm: str) → Iterable[CMSAttributeProvider]

Lazily set up unsigned attribute providers.

Parameters:

  • signature – The signature computed over the signed attributes.

  • signed_attrs – Signed attributes over which the signature was taken.

  • digest_algorithm – The digest algorithm used.

pyhanko.sign.fields module

Utilities to deal with signature form fields and their properties in PDF files.

class pyhanko.sign.fields.FieldMDPAction(*values)

Bases: Enum

Marker for the scope of a /FieldMDP policy.

ALL = '/All'

The policy locks all form fields.

INCLUDE = '/Include'

The policy locks all fields in the list (see FieldMDPSpec.fields).

EXCLUDE = '/Exclude'

The policy locks all fields except those specified in the list (see FieldMDPSpec.fields).

class pyhanko.sign.fields.FieldMDPSpec(action: FieldMDPAction, fields: List[str] | None = None)

Bases: object

/FieldMDP policy description.

This class models both field lock dictionaries and /FieldMDP transformation parameters.

action: FieldMDPAction

Indicates the scope of the policy.

fields: List[str] | None = None

Indicates the fields subject to the policy, unless action is FieldMDPAction.ALL.

as_pdf_object() → DictionaryObject

Render this /FieldMDP policy description as a PDF dictionary.

Returns:

A DictionaryObject.

as_transform_params() → DictionaryObject

Render this /FieldMDP policy description as a PDF dictionary, ready for inclusion into the /TransformParams entry of a /FieldMDP dictionary associated with a signature object.

Returns:

A DictionaryObject.

as_sig_field_lock() → DictionaryObject

Render this /FieldMDP policy description as a PDF dictionary, ready for inclusion into the /Lock dictionary of a signature field.

Returns:

A DictionaryObject.

classmethod from_pdf_object(pdf_dict) → FieldMDPSpec

Read a PDF dictionary into a FieldMDPSpec object.

Parameters:

pdf_dict – A DictionaryObject.

Returns:

A FieldMDPSpec object.

is_locked(field_name: str) → bool

Adjudicate whether a field should be locked by the policy described by this FieldMDPSpec object.

Parameters:

field_name – The name of a form field.

Returns:

True if the field should be locked, False otherwise.

class pyhanko.sign.fields.InvisSigSettings(set_print_flag: bool = True, set_hidden_flag: bool = False, box_out_of_bounds: bool = False)

Bases: object

Invisible signature widget generation settings.

These settings exist because there is no real way of including an untagged invisible signature in a document that complies with the requirements of both PDF/A-2 (or -3) and PDF/UA-1.

Compatibility with PDF/A (the default) requires the print flag to be set. Compatibility with PDF/UA requires the hidden flag to be set (which is banned in PDF/A) or the box to be outside the crop box.

set_print_flag: bool = True

Set the print flag. Required in PDF/A.

set_hidden_flag: bool = False

Set the hidden flag. Required in PDF/UA.

box_out_of_bounds: bool = False

Put the box out of bounds (technically, this just makes the box zero-sized with large negative coordinates).

This is a hack to get around the fact that PDF/UA requires the hidden flag to be set on all in-bounds untagged annotations, and some validators consider [0, 0, 0, 0] to be an in-bounds rectangle if (0, 0) is a point that falls within the crop box.

class pyhanko.sign.fields.MDPPerm(*values)

Bases: OrderedEnum

Indicates a /DocMDP level.

Cf. Table 254 in ISO 32000-1.

NO_CHANGES = 1

No changes to the document are allowed.

Warning

This does not apply to DSS updates and the addition of document time stamps.

FILL_FORMS = 2

Form filling & signing is allowed.

ANNOTATE = 3

Form filling, signing and commenting are allowed.

Warning

Validating this /DocMDP level is not currently supported, but included in the list for completeness.

class pyhanko.sign.fields.SeedLockDocument(*values)

Bases: Enum

Provides a recommendation to the signer as to whether the document should be locked after signing. The corresponding flag in SigSeedValueSpec.flags determines whether this constraint is a required constraint.

LOCK = '/true'

Lock the document after signing.

DO_NOT_LOCK = '/false'

Lock the document after signing.

SIGNER_DISCRETION = '/auto'

Leave the decision up to the signer.

Note

This is functionally equivalent to not specifying any value.

class pyhanko.sign.fields.SeedValueDictVersion(*values)

Bases: OrderedEnum

Specify the minimal compliance level for a seed value dictionary processor.

PDF_1_5 = 1

Require the reader to understand all keys defined in PDF 1.5.

PDF_1_7 = 2

Require the reader to understand all keys defined in PDF 1.7.

PDF_2_0 = 3

Require the reader to understand all keys defined in PDF 2.0.

class pyhanko.sign.fields.SigCertConstraintFlags(*values)

Bases: Flag

Flags for the /Ff entry in the certificate seed value dictionary for a dictionary field. These mark which of the constraints are to be strictly enforced, as opposed to optional ones.

Warning

While this enum records values for all flags, not all corresponding constraint types have been implemented yet.

SUBJECT = 1

See SigCertConstraints.subjects.

ISSUER = 2

See SigCertConstraints.issuers.

OID = 4

Currently not supported.

SUBJECT_DN = 8

See SigCertConstraints.subject_dn.

RESERVED = 16

Currently not supported (reserved).

KEY_USAGE = 32

See SigCertConstraints.key_usage.

URL = 64

See SigCertConstraints.info_url.

Note

As specified in the standard, this enforcement bit is supposed to be ignored by default. We include it for compatibility reasons.

UNSUPPORTED = 20

Flags for which the corresponding constraint is unsupported.

class pyhanko.sign.fields.SigCertConstraints(flags: SigCertConstraintFlags = <SigCertConstraintFlags: 0>, subjects: List[Certificate] | None = None, subject_dn: Name | None = None, issuers: List[Certificate] | None = None, info_url: str | None = None, url_type: NameObject = '/Browser', key_usage: List[SigCertKeyUsage] | None = None)

Bases: object

This part of the seed value dictionary allows the document author to set constraints on the signer’s certificate.

See Table 235 in ISO 32000-1.

flags: SigCertConstraintFlags = 0

Enforcement flags. By default, all entries are optional.

subjects: List[Certificate] | None = None

Explicit list of certificates that can be used to sign a signature field.

subject_dn: Name | None = None

Certificate subject names that can be used to sign a signature field. Subject DN entries that are not mentioned are unconstrained.

issuers: List[Certificate] | None = None

List of issuer certificates that the signer certificate can be issued by. Note that these issuers do not need to be the direct issuer of the signer’s certificate; any descendant relationship will do.

info_url: str | None = None

Informational URL that should be opened when an appropriate certificate cannot be found (if url_type is /Browser, that is).

Note

PyHanko ignores this value, but we include it for compatibility.

url_type: NameObject = '/Browser'

Handler that should be used to open info_url. /Browser is the only implementation-independent value.

key_usage: List[SigCertKeyUsage] | None = None

Specify the key usage extensions that should (or should not) be present on the signer’s certificate.

classmethod from_pdf_object(pdf_dict)

Read a PDF dictionary into a SigCertConstraints object.

Parameters:

pdf_dict – A DictionaryObject.

Returns:

A SigCertConstraints object.

as_pdf_object()

Render this SigCertConstraints object to a PDF dictionary.

Returns:

A DictionaryObject.

satisfied_by(signer: Certificate, validation_path: ValidationPath | None)

Evaluate whether a signing certificate satisfies the required constraints of this SigCertConstraints object.

Parameters:

  • signer – The candidate signer’s certificate.

  • validation_path – Validation path of the signer’s certificate.

Raises:

UnacceptableSignerError – Raised if the conditions are not met.

class pyhanko.sign.fields.SigCertKeyUsage(must_have: KeyUsage | None = None, forbidden: KeyUsage | None = None)

Bases: object

Encodes the key usage bits that must (resp. must not) be active on the signer’s certificate.

Note

See § 4.2.1.3 in RFC 5280 and KeyUsage for more information on key usage extensions.

Note

The human-readable names of the key usage extensions are recorded in camelCase in RFC 5280, but this class uses the naming convention of KeyUsage in asn1crypto. The conversion is done by replacing camelCase with snake_case. For example, nonRepudiation becomes non_repudiation, and digitalSignature turns into digital_signature.

Note

This class is intended to closely replicate the definition of the KeyUsage entry Table 235 in ISO 32000-1. In particular, it does not provide a mechanism to deal with extended key usage extensions (cf. § 4.2.1.12 in RFC 5280).

Parameters:

  • must_have – The KeyUsage object encoding the key usage extensions that must be present on the signer’s certificate.

  • forbidden – The KeyUsage object encoding the key usage extensions that must not be present on the signer’s certificate.

encode_to_sv_string()

Encode the key usage requirements in the format specified in the PDF specification.

Returns:

A string.

classmethod read_from_sv_string(ku_str)

Parse a PDF KeyUsage string into an instance of SigCertKeyUsage. See Table 235 in ISO 32000-1.

Parameters:

ku_str – A PDF KeyUsage string.

Returns:

An instance of SigCertKeyUsage.

classmethod from_sets(must_have: Set[str] | None = None, forbidden: Set[str] | None = None)

Initialise a SigCertKeyUsage object from two sets.

Parameters:

  • must_have – The key usage extensions that must be present on the signer’s certificate.

  • forbidden – The key usage extensions that must not be present on the signer’s certificate.

Returns:

A SigCertKeyUsage object encoding these.

must_have_set() → Set[str]

Return the set of key usage extensions that must be present on the signer’s certificate.

forbidden_set() → Set[str]

Return the set of key usage extensions that must not be present on the signer’s certificate.

class pyhanko.sign.fields.SigFieldSpec(sig_field_name: str, on_page: int = 0, box: Tuple[int, int, int, int] | None = None, seed_value_dict: SigSeedValueSpec | None = None, field_mdp_spec: FieldMDPSpec | None = None, doc_mdp_update_value: MDPPerm | None = None, combine_annotation: bool = True, empty_field_appearance: bool = False, invis_sig_settings: InvisSigSettings = InvisSigSettings(set_print_flag=True, set_hidden_flag=False, box_out_of_bounds=False), readable_field_name: str | None = None, visible_sig_settings: VisibleSigSettings = VisibleSigSettings(rotate_with_page=True, scale_with_page_zoom=True, print_signature=True))

Bases: object

Description of a signature field to be created.

sig_field_name: str

Name of the signature field.

on_page: int = 0

Index of the page on which the signature field should be included (starting at 0). A negative number counts pages from the back of the document, with index -1 referring to the last page.

Note

This is essentially only relevant for visible signature fields, i.e. those that have a widget associated with them.

box: Tuple[int, int, int, int] | None = None

Bounding box of the signature field, if applicable.

Typically specified in ll_x, ll_y, ur_x, ur_y format, where ll_* refers to the lower left and ur_* to the upper right corner.

seed_value_dict: SigSeedValueSpec | None = None

Specification for the seed value dictionary, if applicable.

field_mdp_spec: FieldMDPSpec | None = None

Specification for the field lock dictionary, if applicable.

doc_mdp_update_value: MDPPerm | None = None

Value to use for the document modification policy associated with the signature in this field.

This value will be embedded into the field lock dictionary if specified, and is meaningless if field_mdp_spec is not specified.

Warning

DocMDP entries for approval signatures are a PDF 2.0 feature. Older PDF software will likely ignore this part of the field lock dictionary.

combine_annotation: bool = True

Flag controlling whether the field should be combined with its annotation dictionary; True by default.

empty_field_appearance: bool = False

Generate a neutral appearance stream for empty, visible signature fields. If False, an empty appearance stream will be put in.

Note

We use an empty appearance stream to satisfy the appearance requirements for widget annotations in ISO 32000-2. However, even when a nontrivial appearance stream is present on an empty signature field, many viewers will not use it to render the appearance of the empty field on-screen.

Instead, these viewers typically substitute their own native widget.

invis_sig_settings: InvisSigSettings = InvisSigSettings(set_print_flag=True, set_hidden_flag=False, box_out_of_bounds=False)

Advanced settings to control invisible signature field generation.

readable_field_name: str | None = None

Human-readable field name (/TU entry).

Note

This value is commonly rendered as a tooltip in viewers, but also serves an accessibility purpose.

visible_sig_settings: VisibleSigSettings = VisibleSigSettings(rotate_with_page=True, scale_with_page_zoom=True, print_signature=True)

Advanced settings to control the generation of visible signature fields.

format_lock_dictionary() → DictionaryObject | None
class pyhanko.sign.fields.SigSeedSubFilter(*values)

Bases: Enum

Enum declaring all supported /SubFilter values.

ADOBE_PKCS7_DETACHED = '/adbe.pkcs7.detached'
PADES = '/ETSI.CAdES.detached'
ETSI_RFC3161 = '/ETSI.RFC3161'
class pyhanko.sign.fields.SigSeedValFlags(*values)

Bases: Flag

Flags for the /Ff entry in the seed value dictionary for a signature field. These mark which of the constraints are to be strictly enforced, as opposed to optional ones.

Warning

The flags LEGAL_ATTESTATION and APPEARANCE_FILTER are processed in accordance with the specification when creating a signature, but support is nevertheless limited.

  • PyHanko does not support legal attestations at all, so given that the LEGAL_ATTESTATION requirement flag only restricts the legal attestations that can be used by the signer, pyHanko can safely ignore it when signing.

    On the other hand, since the validator is not aware of legal attestations either, it cannot validate signatures that make legal_attestations a mandatory constraint.

  • Since pyHanko does not define any named appearances, setting the APPEARANCE_FILTER flag and the appearance entry in the seed value dictionary will make pyHanko refuse to sign the document.

    When validating, the situation is different: since pyHanko has no way of knowing whether the signer used the named appearance imposed by the seed value dictionary, it will simply emit a warning and continue validating the signature.

FILTER = 1

Makes the signature handler setting mandatory. PyHanko only supports /Adobe.PPKLite.

SUBFILTER = 2

See subfilters.

V = 4

See sv_dict_version.

REASONS = 8

See reasons.

LEGAL_ATTESTATION = 16

See legal_attestations.

ADD_REV_INFO = 32

See add_rev_info.

DIGEST_METHOD = 64

See digest_method.

LOCK_DOCUMENT = 128

See lock_document.

APPEARANCE_FILTER = 256

See appearance.

class pyhanko.sign.fields.SigSeedValueSpec(flags: SigSeedValFlags = <SigSeedValFlags: 0>, reasons: List[str] | None = None, timestamp_server_url: str | None = None, timestamp_required: bool = False, cert: SigCertConstraints | None = None, subfilters: List[SigSeedSubFilter] | None = None, digest_methods: List[str] | None = None, add_rev_info: bool | None = None, seed_signature_type: SeedSignatureType | None = None, sv_dict_version: SeedValueDictVersion | int | None = None, legal_attestations: List[str] | None = None, lock_document: SeedLockDocument | None = None, appearance: str | None = None)

Bases: object

Python representation of a PDF seed value dictionary.

flags: SigSeedValFlags = 0

Enforcement flags. By default, all entries are optional.

reasons: List[str] | None = None

Acceptable reasons for signing.

timestamp_server_url: str | None = None

RFC 3161 timestamp server endpoint suggestion.

timestamp_required: bool = False

Flags whether a timestamp is required. This flag is only meaningful if timestamp_server_url is specified.

cert: SigCertConstraints | None = None

Constraints on the signer’s certificate.

subfilters: List[SigSeedSubFilter] | None = None

Acceptable /SubFilter values.

digest_methods: List[str] | None = None

Acceptable digest methods.

add_rev_info: bool | None = None

Indicates whether revocation information should be embedded.

Warning

This flag exclusively refers to the Adobe-style revocation information embedded within the CMS object that is written to the signature field. PAdES-style revocation information that is saved to the document security store (DSS) does not satisfy the requirement. Additionally, the standard mandates that /SubFilter be equal to /adbe.pkcs7.detached if this flag is True.

seed_signature_type: SeedSignatureType | None = None

Specifies the type of signature that should occupy a signature field; this represents the /MDP entry in the seed value dictionary. See SeedSignatureType for details.

Caution

Since a certification-type signature is by definition the first signature applied to a document, compliance with this requirement cannot be cryptographically enforced.

sv_dict_version: SeedValueDictVersion | int | None = None

Specifies the compliance level required of a seed value dictionary processor. If None, pyHanko will compute an appropriate value.

Note

You may also specify this value directly as an integer. This covers potential future versions of the standard that pyHanko does not support out of the box.

legal_attestations: List[str] | None = None

Specifies the possible legal attestations that a certification signature occupying this signature field can supply. The corresponding flag in flags indicates whether this is a mandatory constraint.

Caution

Since legal_attestations is only relevant for certification signatures, compliance with this requirement cannot be reliably enforced. Regardless, since pyHanko’s validator is also unaware of legal attestation settings, it will refuse to validate signatures where this seed value constitutes a mandatory constraint.

Additionally, since pyHanko does not support legal attestation specifications at all, it vacuously satisfies the requirements of this entry no matter what, and will therefore ignore it when signing.

lock_document: SeedLockDocument | None = None

Tell the signer whether or not the document should be locked after signing this field; see SeedLockDocument for details.

The corresponding flag in flags indicates whether this constraint is mandatory.

appearance: str | None = None

Specify a named appearance to use when generating the signature. The corresponding flag in flags indicates whether this constraint is mandatory.

Caution

There is no standard registry of named appearances, so these constraints are not portable, and cannot be validated.

PyHanko currently does not define any named appearances.

as_pdf_object()

Render this SigSeedValueSpec object to a PDF dictionary.

Returns:

A DictionaryObject.

classmethod from_pdf_object(pdf_dict)

Read from a seed value dictionary.

Parameters:

pdf_dict – A DictionaryObject.

Returns:

A SigSeedValueSpec object.

build_timestamper()

Return a timestamper object based on the timestamp_server_url attribute of this SigSeedValueSpec object.

Returns:

A HTTPTimeStamper.

class pyhanko.sign.fields.SignatureFormField(field_name, *, box=None, include_on_page=None, combine_annotation=True, invis_settings: InvisSigSettings = InvisSigSettings(set_print_flag=True, set_hidden_flag=False, box_out_of_bounds=False), visible_settings: VisibleSigSettings = VisibleSigSettings(rotate_with_page=True, scale_with_page_zoom=True, print_signature=True), annot_flags=None)

Bases: DictionaryObject

register_widget_annotation(writer: BasePdfFileWriter, sig_field_ref)
class pyhanko.sign.fields.VisibleSigSettings(rotate_with_page: bool = True, scale_with_page_zoom: bool = True, print_signature: bool = True)

Bases: object

Added in version 0.14.0.

Additional flags used when setting up visible signature widgets.

rotate_with_page: bool = True

Allow the signature widget to rotate with the page if rotation is applied (e.g. by way of the page’s /Rotate entry). Default is True.

Note

If False, this will cause the NoRotate flag to be set.

scale_with_page_zoom: bool = True

Allow the signature widget to scale with the page’s zoom level. Default is True.

Note

If False, this will cause the NoZoom flag to be set.

print_signature: bool = True

Render the signature when the document is printed. Default True.

pyhanko.sign.fields.append_signature_field(pdf_out: BasePdfFileWriter, sig_field_spec: SigFieldSpec)

Append signature fields to a PDF file.

Parameters:

  • pdf_out – Incremental writer to house the objects.

  • sig_field_spec – A SigFieldSpec object describing the signature field to add.

pyhanko.sign.fields.apply_sig_field_spec_properties(pdf_out: BasePdfFileWriter, sig_field: DictionaryObject, sig_field_spec: SigFieldSpec)

Internal function to apply field spec properties to a newly created field.

pyhanko.sign.fields.ensure_sig_flags(writer: BasePdfFileWriter, lock_sig_flags: bool = True)

Ensure the SigFlags setting is present in the AcroForm dictionary, and the /NeedAppearances setting is cleared if necessary.

Parameters:

  • writer – A PDF writer.

  • lock_sig_flags – Whether to flag the document as append-only.

pyhanko.sign.fields.enumerate_sig_fields(handler: PdfHandler, filled_status: bool | None = None, with_name: str | None = None)

Enumerate signature fields.

Parameters:

  • handler – The PdfHandler to operate on.

  • filled_status – Optional boolean. If True (resp. False) then all filled (resp. empty) fields are returned. If left None (the default), then all fields are returned.

  • with_name – If not None, only look for fields with the specified name.

Returns:

A generator producing signature fields.

pyhanko.sign.fields.prepare_sig_field(sig_field_name, root, update_writer: BasePdfFileWriter, existing_fields_only=False, **kwargs)

Returns a tuple of a boolean and a reference to a signature field. The boolean is True if the field was created, and False otherwise.

Danger

This function is internal API.

pyhanko.sign.general module

General tools related to Cryptographic Message Syntax (CMS) signatures, not necessarily to the extent implemented in the PDF specification.

CMS is defined in RFC 5652. To parse CMS messages, pyHanko relies heavily on asn1crypto.

exception pyhanko.sign.general.CMSExtractionError(failure_message)

Bases: ValueErrorWithMessage

exception pyhanko.sign.general.CMSStructuralError(failure_message)

Bases: ValueErrorWithMessage

Structural error in a CMS object.

exception pyhanko.sign.general.MultivaluedAttributeError

Bases: ValueError

exception pyhanko.sign.general.NonexistentAttributeError

Bases: KeyError

class pyhanko.sign.general.SignedDataCerts(signer_cert: Certificate, other_certs: List[Certificate], attribute_certs: List[AttributeCertificateV2])

Bases: object

Value type to describe certificates included in a CMS signed data payload.

signer_cert: Certificate

The certificate identified as the signer’s certificate.

other_certs: List[Certificate]

Other (public-key) certificates included in the signed data object.

attribute_certs: List[AttributeCertificateV2]

Attribute certificates included in the signed data object.

exception pyhanko.sign.general.SigningError(msg: str, *args)

Bases: FormFillingError

Error encountered while signing a file.

exception pyhanko.sign.general.UnacceptableSignerError(msg: str, *args)

Bases: SigningError

Error raised when a signer was judged unacceptable.

exception pyhanko.sign.general.ValueErrorWithMessage(failure_message)

Bases: ValueError

Value error with a failure message attribute that can be conveniently extracted, instead of having to rely on extracting exception args generically.

pyhanko.sign.general.as_signing_certificate(cert: Certificate) → SigningCertificate

Format an ASN.1 SigningCertificate object, where the certificate is identified by its SHA-1 digest.

Parameters:

cert – An X.509 certificate.

Returns:

A tsp.SigningCertificate object referring to the original certificate.

pyhanko.sign.general.as_signing_certificate_v2(cert: Certificate, hash_algo='sha256') → SigningCertificateV2

Format an ASN.1 SigningCertificateV2 value, where the certificate is identified by the hash algorithm specified.

Parameters:

  • cert – An X.509 certificate.

  • hash_algo – Hash algorithm to use to digest the certificate. Default is SHA-256.

Returns:

A tsp.SigningCertificateV2 object referring to the original certificate.

pyhanko.sign.general.byte_range_digest(stream: IO, byte_range: Iterable[int], md_algorithm: str, chunk_size=4096) → Tuple[int, bytes]

Internal API to compute byte range digests. Potentially dangerous if used without due caution.

Parameters:

  • stream – Stream over which to compute the digest. Must support seeking and reading.

  • byte_range – The byte range, as a list of (offset, length) pairs, flattened.

  • md_algorithm – The message digest algorithm to use.

  • chunk_size – The I/O chunk size to use.

Returns:

A tuple of the total digested length, and the actual digest.

pyhanko.sign.general.check_ess_certid(cert: Certificate, certid: ESSCertID | ESSCertIDv2)

Match an ESSCertID value against a certificate.

Parameters:

  • cert – The certificate to match against.

  • certid – The ESSCertID value.

Returns:

True if the ESSCertID matches the certificate, False otherwise.

pyhanko.sign.general.extract_certificate_info(signed_data: SignedData) → SignedDataCerts

Extract and classify embedded certificates found in the certificates field of the signed data value.

Parameters:

signed_data – A CMS SignedData value.

Returns:

A SignedDataCerts object containing the embedded certificates.

pyhanko.sign.general.extract_signer_info(signed_data: SignedData) → SignerInfo

Extract the unique SignerInfo entry of a CMS signed data value, or throw a ValueError.

Parameters:

signed_data – A CMS SignedData value.

Returns:

A CMS SignerInfo value.

Raises:

ValueError – If the number of SignerInfo values is not exactly one.

pyhanko.sign.general.find_cms_attribute(attrs: Iterable[CMSAttribute] | None, name: str)

Deprecated since version 0.35.0.

Find and return CMS attribute values of a given type.

Parameters:

  • attrs – The cms.CMSAttributes object.

  • name – The attribute type as a string (as defined in asn1crypto).

Returns:

The values associated with the requested type, if present.

Raises:

NonexistentAttributeError – Raised when no such type entry could be found in the cms.CMSAttributes object.

pyhanko.sign.general.find_cms_attribute_iter(attrs: Iterable[CMSAttribute] | None, name: str)

Added in version 0.35.0.

Find and return CMS attribute values of a given type in a generator.

Note

This function will return an empty generator rather than throwing NonexistentAttributeError.

Parameters:

  • attrs – The cms.CMSAttributes object.

  • name – The attribute type as a string (as defined in asn1crypto).

Returns:

The values associated with the requested type, if present.

pyhanko.sign.general.find_unique_cms_attribute(attrs: Iterable[CMSAttribute] | None, name: str)

Find and return a unique CMS attribute value of a given type.

Parameters:

  • attrs – The cms.CMSAttributes object.

  • name – The attribute type as a string (as defined in asn1crypto).

Returns:

The value associated with the requested type, if present.

Raises:
pyhanko.sign.general.get_cms_hash_algo_for_mechanism(mech: SignedDigestAlgorithm) → str

Internal function that takes a SignedDigestAlgorithm instance and returns the name of the digest algorithm that has to be used to compute the messageDigest attribute.

Parameters:

mech – A signature mechanism.

Returns:

A digest algorithm name.

pyhanko.sign.general.load_cert_from_pemder(cert_file)

A convenience function to load a single PEM/DER-encoded certificate from a file.

Parameters:

cert_file – A file name.

Returns:

An asn1crypto.x509.Certificate object.

pyhanko.sign.general.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.general.load_certs_from_pemder_data(cert_data_bytes: bytes)

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

Parameters:

cert_data_bytes – bytes object from which to extract certificates.

Returns:

A generator producing asn1crypto.x509.Certificate objects.

pyhanko.sign.general.load_private_key_from_pemder(key_file, passphrase: bytes | None) → PrivateKeyInfo

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

Parameters:

  • key_file – File to read the key from.

  • passphrase – Key passphrase.

Returns:

A private key encoded as an unencrypted PKCS#8 PrivateKeyInfo object.

pyhanko.sign.general.load_private_key_from_pemder_data(key_bytes: bytes, passphrase: bytes | None) → PrivateKeyInfo

A convenience function to load PEM/DER-encoded keys from binary data.

Parameters:

  • key_bytes – bytes object to read the key from.

  • passphrase – Key passphrase.

Returns:

A private key encoded as an unencrypted PKCS#8 PrivateKeyInfo object.

pyhanko.sign.general.match_issuer_serial(expected_issuer_serial: IssuerAndSerialNumber | IssuerSerial, cert: Certificate) → bool

Match the issuer and serial number of an X.509 certificate against some expected identifier.

Parameters:

  • expected_issuer_serial – A certificate identifier, either cms.IssuerAndSerialNumber or tsp.IssuerSerial.

  • cert – An x509.Certificate.

Returns:

True if there’s a match, False otherwise.

pyhanko.sign.general.optimal_pss_params(cert: Certificate, digest_algorithm: str) → RSASSAPSSParams

Figure out the optimal RSASSA-PSS parameters for a given certificate. The subject’s public key must be an RSA key.

Parameters:

  • cert – An RSA X.509 certificate.

  • digest_algorithm – The digest algorithm to use.

Returns:

RSASSA-PSS parameters.

pyhanko.sign.general.simple_cms_attribute(attr_type, value)

Convenience method to quickly construct a CMS attribute object with one value.

Parameters:

  • attr_type – The attribute type, as a string or OID.

  • value – The value.

Returns:

A cms.CMSAttribute object.

pyhanko.sign.pkcs11 module

This module provides PKCS#11 integration for pyHanko, by providing a wrapper for python-pkcs11 that can be seamlessly plugged into a PdfSigner.

class pyhanko.sign.pkcs11.PKCS11Signer(pkcs11_session: Session, cert_label: str | None = None, signing_cert: Certificate | None = None, ca_chain=None, key_label: str | None = None, prefer_pss=False, embed_roots=True, other_certs_to_pull=(), bulk_fetch=True, key_id: bytes | None = None, cert_id: bytes | None = None, use_raw_mechanism=False, signature_mechanism: SignedDigestAlgorithm | None = None, base_sign_kwargs: Dict[str, Any] | None = None)

Bases: Signer

Signer implementation for PKCS11 devices.

Parameters:

  • pkcs11_session – The PKCS11 session object to use.

  • cert_label – The label of the certificate that will be used for signing, to be pulled from the PKCS#11 token.

  • cert_id – ID of the certificate object that will be used for signing, to be pulled from the PKCS#11 token.

  • signing_cert – The signer’s certificate. If the signer’s certificate is provided via this parameter, the cert_label and cert_id parameters will not be used to retrieve the signer’s certificate.

  • ca_chain – Set of other relevant certificates (as asn1crypto.x509.Certificate objects).

  • key_label –

    The label of the key that will be used for signing. Defaults to the value of cert_label if left unspecified and key_id is also unspecified.

    Note

    At least one of key_id, key_label and cert_label must be supplied.

  • key_id – ID of the private key object (optional).

  • other_certs_to_pull – List labels of other certificates to pull from the PKCS#11 device. Defaults to the empty tuple. If None, pull all certificates.

  • bulk_fetch – Boolean indicating the fetching strategy. If True, fetch all certs and filter the unneeded ones. If False, fetch the requested certs one by one. Default value is True, unless other_certs_to_pull has one or fewer elements, in which case it is always treated as False.

  • use_raw_mechanism –

    Use the ‘raw’ equivalent of the selected signature mechanism. This is useful when working with tokens that do not support a hash-then-sign mode of operation.

    Note

    This functionality is only available for ECDSA at this time. Support for other signature schemes will be added on an as-needed basis.

  • signature_mechanism – Specify the signature mechanism explicitly. By default, pyHanko will attempt to infer it from the key’s properties.

  • base_sign_kwargs –

    Directly specify some of the keyword arguments passed to the pkcs11.SignMixin.sign() method.

    This can be used as an escape hatch to enable functionality (advanced auth, additional signing mechanisms) that are not directly supported by pyHanko.

default_cert_query_params: Dict[Attribute, Any]
default_key_query_params: Dict[Attribute, Any]
property cert_registry: CertificateStore

Changed in version 0.18.0: Turned into a property instead of a class attribute.

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

property signing_cert

Changed in version 0.14.0: Made optional (see note)

Changed in version 0.18.0: Turned into a property instead of a class attribute.

The certificate that will be used to create the signature.

Note

This is an optional field only to a limited extent. Subclasses may require it to be present, and not setting it at the beginning of the signing process implies that certain high-level convenience features will no longer work or be limited in function (e.g., automatic hash selection, appearance generation, revocation information collection, …).

However, making signing_cert optional enables certain signing workflows where the certificate of the signer is not known until the signature has actually been produced. This is most relevant in certain types of remote signing scenarios.

sign_kwargs(data_to_sign: bytes) → Dict[str, Any]

Supply keyword arguments to pass to the pkcs11.SignMixin.sign() method.

This can be used as an escape hatch to enable functionality (advanced auth, additional signing mechanisms) that are not directly supported by pyHanko.

Parameters:

data_to_sign –

The data being signed.

Note

In typical cases this parameter can be ignored; pyHanko exposes it to subclasses to allow for just-in-time credentials that depend on the content being signed.

Returns:

A dictionary of keyword arguments.

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

bulk_cert_fetch_params() → Dict[Attribute, Any]

Search parameters to bulk fetch certificates from the token.

Note

Can be overridden in subclasses.

single_cert_fetch_params(label: str | None, cert_id: bytes | None) → Dict[Attribute, Any]

Search parameters to fetch a single certificate from the token.

Note

Can be overridden in subclasses.

signing_key_fetch_params() → Dict[Attribute, Any]

Search parameters to fetch the signing key from the token.

Note

Can be overridden in subclasses.

async ensure_objects_loaded()

Async method that, when awaited, ensures that objects (relevant certificates, key handles, …) are loaded.

This coroutine is guaranteed to be called & awaited in sign_raw(), but some property implementations may cause object loading to be triggered synchronously (for backwards compatibility reasons). This blocks the event loop the first time it happens.

To avoid this behaviour, asynchronous code should ideally perform await signer.ensure_objects_loaded() after instantiating the signer.

Note

The asynchronous context manager on PKCS11SigningContext takes care of that automatically.

class pyhanko.sign.pkcs11.PKCS11SigningContext(config: PKCS11SignatureConfig, user_pin: str | None = None)

Bases: object

Context manager for PKCS#11 configurations.

pyhanko.sign.pkcs11.find_token(slots: List[Slot], slot_no: int | None = None, token_criteria: TokenCriteria | None = None) → Token | None

Internal helper method to find a token.

Parameters:

  • slots – The list of slots.

  • slot_no – Slot number to use. If not specified, the first slot containing a token satisfying the criteria will be used

  • token_criteria – Criteria the token must satisfy.

Returns:

A PKCS#11 token object, or None if none was found.

pyhanko.sign.pkcs11.open_pkcs11_session(lib_location: str, slot_no: int | None = None, token_label: str | None = None, token_criteria: TokenCriteria | None = None, user_pin: str | object | None = None) → Session

Open a PKCS#11 session

Parameters:

  • lib_location – Path to the PKCS#11 module.

  • slot_no – Slot number to use. If not specified, the first slot containing a token labelled token_label will be used.

  • token_label –

    Deprecated since version 0.14.0: Use token_criteria instead.

    Label of the token to use. If None, there is no constraint.

  • token_criteria – Criteria that the token should match.

  • user_pin –

    User PIN to use, or PROTECTED_AUTH. If None, authentication is skipped.

    Note

    Some PKCS#11 implementations do not require PIN when the token is opened, but will prompt for it out-of-band when signing. Whether PROTECTED_AUTH or None is used in this case depends on the implementation.

Returns:

An open PKCS#11 session object.

pyhanko.sign.pkcs11.select_pkcs11_signing_params(signature_mechanism: SignedDigestAlgorithm, digest_algorithm: str, use_raw_mechanism: bool, sign_kwargs: Dict[str, Any]) → PKCS11SignatureOperationSpec

Internal helper function to set up a PKCS #11 signing operation.

Parameters:

  • signature_mechanism – The signature mechanism to use (as an ASN.1 value)

  • digest_algorithm – The digest algorithm to use

  • use_raw_mechanism – Whether to attempt to use the raw mechanism on pre-hashed data.

  • sign_kwargs – Override kwargs manually.

Returns:

Module contents

class pyhanko.sign.ExternalSigner(signing_cert: Certificate | None, cert_registry: CertificateStore | None, signature_value: bytes | int | None = None, signature_mechanism: SignedDigestAlgorithm | None = None, prefer_pss: bool = False, embed_roots: bool = True)

Bases: Signer

Class to help formatting CMS objects for use with remote signing. It embeds a fixed signature value into the CMS, set at initialisation.

Intended for use with Interrupted signing.

Parameters:

  • signing_cert – The signer’s certificate.

  • cert_registry – The certificate registry to use in CMS generation.

  • signature_value – The value of the signature as a byte string, a placeholder length, or None.

  • signature_mechanism – The signature mechanism used by the external signing service.

  • prefer_pss – Switch to prefer PSS when producing RSA signatures, as opposed to RSA with PKCS#1 v1.5 padding.

  • embed_roots – Whether to embed relevant root certificates into the CMS payload.

async async_sign_raw(data: bytes, digest_algorithm: str, dry_run=False) → bytes

Return a fixed signature value.

class pyhanko.sign.PdfSignatureMetadata(field_name: str | None = None, md_algorithm: str | None = None, location: str | None = None, reason: str | None = None, contact_info: str | None = None, name: str | None = None, app_build_props: BuildProps | None = None, prop_auth_time: int | None = None, prop_auth_type: SigAuthType | None = None, certify: bool = False, subfilter: SigSeedSubFilter | None = None, embed_validation_info: bool = False, use_pades_lta: bool = False, timestamp_field_name: str | None = None, validation_context: ValidationContext | None = None, docmdp_permissions: MDPPerm = MDPPerm.FILL_FORMS, signer_key_usage: Set[str] = <factory>, cades_signed_attr_spec: CAdESSignedAttrSpec | None = None, dss_settings: 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: ValidationContext | None = None)

Bases: object

Specification for a PDF signature.

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

Location of signing.

reason: str | None = None

Reason for signing (textual).

contact_info: str | None = None

Information provided by the signer to enable the receiver to contact the signer to verify the signature.

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

Properties of the application that created the signature.

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

prop_auth_time: int | None = None

Number of seconds since signer was last authenticated.

prop_auth_type: SigAuthType | None = None

Signature /Prop_AuthType to use.

This should be one of PIN or PASSWORD or FINGERPRINT If not specified, this property won’t be set on the signature dictionary.

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: SigSeedSubFilter | None = 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 = 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: ValidationContext | None = 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: CAdESSignedAttrSpec | None = None

Added 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)

Added in version 0.8.0.

DSS output settings. See DSSContentSettings.

tight_size_estimates: bool = False

Added 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: ValidationContext | None = None

Added in version 0.11.0.

Validation context for attribute certificates

class pyhanko.sign.PdfSigner(signature_meta: PdfSignatureMetadata, signer: Signer, *, timestamper: TimeStamper | None = None, stamp_style: BaseStampStyle | None = None, new_field_spec: SigFieldSpec | None = 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 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.

stamp_style: BaseStampStyle
signer_hash_algo: str | None
property default_md_for_signer: str | None

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]

Added 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)

Added 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.PdfTimeStamper(timestamper: TimeStamper, field_name: str | None = 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: TimeStamper | None = 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: TimeStamper | None = 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)

Added 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_context – pyhanko_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)

Added 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 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.Signer(*, prefer_pss: bool = False, embed_roots: bool = True, signature_mechanism: SignedDigestAlgorithm | None = None, signing_cert: Certificate | None = None, cert_registry: CertificateStore | None = None, attribute_certs: Iterable[AttributeCertificateV2] = ())

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 PKCS#11 device.

Parameters:

  • prefer_pss – When signing using an RSA key, prefer PSS padding to legacy PKCS#1 v1.5 padding. Default is False. This option has no effect on non-RSA signatures.

  • embed_roots –

    Added in version 0.9.0.

    Option that controls whether or not additional self-signed certificates should be embedded into the CMS payload. The default is True.

    Note

    The signer’s certificate is always embedded, even if it is self-signed.

    Note

    Trust roots are configured by the validator, so embedding them doesn’t affect the semantics of a typical validation process. Therefore, they can be safely omitted in most cases. Nonetheless, embedding the roots can be useful for documentation purposes. In addition, some validators are poorly implemented, and will refuse to build paths if the roots are not present in the file.

    Warning

    To be precise, if this flag is False, a certificate will be dropped if (a) it is not the signer’s, (b) it is self-issued and (c) its subject and authority key identifiers match (or either is missing). In other words, we never validate the actual self-signature. This heuristic is sufficiently accurate for most applications.

  • signature_mechanism – The (cryptographic) signature mechanism to use for all signing operations. If unset, the default behaviour is to try to impute a reasonable one given the preferred digest algorithm and public key.

  • signing_cert – See signing_cert.

  • attribute_certs – See attribute_certs.

  • cert_registry – Initial value for cert_registry. If unset, an empty certificate store will be initialised.

signed_attr_prov_spec: SignedAttributeProviderSpec | None
unsigned_attr_prov_spec: UnsignedAttributeProviderSpec | None
property signature_mechanism: SignedDigestAlgorithm | None

Changed in version 0.18.0: Turned into a property instead of a class attribute.

The (cryptographic) signature mechanism to use for all signing operations.

property signing_cert: Certificate | None

Changed in version 0.14.0: Made optional (see note)

Changed in version 0.18.0: Turned into a property instead of a class attribute.

The certificate that will be used to create the signature.

Note

This is an optional field only to a limited extent. Subclasses may require it to be present, and not setting it at the beginning of the signing process implies that certain high-level convenience features will no longer work or be limited in function (e.g., automatic hash selection, appearance generation, revocation information collection, …).

However, making signing_cert optional enables certain signing workflows where the certificate of the signer is not known until the signature has actually been produced. This is most relevant in certain types of remote signing scenarios.

property cert_registry: CertificateStore

Changed in version 0.18.0: Turned into a property instead of a class attribute.

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

property attribute_certs: Iterable[AttributeCertificateV2]

Changed in version 0.18.0: Turned into a property instead of a class attribute.

Attribute certificates to include with the signature.

Note

Only v2 attribute certificates are supported.

get_signature_mechanism_for_digest(digest_algorithm: str | None) → SignedDigestAlgorithm

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.

Returns:

A SignedDigestAlgorithm object.

property subject_name: str | None
Returns:

The subject’s common name as a string, extracted from signing_cert, or None if no signer’s certificate is available

static format_revinfo(ocsp_responses: list | None = None, crls: list | None = 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.

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.

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

async unsigned_attrs(digest_algorithm: str, signature: bytes, signed_attrs: CMSAttributes, timestamper=None, dry_run=False) → CMSAttributes | None

Changed in version 0.9.0: Made asynchronous _(breaking change)_

Changed in version 0.14.0: Added signed_attrs parameter _(breaking change)_

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.

  • signed_attrs – Signed attributes of the signature.

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

async signed_attrs(data_digest: bytes, digest_algorithm: str, attr_settings: PdfCMSSignedAttributes | None = None, content_type='data', use_pades=False, timestamper=None, dry_run=False, is_pdf_sig=True)

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.

Changed in version 0.9.0: Made asynchronous, grouped some parameters under attr_settings _(breaking change)_

Format the signed attributes for a CMS signature.

Parameters:

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

  • digest_algorithm –

    Added in version 0.4.0.

    Name of the digest algorithm used to compute the digest.

  • use_pades – Respect PAdES requirements.

  • dry_run –

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

  • attr_settings – PdfCMSSignedAttributes object describing the attributes to be added.

  • timestamper –

    Added in version 0.5.0.

    Timestamper to use when creating timestamp tokens.

  • content_type –

    CMS content type of the encapsulated data. Default is data.

    Danger

    This parameter is internal API, and non-default values must not be used to produce PDF signatures.

  • is_pdf_sig –

    Whether the signature being generated is for use in a PDF document.

    Danger

    This parameter is internal API.

Returns:

An asn1crypto.cms.CMSAttributes object.

async async_sign(data_digest: bytes, digest_algorithm: str, dry_run=False, use_pades=False, timestamper=None, signed_attr_settings: PdfCMSSignedAttributes | None = None, is_pdf_sig=True, encap_content_info=None) → ContentInfo

Added in version 0.9.0.

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.

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

  • signed_attr_settings – PdfCMSSignedAttributes object describing the attributes to be added.

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

  • is_pdf_sig –

    Whether the signature being generated is for use in a PDF document.

    Danger

    This parameter is internal API.

  • encap_content_info –

    Data to encapsulate in the CMS object.

    Danger

    This parameter is internal API, and must not be used to produce PDF signatures.

Returns:

An ContentInfo object.

async async_sign_prescribed_attributes(digest_algorithm: str, signed_attrs: CMSAttributes, cms_version='v1', dry_run=False, timestamper=None, encap_content_info=None) → ContentInfo

Added in version 0.9.0.

Start the CMS signing process with the prescribed set of signed attributes.

Parameters:

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

  • signed_attrs – CMS attributes to sign.

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

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

  • cms_version – CMS version to use.

  • encap_content_info –

    Data to encapsulate in the CMS object.

    Danger

    This parameter is internal API, and must not be used to produce PDF signatures.

Returns:

An ContentInfo object.

async async_sign_general_data(input_data: IO | bytes | ContentInfo | EncapsulatedContentInfo, digest_algorithm: str, detached=True, use_cades=False, timestamper=None, chunk_size=4096, signed_attr_settings: PdfCMSSignedAttributes | None = None, max_read=None) → ContentInfo

Added in version 0.9.0.

Produce a CMS signature for an arbitrary data stream (not necessarily PDF data).

Parameters:

  • input_data –

    The input data to sign. This can be either a bytes object a file-type object, a cms.ContentInfo object or a cms.EncapsulatedContentInfo object.

    Warning

    asn1crypto mandates cms.ContentInfo for CMS v1 signatures. In practical terms, this means that you need to use cms.ContentInfo if the content type is data, and cms.EncapsulatedContentInfo otherwise.

    Warning

    We currently only support CMS v1, v3 and v4 signatures. This is only a concern if you need certificates or CRLs of type ‘other’, in which case you can change the version yourself (this will not invalidate any signatures). You’ll also need to do this if you need support for version 1 attribute certificates, or if you want to sign with subjectKeyIdentifier in the sid field.

  • digest_algorithm – The name of the digest algorithm to use.

  • detached – If True, create a CMS detached signature (i.e. an object where the encapsulated content is not embedded in the signature object itself). This is the default. If False, the content to be signed will be embedded as encapsulated content.

  • signed_attr_settings – PdfCMSSignedAttributes object describing the attributes to be added.

  • use_cades – Construct a CAdES-style CMS object.

  • timestamper –

    PdfTimeStamper to use to create a signature timestamp

    Note

    If you want to create a content timestamp (as opposed to a signature timestamp), see CAdESSignedAttrSpec.

  • chunk_size – Chunk size to use when consuming input data.

  • max_read – Maximal number of bytes to read from the input stream.

Returns:

A CMS ContentInfo object of type signedData.

sign(data_digest: bytes, digest_algorithm: str, timestamp: datetime | None = None, dry_run=False, revocation_info=None, use_pades=False, timestamper=None, cades_signed_attr_meta: CAdESSignedAttrSpec | None = None, encap_content_info=None) → ContentInfo

Deprecated since version 0.9.0: Use async_sign() instead. The implementation of this method will invoke async_sign() using asyncio.run().

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 –

    Signing time to embed into the signed attributes (will be ignored if use_pades is True).

    Note

    This timestamp value is to be interpreted as an unfounded assertion by the signer, which may or may not be good enough for your purposes.

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

    Added in version 0.5.0.

    Specification for CAdES-specific signed attributes.

  • encap_content_info –

    Data to encapsulate in the CMS object.

    Danger

    This parameter is internal API, and must not be used to produce PDF signatures.

Returns:

An ContentInfo object.

sign_prescribed_attributes(digest_algorithm: str, signed_attrs: CMSAttributes, cms_version='v1', dry_run=False, timestamper=None, encap_content_info=None) → ContentInfo

Deprecated since version 0.9.0: Use async_sign_prescribed_attributes() instead. The implementation of this method will invoke async_sign_prescribed_attributes() using asyncio.run().

Start the CMS signing process with the prescribed set of signed attributes.

Parameters:

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

  • signed_attrs – CMS attributes to sign.

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

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

  • cms_version – CMS version to use.

  • encap_content_info –

    Data to encapsulate in the CMS object.

    Danger

    This parameter is internal API, and must not be used to produce PDF signatures.

Returns:

An ContentInfo object.

sign_general_data(input_data: IO | bytes | ContentInfo | EncapsulatedContentInfo, digest_algorithm: str, detached=True, timestamp: datetime | None = None, use_cades=False, timestamper=None, cades_signed_attr_meta: CAdESSignedAttrSpec | None = None, chunk_size=4096, max_read=None) → ContentInfo

Added in version 0.7.0.

Deprecated since version 0.9.0: Use async_sign_general_data() instead. The implementation of this method will invoke async_sign_general_data() using asyncio.run().

Produce a CMS signature for an arbitrary data stream (not necessarily PDF data).

Parameters:

  • input_data –

    The input data to sign. This can be either a bytes object a file-type object, a cms.ContentInfo object or a cms.EncapsulatedContentInfo object.

    Warning

    asn1crypto mandates cms.ContentInfo for CMS v1 signatures. In practical terms, this means that you need to use cms.ContentInfo if the content type is data, and cms.EncapsulatedContentInfo otherwise.

    Warning

    We currently only support CMS v1, v3 and v4 signatures. This is only a concern if you need certificates or CRLs of type ‘other’, in which case you can change the version yourself (this will not invalidate any signatures). You’ll also need to do this if you need support for version 1 attribute certificates, or if you want to sign with subjectKeyIdentifier in the sid field.

  • digest_algorithm – The name of the digest algorithm to use.

  • detached – If True, create a CMS detached signature (i.e. an object where the encapsulated content is not embedded in the signature object itself). This is the default. If False, the content to be signed will be embedded as encapsulated content.

  • timestamp –

    Signing time to embed into the signed attributes (will be ignored if use_cades is True).

    Note

    This timestamp value is to be interpreted as an unfounded assertion by the signer, which may or may not be good enough for your purposes.

  • use_cades – Construct a CAdES-style CMS object.

  • timestamper –

    PdfTimeStamper to use to create a signature timestamp

    Note

    If you want to create a content timestamp (as opposed to a signature timestamp), see CAdESSignedAttrSpec.

  • cades_signed_attr_meta – Specification for CAdES-specific signed attributes.

  • chunk_size – Chunk size to use when consuming input data.

  • max_read – Maximal number of bytes to read from the input stream.

Returns:

A CMS ContentInfo object of type signedData.

class pyhanko.sign.SimpleSigner(signing_cert: Certificate, signing_key: PrivateKeyInfo, cert_registry: CertificateStore, signature_mechanism: SignedDigestAlgorithm | None = None, prefer_pss: bool = False, embed_roots: bool = True, attribute_certs: Iterable[AttributeCertificateV2] | None = None)

Bases: Signer

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

signing_key: PrivateKeyInfo

Private key associated with the certificate in signing_cert.

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

sign_raw(data: bytes, digest_algorithm: str) → bytes

Synchronous raw signature implementation.

Parameters:

  • data – Data to be signed.

  • digest_algorithm – Digest algorithm to use.

Returns:

Raw signature encoded according to the conventions of the signing algorithm used.

classmethod load_pkcs12_data(pkcs12_bytes: bytes, other_certs: Iterable[Certificate], passphrase: bytes | None = None, signature_mechanism: SignedDigestAlgorithm | None = None)

Load certificates and key material from an in-memory PCKS#12 archive

Parameters:

  • pkcs12_bytes – PKCS#12 data.

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

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

  • signature_mechanism – Override the signature mechanism to use.

Returns:

A SimpleSigner object initialised with key material loaded.

Raises:

ValueError – if the PKCS#12 data fails to be loaded.

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

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

Note

Generally, the API of load_pkcs12_data() is less clunky. This method was originally

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.

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

  • 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, or None if the operation failed.

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.

async pyhanko.sign.async_sign_pdf(pdf_out: BasePdfFileWriter, signature_meta: PdfSignatureMetadata, signer: Signer, timestamper: TimeStamper | None = None, new_field_spec: SigFieldSpec | None = None, existing_fields_only=False, bytes_reserved=None, in_place=False, output=None)

Thin convenience wrapper around async_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.

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

  • 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.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.sign_pdf(pdf_out: BasePdfFileWriter, signature_meta: PdfSignatureMetadata, signer: Signer, timestamper: TimeStamper | None = None, new_field_spec: SigFieldSpec | None = None, existing_fields_only=False, bytes_reserved=None, in_place=False, output=None)

Thin convenience wrapper around 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.

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

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