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.

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.general.find_cms_attribute(attrs, name)

Find and return CMS attribute values of a given type.

Note

This function will also check for duplicates, but not in the sense of multivalued attributes. In other words: multivalued attributes are allowed; listing the same attribute OID more than once is not.

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
pyhanko.sign.general.find_unique_cms_attribute(attrs, name)

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
exception pyhanko.sign.general.NonexistentAttributeError

Bases: KeyError

exception pyhanko.sign.general.MultivaluedAttributeError

Bases: ValueError

class pyhanko.sign.general.CertificateStore

Bases: CertificateCollection, ABC

register(cert: Certificate) bool

Register a single certificate.

Parameters

cert – Certificate to add.

Returns

True if the certificate was added, False if it already existed in this store.

register_multiple(certs: Iterable[Certificate])

Register multiple certificates.

Parameters

certs – Certificates to register.

Returns

True if at least one certificate was added, False if all certificates already existed in this store.

class pyhanko.sign.general.SimpleCertificateStore

Bases: CertificateStore

Simple trustless certificate store.

classmethod from_certs(certs)
register(cert: Certificate) bool

Register a single certificate.

Parameters

cert – Certificate to add.

Returns

True if the certificate was added, False if it already existed in this store.

retrieve_many_by_key_identifier(key_identifier: bytes)

Retrieves possibly multiple certs via the corresponding key identifiers

Parameters

key_identifier – A byte string of the key identifier

Returns

A list of asn1crypto.x509.Certificate objects

retrieve_by_name(name: Name)

Retrieves a list certs via their subject name

Parameters

name – An asn1crypto.x509.Name object

Returns

A list of asn1crypto.x509.Certificate objects

retrieve_by_issuer_serial(issuer_serial)

Retrieve a certificate by its issuer_serial value.

Parameters

issuer_serial – The issuer_serial value of the certificate.

Returns

The certificate corresponding to the issuer_serial key passed in.

Returns

None or an asn1crypto.x509.Certificate object

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

Bases: ValueError

Error encountered while signing a file.

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

Bases: SigningError

Error raised when a signer was judged unacceptable.

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.

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.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.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_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_private_key_from_pemder(key_file, passphrase: Optional[bytes]) 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_certs_from_pemder_data(cert_data_bytes: bytes)

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

Parameters

cert_data_bytesbytes object from which to extract certificates.

Returns

A generator producing asn1crypto.x509.Certificate objects.

pyhanko.sign.general.load_private_key_from_pemder_data(key_bytes: bytes, passphrase: Optional[bytes]) PrivateKeyInfo

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

Parameters
  • key_bytesbytes object to read the key from.

  • passphrase – Key passphrase.

Returns

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

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.get_pyca_cryptography_hash(algorithm, prehashed=False) Union[HashAlgorithm, Prehashed]
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.process_pss_params(params: RSASSAPSSParams, digest_algorithm, prehashed=False)

Extract PSS padding settings and message digest from an RSASSAPSSParams value.

Internal API.

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.match_issuer_serial(expected_issuer_serial: Union[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.check_ess_certid(cert: Certificate, certid: Union[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.

exception pyhanko.sign.general.CMSExtractionError(failure_message)

Bases: ValueErrorWithMessage

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.

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.

exception pyhanko.sign.general.CMSStructuralError(failure_message)

Bases: ValueErrorWithMessage

Structural error in a CMS object.