As far back as 1994, Matt Blaze, renowned security researcher and author of CFS, wrote:
“As distributed computing systems grow in size, complexity and variety of application, the problem of protecting sensitive data from unauthorized disclosure and tampering becomes increasingly important. Cryptographic techniques can play an important role in protecting communication links and file data, since access to data can be limited to those who hold the proper key.”
Fast forward to today, and in Filecoin’s distributed storage system, one of his observations continues to stand out: keys for communication are distributed in space: two parties, two places, one moment. Simple. But keys for stored files are distributed in time and space: whoever encrypts today must be able to decrypt in ten years, and the person who made the key may not be around to help (and their laptop definitely won’t be!).
The classic answer was a central ‘locksmith’, a service that cuts every key and quietly keeps a copy for safekeeping. Blaze concluded that the locksmith model scales badly for file encryption. Thirty years later, it still does: indeed, with more files and more encryption, it’s even worse!
Over the past few weeks, we’ve been designing the encryption key layer for encrypted storage on Filecoin. We called it Keysmith, a key forge that fulfils all the needs of the privacy layer with no central locksmith.
📋 The brief
The job sounds simple: just encrypt your file before upload, and there you go! 1 line of JavaScript. Applications decide who may read what, so Keysmith’s only job is to produce the right key at the right moment. So what’s the problem? Or why not just use a password?
Remember, encryption key management scales across space and time. So Keysmith has to produce ALL the right keys, ANYWHERE you need them, FOREVER. I’ll bet you don’t even remember how many passwords you’ve forgotten!
If that general requirement isn’t hard enough, there were some additional specific constraints:
- Fully recoverable from the wallet alone. Lose the laptop, the browser storage, the notes and every backup. If you still have your wallet, you get all of your data back. No exported seed, no recovery file, no second password, no key server.
- No on-chain storage of keys or grants. A chain write is public, permanent and costs gas. A ledger of who may read what is exactly the metadata you don’t want carved into stone, especially as it will grow enormous over time!
- No special software. Owners use the wallets they already have. Recipients and agents hold ordinary secp256k1 keys. Storage providers verify with what they already run. Everything else runs in WebCrypto.
- Filecoin’s network remains open. Your data doesn’t have to be. Pieces are addressed by CID (Content Identifier), served by any provider that holds a copy, and cached, indexed, and moved around by repair. Encryption has to ride along with that, not fight it. A design that only works if you know which provider holds the bytes breaks as soon as the piece moves (eg, during a repair operation).
- Delegate without the owner online. Agents, CI jobs and session keys must be able to work, and delegate narrower access, while the funding wallet stays safely in the drawer.
Each constraint on its own is easy. Together they eliminated almost every obvious approach. A key server fails the first and third. On-chain access lists fail the second. A per-recipient key map inside every object fails the moment membership changes, because you have to rewrite every piece. Provider-enforced access control fails the fourth.
✍️ The raw material: one signature
If the wallet is the only thing you’re guaranteed to keep, the wallet has to be where every key comes from. So the root of everything is a single signature: the owner’s wallet signs a typed message naming the owner and some metadata, and HKDF turns that signature into a key. And if you need it back, the same wallet, same message, same signature, gives you back the same key. Nothing is stored because nothing needs to be.
And all this with widely supported mechanisms — Ethereum standard signing mechanisms, mainstream key derivation functions, and portable compact encoding. No novel crazy primitives to trip us up.
That key becomes the root of a tree, a top-level Group Key, from which file (or piece) encryption keys can be deterministically derived.
Deriving keys from signatures has a famous weakness: ‘deterministic’ is a convention, not a law. It would be quite unfortunate (for this use case) if signing the same message twice produced a different signature. RFC-6979 deterministic nonces are designed to address this problem, but it’s just a convention, not a reliably available tool, so we took extra care to ensure deterministic behaviour in each user’s environment before the user can upload a gigabyte of unrecoverable data!
We also skip the chainId and verifyingContract in the wallet signing operations. That may look odd to anyone used to EIP-712, but we can’t allow a redeployed contract to orphan a decade of encrypted data!
Just a couple of the many important technical lessons baked into Keysmith.
🌳 Drawing it out: the key tree
So why does the Group Key become the root of a tree? Keysmith is not simply answering a dumb data-at-rest requirement for anti-dumpster-diving or disk encryption. We also need to share small portions of the encrypted data with third parties, some of whom may not even have a wallet.
Crude data-at-rest techniques, such as using the same key to encrypt everything in a dataset, would be useless for sharing: we need something more subtle. And just having derived piece keys would also fail: it would be hard to share multiple pieces with someone, and impossible to share write access.
So instead, the signature-derived Group Key is the top of a tree, the leaves of the tree are individual keys for each piece, and all the nodes in between (‘groups’) are sharing groups that enable sessions and agents to work together on the data they rightly share, protected from prying eyes, and prevented from prying on others.
Groups are the intermediate nodes on the tree of keys between the all-powerful root Group Key and single-piece keys that unlocked the powerful read/write sharing semantics we needed. They allow delegation of a portion of the entire key space to non-owner actors, processes, or agents. A group key is derived from its parent’s key, so holding a group means you can access all data and sub-groups beneath it, but nothing above or beside it, allowing apps/users to limit access to different session keys/apps.
The group is a user/application-chosen access label (string) such as agent-memory or super-secret. Keysmith is unopinionated about how groups are used, what’s in them, or how deeply you nest them, other than the / separator, which lets you specify subgroups and finer divisions. They are highly flexible and can model metaphors like ‘subfolders’, ‘roles’, or ‘security classification’. Any of these metaphors (and more!) work, but it's very dangerous to mix them!
Examples:
- Clearance levels/MLS:
top-secretcontainstop-secret/secret, which containstop-secret/secret/official. A holder oftop-secret/secretcan grant an agent access totop-secret/secret/official, and they can happily operate in thatofficiallayer without being able to walk back up the tree. - Naive RBAC roles:
super-admincontainssuper-admin/admin, which containssuper-admin/admin/user. A holder ofsuper-admincan grant a session key access tosuper-admin/admin, and they can happily manage users without being able to walk back up the tree. - Groups: Top-level
teamscontainsteams/a-teamandteams/tiger-team. Agents can be given access to multiple disjoint sub-groups so they can work in restricted, defined areas. A holder of teams can see and delegate data for all the subgroups, while holders ofteams/a-teamandteams/tiger-teamare kept separate and cannot read or write each other’s data.
This may look counter-intuitive, starting at the most privileged and walking outward, or specifying the whole top-secret/secret/official rather than just official, but this enables verifiers to walk the entire path to look at and verify where the grant came from (all the way back to the root). The actual node key shared is only the last element of the path. So you can verify up, but only derive and decrypt down.
⚖️ The easy recovery trade-off
It is extremely elegant to recover all your data from a single wallet operation. But it comes at a price.
Any scheme where the wallet alone suffices for recovery is a scheme where eliciting the wallet’s signature alone suffices for compromise. A signature over a public, deterministic message is a bearer credential which can be stolen and misused. That’s not a flaw in the construction — it’s how recovery works — but it does mean you have to be careful with what you sign, and in what dApps. But then…everyone is careful with what they sign, you’d hope!
Defending against this is relatively straightforward, and depends on containment and visibility. A user can have as many trees as they like under different Group Keys, and a signature unlocks only one group at a time. When reconstructing the root of a tree from a signature, the Group Key ID appears in the signature prompt, and day-to-day operations should never ask for it, so seeing an unexpected prompt is itself a warning sign.
So there are 3 things to keep in mind to stay safe whilst enjoying the robustness and convenience of Keysmith recovery:
- Signing messages with your wallet is meaningful! Think about whether you need to do it and check the parameters displayed carefully
- If you separate different levels of sensitive data into different trees (i.e., different Group Key IDs), then a successful attacker can compromise only one set of keys at a time.
- An optional password can be added to the root key derivation step, giving you even more protection and a warning against phishing.
🔖 Hallmarks: stamping the piece’s origins at the forge
So far, so good. We have a system that can generate any key you need from a single wallet operation. Great! It’s a thousand-key keyring that fits in your pocket!
Now picture a piece of data sitting in front of you, and a thousand keys in your hand. Which one opens it? With no index anywhere, and the need to recover data years from now wherever we might find it, each piece has to carry enough information on its own to tell the recovery user how to decrypt it: or, in other words, which key to use.
The solution is the Filecoin Encryption Envelope (FEE): a standard way to package encrypted data on Filecoin so every piece carries labels saying how it was produced and protected. It’s structured as a world-readable header in integrity-protected COSE (the IETF’s established compact format for encrypted objects) followed by chunked encrypted bytes. This mix of sealed and open sections means you can open the part of the data you need, while any tampering with the label or the contents is caught.
That metadata (the COSE header) is what makes a key system like Keysmith workable over the long term. Files stored on Filecoin move about: they’re copied between providers, repaired and re-homed, or they may sit untouched for a decade. Keys and owners can change. Keeping up with all this would be borderline impossible, but with FEE the metadata travels with the piece, so years from now, when you need to read your file, it tells you exactly which key to use.
We stamp every FEE envelope with these metadata entries:
-
foc/own: the data owner’s address — ensures we know who owns it -
foc/gkid: the Group Key ID — ensures we know which ‘keyring’ to use -
foc/group: the group path/sub-group, such as finance — ensures we know which subset of keys to look in -
foc/salt: the 16-byte salt that names this piece — ensures we find the actual, unique key
Like a hallmark stamped on silver, the labels are readable by anyone, and they can’t be altered without detection: every chunk’s authentication tag covers them. They also travel with the bytes, wherever repair or replication takes them, for verification and identification whenever the data is wanted back.
In short:
- At the point of writing, your dataset metadata has everything you need to successfully encrypt a piece with the right keys and metadata
- At the point of reading, the piece has everything you need to successfully decrypt it again (as long as you have the right wallet!)
Which brings us to the scenario that matters. Somebody loses their laptop, browser storage, notes, and every backup. They have a wallet.
- Fetch. Download each piece by its CID from whichever provider holds it.
- Read the hallmarks. Take the metadata from the envelope header.
- Sign once. Sign an EIP-712 message to derive the Group Key.
- Derive. Use the Group Key, group, and salt to arrive at the piece key.
- Decrypt. Breathe a sigh of relief.
🤝 Sharing: cutting copies
Recovery was the hardest constraint, but sharing is where a key layer earns its living. We can’t have a centralized rights management system or access control gateway, so how can we share data without writing anything down or remembering any passwords?
The answer depends on whom you’re sharing with:
- If it’s a capable party with access to a session key or similar, or Filecoin utilities, simply ‘invite’ them to participate in a Keysmith group by wrapping the node key to their public key.
- If it’s an anonymous party or someone who can’t or won’t share a public key with you, or perhaps can’t run the filecoin-pin utility, then just send them a link, just like other cloud software!
So then, there are 2 main routes to follow:
🤖 1. A whole group, to an agent
The A-Team wants an agent that files and summarises its reports overnight. It needs to read and write everything under teams/a-team, and nothing else.
The owner does three things there:
- They fetch (by some channel) the public key of the intended recipient (usually another FWSS session key)
- They use their wallet to derive the Group Key
- They use the Group Key to derive the
teams/a-teamkey - They wrap the
teams/a-teamkey to the recipient’s public key, along with some simple metadata
The result is a grant of a few hundred bytes, which gives that session key only the narrow teams/a-team key.
From then on, the agent derives every piece key under teams/a-team for itself and reads and writes without ever needing to touch the wallet again. It can’t walk up the tree or sideways: Tiger Team’s data is as opaque to it as to a stranger. But all session keys with shared groups can collaborate freely in their allocated spaces.
Note that this route can deliver anything in the key tree, so if you want a read-only share of a single piece with strong recipient guarantees, this route is for you.
🔗 2. One piece, by share link
The data owner needs to share a single file (eg a contract or audit report) with an outside party: someone with no wallet, no account and no intention of installing any custom software or performing special key exchanges.
The owner does three things there:
- They authorise a session key for this agent for storage with any group that covers the target piece
- They use this granted session to forge a Share Link that encodes the piece key and retrieval CID into a single link, and generates a wrap key package to decrypt it.
- They share the link with their target recipient, making one choice:
- Encode everything (including the key block) as a single link: creates a public bearer credential that anyone can read anonymously.
- Encode the keyblock separately, and send it over a separate secure channel: the link is then useless without the key, enabling stronger privacy and security of the file if needed.
A link has to go somewhere, of course, so the Filecoin team has built a small content viewer app that understands this link format and can unpack and display the content of encrypted pieces. So, to share a piece with someone, simply send them a URL, which opens in this viewer and shows them what they need to see.
Again, even though this is on the public Internet, you can choose to detach and send the key separately, so you stay in control of your privacy. And because the viewer is content-addressed, the link fixes exactly which code will touch the key: nobody can swap in a different viewer behind the same URL, peek at your keys or private data, or record who is looking at what. Everything stays local on the recipient’s machine.
✅ So, did we solve it?
Yes!
- Recoverable from the wallet alone.
- Nothing secret or per-grant on-chain.
- No special software
- Filecoin’s openness intact
- Onward delegation without exposing the owner’s key.
- Everything remains content-addressed for verifiability and immutability
And it’s real. @filoz/keysmith 0.2.0 is released!
And for those inclined to dig under the covers and play with CBOR, or just see how all this really works, check out: https://fidlabs.github.io/keysmith-inspector/
Blaze’s locksmith was a central service that cut every key and kept a copy. Keysmith turns out to be the opposite: there’s no central workshop and no key cabinet, just a nimble, private smith in every wallet, forging the keys whenever they’re needed. No locksmith required.



