Outside timestamps
A workspace may have an RFC 3161 timestamp authority sign its checkpoints. A timestamp token over a checkpoint is the authority's signed statement that the log had that head at the token's time. Two things follow, and nothing more:
- every record the checkpoint covers (the leaves
0tosize - 1of the log, log.md) existed by that time; - a history changed afterwards has another head at that size, which the token does not fit, whoever signed the changed checkpoint.
A token says nothing about records after its checkpoint, and nothing about whether what a record says is true. The time is the authority's.
Vectors: 21-timestamp, 22-bundle-timestamps, 23-segments.
The imprint
A token is over the SHA-256 of the checkpoint's text: the three lines a checkpoint note signs, each ended by a line feed,
<origin>
<size>
<root, standard base64>
and not the note's signature lines. This hash is the token's message imprint; its hash algorithm is SHA-256.
The token
A token is the TimeStampToken of RFC 3161: a DER-encoded CMS ContentInfo whose content is SignedData (RFC 5652) with the encapsulated content type id-ct-TSTInfo (1.2.840.113549.1.9.16.1.4). Where it is a file, the file is those DER bytes (the form openssl ts -reply -token_in reads); where it is a JSON member, it is their standard base64.
A verifier refuses a token unless all of this holds:
- Form. The bytes are one DER value with nothing after it, at most 64 KiB.
SignedDatahas version 3, exactly oneSignerInfo, and itsdigestAlgorithmsname the signer's digest algorithm and no algorithm outside SHA-256, SHA-384 and SHA-512. An algorithm identifier's parameters are absent or NULL (RSASSA-PSS has its own). The signer info has version 1 with an issuer and serial number, or version 3 with a subject key identifier, and it has signed attributes. Every entry ofcertificatesis an X.509 certificate that parses, or another form under a context tag 0 to 3, which is skipped; every entry ofcrlsis a certificate revocation list that parses, or another form under the context tag 1. Revocation lists are not otherwise used. - Content.
TSTInfohas version 1; itsmessageImprintnames SHA-256 and holds the imprint above.genTimeis a UTCGeneralizedTime, with or without fractions of a second: the token's time. - Signed attributes. The
content-typeattribute isid-ct-TSTInfo; themessage-digestattribute is the digest, under the signer's digest algorithm, of theTSTInfobytes. When the token has asigning-certificate(1.2.840.113549.1.9.16.2.12) orsigning-certificate-v2(…2.47) attribute, its first certificate hash is the hash of the signer's certificate. - Signer. The signer's certificate is the one the signer info names: among the certificates the token carries when it carries any, otherwise among the pinned ones.
- Signature. The signature checks, with the signer certificate's key, over the DER encoding of the signed attributes as a
SET OF(the bytes of the[0]field with the tag byte0x31). Accepted: RSA PKCS #1 v1.5 and RSASSA-PSS, ECDSA, each with SHA-256, SHA-384 or SHA-512, and Ed25519. - Trust. The signer's certificate has the extended key usage
id-kp-timeStamping, the token's time is within its validity, and it is one of the pinned certificates, byte for byte, or chains to one through the certificates the token carries, with every certificate of the chain valid at the token's time and allowed for timestamping.
Certificates are judged at the token's time, never at the time of the check: a token outlives its signer's certificate. Revocation is not checked; an offline verifier cannot ask. Whether an authority's key was safe when it signed is a question for the authority's own records.
Pinned certificates
The reader takes the authority's certificate from the authority: its own timestamping certificate, or the root it chains to. Never from the export. antler-verify --tsa-cert <file> pins a file of PEM certificates, or one DER certificate.
With a certificate pinned:
- every token an export carries must verify (steps 1 to 6), each against the checkpoint it is over; one that does not is a failure;
- an export that carries no token at all is a failure: whoever pins an authority expects its tokens, and their absence would otherwise hide that they were removed.
With none pinned, steps 1 and 2 are still made against the checkpoint (a token over another head is a failure), the signature and the signer are not checked, and the verifier says the tokens prove nothing yet. The export's outcome is otherwise unchanged.
In a bundle
A bundle's manifest (bundle.md) lists its tokens:
"timestamps": [{"size": 8, "file": "timestamps/8.tsr"}]
size is the size of the checkpoint the token is over and file the token's path in the bundle. For each entry: the file must be in the bundle; the bundle must hold a checkpoint of that size that verifies (step 1 of checking a bundle), which the bundle's consistency proofs tie to its newest; and the token must check against that checkpoint.
A bundle of a window carries the tokens whose time is at or after the window's start, up to and including the first one at or after its end.
In delivered segments
A segment's trailer (segments.md) carries tokens with the checkpoint each is over. See there.
What a verifier reports
How many tokens verified, the size and time of the oldest and the newest, and how many records after the newest timestamped checkpoint have no outside timestamp. Those records are not suspect; nothing outside the workspace has yet said when they existed.