pyhanko.sign.fields module¶

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

class pyhanko.sign.fields.SigFieldSpec(sig_field_name: str, on_page: int = 0, box: (<class 'int'>, <class 'int'>, <class 'int'>, <class 'int'>) = None, seed_value_dict: pyhanko.sign.fields.SigSeedValueSpec = None, field_mdp_spec: pyhanko.sign.fields.FieldMDPSpec = None, doc_mdp_update_value: pyhanko.sign.fields.MDPPerm = None)¶

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

Note

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

box: (<class ‘int’>, <class ‘int’>, <class ‘int’>, <class ‘int’>) = None¶: Bounding box of the signature field, if applicable.

seed_value_dict: pyhanko.sign.fields.SigSeedValueSpec = None¶: Specification for the seed value dictionary, if applicable.

field_mdp_spec: pyhanko.sign.fields.FieldMDPSpec = None¶: Specification for the field lock dictionary, if applicable.

doc_mdp_update_value: pyhanko.sign.fields.MDPPerm = 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.

format_lock_dictionary() → Optional[pyhanko.pdf_utils.generic.DictionaryObject]¶

class pyhanko.sign.fields.SigSeedValFlags(value)¶

Bases: enum.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

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

FILTER = 1¶

SUBFILTER = 2¶

V = 4¶

REASONS = 8¶

LEGAL_ATTESTATION = 16¶

ADD_REV_INFO = 32¶

DIGEST_METHOD = 64¶

LOCK_DOCUMENT = 128¶

APPEARANCE_FILTER = 256¶

UNSUPPORTED = 400¶: Flags for which the corresponding constraint is unsupported.

class pyhanko.sign.fields.SigCertConstraints(flags: pyhanko.sign.fields.SigCertConstraintFlags = <SigCertConstraintFlags.0: 0>, subjects: Optional[List[asn1crypto.x509.Certificate]] = None, subject_dn: Optional[asn1crypto.x509.Name] = None, issuers: Optional[List[asn1crypto.x509.Certificate]] = None, info_url: Optional[str] = None, url_type: pyhanko.pdf_utils.generic.NameObject = '/Browser')¶

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: pyhanko.sign.fields.SigCertConstraintFlags = 0¶: Enforcement flags. By default, all entries are optional.

subjects: List[asn1crypto.x509.Certificate] = None¶: Explicit list of certificates that can be used to sign a signature field.

subject_dn: asn1crypto.x509.Name = None¶: Certificate subject names that can be used to sign a signature field. Subject DN entries that are not mentioned are unconstrained.

issuers: List[asn1crypto.x509.Certificate] = 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¶: Informational URL that should be opened when an appropriate signature cannot be found.

url_type: pyhanko.pdf_utils.generic.NameObject = '/Browser'¶: Handler that should be used to open info_url. /Browser is the only implementation-independent value.

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: asn1crypto.x509.Certificate, validation_path: Optional[certvalidator.path.ValidationPath])¶

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.SigSeedValueSpec(flags: pyhanko.sign.fields.SigSeedValFlags = <SigSeedValFlags.0: 0>, reasons: Optional[List[str]] = None, timestamp_server_url: Optional[str] = None, timestamp_required: bool = False, cert: Optional[pyhanko.sign.fields.SigCertConstraints] = None, subfilters: Optional[List[pyhanko.sign.fields.SigSeedSubFilter]] = None, digest_methods: Optional[List[str]] = None, add_rev_info: Optional[bool] = None)¶

Bases: object

Python representation of a PDF seed value dictionary.

flags: pyhanko.sign.fields.SigSeedValFlags = 0¶: Enforcement flags. By default, all entries are optional.

reasons: List[str] = None¶: Acceptable reasons for signing.

timestamp_server_url: str = 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: pyhanko.sign.fields.SigCertConstraints = None¶: Constraints on the signer’s certificate.

subfilters: List[pyhanko.sign.fields.SigSeedSubFilter] = None¶: Acceptable /SubFilter values.

digest_methods: List[str] = None¶: Acceptable digest methods.

add_rev_info: bool = 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.

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.SigCertConstraintFlags(value)¶

Bases: enum.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¶

ISSUER = 2¶

OID = 4¶

SUBJECT_DN = 8¶

RESERVED = 16¶

KEY_USAGE = 32¶

URL = 64¶

class pyhanko.sign.fields.SigSeedSubFilter(value)¶

Bases: enum.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.MDPPerm(value)¶

Bases: pyhanko.pdf_utils.misc.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.FieldMDPAction(value)¶

Bases: enum.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: pyhanko.sign.fields.FieldMDPAction, fields: Optional[List[str]] = None)¶

Bases: object

/FieldMDP policy description.

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

action: pyhanko.sign.fields.FieldMDPAction¶: Indicates the scope of the policy.

fields: Optional[List[str]] = None¶: Indicates the fields subject to the policy, unless action is FieldMDPAction.ALL.

as_pdf_object() → pyhanko.pdf_utils.generic.DictionaryObject ¶

Render this /FieldMDP policy description as a PDF dictionary.

Returns: A DictionaryObject.

as_transform_params() → pyhanko.pdf_utils.generic.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() → pyhanko.pdf_utils.generic.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) → pyhanko.sign.fields.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.SignatureFormField(field_name, include_on_page, *, writer, sig_object_ref=None, box=None, appearances: Optional[pyhanko.stamp.AnnotAppearances] = None)¶: Bases: pyhanko.pdf_utils.generic.DictionaryObject

pyhanko.sign.fields.enumerate_sig_fields(handler: pyhanko.pdf_utils.rw_common.PdfHandler, filled_status=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.

Returns

A generator producing signature fields.

pyhanko.sign.fields.append_signature_field(pdf_out: pyhanko.pdf_utils.incremental_writer.IncrementalPdfFileWriter, sig_field_spec: pyhanko.sign.fields.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.