Reference

Federated key vaults.

By Gil Salu, Cyaxios

A data privacy vault holds your data. TN holds your keys. Sealed logs route to the reader vaults you choose, and no central publisher ever holds the keys that open them.

A federated key vault is a key store that coordinates with other key stores through the protocol rather than through a central authority. Each party runs its own vault and holds only the key material it is entitled to. The record travels as ciphertext, and the keys that open it move on a separate path, addressed to specific readers. No single vault sees every key, and no single operator can read the log.

How sealed logs reach federated readers

TN seals each log entry at the source. Sensitive fields are grouped, and each group is encrypted to a per-recipient key before the bytes hit disk. A reader who holds the key for a group decrypts that group and nothing else. A reader without the key sees ciphertext. The same record carries every reader's view at once.

Recipients are addressed by DID, a decentralized identifier that is itself a public key. Because the DID is the key, the publisher can wrap a group key for a named recipient without a lookup, a registry, or a network round-trip to a central directory. The wrapped key lands in that recipient's pickup area. The recipient's own vault unwraps it locally.

Seal per group

Each sensitive field group is encrypted under its own group key at write time. Public fields stay in the clear.

Wrap per recipient

The group key is wrapped to each reader's DID. One sealed record, many recipient-specific keys, no shared secret on the wire.

Unwrap per vault

Each reader's vault pulls its wrapped keys and unwraps them locally. The publisher never holds a reader's private key.

This is what makes the arrangement federated rather than centralized. The publisher decides who is on the grant list. The protocol distributes a separate key to each name on it. The publisher's vault never holds the private halves that open those keys, so it cannot read on a reader's behalf, and one reader cannot read another reader's group.

Who holds the keys in a federated setup?

No central party does. Each participant holds the keys for the groups they have been granted, and no more.

The private half of every identity is generated locally and never leaves the machine that made it. The vault holds a copy only in wrapped form. If the vault is breached, the attacker gets blobs they cannot open.

The threat model this addresses

Centralizing decryption keys is convenient and dangerous. A single key store that can read every party's data is one point of compromise, one point of legal reach, and one insider away from a breach. Federating the keys removes that point.

Central key custody

A central store that can decrypt is one subpoena, one stolen credential, or one bug away from exposing every reader at once. TN holds no key that opens a reader's data.

Insider risk

An operator with database access to a custodial store can read what it holds. A TN vault operator sees only ciphertext, so the privileged-insider path leads nowhere.

Residency violations

Each party can run its vault in its own jurisdiction. Key material for a region stays in that region. No central vault aggregates keys across borders.

The signature on each entry is always public, so origin is never hidden. Anyone can verify the record came from the publisher. What federation hides is the payload, and only from parties the publisher did not grant.

Where this maps to compliance

Federated key custody is not only a security posture. It lines up with several requirements that compliance teams already have to answer for.

Data residency. A self-hosted vault runs on infrastructure you choose, in the jurisdiction you choose. Key material generated in a region can stay in that region. Because the record is ciphertext to anyone without the key, the readable copy only ever exists where a granted key is unwrapped.

Cross-border transfers. The GDPR restricts transfers of personal data to third countries (GDPR Article 44). When a record crosses a border as ciphertext and the key never follows, the personal data that leaves your boundary is unintelligible to anyone but the named reader who holds the key. The grant, not the network path, decides who can read.

Key management. NIST SP 800-57 Part 1, Revision 5 sets out the lifecycle a key is meant to follow: generation, distribution, use, rotation, and destruction, with separation of duties so that no single role holds every key. Per-recipient key distribution and scheduled rotation implement that separation by construction. Recipients are addressed by DID under the W3C standards for decentralized identifiers and the did:key method, so identity is anchored in the key itself rather than in a central registry that could become a custody choke point.

A worked example

A payments service writes an order.placed entry. The order_id is public. The customer email is in a pii group. The card detail is in a payments group. Two readers are granted: a fraud team at one company and a finance team at another, each running its own vault in its own jurisdiction.

# publisher grants each reader the group it needs
$ tn add_recipient pii did:key:z6MkFraudTeam...
$ tn add_recipient payments did:key:z6MkFinanceTeam...

# the entry is written once, sealed per group
tn.log("order.placed", order_id=o.id, email=o.email, card_last4=o.card)

One sealed record is produced. The pii group key is wrapped to the fraud team's DID, the payments group key to the finance team's DID. Granting each reader mints a per-recipient .tnpkg kit carrying only that reader's wrapped group key.

# on the fraud team's machine, its own vault
$ tn absorb fraud-team-pii.tnpkg

# on the finance team's machine, a different vault
$ tn absorb finance-team-payments.tnpkg
    
Each kit installs the reader's group key into that reader's own
    vault, and the same key can later be picked up on
    tn wallet sync. The fraud team reads the email and sees
    the card field as ciphertext. The finance team reads the card field
    and sees the email as ciphertext. The same entry reached two
    independent reader vaults,
    each in its own region, and no vault ever held a key that opened the
    other reader's group. Revoke either reader and a
    rotation mints a fresh group key for the
    remaining members. From the next entry on, the revoked party sees
    ciphertext again.


    
Per project, non-custodial, self-hostable

    
Each TN project has its own vault and its own identity. Key
    material is isolated per project. A grant change or rotation in one
    project's vault has no effect on any other project's vault.

    
The vault holds ciphertext only. The unlock secret stays on the
    user's machine, encrypted at rest. Keys are recoverable on a new
    machine via tn wallet restore, authenticated with the
    device key or a recovery mnemonic. If the original machine is lost,
    that restore brings up a fresh install with the same key
    material.

    
The hosted vault is one deployment option. The same vault server
    runs on any infrastructure under the same protocol, including
    on-premise hardware and private VPS deployments. Federation happens
    at the protocol layer. Vaults coordinate through DIDs and group keys,
    and the TN library is agnostic to which vault holds the upstream
    backups for any given counterparty.


    

      
What the vault never sees

      
Your data. Your cleartext. Your unlock secret. The vault stores
      encrypted key backups, encrypted by your local unlock secret, and
      stages wrapped keys for pickup. It can open none of them.

    


    ← Back to the vault