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.

class pyhanko.sign.general.SignatureStatus(intact: bool, valid: bool, trusted: bool, revoked: bool, signing_cert: asn1crypto.x509.Certificate, pkcs7_signature_mechanism: str, md_algorithm: str, validation_path: certvalidator.path.ValidationPath)¶

Bases: object

Class describing the validity of a (general) CMS signature.

intact: bool¶: Reports whether the signature is intact, i.e. whether the hash of the message content (which may or may not be embedded inside the CMS object itself) matches the hash value that was signed.

valid: bool¶: Reports whether the signature is valid, i.e. whether the hash’s signature actually validates.

trusted: bool¶: Reports whether the signer’s certificate is trusted w.r.t. the currently relevant validation context and key usage requirements.

revoked: bool¶: Reports whether the signer’s certificate has been revoked or not. If this field is True, then obviously trusted will be False.

signing_cert: asn1crypto.x509.Certificate¶: Contains the certificate of the signer, as embedded in the CMS object.

pkcs7_signature_mechanism: str¶: PKCS7 signature mechanism used.

md_algorithm: str¶: Message digest algorithm used.

validation_path: certvalidator.path.ValidationPath¶: Validation path providing a valid chain of trust from the signer’s certificate to a trusted root certificate.

key_usage: ClassVar[Set[str]] = {'non_repudiation'}¶: Class property indicating which key usage extensions are required to be present on the signer’s certificate. The default is non_repudiation only.

extd_key_usage: ClassVar[Set[str]] = {}¶: Class property indicating which extended key usage extensions are required to be present on the signer’s certificate.

summary_fields()¶

summary()¶: Provide a textual but machine-parsable summary of the validity.

classmethod validate_cert_usage(validator: certvalidator.CertificateValidator, key_usage_settings: Optional[pyhanko.sign.general.KeyUsageConstraints] = None)¶

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

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

class pyhanko.sign.general.CertificateStore¶

Bases: object

Bare-bones interface for modelling a collection of certificates.

register(cert: asn1crypto.x509.Certificate)¶

Add a certificate to the collection.

Parameters: cert – The certificate to add.

register_multiple(certs)¶

Register multiple certificates.

Parameters: certs – Certificates to register.

class pyhanko.sign.general.SimpleCertificateStore¶

Bases: pyhanko.sign.general.CertificateStore

Unopinionated replacement for certvalidator’s CertificateRegistry in cases where we explicitly don’t care about whether the certs are trusted or not.

register(cert: asn1crypto.x509.Certificate)¶

Add a certificate to the collection.

Parameters: cert – The certificate to add.

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.

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.