{"id":10202,"library":"rfc3161-client","title":"RFC 3161 Client","description":"A Python client library for interacting with RFC 3161 compliant Timestamping Authorities (TSAs). It enables users to request timestamps for data and verify existing RFC 3161 timestamp responses. The library is actively maintained, with regular releases addressing bug fixes, security enhancements, and feature improvements, currently at version 1.0.6.","status":"active","version":"1.0.6","language":"en","source_language":"en","source_url":"https://github.com/trailofbits/rfc3161-client","tags":["cryptography","timestamp","rfc3161","security","verification"],"install":[{"cmd":"pip install rfc3161-client","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides core cryptographic primitives for hash operations, certificate handling, and signature verification.","package":"cryptography","optional":false}],"imports":[{"symbol":"TimestampRequest","correct":"from rfc3161_client import TimestampRequest"},{"symbol":"VerifierBuilder","correct":"from rfc3161_client import VerifierBuilder"},{"symbol":"HashAlgorithm","correct":"from rfc3161_client import HashAlgorithm"},{"symbol":"TimestampVerificationError","correct":"from rfc3161_client.exceptions import TimestampVerificationError"},{"symbol":"TSAResponseError","correct":"from rfc3161_client.exceptions import TSAResponseError"}],"quickstart":{"code":"import os\nimport hashlib\nfrom rfc3161_client import TimestampRequest, VerifierBuilder, HashAlgorithm\nfrom rfc3161_client.exceptions import TSAResponseError, TimestampVerificationError\n\n# Use a public TSA URL. For production, ensure this is a trusted service.\n# Example: http://timestamp.digicert.com or a URL from your trusted provider.\nTSA_URL = os.environ.get('RFC3161_TSA_URL', 'http://timestamp.digicert.com')\n\n# 1. Prepare data to be timestamped\nmessage = b\"This is the data to be timestamped.\"\nmessage_hash = hashlib.sha256(message).digest()\n\nprint(f\"Attempting to timestamp data using TSA: {TSA_URL}\")\n\n# 2. Request a timestamp from the TSA\ntry:\n    request = TimestampRequest(\n        tsa_url=TSA_URL,\n        hashed_message=message_hash,\n        hash_algorithm=HashAlgorithm.SHA256,\n    )\n    timestamp_response = request.get_timestamp_response()\n    print(\"Timestamp received successfully.\")\n\n    # 3. Verify the timestamp response\n    # For robust verification, provide 'trusted_root_certs' of the TSA.\n    # If not provided, the verifier attempts to build a chain from certs\n    # embedded in the response or system CAs where possible (less secure).\n    verifier = VerifierBuilder().build()\n    is_valid = verifier.verify(\n        timestamp_response=timestamp_response,\n        hashed_message=message_hash,\n        hash_algorithm=HashAlgorithm.SHA256,\n        # trusted_root_certs=[b\"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"],\n    )\n\n    if is_valid:\n        print(\"Timestamp verification successful.\")\n    else:\n        print(\"Timestamp verification FAILED.\")\n\nexcept TSAResponseError as e:\n    print(f\"Error from TSA: {e}\")\nexcept TimestampVerificationError as e:\n    print(f\"Timestamp verification error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to request an RFC 3161 timestamp for a message hash and then verify the received response. It highlights the basic flow: hashing data, sending a `TimestampRequest`, and using a `VerifierBuilder` to confirm the authenticity and integrity of the timestamp."},"warnings":[{"fix":"Upgrade to `rfc3161-client` `v1.0.6` or newer to ensure correct leaf certificate selection and secure timestamp verification.","message":"Prior to v1.0.6, the verification process could incorrectly pick the leaf certificate during chain validation, potentially allowing an attacker to spoof a timestamp's origin if they could modify the response. This was a critical security vulnerability in verification.","severity":"gotcha","affected_versions":"<= v1.0.5"},{"fix":"Upgrade to `rfc3161-client` `v1.0.4` or newer to align verification with RFC 3161, ensuring certificate chain validity is checked at the timestamp's creation time.","message":"Before v1.0.4, timestamp verification did not correctly use the timestamp's creation time as the reference for certificate chain validity. This could lead to incorrect validation of older timestamps, where a certificate might have expired relative to the current time but was valid at the time the timestamp was issued.","severity":"gotcha","affected_versions":"<= v1.0.3"},{"fix":"Update any type hints or code that directly references `_Verifier` to use the public `Verifier` class instead. Typical usage `VerifierBuilder().build()` remains compatible.","message":"The return type of `VerifierBuilder.build()` was changed from `_Verifier` (a private class) to `Verifier` in v1.0.2. While `_Verifier` was not intended for direct use, code that type-hinted or explicitly accessed private attributes of `_Verifier` may break.","severity":"breaking","affected_versions":"<= v1.0.1"},{"fix":"Ensure the TSA's certificate chain is correctly configured with the `id-kp-timeStamping` EKU. If you encounter verification failures, check the TSA certificate's EKUs and consult your TSA provider.","message":"As of v1.0.1, the `Verifier` enforces that the Extended Key Usage (EKU) in the TSA's signing certificate explicitly includes the `id-kp-timeStamping` OID. If a TSA's certificate lacks this OID, verification will now fail where it might have implicitly succeeded in older versions.","severity":"gotcha","affected_versions":"<= v1.0.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify that the `tsa_url` is correct and the TSA server is online and accessible from your environment. Check network connectivity and local firewall rules.","cause":"The Timestamping Authority (TSA) server is unreachable, the URL is incorrect, or a network issue (e.g., firewall) is blocking the connection.","error":"requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))"},{"fix":"Review the `TSAResponseError` message for specific details from the TSA. Ensure your `TimestampRequest` parameters (e.g., `hash_algorithm`) are supported by the TSA. Consult the TSA's documentation or status page.","cause":"The TSA responded with data that could not be parsed as a valid RFC 3161 timestamp response, or indicated an error internally. This can happen if the TSA is misconfigured or if the request was malformed.","error":"rfc3161_client.exceptions.TSAResponseError: An error occurred while parsing the response from the TSA."},{"fix":"For production, always supply `trusted_root_certs` for the TSA to the `VerifierBuilder`. Ensure the `hashed_message` and `hash_algorithm` passed to `verifier.verify()` precisely match the data that was timestamped. Review the detailed error message for specific verification failures.","cause":"The timestamp response could not be successfully verified. Common causes include an invalid signature, an untrusted certificate chain (e.g., missing root CA), a certificate that is not valid for timestamping, or a mismatch between the provided `hashed_message` and what's in the timestamp token.","error":"rfc3161_client.exceptions.TimestampVerificationError: ..."},{"fix":"Upgrade to `rfc3161-client` `v1.0.3` or newer to use the `verify_message` method. If upgrading is not immediately possible, manually compute the hash of your message and use the `verifier.verify(timestamp_response, hashed_message, hash_algorithm)` method.","cause":"The `verify_message` method, which allows direct verification against the original message instead of its hash, was added in `v1.0.2` and fully exposed in `v1.0.3`. This error occurs if you are attempting to use `verify_message` on an older version of the library.","error":"AttributeError: 'Verifier' object has no attribute 'verify_message'"}]}