pyhanko.sign.signers module¶
-
class
pyhanko.sign.signers.
PdfSignatureMetadata
(field_name: Optional[str] = None, md_algorithm: Optional[str] = None, location: Optional[str] = None, reason: Optional[str] = None, name: Optional[str] = None, certify: bool = False, subfilter: Optional[pyhanko.sign.fields.SigSeedSubFilter] = None, embed_validation_info: bool = False, use_pades_lta: bool = False, timestamp_field_name: Optional[str] = None, validation_context: Optional[certvalidator.context.ValidationContext] = None, docmdp_permissions: pyhanko.sign.fields.MDPPerm = <MDPPerm.FILL_FORMS: 2>, signer_key_usage: Set[str] = <factory>, cades_signed_attr_spec: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None)¶ Bases:
object
Specification for a PDF signature.
-
field_name
: str = None¶ The name of the form field to contain the signature. If there is only one available signature field, the name may be inferred.
-
md_algorithm
: str = None¶ The name of the digest algorithm to use. It should be supported by
hashlib
.If
None
, this will ordinarily default to the value ofDEFAULT_MD
, unless a seed value dictionary and/or a prior certification signature happen to be available.
-
location
: str = None¶ Location of signing.
-
reason
: str = None¶ Reason for signing (textual).
-
name
: str = None¶ Name of the signer. This value is usually not necessary to set, since it should appear on the signer’s certificate, but there are cases where it might be useful to specify it here (e.g. in situations where signing is delegated to a trusted third party).
-
certify
: bool = False¶ Sign with an author (certification) signature, as opposed to an approval signature. A document can contain at most one such signature, and it must be the first one.
-
subfilter
: pyhanko.sign.fields.SigSeedSubFilter = None¶ Signature subfilter to use.
This should be one of
ADOBE_PKCS7_DETACHED
orPADES
. If not specified, the value may be inferred from the signature field’s seed value dictionary. Failing that,ADOBE_PKCS7_DETACHED
is used as the default value.
-
embed_validation_info
: bool = False¶ Flag indicating whether validation info (OCSP responses and/or CRLs) should be embedded or not. This is necessary to be able to validate signatures long after they have been made. This flag requires
validation_context
to be set.The precise manner in which the validation info is embedded depends on the (effective) value of
subfilter
:With
ADOBE_PKCS7_DETACHED
, the validation information will be embedded inside the CMS object containing the signature.With
PADES
, the validation information will be embedded into the document security store (DSS).
-
use_pades_lta
: bool = False¶ If
True
, the signer will append an additional document timestamp after writing the signature’s validation information to the document security store (DSS). This flag is only meaningful ifsubfilter
isPADES
.The PAdES B-LTA profile solves the long-term validation problem by adding a timestamp chain to the document after the regular signatures, which is updated with new timestamps at regular intervals. This provides an audit trail that ensures the long-term integrity of the validation information in the DSS, since OCSP responses and CRLs also have a finite lifetime.
-
timestamp_field_name
: str = None¶ Name of the timestamp field created when
use_pades_lta
isTrue
. If not specified, a unique name will be generated usinguuid
.
-
validation_context
: certvalidator.context.ValidationContext = None¶ The validation context to use when validating signatures. If provided, the signer’s certificate and any timestamp certificates will be validated before signing.
This parameter is mandatory when
embed_validation_info
isTrue
.
-
docmdp_permissions
: pyhanko.sign.fields.MDPPerm = 2¶ Indicates the document modification policy that will be in force after this signature is created.
Warning
For non-certification signatures, this is only explicitly allowed since PDF 2.0 (ISO 32000-2), so older software may not respect this setting on approval signatures.
-
signer_key_usage
: Set[str]¶ Key usage extensions required for the signer’s certificate. Defaults to
non_repudiation
only, but sometimesdigital_signature
or a combination of both may be more appropriate. Seex509.KeyUsage
for a complete list.Only relevant if a validation context is also provided.
-
cades_signed_attr_spec
: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None¶ New in version 0.5.0.
Specification for CAdES-specific attributes.
-
-
class
pyhanko.sign.signers.
Signer
(prefer_pss=False)¶ Bases:
object
Abstract signer object that is agnostic as to where the cryptographic operations actually happen.
As of now, pyHanko provides two implementations:
SimpleSigner
implements the easy case where all the key material can be loaded into memory.PKCS11Signer
implements a signer that is capable of interfacing with a PKCS11 device (see alsoBEIDSigner
).
-
signing_cert
: asn1crypto.x509.Certificate¶ The certificate that will be used to create the signature.
-
cert_registry
: pyhanko.sign.general.CertificateStore¶ Collection of certificates associated with this signer. Note that this is simply a bookkeeping tool; in particular it doesn’t care about trust.
-
signature_mechanism
: asn1crypto.algos.SignedDigestAlgorithm = None¶ The (cryptographic) signature mechanism to use.
-
get_signature_mechanism
(digest_algorithm)¶ Get the signature mechanism for this signer to use. If
signature_mechanism
is set, it will be used. Otherwise, this method will attempt to put together a default based on mechanism used in the signer’s certificate.- Parameters
digest_algorithm – Digest algorithm to use as part of the signature mechanism. Only used if a signature mechanism object has to be put together on-the-fly, and the digest algorithm could not be inferred from the signer’s certificate.
- Returns
A
SignedDigestAlgorithm
object.
-
sign_raw
(data: bytes, digest_algorithm: str, dry_run=False) → bytes¶ Compute the raw cryptographic signature of the data provided, hashed using the digest algorithm provided.
- Parameters
data – Data to sign.
digest_algorithm –
Digest algorithm to use.
Warning
If
signature_mechanism
also specifies a digest, they should match.dry_run – Do not actually create a signature, but merely output placeholder bytes that would suffice to contain an actual signature.
- Returns
Signature bytes.
-
property
subject_name
¶ - Returns
The subject’s common name as a string, extracted from
signing_cert
.
-
static
format_revinfo
(ocsp_responses: Optional[list] = None, crls: Optional[list] = None)¶ Format Adobe-style revocation information for inclusion into a CMS object.
- Parameters
ocsp_responses – A list of OCSP responses to include.
crls – A list of CRLs to include.
- Returns
A CMS attribute containing the relevant data.
-
signed_attrs
(data_digest: bytes, digest_algorithm: str, timestamp: Optional[datetime.datetime] = None, revocation_info=None, use_pades=False, cades_meta: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None, timestamper=None, dry_run=False)¶ Changed in version 0.4.0: Added positional
digest_algorithm
parameter _(breaking change)_.Changed in version 0.5.0: Added
dry_run
,timestamper
andcades_meta
parameters.Format the signed attributes for a CMS signature.
- Parameters
data_digest – Raw digest of the data to be signed.
digest_algorithm –
New in version 0.4.0.
Name of the digest algorithm used to compute the digest.
timestamp – Current timestamp (ignored when
use_pades
isTrue
).revocation_info – Revocation information to embed; this should be the output of a call to
Signer.format_revinfo()
orNone
(ignored whenuse_pades
isTrue
).use_pades – Respect PAdES requirements.
dry_run –
New in version 0.5.0.
Flag indicating “dry run” mode. If
True
, only the approximate size of the output matters, so cryptographic operations can be replaced by placeholders.timestamper –
New in version 0.5.0.
Timestamper to use when creating timestamp tokens.
cades_meta –
New in version 0.5.0.
Specification for CAdES-specific attributes.
- Returns
An
asn1crypto.cms.CMSAttributes
object.
-
unsigned_attrs
(digest_algorithm, signature: bytes, timestamper=None, dry_run=False) → Optional[asn1crypto.cms.CMSAttributes]¶ Compute the unsigned attributes to embed into the CMS object. This function is called after signing the hash of the signed attributes (see
signed_attrs()
).By default, this method only handles timestamp requests, but other functionality may be added by subclasses
If this method returns
None
, no unsigned attributes will be embedded.- Parameters
digest_algorithm – Digest algorithm used to hash the signed attributes.
signature – Signature of the signed attribute hash.
timestamper – Timestamp supplier to use.
dry_run – Flag indicating “dry run” mode. If
True
, only the approximate size of the output matters, so cryptographic operations can be replaced by placeholders.
- Returns
The unsigned attributes to add, or
None
.
-
signer_info
(digest_algorithm: str, signed_attrs, signature)¶ Format the
SignerInfo
entry for a CMS signature.- Parameters
digest_algorithm – Digest algorithm to use.
signed_attrs – Signed attributes (see
signed_attrs()
).signature – The raw signature to embed (see
sign_raw()
).
- Returns
An
asn1crypto.cms.SignerInfo
object.
-
sign
(data_digest: bytes, digest_algorithm: str, timestamp: Optional[datetime.datetime] = None, dry_run=False, revocation_info=None, use_pades=False, timestamper=None, cades_signed_attr_meta: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None) → asn1crypto.cms.ContentInfo¶ Produce a detached CMS signature from a raw data digest.
- Parameters
data_digest – Digest of the actual content being signed.
digest_algorithm – Digest algorithm to use. This should be the same digest method as the one used to hash the (external) content.
timestamp – Current timestamp (ignored when
use_pades
isTrue
).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 whenuse_pades
isTrue
).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’sdummy_response()
method will be called to obtain a placeholder token. Note that with a standardHTTPTimeStamper
, this might still hit the timestamping server (in order to produce a realistic size estimate), but the dummy response will be cached.cades_signed_attr_meta –
New in version 0.5.0.
Specification for CAdES-specific attributes.
- Returns
An
ContentInfo
object.
-
class
pyhanko.sign.signers.
SimpleSigner
(signing_cert: asn1crypto.x509.Certificate, signing_key: asn1crypto.keys.PrivateKeyInfo, cert_registry: pyhanko.sign.general.CertificateStore, signature_mechanism: Optional[asn1crypto.algos.SignedDigestAlgorithm] = None, prefer_pss=False)¶ Bases:
pyhanko.sign.signers.Signer
Simple signer implementation where the key material is available in local memory.
-
signing_key
: asn1crypto.keys.PrivateKeyInfo¶ Private key associated with the certificate in
signing_cert
.
-
sign_raw
(data: bytes, digest_algorithm: str, dry_run=False) → bytes¶ Compute the raw cryptographic signature of the data provided, hashed using the digest algorithm provided.
- Parameters
data – Data to sign.
digest_algorithm –
Digest algorithm to use.
Warning
If
signature_mechanism
also specifies a digest, they should match.dry_run – Do not actually create a signature, but merely output placeholder bytes that would suffice to contain an actual signature.
- Returns
Signature bytes.
-
classmethod
load_pkcs12
(pfx_file, ca_chain_files=None, passphrase=None, signature_mechanism=None, prefer_pss=False)¶ Load certificates and key material from a PCKS#12 archive (usually
.pfx
or.p12
files).- Parameters
pfx_file – Path to the PKCS#12 archive.
ca_chain_files – Path to (PEM/DER) files containing other relevant certificates not included in the PKCS#12 file.
passphrase – Passphrase to decrypt the PKCS#12 archive, if required.
signature_mechanism – Override the signature mechanism to use.
prefer_pss – Prefer PSS signature mechanism over RSA PKCS#1 v1.5 if there’s a choice.
- Returns
A
SimpleSigner
object initialised with key material loaded from the PKCS#12 file provided.
-
classmethod
load
(key_file, cert_file, ca_chain_files=None, key_passphrase=None, other_certs=None, signature_mechanism=None, prefer_pss=False)¶ Load certificates and key material from PEM/DER files.
- Parameters
key_file – File containing the signer’s private key.
cert_file – File containing the signer’s certificate.
ca_chain_files – File containing other relevant certificates.
key_passphrase – Passphrase to decrypt the private key (if required).
other_certs – Other relevant certificates, specified as a list of
asn1crypto.x509.Certificate
objects.signature_mechanism – Override the signature mechanism to use.
prefer_pss – Prefer PSS signature mechanism over RSA PKCS#1 v1.5 if there’s a choice.
- Returns
A
SimpleSigner
object initialised with key material loaded from the files provided.
-
-
class
pyhanko.sign.signers.
PdfTimeStamper
(timestamper: pyhanko.sign.timestamps.TimeStamper)¶ Bases:
object
Class to encapsulate the process of appending document timestamps to PDF files.
-
generate_timestamp_field_name
() → str¶ Generate a unique name for a document timestamp field using
uuid
.- Returns
The field name, as a (Python) string.
-
timestamp_pdf
(pdf_out: pyhanko.pdf_utils.incremental_writer.IncrementalPdfFileWriter, md_algorithm, validation_context, bytes_reserved=None, validation_paths=None, timestamper: Optional[pyhanko.sign.timestamps.TimeStamper] = None, *, in_place=False, output=None, chunk_size=4096)¶ Timestamp the contents of
pdf_out
. Note thatpdf_out
should not be written to after this operation.- Parameters
pdf_out – An
IncrementalPdfFileWriter
.md_algorithm – The hash algorithm to use when computing message digests.
validation_context – The
certvalidator.ValidationContext
against which the TSA response should be validated. This validation context will also be used to update the DSS.bytes_reserved – Bytes to reserve for the CMS object in the PDF file. If not specified, make an estimate based on a dummy signature.
validation_paths – If the validation path(s) for the TSA’s certificate are already known, you can pass them using this parameter to avoid having to run the validation logic again.
timestamper – Override the default
TimeStamper
associated with thisPdfTimeStamper
.output – Write the output to the specified output stream. If
None
, write to a newBytesIO
object. Default isNone
.in_place – Sign the original input stream in-place. This parameter overrides
output
.chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support
memoryview
. Default is 4096.
- Returns
The output stream containing the signed output.
-
update_archival_timestamp_chain
(reader: pyhanko.pdf_utils.reader.PdfFileReader, validation_context, in_place=True, output=None, chunk_size=4096, default_md_algorithm='sha256')¶ Validate the last timestamp in the timestamp chain on a PDF file, and write an updated version to an output stream.
- Parameters
reader – A
PdfReader
encapsulating the input file.validation_context –
certvalidator.ValidationContext
object to validate the last timestamp.output – Write the output to the specified output stream. If
None
, write to a newBytesIO
object. Default isNone
.in_place – Sign the original input stream in-place. This parameter overrides
output
.chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support
memoryview
. Default is 4096.default_md_algorithm – Message digest to use if there are no preceding timestamps in the file.
- Returns
The output stream containing the signed output.
-
-
class
pyhanko.sign.signers.
PdfSigner
(signature_meta: pyhanko.sign.signers.PdfSignatureMetadata, signer: pyhanko.sign.signers.Signer, *, timestamper: Optional[pyhanko.sign.timestamps.TimeStamper] = None, stamp_style: Optional[pyhanko.stamp.TextStampStyle] = None, new_field_spec: Optional[pyhanko.sign.fields.SigFieldSpec] = None)¶ Bases:
pyhanko.sign.signers.PdfTimeStamper
Class to handle PDF signatures in general.
- Parameters
signature_meta – The specification of the signature to add.
signer –
Signer
object to use to produce the signature object.timestamper –
TimeStamper
object to use to produce any time stamp tokens that might be required.stamp_style – Stamp style specification to determine the visible style of the signature, typically an object of type
TextStampStyle
orQRStampStyle
. Defaults toDEFAULT_SIGNING_STAMP_STYLE
.new_field_spec – If a new field is to be created, this parameter allows the caller to specify the field’s properties in the form of a
SigFieldSpec
. This parameter is only meaningful ifexisting_fields_only
isFalse
.
-
generate_timestamp_field_name
() → str¶ Look up the timestamp field name in the
PdfSignatureMetadata
object associated with thisPdfSigner
. If not specified, generate a unique field name usinguuid
.- Returns
The field name, as a (Python) string.
-
sign_pdf
(pdf_out: pyhanko.pdf_utils.writer.BasePdfFileWriter, existing_fields_only=False, bytes_reserved=None, *, appearance_text_params=None, in_place=False, output=None, chunk_size=4096)¶ Sign a PDF file using the provided output writer.
- Parameters
pdf_out – A PDF file writer (usually an
IncrementalPdfFileWriter
) containing the data to sign.existing_fields_only – If
True
, never create a new empty signature field to contain the signature. IfFalse
, a new field may be created if no field matchingfield_name
exists.bytes_reserved – Bytes to reserve for the CMS object in the PDF file. If not specified, make an estimate based on a dummy signature.
appearance_text_params – Dictionary with text parameters that will be passed to the signature appearance constructor (if applicable).
output – Write the output to the specified output stream. If
None
, write to a newBytesIO
object. Default isNone
.in_place – Sign the original input stream in-place. This parameter overrides
output
.chunk_size – Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support
memoryview
. Default is 4096.
- Returns
The output stream containing the signed data.
-
class
pyhanko.sign.signers.
PdfCMSEmbedder
(new_field_spec: Optional[pyhanko.sign.fields.SigFieldSpec] = None)¶ Bases:
object
Low-level class that handles embedding CMS objects into PDF signature fields.
It also takes care of appearance generation and DocMDP configuration, but does not otherwise offer any of the conveniences of
PdfSigner
.- Parameters
new_field_spec –
SigFieldSpec
to use when creating new fields on-the-fly.
-
write_cms
(field_name: str, writer: pyhanko.pdf_utils.writer.BasePdfFileWriter, existing_fields_only=False)¶ This method returns a generator coroutine that controls the process of embedding CMS data into a PDF signature field. Can be used for both timestamps and regular signatures.
Danger
This is a very low-level interface that performs virtually no error checking, and is intended to be used in situations where the construction of the CMS object to be embedded is not under the caller’s control (e.g. a remote signer that produces full-fledged CMS objects).
In almost every other case, you’re better of using
PdfSigner
instead, with a customSigner
implementation to handle the cryptographic operations if necessary.The coroutine follows the following specific protocol.
First, it retrieves or creates the signature field to embed the CMS object in, and yields a reference to said field.
The caller should then send in a
SigObjSetup
object, which is subsequently processed by the coroutine. For convenience, the coroutine will then yield a reference to the signature dictionary (as embedded in the PDF writer).Next, the caller should send a
SigIOSetup
object, describing how the resulting document should be hashed and written to the output. The coroutine will write the entire document with a placeholder region reserved for the signature, compute the document’s hash and yield it to the caller.From this point onwards, no objects may be changed or added to the
IncrementalPdfFileWriter
currently in use.Finally, the caller should pass in a CMS object to place inside the signature dictionary. The CMS object can be supplied as a raw
bytes
object, or anasn1crypto
-style object. The coroutine’s final yield is a tupleoutput, sig_contents
, whereoutput
is the output stream used, andsig_contents
is the value of the signature dictionary’s/Contents
entry, given as a hexadecimal string.
Caution
It is the caller’s own responsibility to ensure that enough room is available in the placeholder signature object to contain the final CMS object.
- Parameters
field_name – The name of the field to fill in. This should be a field of type
/Sig
.writer – An
IncrementalPdfFileWriter
containing the document to sign.existing_fields_only – If
True
, never create a new empty signature field to contain the signature. IfFalse
, a new field may be created if no field matchingfield_name
exists.
- Returns
A generator coroutine implementing the protocol described above.
-
class
pyhanko.sign.signers.
SigObjSetup
(sig_placeholder: pyhanko.sign.signers.PdfSignedData, mdp_setup: Optional[pyhanko.sign.signers.SigMDPSetup] = None, appearance_setup: Optional[pyhanko.sign.signers.SigAppearanceSetup] = None)¶ Bases:
object
Describes the signature dictionary to be embedded as the form field’s value.
-
sig_placeholder
: pyhanko.sign.signers.PdfSignedData¶ Bare-bones placeholder object, usually of type
SignatureObject
orDocumentTimestamp
.In particular, this determines the number of bytes to allocate for the CMS object.
-
mdp_setup
: Optional[pyhanko.sign.signers.SigMDPSetup] = None¶ Optional DocMDP settings, see
SigMDPSetup
.
-
appearance_setup
: Optional[pyhanko.sign.signers.SigAppearanceSetup] = None¶ Optional appearance settings, see
SigAppearanceSetup
.
-
-
class
pyhanko.sign.signers.
SigAppearanceSetup
(style: pyhanko.stamp.TextStampStyle, timestamp: datetime.datetime, name: str, text_params: Optional[dict] = None)¶ Bases:
object
Signature appearance configuration.
Part of the low-level
PdfCMSEmbedder
API, seeSigObjSetup
.-
style
: pyhanko.stamp.TextStampStyle¶ Stamp style to use to generate the appearance.
-
timestamp
: datetime.datetime¶ Timestamp to show in the signature appearance.
-
name
: str¶ Signer name to show in the signature appearance.
-
text_params
: dict = None¶ Additional text interpolation parameters to pass to the underlying stamp style.
-
-
class
pyhanko.sign.signers.
SigMDPSetup
(md_algorithm: str, certify: bool = False, field_lock: Union[pyhanko.sign.fields.FieldMDPSpec, NoneType] = None, docmdp_perms: Union[pyhanko.sign.fields.MDPPerm, NoneType] = None)¶ Bases:
object
-
md_algorithm
: str¶ Message digest algorithm to write into the signature reference dictionary, if one is written at all.
Warning
It is the caller’s responsibility to make sure that this value agrees with the value embedded into the CMS object, and with the algorithm used to hash the document. The low-level
PdfCMSEmbedder
API will simply take it at face value.
-
certify
: bool = False¶ Sign with an author (certification) signature, as opposed to an approval signature. A document can contain at most one such signature, and it must be the first one.
-
field_lock
: Optional[pyhanko.sign.fields.FieldMDPSpec] = None¶ Field lock information to write to the signature reference dictionary.
-
docmdp_perms
: Optional[pyhanko.sign.fields.MDPPerm] = None¶ DocMDP permissions to write to the signature reference dictionary.
-
-
class
pyhanko.sign.signers.
PdfByteRangeDigest
(data_key='/Contents', *, bytes_reserved=None)¶ Bases:
pyhanko.pdf_utils.generic.DictionaryObject
-
fill
(writer: pyhanko.pdf_utils.writer.BasePdfFileWriter, md_algorithm, in_place=False, output=None, chunk_size=4096)¶ Generator coroutine that handles the document hash computation and the actual filling of the placeholder data.
This is internal API; you should use use
PdfSigner
wherever possible. If you really need fine-grained control, usePdfCMSEmbedder
instead.
-
-
class
pyhanko.sign.signers.
PdfSignedData
(obj_type, subfilter: pyhanko.sign.fields.SigSeedSubFilter = <SigSeedSubFilter.ADOBE_PKCS7_DETACHED: '/adbe.pkcs7.detached'>, timestamp: Optional[datetime.datetime] = None, bytes_reserved=None)¶ Bases:
pyhanko.sign.signers.PdfByteRangeDigest
Generic class to model signature dictionaries in a PDF file. See also
SignatureObject
andDocumentTimestamp
.- Parameters
obj_type – The type of signature object.
subfilter – See
SigSeedSubFilter
.timestamp – The timestamp to embed into the
/M
entry.bytes_reserved –
The number of bytes to reserve for the signature. Defaults to 16 KiB.
Warning
Since the CMS object is written to the output file as a hexadecimal string, you should request twice the (estimated) number of bytes in the DER-encoded version of the CMS object.
-
class
pyhanko.sign.signers.
SignatureObject
(timestamp: Optional[datetime.datetime] = None, subfilter: pyhanko.sign.fields.SigSeedSubFilter = <SigSeedSubFilter.ADOBE_PKCS7_DETACHED: '/adbe.pkcs7.detached'>, name=None, location=None, reason=None, bytes_reserved=None)¶ Bases:
pyhanko.sign.signers.PdfSignedData
Class modelling a (placeholder for) a regular PDF signature.
- Parameters
timestamp – The (optional) timestamp to embed into the
/M
entry.subfilter – See
SigSeedSubFilter
.bytes_reserved –
The number of bytes to reserve for the signature. Defaults to 16 KiB.
Warning
Since the CMS object is written to the output file as a hexadecimal string, you should request twice the (estimated) number of bytes in the DER-encoded version of the CMS object.
name – Signer name. You probably want to leave this blank, viewers should default to the signer’s subject name.
location – Optional signing location.
reason – Optional signing reason. May be restricted by seed values.
-
class
pyhanko.sign.signers.
DocumentTimestamp
(bytes_reserved=None)¶ Bases:
pyhanko.sign.signers.PdfSignedData
Class modelling a (placeholder for) a regular PDF signature.
- Parameters
bytes_reserved –
The number of bytes to reserve for the signature. Defaults to 16 KiB.
Warning
Since the CMS object is written to the output file as a hexadecimal string, you should request twice the (estimated) number of bytes in the DER-encoded version of the CMS object.
-
class
pyhanko.sign.signers.
SigIOSetup
(md_algorithm: str, in_place: bool = False, chunk_size: int = 4096, output: Optional[io.BufferedIOBase] = None)¶ Bases:
object
I/O settings for writing signed PDF documents.
Objects of this type are used in the penultimate phase of the
PdfCMSEmbedder
protocol.-
md_algorithm
: str¶ Message digest algorithm to use to compute the document hash. It should be supported by
hashlib
.Warning
This is also the message digest algorithm that should appear in the corresponding
signerInfo
entry in the CMS object that ends up being embedded in the signature field.
-
in_place
: bool = False¶ Sign the input in-place. If
False
, write output to aBytesIO
object, oroutput
if the latter is notNone
.
-
chunk_size
: int = 4096¶ Size of the internal buffer (in bytes) used to feed data to the message digest function if the input stream does not support
memoryview
. Default is 4096.
-
output
: Optional[io.BufferedIOBase] = None¶ Write the output to the specified output stream. If
None
, write to a newBytesIO
object. Default isNone
.
-
-
pyhanko.sign.signers.
sign_pdf
(pdf_out: pyhanko.pdf_utils.writer.BasePdfFileWriter, signature_meta: pyhanko.sign.signers.PdfSignatureMetadata, signer: pyhanko.sign.signers.Signer, timestamper: Optional[pyhanko.sign.timestamps.TimeStamper] = None, new_field_spec: Optional[pyhanko.sign.fields.SigFieldSpec] = None, existing_fields_only=False, bytes_reserved=None, in_place=False, output=None)¶ Thin convenience wrapper around
PdfSigner.sign_pdf()
.- Parameters
pdf_out – An
IncrementalPdfFileWriter
.bytes_reserved – Bytes to reserve for the CMS object in the PDF file. If not specified, make an estimate based on a dummy signature.
signature_meta – The specification of the signature to add.
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 aBytesIO
object.existing_fields_only – If
True
, never create a new empty signature field to contain the signature. IfFalse
, a new field may be created if no field matchingfield_name
exists.new_field_spec – If a new field is to be created, this parameter allows the caller to specify the field’s properties in the form of a
SigFieldSpec
. This parameter is only meaningful ifexisting_fields_only
isFalse
.output – Write the output to the specified output stream. If
None
, write to a newBytesIO
object. Default isNone
.
- Returns
The output stream containing the signed output.
-
pyhanko.sign.signers.
load_certs_from_pemder
(cert_files)¶ A convenience function to load PEM/DER-encoded certificates from files.
- Parameters
cert_files – An iterable of file names.
- Returns
A generator producing
asn1crypto.x509.Certificate
objects.
-
pyhanko.sign.signers.
DEFAULT_MD
= 'sha256'¶ Default message digest algorithm used when computing digests for use in signatures.
-
pyhanko.sign.signers.
DEFAULT_SIGNING_STAMP_STYLE
= TextStampStyle(text_box_style=TextBoxStyle(font=<pyhanko.pdf_utils.font.SimpleFontEngine object>, font_size=10, leading=None, text_sep=10, border_width=0, vertical_center=True), border_width=3, stamp_text='Digitally signed by %(signer)s.\nTimestamp: %(ts)s.', timestamp_format='%Y-%m-%d %H:%M:%S %Z', background=<pyhanko.pdf_utils.content.RawContent object>, background_opacity=0.6)¶ Default stamp style used for visible signatures.