pyhanko.sign.validation module¶
-
class
pyhanko.sign.validation.
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.
ModificationLevel
(value)¶ Bases:
pyhanko.pdf_utils.misc.OrderedEnum
Records the (semantic) modification level of a document.
Compare
MDPPerm
, which records the document modification policy associated with a particular signature, as opposed to the empirical judgment indicated by this enum.-
NONE
= 0¶ The document was not modified at all (i.e. it is byte-for-byte unchanged).
-
LTA_UPDATES
= 1¶ The only updates are signature long term archival (LTA) updates. That is to say, updates to the document security store or new document time stamps. For the purposes of evaluating whether a document has been modified in the sense defined in the PAdES and ISO 32000-2 standards, these updates do not count. Adding form fields is permissible at this level, but only if they are signature fields. This is necessary for proper document timestamp support.
-
FORM_FILLING
= 2¶ The only updates are extra signatures and updates to form field values or their appearance streams, in addition to the previous levels.
-
ANNOTATIONS
= 3¶ In addition to the previous levels, manipulating annotations is also allowed at this level.
Note
This level is currently unused, and modifications to annotations other than those permitted to fill in forms are treated as suspicious.
-
OTHER
= 4¶ The document has been modified in ways that aren’t on the validator’s whitelist. This always invalidates the corresponding signature, irrespective of cryptographical integrity or
/DocMDP
settings.
-
-
class
pyhanko.sign.validation.
PdfSignatureStatus
(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, coverage: pyhanko.sign.validation.SignatureCoverageLevel, modification_level: pyhanko.sign.validation.ModificationLevel, seed_value_ok: bool, docmdp_ok: bool, signer_reported_dt: Optional[datetime.datetime] = None, timestamp_validity: Optional[pyhanko.sign.timestamps.TimestampSignatureStatus] = None)¶ Bases:
pyhanko.sign.general.SignatureStatus
Class to indicate the validation status of a PDF signature.
-
coverage
: pyhanko.sign.validation.SignatureCoverageLevel¶ Indicates how much of the document is covered by the signature.
-
modification_level
: pyhanko.sign.validation.ModificationLevel¶ Indicates the degree to which the document was modified after the signature was applied.
-
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
.
-
docmdp_ok
: bool¶ Indicates whether the signature’s
modification_level
is in line with the document signature policy in force.
-
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.timestamps.TimestampSignatureStatus] = None¶ Validation status of the timestamp token embedded in this signature, if present.
-
property
bottom_line
¶ 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.
-
summary_fields
()¶
-
pretty_print_details
()¶
-
-
class
pyhanko.sign.validation.
EmbeddedPdfSignature
(reader: pyhanko.pdf_utils.reader.PdfFileReader, sig_field: pyhanko.pdf_utils.generic.DictionaryObject)¶ Bases:
object
Class modelling a signature embedded in a PDF document.
-
sig_object
: pyhanko.pdf_utils.generic.DictionaryObject¶ The signature dictionary.
-
sig_field
: pyhanko.pdf_utils.generic.DictionaryObject¶ The field dictionary of the form field containing the signature.
-
signed_data
: asn1crypto.cms.SignedData¶ CMS signed data in the signature.
-
signer_cert
: asn1crypto.x509.Certificate¶ Certificate of the signer.
-
property
field_name
¶ - Returns
Name of the signature field.
-
property
self_reported_timestamp
¶ - Returns
The signing time as reported by the signer, if embedded in the signature’s signed attributes.
-
property
external_timestamp_data
¶ - Returns
The signed data component of the timestamp token embedded in this signature, if present.
-
compute_integrity_info
(skip_diff=False)¶ Compute the various integrity indicators of this signature.
- Parameters
skip_diff – If
True
, skip the (rather expensive) modification level evaluation.
-
summarise_integrity_info
() → dict¶ Compile the integrity information for this signature into a dictionary that can later be passed to
PdfSignatureStatus
as kwargs.- Returns
A kwargs dictionary.
-
property
docmdp_level
¶ - Returns
The document modification policy required by this signature.
Warning
This does not take into account the DocMDP requirements of earlier signatures (if present).
The specification forbids signing with a more lenient DocMDP than the one currently in force, so this should not happen in a compliant document. That being said, any potential violations will still invalidate the earlier signature with the stricter DocMDP policy.
-
property
fieldmdp
¶ - Returns
Read the field locking policy of this signature, if applicable. See also
FieldMDPSpec
.
-
compute_digest
() → bytes¶ Compute the
/ByteRange
digest of this signature. The result will be cached.- Returns
The digest value.
-
compute_tst_digest
() → Optional[bytes]¶ Compute the digest of the signature needed to validate its timestamp token (if present).
Warning
This computation is only relevant for timestamp tokens embedded inside a regular signature. If the signature in question is a document timestamp (where the entire signature object is a timestamp token), this method does not apply.
- Returns
The digest value, or
None
if there is no timestamp token.
-
evaluate_signature_coverage
() → pyhanko.sign.validation.SignatureCoverageLevel¶ Internal method used to evaluate the coverage level of a signature.
- Returns
The coverage level of the signature.
-
evaluate_modifications
() → pyhanko.sign.validation.ModificationLevel¶ Internal method used to evaluate the modification level of a signature.
- Returns
The modification level of the signature.
-
-
class
pyhanko.sign.validation.
DocMDPInfo
(permission, author_sig)¶ Bases:
tuple
Encodes certification information for a signed document, consisting of a reference to the author signature, together with the associated DocMDP policy.
Alias for field number 1
-
property
permission
¶ Alias for field number 0
-
class
pyhanko.sign.validation.
RevocationInfoValidationType
(value)¶ Bases:
enum.Enum
Indicates a validation profile to use when validating revocation info.
-
ADOBE_STYLE
= 'adobe'¶ Retrieve validation information from the CMS object, using Adobe’s revocation info archival attribute.
-
PADES_LT
= 'pades'¶ Retrieve validation information from the DSS, and require the signature’s embedded timestamp to still be valid.
-
PADES_LTA
= 'pades-lta'¶ Retrieve validation information from the DSS, but read & validate the chain of document timestamps leading up to the signature to establish the integrity of the validation information at the time of signing.
-
classmethod
as_tuple
()¶
-
-
class
pyhanko.sign.validation.
VRI
(certs: set = <factory>, ocsps: set = <factory>, crls: set = <factory>)¶ Bases:
object
VRI dictionary as defined in PAdES / ISO 32000-2. These dictionaries collect data that may be relevant for the validation of a specific signature.
Note
The data are stored as PDF indirect objects, not asn1crypto values. In particular, values are tied to a specific PDF handler.
-
certs
: set¶ Relevant certificates.
-
ocsps
: set¶ Relevant OCSP responses.
-
crls
: set¶ Relevant CRLs.
-
as_pdf_object
() → pyhanko.pdf_utils.generic.DictionaryObject¶ - Returns
A PDF dictionary representing this VRI entry.
-
-
class
pyhanko.sign.validation.
DocumentSecurityStore
(writer, certs=None, ocsps=None, crls=None, vri_entries=None, backing_pdf_object=None)¶ Bases:
object
Representation of a DSS in Python.
-
static
sig_content_identifier
(contents) → pyhanko.pdf_utils.generic.NameObject¶ Hash the contents of a signature object to get the corresponding VRI identifier.
This is internal API.
- Parameters
contents – Signature contents.
- Returns
A name object to put into the DSS.
-
register_vri
(identifier, paths, validation_context)¶ Register validation information for a set of signing certificates associated with a particular signature.
- Parameters
identifier – Identifier of the signature object (see sig_content_identifier)
paths – Validation paths to add.
validation_context – Validation context to source CRLs and OCSP responses from.
-
as_pdf_object
()¶ Convert the
DocumentSecurityStore
object to a python dictionary. This method also handles DSS updates.- Returns
A PDF object representing this DSS.
-
as_validation_context
(validation_context_kwargs, include_revinfo=True) → certvalidator.context.ValidationContext¶ Construct a validation context from the data in this DSS.
- Parameters
validation_context_kwargs – Extra kwargs to pass to the
__init__
function.include_revinfo – If
False
, revocation info is skipped.
- Returns
A validation context preloaded with information from this DSS.
-
classmethod
read_dss
(handler: pyhanko.pdf_utils.rw_common.PdfHandler) → pyhanko.sign.validation.DocumentSecurityStore¶ Read a DSS record from a file and add the data to a validation context.
- Parameters
handler – PDF handler from which to read the DSS.
- Returns
A DocumentSecurityStore object describing the current state of the DSS.
-
classmethod
add_dss
(output_stream, sig_contents, paths, validation_context)¶ Add or update a DSS, and add the new information to a specific VRI. This will be done as an incremental update.
- Parameters
output_stream – Output stream to write to.
sig_contents – Contents of the new signature (used to compute the VRI hash)
paths – Validation paths that have been established, and need to be added to the DSS.
validation_context – Validation context from which to draw OCSP responses and CRLs.
-
static
-
pyhanko.sign.validation.
apply_adobe_revocation_info
(signer_info: asn1crypto.cms.SignerInfo, validation_context_kwargs=None) → certvalidator.context.ValidationContext¶ Read Adobe-style revocation information from a CMS object, and load it into a validation context.
- Parameters
signer_info – Signer info CMS object.
validation_context_kwargs – Extra kwargs to pass to the
__init__
function.
- Returns
A validation context preloaded with the relevant revocation information.
-
pyhanko.sign.validation.
read_certification_data
(reader: pyhanko.pdf_utils.reader.PdfFileReader) → Optional[pyhanko.sign.validation.DocMDPInfo]¶ Read the certification information for a PDF document, if present.
- Parameters
reader – Reader representing the input document.
- Returns
A
DocMDPInfo
object containing the relevant data, orNone
.
-
pyhanko.sign.validation.
validate_pdf_ltv_signature
(embedded_sig: pyhanko.sign.validation.EmbeddedPdfSignature, validation_type: pyhanko.sign.validation.RevocationInfoValidationType, validation_context_kwargs=None, bootstrap_validation_context=None, force_revinfo=False) → pyhanko.sign.validation.PdfSignatureStatus¶ Validate a PDF LTV signature according to a particular profile.
- Parameters
embedded_sig – Embedded signature to evaluate.
validation_type – Validation profile to use.
validation_context_kwargs – Keyword args to instantiate
certvalidator.ValidationContext
objects needed over the course of the validation.bootstrap_validation_context – Validation context used to validate the current timestamp.
force_revinfo – Require all certificates encountered to have some form of live revocation checking provisions.
- Returns
The status of the signature.
-
pyhanko.sign.validation.
validate_pdf_signature
(embedded_sig: pyhanko.sign.validation.EmbeddedPdfSignature, signer_validation_context: Optional[certvalidator.context.ValidationContext] = None, ts_validation_context: Optional[certvalidator.context.ValidationContext] = None) → pyhanko.sign.validation.PdfSignatureStatus¶ Validate a PDF signature.
- Parameters
embedded_sig – Embedded signature to evaluate.
signer_validation_context – Validation context to use to validate the signature’s chain of trust.
ts_validation_context – Validation context to use to validate the timestamp’s chain of trust (defaults to
signer_validation_context
).
- Returns
The status of the PDF signature in question.
-
pyhanko.sign.validation.
validate_cms_signature
(signed_data: asn1crypto.cms.SignedData, status_cls: Type[StatusType] = <class 'pyhanko.sign.general.SignatureStatus'>, raw_digest: Optional[bytes] = None, validation_context: Optional[certvalidator.context.ValidationContext] = None, status_kwargs: Optional[dict] = None, externally_invalid=False)¶ Validate a detached CMS signature (i.e. a
SignedData
object).- Parameters
signed_data – The
asn1crypto.cms.SignedData
object to validate.status_cls – Status class to use for the validation result.
raw_digest – Raw digest, computed from context.
validation_context – Validation context to validate the signer’s certificate.
status_kwargs – Other keyword arguments to pass to the
status_class
when reporting validation results.externally_invalid –
If
True
, there is an external reason why the signature cannot be valid, but the remaining validation logic still has to be run.This option is considered internal API, the semantics of which may change without notice in the future.
- Returns
A
SignatureStatus
object (or an instance of a proper subclass)
-
exception
pyhanko.sign.validation.
ValidationInfoReadingError
¶ Bases:
ValueError
Error reading validation info.
-
exception
pyhanko.sign.validation.
SignatureValidationError
¶ Bases:
ValueError
Error validating a signature.
-
exception
pyhanko.sign.validation.
SigSeedValueValidationError
¶ Bases:
pyhanko.sign.validation.SignatureValidationError
Error validating a signature’s seed value constraints.
-
exception
pyhanko.sign.validation.
SuspiciousModification
¶ Bases:
ValueError
Error indicating a suspicious modification