pyhanko.sign.signers.pdf_cms module¶
This module defines utility classes to format CMS objects for use in PDF signatures.
- class pyhanko.sign.signers.pdf_cms.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
).
- 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.
- 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, content_type='data', 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.
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.
- 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, encap_content_info=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 –
Signing time to embed into the signed attributes (will be ignored if
use_pades
isTrue
).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 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 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: asn1crypto.cms.CMSAttributes, cms_version='v1', dry_run=False, timestamper=None, encap_content_info=None) asn1crypto.cms.ContentInfo ¶
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’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.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: Union[IO, bytes, asn1crypto.cms.ContentInfo, asn1crypto.cms.EncapsulatedContentInfo], digest_algorithm: str, detached=True, timestamp: Optional[datetime.datetime] = None, use_cades=False, timestamper=None, cades_signed_attr_meta: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None, chunk_size=4096, max_read=None) asn1crypto.cms.ContentInfo ¶
Produce a CMS signature for an arbitrary data stream (not necessarily PDF data).
New in version 0.7.0.
- Parameters
input_data –
The input data to sign. This can be either a
bytes
object a file-type object, acms.ContentInfo
object or acms.EncapsulatedContentInfo
object.Warning
asn1crypto
mandatescms.ContentInfo
for CMS v1 signatures. In practical terms, this means that you need to usecms.ContentInfo
if the content type isdata
, andcms.EncapsulatedContentInfo
otherwise.Warning
We currently only support CMS v1 and v3 signatures. This is only a concern if you need attribute certificate support, in which case you can override the CMS version number yourself (this will not invalidate any signatures).
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. IfFalse
, 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
isTrue
).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 timestampNote
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.signers.pdf_cms.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.pdf_cms.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.pdf_cms.ExternalSigner(signing_cert: asn1crypto.x509.Certificate, cert_registry: pyhanko.sign.general.CertificateStore, signature_value: bytes, signature_mechanism: Optional[asn1crypto.algos.SignedDigestAlgorithm] = None, prefer_pss=False)¶
Bases:
pyhanko.sign.signers.pdf_cms.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.
- 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.
- sign_raw(data: bytes, digest_algorithm: str, dry_run=False) bytes ¶
Return a fixed signature value.
- class pyhanko.sign.signers.pdf_cms.PdfCMSSignedAttributes(signing_time: Optional[datetime.datetime] = None, adobe_revinfo_attr: Optional[asn1crypto.cms.CMSAttribute] = None, cades_signed_attrs: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None)¶
Bases:
object
New in version 0.7.0.
Serialisable container class describing input for various signed attributes in a CMS object for a PDF signature.
- signing_time: Optional[datetime.datetime] = None¶
Timestamp for the
signingTime
attribute. Will be ignored in a PAdES context.
- adobe_revinfo_attr: Optional[asn1crypto.cms.CMSAttribute] = None¶
Adobe-style signed revocation info attribute.
- cades_signed_attrs: Optional[pyhanko.sign.ades.api.CAdESSignedAttrSpec] = None¶
Optional settings for CAdES-style signed attributes.