rfc3161-client

rfc3161-client is a Python library implementing the Time-Stamp Protocol (TSP) described in RFC 3161.

It is composed of three subprojects:

• 🦀 tsp-asn1: A Rust crate using rust-asn1 to create the types used by the Time-Stamp protocol. This crate depends on rust-asn1 and cryptography to minimize the amount of duplicated code. While it is usable as a standalone crate, this is not officially supported. Drop us a message if you are interested in using it.
• 🦀 rfc3161-client: Another Rust crate that provides Python bindings to the tsp-asn1 crate using PyO3.
• 🐍 rfc3161-client A Python library using the crate above to provide a usable API to create Timestamp Request and read Timestamp Response.

Goals and anti-goals

• This library should be correct and provide an accurate implementation of protocol described in the RFC 3161.
• This library does not perform any network activity, it simply provides primitive to build and verify objects. Network activity must be handled separately.

Usage

There are two parts to timestamping: retrieving + verifying the timestamp.

1. Retrieving a timestamp

The below code uses requests to get the timestamp from the Identrust TSA server:

# /// script
# dependencies = [
#   "requests",
#   "rfc3161-client",
# ]
# ///
import requests
from rfc3161_client import (
    decode_timestamp_response,
    TimestampRequestBuilder,
    VerifierBuilder,
    VerificationError,
)

# the data to sign. Could be a hash or any message. Should be bytes
message = b"Hello, World!"

# build the timestamp request
timestamp_request = (
    TimestampRequestBuilder().data(message).build()
    # Note: you could also add .hash_algorithm(XXX) to specify a specific hash algorithm
    # this means the algorithm check in the next section is not necessary
)

# TSA servers must be RFC 3161 compliant (see https://github.com/trailofbits/rfc3161-client/issues/46
# for a list of working servers)
tsa_server = "http://timestamp.identrust.com"

# make the request, remember to set content-type headers appropriately
response = requests.post(
    tsa_server,
    data=timestamp_request.as_bytes(),
    headers={"Content-Type": "application/timestamp-query"},
)
response.raise_for_status()

# if successful, should give a valid TimeStampResponse object
timestamp_response = decode_timestamp_response(response.content)

Verifying a timestamp

The second part is to verify the timestamp, this is done against a set of root certificates. In this example, we'll Mozilla's list of root certs provided in the certifi package:

import certifi
from cryptography import x509
import hashlib


# get the message hash (hash method depends on what the TSA used)
message_hash = None
hash_algorithm = timestamp_response.tst_info.message_imprint.hash_algorithm
if hash_algorithm == x509.ObjectIdentifier(value="2.16.840.1.101.3.4.2.3"):
    message_hash = hashlib.sha512(message).digest()
elif hash_algorithm == x509.ObjectIdentifier(value="2.16.840.1.101.3.4.2.1"):
    message_hash = hashlib.sha256(message).digest()

# get trusted root certs from certifi
with open(certifi.where(), "rb") as f:
    cert_authorities = x509.load_pem_x509_certificates(f.read())

# for each of the root certs we have, try to verify the TSR with it
root_cert = None
for certificate in cert_authorities:
    verifier = VerifierBuilder().add_root_certificate(certificate).build()
    try:
        verifier.verify(timestamp_response, message_hash)
        root_cert = certificate
        break
    except VerificationError:
        continue

# if successful, the TSR was verified and we should have the root cert that signed this TSR :)
print("Here's the root cert that signed your TSR:")
print(root_cert)

License

Copyright 2024 Trail of Bits

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Authors

Trail of Bits