Timestamps and anchors

What this is about

A hash chain in your own database can be recomputed by anyone who controls the database. They change an entry and recompute all following hashes consistently. The chain alone does not notice.

A timestamp helps against this: a signed statement that a certain hash already existed at a certain time. At fixed intervals CRMS has the latest entries of all journals stamped. This is called anchoring, and the result is an anchor.

How the journals are built is described in The two hash chains.

An anchoring pass

• How often: every CODAMAI_CRMS_ANCHOR_INTERVAL (default PT1H, so hourly). The first pass starts one minute after the start.
• Which tenants: all that CIAS knows, suspended and closed ones too. Their journals have to stay anchored as well.
• If a tenant cannot be reached: it is left out and the others are anchored. The next pass tries again.
• Who runs it: every instance with CODAMAI_CRMS_SCHEDULING_ENABLED=true (default). With several instances, leave it on in exactly one.

The Merkle tree

A Merkle tree combines many hashes into a single one, the root. Two hashes at a time are hashed together until only one is left. So one timestamp is enough for all tenants, however many there are.

flowchart BT
  A["Leaf: system"] --> AB["Node"]
  B["Leaf: acme"] --> AB
  C["Leaf: beta"] --> CD["Node"]
  D["Leaf: gamma"] --> CD
  AB --> R["Root → timestamp"]
  CD --> R

• A leaf is the canonical JSON {journal, sequence, hash} of the journal head. The leaves are sorted by journal, so the same heads always give the same root.
• The tree follows RFC 6962: leaves get the byte 0x00 before hashing, nodes 0x01.
• A journal’s proof path is the list of neighbor hashes on the way from the leaf to the root. With it, a tenant shows that its journal head is inside the stamped root, without seeing the other journals.

What the anchor check finds

The anchor check takes a journal’s newest proof path and checks it station by station. Together with verifying the chain itself, it also finds a journal that was recomputed consistently.

These results are keys in a check result, not error answers.

The timestamp authority

A timestamp authority (TSA) signs hashes together with a time. CRMS brings its own, which works according to RFC 3161:

• Its key comes as a PKCS#12 file, Base64 encoded, from CODAMAI_CRMS_TSA_KEYSTORE, the password from CODAMAI_CRMS_TSA_KEYSTORE_PASSWORD. Without a key, CRMS does not start.
• The certificate must carry the usage timeStamping, marked as critical. Otherwise CRMS does not start.
• The time comes from the system clock. Keep it synchronized, for example with NTP.
• Every timestamp has a random 128-bit serial number and carries the certificate it was signed with.

Which timestamp CRMS trusts

A timestamp is verified against the certificate that signed it. That certificate must be trusted, and it must have been valid at the time of the stamp.

The trust list is CODAMAI_CRMS_TSA_TRUSTED_CERTIFICATES: PEM certificates one after the other, or that PEM as Base64 if the environment takes no line breaks. The certificates are public, but they always come from the configuration, never from the database. Otherwise the database administration could add a certificate of its own and stamp a rewritten history.

Expiry of the certificate

Replacing the key

With a certificate authority of your own, you list that authority’s certificate instead. Then every timestamping certificate it issues is accepted, and a replacement needs no change to the list.

An overview of the variables is in Configuration.

Pitfalls

Next

• The two hash chains
• The seal
• Verify and read