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)

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.