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 aValueError
.- 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
ortsp.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 theESSCertID
matches the certificate,False
otherwise.