pyhanko.sign.validation.dss module

class pyhanko.sign.validation.dss.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() DictionaryObject
Returns

A PDF dictionary representing this VRI entry.

class pyhanko.sign.validation.dss.DocumentSecurityStore(writer: BasePdfFileWriter, certs=None, ocsps=None, crls=None, vri_entries=None, backing_pdf_object=None)

Bases: object

Representation of a DSS in Python.

property modified
static sig_content_identifier(contents) 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, *, certs=(), ocsps=(), crls=())

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). If None, only embed the data into the DSS without associating it with any VRI.

  • certs – Certificates to add.

  • ocsps – OCSP responses to add.

  • crls – CRLs to add.

as_pdf_object()

Convert the DocumentSecurityStore object to a python dictionary. This method also handles DSS updates.

Returns

A PDF object representing this DSS.

load_certs()

Return a generator that parses and yields all certificates in the DSS.

Returns

A generator yielding Certificate objects.

as_validation_context(validation_context_kwargs, include_revinfo=True) 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: PdfHandler) 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 supply_dss_in_writer(pdf_out: BasePdfFileWriter, sig_contents, *, certs=None, ocsps=None, crls=None, paths=None, validation_context=None, embed_roots: bool = True) DocumentSecurityStore

Add or update a DSS, and optionally associate the new information with a VRI entry tied to a signature object.

You can either specify the CMS objects to include directly, or pass them in as output from pyhanko_certvalidator.

Parameters
  • pdf_out – PDF writer to write to.

  • sig_contents – Contents of the new signature (used to compute the VRI hash), as a hexadecimal string, including any padding. If None, the information will not be added to any VRI dictionary.

  • certs – Certificates to include in the VRI entry.

  • ocsps – OCSP responses to include in the VRI entry.

  • crls – CRLs to include in the VRI entry.

  • 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.

  • embed_roots

    New in version 0.9.0.

    Option that controls whether the root certificate of each validation path should be embedded into the DSS. The default is True.

    Note

    Trust roots are configured by the validator, so embedding them typically does nothing in a typical validation process. Therefore they can be safely omitted in most cases. Nonetheless, embedding the roots can be useful for documentation purposes.

    Warning

    This only applies to paths, not the certs parameter.

Returns

a DocumentSecurityStore object containing both the new and existing contents of the DSS (if any).

classmethod add_dss(output_stream, sig_contents, *, certs=None, ocsps=None, crls=None, paths=None, validation_context=None, force_write: bool = False, embed_roots: bool = True, file_credential: Optional[SerialisedCredential] = None)

Wrapper around supply_dss_in_writer().

The result is applied to the output stream 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), as a hexadecimal string, including any padding. If None, the information will not be added to any VRI dictionary.

  • certs – Certificates to include in the VRI entry.

  • ocsps – OCSP responses to include in the VRI entry.

  • crls – CRLs to include in the VRI entry.

  • paths – Validation paths that have been established, and need to be added to the DSS.

  • force_write – Force a write even if the DSS doesn’t have any new content.

  • validation_context – Validation context from which to draw OCSP responses and CRLs.

  • embed_roots

    New in version 0.9.0.

    Option that controls whether the root certificate of each validation path should be embedded into the DSS. The default is True.

    Note

    Trust roots are configured by the validator, so embedding them typically does nothing in a typical validation process. Therefore they can be safely omitted in most cases. Nonetheless, embedding the roots can be useful for documentation purposes.

    Warning

    This only applies to paths, not the certs parameter.

  • file_credential

    New in version 0.13.0.

    Serialised file credential, to update encrypted files.

async pyhanko.sign.validation.dss.async_add_validation_info(embedded_sig: EmbeddedPdfSignature, validation_context: ValidationContext, skip_timestamp=False, add_vri_entry=True, in_place=False, output=None, force_write=False, chunk_size=4096, embed_roots: bool = True)

Add validation info (CRLs, OCSP responses, extra certificates) for a signature to the DSS of a document in an incremental update. This is a wrapper around collect_validation_info().

Parameters
  • embedded_sig – The signature for which the revocation information needs to be collected.

  • validation_context – The validation context to use.

  • skip_timestamp – If True, do not attempt to validate the timestamp attached to the signature, if one is present.

  • add_vri_entry – Add a /VRI entry for this signature to the document security store. Default is True.

  • output – Write the output to the specified output stream. If None, write to a new BytesIO object. Default is None.

  • in_place – Sign the original input stream in-place. This parameter overrides output.

  • chunk_size – Chunk size parameter to use when copying output to a new stream (irrelevant if in_place is True).

  • force_write – Force a new revision to be written, even if not necessary (i.e. when all data in the validation context is already present in the DSS).

  • embed_roots

    Option that controls whether the root certificate of each validation path should be embedded into the DSS. The default is True.

    Note

    Trust roots are configured by the validator, so embedding them typically does nothing in a typical validation process. Therefore they can be safely omitted in most cases. Nonetheless, embedding the roots can be useful for documentation purposes.

Returns

The (file-like) output object to which the result was written.

async pyhanko.sign.validation.dss.collect_validation_info(embedded_sig: EmbeddedPdfSignature, validation_context: ValidationContext, skip_timestamp=False)

Query revocation info for a PDF signature using a validation context, and store the results in a validation context.

This works by validating the signer’s certificate against the provided validation context, which causes revocation info to be cached for later retrieval.

Warning

This function does not actually validate the signature, but merely checks the signer certificate’s chain of trust.

Parameters
  • embedded_sig – Embedded PDF signature to operate on.

  • validation_context – Validation context to use.

  • skip_timestamp – If the signature has a time stamp token attached to it, also collect revocation information for the timestamp.

Returns

A list of validation paths.