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.

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.

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: pyhanko_certvalidator.registry.CertificateCollection, abc.ABC

register(cert: asn1crypto.x509.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: pyhanko_certvalidator.registry.CertificateStore

Simple trustless certificate store.

classmethod from_certs(certs)

register(cert: asn1crypto.x509.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: asn1crypto.x509.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

Bases: ValueError

Error encountered while signing a file.

exception pyhanko.sign.general.UnacceptableSignerError

Bases: pyhanko.sign.general.SigningError

Error raised when a signer was judged unacceptable.

class pyhanko.sign.general.SignedDataCerts(signer_cert: asn1crypto.x509.Certificate, other_certs: List[asn1crypto.x509.Certificate], attribute_certs: List[asn1crypto.cms.AttributeCertificateV2])

Bases: object

Value type to describe certificates included in a CMS signed data payload.

signer_cert: asn1crypto.x509.Certificate: The certificate identified as the signer’s certificate.

other_certs: List[asn1crypto.x509.Certificate]: Other (public-key) certificates included in the signed data object.

attribute_certs: List[asn1crypto.cms.AttributeCertificateV2]: Attribute certificates included in the signed data object.

pyhanko.sign.general.extract_signer_info(signed_data: asn1crypto.cms.SignedData) → asn1crypto.cms.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: asn1crypto.cms.SignedData) → pyhanko.sign.general.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]) → asn1crypto.keys.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.get_pyca_cryptography_hash(algorithm, prehashed=False)

pyhanko.sign.general.optimal_pss_params(cert: asn1crypto.x509.Certificate, digest_algorithm: str) → asn1crypto.algos.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: asn1crypto.algos.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: asn1crypto.x509.Certificate) → asn1crypto.tsp.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: asn1crypto.x509.Certificate, hash_algo='sha256') → asn1crypto.tsp.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[asn1crypto.cms.IssuerAndSerialNumber, asn1crypto.tsp.IssuerSerial], cert: asn1crypto.x509.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: asn1crypto.x509.Certificate, certid: Union[asn1crypto.tsp.ESSCertID, asn1crypto.tsp.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: Bases: ValueError