pyhanko.sign.timestamps module

Module to handle the timestamping functionality in pyHanko.

Many PDF signature profiles require trusted timestamp tokens. The tools in this module allow pyHanko to obtain such tokens from RFC 3161-compliant time stamping authorities.

class pyhanko.sign.timestamps.TimestampSignatureStatus(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, timestamp: datetime.datetime)

Bases: pyhanko.sign.general.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[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.

class pyhanko.sign.timestamps.TimeStamper

Bases: object

Class to make RFC 3161 timestamp requests.

dummy_response(md_algorithm)asn1crypto.cms.ContentInfo

Return a dummy response for use in CMS object size estimation.

For every new md_algorithm passed in, this method will call the timestamp() method exactly once, with a dummy digest. The resulting object will be cached and reused for future invocations of dummy_response() with the same md_algorithm value.

Parameters

md_algorithm – Message digest algorithm to use.

Returns

A timestamp token, encoded as an asn1crypto.cms.ContentInfo object.

validation_paths(validation_context)

Produce validation paths for the certificates gathered by this TimeStamper.

This is internal API.

Parameters

validation_context – The validation context to apply.

Returns

A generator producing validation paths.

request_cms(message_digest, md_algorithm)

Format the body of an RFC 3161 request as a CMS object. Subclasses with more specific needs may want to override this.

Parameters
  • message_digest – Message digest to which the timestamp will apply.

  • md_algorithm

    Message digest algorithm to use.

    Note

    As per RFC 8933, md_algorithm should also be the algorithm used to compute message_digest.

Returns

An asn1crypto.tsp.TimeStampReq object.

request_tsa_response(req: asn1crypto.tsp.TimeStampReq)asn1crypto.tsp.TimeStampResp

Submit the specified timestamp request to the server.

Parameters

req – Request body to submit.

Returns

A timestamp response from the server.

Raises

IOError – Raised in case of an I/O issue in the communication with the timestamping server.

timestamp(message_digest, md_algorithm)asn1crypto.cms.ContentInfo

Request a timestamp for the given message digest.

Parameters
  • message_digest – Message digest to which the timestamp will apply.

  • md_algorithm

    Message digest algorithm to use.

    Note

    As per RFC 8933, md_algorithm should also be the algorithm used to compute message_digest.

Returns

A timestamp token, encoded as an asn1crypto.cms.ContentInfo object.

Raises
  • IOError – Raised in case of an I/O issue in the communication with the timestamping server.

  • TimestampRequestError – Raised if the timestamp server did not return a success response, or if the server’s response is invalid.

class pyhanko.sign.timestamps.HTTPTimeStamper(url, https=False, timeout=5, auth=None, headers=None)

Bases: pyhanko.sign.timestamps.TimeStamper

Standard HTTP-based timestamp client.

request_headers()dict

Format the HTTP request headers.

Returns

Header dictionary.

timestamp(message_digest, md_algorithm)asn1crypto.cms.ContentInfo

Request a timestamp for the given message digest.

Parameters
  • message_digest – Message digest to which the timestamp will apply.

  • md_algorithm

    Message digest algorithm to use.

    Note

    As per RFC 8933, md_algorithm should also be the algorithm used to compute message_digest.

Returns

A timestamp token, encoded as an asn1crypto.cms.ContentInfo object.

Raises
  • IOError – Raised in case of an I/O issue in the communication with the timestamping server.

  • TimestampRequestError – Raised if the timestamp server did not return a success response, or if the server’s response is invalid.

request_tsa_response(req: asn1crypto.tsp.TimeStampReq)asn1crypto.tsp.TimeStampResp

Submit the specified timestamp request to the server.

Parameters

req – Request body to submit.

Returns

A timestamp response from the server.

Raises

IOError – Raised in case of an I/O issue in the communication with the timestamping server.

exception pyhanko.sign.timestamps.TimestampRequestError

Bases: OSError

Raised when an error occurs while requesting a timestamp.