pyhanko.sign.validation.status module
- class pyhanko.sign.validation.status.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
CMS 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 usages are accepted 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 key purposes are accepted to be present on the signer’s certificate.
- summary_fields()
- summary(delimiter=',')
Provide a textual but machine-parsable summary of the validity.
- async classmethod validate_cert_usage(validator: pyhanko_certvalidator.CertificateValidator, key_usage_settings: Optional[pyhanko.sign.validation.settings.KeyUsageConstraints] = None)
- class pyhanko.sign.validation.status.TimestampSignatureStatus(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, timestamp: datetime.datetime)
Bases:
pyhanko.sign.validation.status.SignatureStatus
Signature status class used when validating timestamp tokens.
- key_usage: ClassVar[Set[str]] = {}
There are no (non-extended) key usage requirements for TSA certificates.
- extd_key_usage: ClassVar[Optional[Set[str]]] = {'time_stamping'}
TSA certificates must have the
time_stamping
extended key usage extension (OID 1.3.6.1.5.5.7.3.8).
- timestamp: datetime.datetime
Value of the timestamp token as a datetime object.
- describe_timestamp_trust()
- class pyhanko.sign.validation.status.X509AttributeInfo(attr_type: asn1crypto.cms.AttCertAttributeType, attr_values: Iterable[asn1crypto.core.Asn1Value])
Bases:
object
Info on an X.509 attribute.
- attr_type: asn1crypto.cms.AttCertAttributeType
The certified attribute’s type.
- attr_values: Iterable[asn1crypto.core.Asn1Value]
The certified attribute’s values.
- class pyhanko.sign.validation.status.CertifiedAttributeInfo(attr_type: asn1crypto.cms.AttCertAttributeType, attr_values: Iterable[asn1crypto.core.Asn1Value], validation_results: Iterable[pyhanko_certvalidator.validate.ACValidationResult])
Bases:
pyhanko.sign.validation.status.X509AttributeInfo
Info on a certified attribute, including AC validation results.
- validation_results: Iterable[pyhanko_certvalidator.validate.ACValidationResult]
The validation details for the attribute in question (possibly several if values for the same attribute were sourced from several different ACs).
- class pyhanko.sign.validation.status.ClaimedAttributes
Bases:
object
Container class for extracted information on attributes asserted by a signer without an attribute certificate.
- classmethod from_iterable(attrs: Iterable[asn1crypto.cms.AttCertAttribute])
- class pyhanko.sign.validation.status.CertifiedAttributes
Bases:
object
Container class for extracted attribute certificate information.
- classmethod from_results(results: Iterable[pyhanko_certvalidator.validate.ACValidationResult])
- class pyhanko.sign.validation.status.CAdESSignerAttributeAssertions(claimed_attrs: pyhanko.sign.validation.status.ClaimedAttributes, certified_attrs: Optional[pyhanko.sign.validation.status.CertifiedAttributes] = None, ac_validation_errs: Optional[Collection[Union[pyhanko_certvalidator.errors.PathValidationError, pyhanko_certvalidator.errors.PathBuildingError]]] = None, unknown_attrs_present: bool = False)
Bases:
object
Value type describing information extracted (and, if relevant, validated) from a
signer-attrs-v2
signed attribute.- claimed_attrs: pyhanko.sign.validation.status.ClaimedAttributes
Attributes claimed by the signer without additional justification. May be empty.
- certified_attrs: Optional[pyhanko.sign.validation.status.CertifiedAttributes] = None
Attributes claimed by the signer using an attribute certificate.
This field will only be populated if an attribute certificate validation context is available, otherwise its value will be
None
, even if there are no attribute certificates present.
- ac_validation_errs: Optional[Collection[Union[pyhanko_certvalidator.errors.PathValidationError, pyhanko_certvalidator.errors.PathBuildingError]]] = None
Attribute certificate validation errors.
This field will only be populated if an attribute certificate validation context is available, otherwise its value will be
None
, even if there are no attribute certificates present.
- unknown_attrs_present: bool = False
Records if the
signer-attrs-v2
attribute contained certificate types or signed assertions that could not be processed.This does not affect the validation process by default, but will trigger a warning.
- property valid
- class pyhanko.sign.validation.status.StandardCMSSignatureStatus(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, signer_reported_dt: Optional[datetime.datetime] = None, timestamp_validity: Optional[pyhanko.sign.validation.status.TimestampSignatureStatus] = None, content_timestamp_validity: Optional[pyhanko.sign.validation.status.TimestampSignatureStatus] = None, ac_attrs: Optional[pyhanko.sign.validation.status.CertifiedAttributes] = None, ac_validation_errs: Optional[Collection[Union[pyhanko_certvalidator.errors.PathValidationError, pyhanko_certvalidator.errors.PathBuildingError]]] = None, cades_signer_attrs: Optional[pyhanko.sign.validation.status.CAdESSignerAttributeAssertions] = None)
Bases:
pyhanko.sign.validation.status.SignatureStatus
Status of a standard “end-entity” CMS signature, potentially with timing information embedded inside.
- signer_reported_dt: Optional[datetime.datetime] = None
Signer-reported signing time, if present in the signature.
Generally speaking, this timestamp should not be taken as fact.
- timestamp_validity: Optional[pyhanko.sign.validation.status.TimestampSignatureStatus] = None
Validation status of the signature timestamp token embedded in this signature, if present.
- content_timestamp_validity: Optional[pyhanko.sign.validation.status.TimestampSignatureStatus] = None
Validation status of the content timestamp token embedded in this signature, if present.
- ac_attrs: Optional[pyhanko.sign.validation.status.CertifiedAttributes] = None
Certified attributes sourced from valid attribute certificates embedded into the
SignedData
’scertificates
field and the CAdES-stylesigner-attrs-v2
attribute (if present).Will be
None
if no validation context for attribute certificate validation was provided.Note
There is a semantic difference between attribute certificates extracted from the
certificates
field and those extracted from thesigner-attrs-v2
attribute. In the former case, the ACs are not covered by the signature. However, a CAdES-stylesigner-attrs-v2
attribute is signed, so the signer is expected to have explicitly _acknowledged_ all attributes, in the AC. See alsocades_signer_attrs
.
- ac_validation_errs: Optional[Collection[Union[pyhanko_certvalidator.errors.PathValidationError, pyhanko_certvalidator.errors.PathBuildingError]]] = None
Errors encountered while validating attribute certificates embedded into the
SignedData
’scertificates
field and the CAdES-stylesigner-attrs-v2
attribute (if present).Will be
None
if no validation context for attribute certificate validation was provided.
- cades_signer_attrs: Optional[pyhanko.sign.validation.status.CAdESSignerAttributeAssertions] = None
Information extracted and validated from the signed
signer-attrs-v2
attribute defined in CAdES.
- property bottom_line: bool
Formulates a general judgment on the validity of this signature. This takes into account the cryptographic validity of the signature, the signature’s chain of trust and the validity of the timestamp token (if present).
- Returns
True
if all constraints are satisfied,False
otherwise.
- summary_fields()
- pretty_print_details()
- pretty_print_sections()
- class pyhanko.sign.validation.status.SignatureCoverageLevel(value)
Bases:
pyhanko.pdf_utils.misc.OrderedEnum
Indicate the extent to which a PDF signature (cryptographically) covers a document. Note that this does not pass judgment on whether uncovered updates are legitimate or not, but as a general rule, a legitimate signature will satisfy at least
ENTIRE_REVISION
.- UNCLEAR = 0
The signature’s coverage is unclear and/or disconnected. In standard PDF signatures, this is usually a bad sign.
- CONTIGUOUS_BLOCK_FROM_START = 1
The signature covers a contiguous block in the PDF file stretching from the first byte of the file to the last byte in the indicated
/ByteRange
. In other words, the only interruption in the byte range is fully occupied by the signature data itself.
- ENTIRE_REVISION = 2
The signature covers the entire revision in which it occurs, but incremental updates may have been added later. This is not necessarily evidence of tampering. In particular, it is expected when a file contains multiple signatures. Nonetheless, caution is required.
- ENTIRE_FILE = 3
The entire file is covered by the signature.
- class pyhanko.sign.validation.status.ModificationInfo(coverage: pyhanko.sign.validation.status.SignatureCoverageLevel = None, diff_result: Union[pyhanko.sign.diff_analysis.policy_api.DiffResult, pyhanko.sign.diff_analysis.policy_api.SuspiciousModification, NoneType] = None)
Bases:
object
- coverage: pyhanko.sign.validation.status.SignatureCoverageLevel = None
Indicates how much of the document is covered by the signature.
- diff_result: Optional[Union[pyhanko.sign.diff_analysis.policy_api.DiffResult, pyhanko.sign.diff_analysis.policy_api.SuspiciousModification]] = None
Result of the difference analysis run on the file:
If
None
, no difference analysis was run.If the difference analysis was successful, this attribute will contain a
DiffResult
object.If the difference analysis failed due to unforeseen or suspicious modifications, the
SuspiciousModification
exception thrown by the difference policy will be stored in this attribute.
- property modification_level: Optional[pyhanko.sign.diff_analysis.policy_api.ModificationLevel]
Indicates the degree to which the document was modified after the signature was applied.
Will be
None
if difference analysis results are not available; an instance ofModificationLevel
otherwise.
- class pyhanko.sign.validation.status.PdfSignatureStatus(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, signer_reported_dt: Optional[datetime.datetime] = None, timestamp_validity: Optional[pyhanko.sign.validation.status.TimestampSignatureStatus] = None, content_timestamp_validity: Optional[pyhanko.sign.validation.status.TimestampSignatureStatus] = None, ac_attrs: Optional[pyhanko.sign.validation.status.CertifiedAttributes] = None, ac_validation_errs: Optional[Collection[Union[pyhanko_certvalidator.errors.PathValidationError, pyhanko_certvalidator.errors.PathBuildingError]]] = None, cades_signer_attrs: Optional[pyhanko.sign.validation.status.CAdESSignerAttributeAssertions] = None, coverage: Optional[pyhanko.sign.validation.status.SignatureCoverageLevel] = None, diff_result: Optional[Union[pyhanko.sign.diff_analysis.policy_api.DiffResult, pyhanko.sign.diff_analysis.policy_api.SuspiciousModification]] = None, docmdp_ok: Optional[bool] = None, has_seed_values: bool = False, seed_value_constraint_error: Optional[pyhanko.sign.validation.errors.SigSeedValueValidationError] = None)
Bases:
pyhanko.sign.validation.status.ModificationInfo
,pyhanko.sign.validation.status.StandardCMSSignatureStatus
Class to indicate the validation status of a PDF signature.
- docmdp_ok: Optional[bool] = None
Indicates whether the signature’s
modification_level
is in line with the document signature policy in force.If
None
, compliance could not be determined.
- has_seed_values: bool = False
Records whether the signature form field has seed values.
- seed_value_constraint_error: Optional[pyhanko.sign.validation.errors.SigSeedValueValidationError] = None
Records the reason for failure if the signature field’s seed value constraints didn’t validate.
- property bottom_line: bool
Formulates a general judgment on the validity of this signature. This takes into account the cryptographic validity of the signature, the signature’s chain of trust, compliance with the document modification policy, seed value constraint compliance and the validity of the timestamp token (if present).
- Returns
True
if all constraints are satisfied,False
otherwise.
- property seed_value_ok: bool
Indicates whether the signature satisfies all mandatory constraints in the seed value dictionary of the associated form field.
Warning
Currently, not all seed value entries are recognised by the signer and/or the validator, so this judgment may not be entirely accurate in some cases.
See
SigSeedValueSpec
.
- summary_fields()
- pretty_print_sections()
- class pyhanko.sign.validation.status.DocumentTimestampStatus(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, timestamp: datetime.datetime, coverage: Optional[pyhanko.sign.validation.status.SignatureCoverageLevel] = None, diff_result: Optional[Union[pyhanko.sign.diff_analysis.policy_api.DiffResult, pyhanko.sign.diff_analysis.policy_api.SuspiciousModification]] = None)
Bases:
pyhanko.sign.validation.status.ModificationInfo
,pyhanko.sign.validation.status.TimestampSignatureStatus
Class to indicate the validation status of a PDF document timestamp.