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:

• NonexistentAttributeError – Raised when no such type entry could be found in the cms.CMSAttributes object.

• CMSStructuralError – Raised if the given OID occurs more than once.

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:

• NonexistentAttributeError – Raised when no such type entry could be found in the cms.CMSAttributes object.

• MultivaluedAttributeError – Raised when the attribute’s cardinality is not 1.

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_bytes – bytes 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_bytes – bytes 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.