Key rotation

By Gil Salu, Cyaxios

Rotation is how you change who can read new entries. Drop a teammate, replace a partner, or freshen a group on your own cadence. One command does it.

What rotation does

When you rotate a group, the vault generates a new key for that group and hands it only to the readers still on your list. From the next entry onward, anyone you removed sees ciphertext again. Entries written before the rotation stay readable to whoever had access at the time.

How rotation works under the hood

A TN log is append-only. Each entry is sealed at write time to the group key that was current at that moment, and the entry is signed so anyone can prove it came from you. Rotation does not rewrite, re-encrypt, or replay the existing log. It mints a fresh group key and binds the next entry to it. The chain of past entries is left exactly as it was.

The mechanism is a key change, not a data change. Each field group carries its own key. When you rotate the payments group, the vault generates a new key for that group, wraps it once per remaining reader against that reader's public identity, and stages those wrapped copies for pickup. Nobody emails a secret. Each reader pulls their own wrapped copy and unwraps it locally with a private key that never leaves their machine.

This gives two distinct access directions, and the distinction is the whole point:

• Backward access stands. A reader who held the old key can still open every entry written under it. Those grants are already in their hands. Rotation does not reach back and re-seal history.
• Forward access stops. A removed reader is not handed the new key. From the first entry written after the rotation, that group reads as ciphertext for them, and stays that way for every entry after.

The boundary is the rotation point. Rotation is the single act that drops a reader: the survivors get fresh kits, the dropped reader gets none, and from that entry forward the group is dark to them. There is no separate remove step, and no claw-back of what they already read.

What happens to old log entries when a key rotates?

Nothing. They are not touched. An entry sealed under the previous key remains sealed under that key, and anyone who held that key keeps the ability to open it. This is deliberate. An audit trail that silently became unreadable after a rotation would not be an audit trail. The record an auditor saw last quarter reads the same way this quarter.

Rotation also does not claw back plaintext a reader already decrypted and copied. Once a value has been opened and written somewhere else, it is out of the protocol's reach. Rotation governs who can open new entries, not what a reader has already pulled into their own systems.

The threat model

Two cases drive most rotations: a departed contractor and a compromised partner key. The semantics are the same for both.

A contractor leaves

A contractor had a grant on the payments group for the length of an engagement. The engagement ends. You rotate the group, which hands fresh kits to the survivors and none to the contractor. After the rotation:

• They cannot decrypt any payments field written after the rotation. The new key was never wrapped for them.
• They can still open entries written during their engagement, using the key they already held. That access was granted in good faith and is not retroactively withdrawn.
• They can still hold any plaintext they decrypted and exported while the grant was live. Rotation does not reach copies that already left the log.

A partner key is compromised

Suppose a partner reports that a laptop holding their reader key was lost or that the key leaked. The attacker now holds a key that opens past entries. Rotation contains the blast radius rather than undoing it:

• The leaked key keeps opening the historical entries it could already open. That exposure is fixed at the moment of leak and rotation cannot reverse it.
• Every entry written after the rotation is sealed to a fresh key the attacker does not have. The leak stops compounding from the rotation point forward.
• The signature on every entry is unchanged and still public, so forensic review can still establish exactly which entries existed before the rotation and prove they came from you.

A worked example

The payments group has a publisher, a finance teammate, and an outside auditor named Acme. The engagement with Acme ends. To drop Acme, you rotate the group: the survivors get fresh kits, Acme gets none.

# 1. rotate payments so only the survivors get a fresh kit
$ tn rotate payments

# 2. write a new entry, now sealed under the fresh key
$ tn log --event invoice.settled --field invoice_id=inv_5512 --field amount=900.00

Two facts hold after this sequence. The new invoice.settled entry is out of reach for Acme: it was sealed to the fresh key, which was never wrapped for them. Every entry Acme could read during the engagement still opens for them with the older key they already hold. New entries are dark; old grants stand. That is the entire contract.

The CLI

1. Add a reader

   Mint a reader kit for a recipient and write their .tnpkg. There is no remove verb. To drop a reader, rotate the group (next step) so the survivors get fresh kits and the departing reader gets none.

   # add a reader to a group
   $ tn add_recipient payments did:key:z6MkPartnerAcme...

2. Rotate the group

   One command. The vault mints a new group key and emits a fresh .tnpkg kit to every surviving reader. Omit the group name to rotate all non-internal groups at once.

   # rotate the payments group
   $ tn rotate payments
   
   # rotate every non-internal group
   $ tn rotate

3. Your readers sync

   Each surviving reader picks up their fresh kit on the next tn wallet sync, or installs a delivered .tnpkg with tn absorb. No manual distribution, no email attachments, no chat messages with secrets.

   # on the reader's machine: pick up fresh kits
   $ tn wallet sync
   
   # or install a delivered kit directly
   $ tn absorb payments.tnpkg

4. Verify (optional)

   The rotation lands as an attested entry. Read it back, and inspect the group's surviving recipients.

   # read the log, including the rotation entry
   $ tn read
   
   # inspect groups and their recipients
   $ tn show profiles

What removed readers see

They can still authenticate to the vault. They can still read entries they already had keys for. What they cannot do is decrypt anything written after the rotation. Their pickup area shows nothing new for this group.

Why auditors care about rotation

Key rotation is not a TN invention. It is a named control in every serious key-management standard, and a rotation log is the kind of evidence an auditor can verify directly.

• NIST SP 800-57 Part 1 frames every key as having a lifecycle, with a defined cryptoperiod and a controlled transition to a successor key. Rotating a group key and retiring its predecessor is exactly the lifecycle this guidance describes.
• PCI DSS v4.0 Requirement 3 covers protection of stored account data and calls for documented key-management procedures, including key rotation at the end of a cryptoperiod and retirement of keys that are weakened or suspected of compromise. The contractor and compromised-key cases above map straight onto that requirement.
• GDPR Article 32 requires security of processing appropriate to the risk, naming encryption and the ability to restore and control access. Rotating a group to drop a reader is a concrete, demonstrable access control over personal data carried in your logs.

Because every rotation lands in the same attested log as the entries it governs, the evidence is the record itself. You do not assemble a separate report to show that a key was retired on a given date. tn read reads it back.

Rotate on your own cadence

Rotation is on demand. You rotate when a reader leaves, when a key is suspected of compromise, or on whatever hygiene cadence you set for yourself. There is no built-in scheduler: run tn rotate against a group when you want a fresh key, or tn rotate with no group to refresh every non-internal group at once. Wire it into your own cron or CI if you want it to happen unattended.

# refresh the payments group on demand
$ tn rotate payments

# a periodic hygiene pass over every non-internal group
$ tn rotate

Further reading

On this site:

• What is DRM for logs? the mental model rotation fits into.
• Federated key vaults where the wrapped keys live and how readers pull them.
• Field-level encryption why each group carries its own key.

Standards referenced above:

• NIST SP 800-57 Part 1 Rev. 5, recommendation for key management: key lifecycles and cryptoperiods.
• PCI Security Standards document library, home of PCI DSS v4.0 and Requirement 3 on stored-data key management.
• GDPR Article 32, security of processing.