pyhanko.sign.signers.pdf_byterange module
This module contains the low-level building blocks for dealing with bookkeeping
around /ByteRange
digests in PDF files.
- class pyhanko.sign.signers.pdf_byterange.PreparedByteRangeDigest(document_digest: bytes, md_algorithm: str, reserved_region_start: int, reserved_region_end: int)
Bases:
object
New in version 0.7.0.
Bookkeeping class that contains the digest of a document that is about to be signed (or otherwise authenticated) based on said digest. It also keeps track of the digest algorithm used, and the region in the output stream that will contain the signature.
Instances of this class can easily be serialised, which allows for interrupting the signing process partway through.
- document_digest: bytes
Digest of the document, computed over the appropriate
/ByteRange
.
- md_algorithm: str
Name of the digest algorithm used.
- reserved_region_start: int
Start of the reserved region in the output stream that is not part of the
/ByteRange
.
- reserved_region_end: int
End of the reserved region in the output stream that is not part of the
/ByteRange
.
- fill_with_cms(output: IO, cms_data: Union[bytes, asn1crypto.cms.ContentInfo])
Write a DER-encoded CMS object to the reserved region indicated by
reserved_region_start
andreserved_region_end
in the output stream.- Parameters
output – Output stream to use. Must be writable and seekable.
cms_data – CMS object to write. Can be provided as an
asn1crypto.cms.ContentInfo
object, or as raw DER-encoded bytes.
- Returns
A
bytes
object containing the contents that were written, plus any additional padding.
- fill_reserved_region(output: IO, content_bytes: bytes)
Write hex-encoded contents to the reserved region indicated by
reserved_region_start
andreserved_region_end
in the output stream.- Parameters
output – Output stream to use. Must be writable and seekable.
content_bytes – Content bytes. These will be padded, hexadecimally encoded and written to the appropriate location in output stream.
- Returns
A
bytes
object containing the contents that were written, plus any additional padding.
- class pyhanko.sign.signers.pdf_byterange.PdfByteRangeDigest(data_key='/Contents', *, bytes_reserved=None)
Bases:
pyhanko.pdf_utils.generic.DictionaryObject
General class to model a PDF Dictionary that has a
/ByteRange
entry and a another data entry (named/Contents
by default) that will contain a value based on a digest computed over said/ByteRange
. The/ByteRange
will cover the entire file, except for the value of the data entry itself.Danger
This is internal API.
- Parameters
data_key – Name of the data key, which is
/Contents
by default.bytes_reserved – Number of bytes to reserve for the contents placeholder. If
None
, a generous default is applied, but you should try to estimate the size as accurately as possible.
- 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.
Danger
This is internal API; you should use use
PdfSigner
wherever possible. If you really need fine-grained control, usePdfCMSEmbedder
instead.
- class pyhanko.sign.signers.pdf_byterange.PdfSignedData(obj_type, subfilter: pyhanko.sign.fields.SigSeedSubFilter = SigSeedSubFilter.ADOBE_PKCS7_DETACHED, timestamp: Optional[datetime.datetime] = None, bytes_reserved=None)
Bases:
pyhanko.sign.signers.pdf_byterange.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.pdf_byterange.SignatureObject(timestamp: Optional[datetime.datetime] = None, subfilter: pyhanko.sign.fields.SigSeedSubFilter = SigSeedSubFilter.ADOBE_PKCS7_DETACHED, name=None, location=None, reason=None, bytes_reserved=None)
Bases:
pyhanko.sign.signers.pdf_byterange.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.pdf_byterange.DocumentTimestamp(bytes_reserved=None)
Bases:
pyhanko.sign.signers.pdf_byterange.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.