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: pyhanko_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 obviouslytrusted
will beFalse
.
- 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: pyhanko_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[Optional[Set[str]]] = None¶
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: pyhanko_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 pyhanko_certvalidator’s CertificateRegistry in cases where we explicitly don’t care about whether the certs are trusted or not.
- classmethod from_certs(certs: Iterable[asn1crypto.x509.Certificate])¶
- register(cert: asn1crypto.x509.Certificate)¶
Add a certificate to the collection.
- Parameters
cert – The certificate to add.
- class pyhanko.sign.general.KeyUsageConstraints(key_usage: Optional[Set[str]] = None, key_usage_forbidden: Optional[Set[str]] = None, extd_key_usage: Optional[Set[str]] = None, explicit_extd_key_usage_required: bool = True, match_all_key_usages: bool = False)¶
Bases:
pyhanko.pdf_utils.config_utils.ConfigurableMixin
Convenience class to pass around key usage requirements and validate them. Intended to be flexible enough to handle both PKIX and ISO 32000 certificate seed value constraint semantics.
Changed in version 0.6.0: Bring extended key usage semantics in line with RFC 5280 (PKIX).
- key_usage: Set[str] = None¶
All or some (depending on
match_all_key_usage
) of these key usage extensions must be present in the signer’s certificate. If not set or empty, all key usages are considered acceptable.
- key_usage_forbidden: Set[str] = None¶
These key usage extensions must not be present in the signer’s certificate.
Note
This behaviour is undefined in RFC 5280 (PKIX), but included for compatibility with certificate seed value settings in ISO 32000.
- extd_key_usage: Set[str] = None¶
List of acceptable key purposes that can appear in an extended key usage extension in the signer’s certificate, if such an extension is at all present. If not set, all extended key usages are considered acceptable.
If no extended key usage extension is present, or the
anyExtendedKeyUsage
key purpose ID is present the resulting behaviour depends onexplicit_extd_key_usage_required
.Setting this option to the empty set (as opposed to
None
) effectively bans all (presumably unrecognised) extended key usages.Warning
Note the difference in behaviour with
key_usage
for empty sets of valid usages.Warning
Contrary to what some CAs seem to believe, the criticality of the extended key usage extension is irrelevant here. Even a non-critical EKU extension must be enforced according to RFC 5280 § 4.2.1.12.
In practice, many certificate authorities issue non-repudiation certs that can also be used for TLS authentication by only including the TLS client authentication key purpose ID in the EKU extension. Interpreted strictly, RFC 5280 bans such certificates from being used to sign documents, and pyHanko will enforce these semantics if
extd_key_usage
is notNone
.
- explicit_extd_key_usage_required: bool = True¶
New in version 0.6.0.
Require an extended key usage extension with the right key usages to be present if
extd_key_usage
is non-empty.If this flag is
True
, at least one key purpose inextd_key_usage
must appear in the certificate’s extended key usage, andanyExtendedKeyUsage
will be ignored.
- match_all_key_usages: bool = False¶
New in version 0.6.0.
If
True
, all key usages indicated inkey_usage
must be present in the certificate. IfFalse
, one match suffices.If
key_usage
is empty orNone
, this option has no effect.
- validate(cert: asn1crypto.x509.Certificate)¶
- classmethod process_entries(config_dict)¶
Hook method that can modify the configuration dictionary to overwrite or tweak some of their values (e.g. to convert string parameters into more complex Python objects)
Subclasses that override this method should call
super().process_entries()
, and leave keys that they do not recognise untouched.- Parameters
config_dict – A dictionary containing configuration values.
- Raises
ConfigurationError – when there is a problem processing a relevant entry.
- 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.
- exception pyhanko.sign.general.WeakHashAlgorithmError¶
- exception pyhanko.sign.general.SignatureValidationError¶
Bases:
ValueError
Error validating a signature.
- 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)¶