Private IPFS and Swarm keys
Content addressing, Bitswap, swarm keys, and why a closed IPFS network needs its own directory.
What is the IPFS protocol?
The Interplanetary File System (IPFS) is a protocol designed to decentralize the traditional internet protocol. It is an open-source, peer-to-peer protocol that uses content addressing to distribute and store data across multiple nodes.
Its operation is based on three main pillars:
Data integrity: Since the hash is derived from the contents of the file, any modification to the file results in a different hash, ensuring data integrity.
Efficient data retrieval: Users can request data using its hash, enabling faster and more efficient retrieval of data from the nearest available node.
Elimination of data duplication: Content-based addressing inherently eliminates data duplication, as each unique file has a single hash.
NeoDrive runs on IPFS. It runs on a closed swarm, with the rules that implies, and with the pieces Neova added so a closed swarm can still find and serve files quickly.
The address is the content
On the ordinary web, a file has a location: a host and a path. If that host is gone, the address is empty.
On IPFS, a file has a fingerprint, the CID (Content Identifier). You ask for the content with that fingerprint. Any node that holds it can serve it. The receiving node recomputes the fingerprint. If a single byte was altered, the fingerprint no longer matches, and the content is rejected. Integrity is part of the address.
A large file is stored as a tree. Kubo splits it into blocks of about 256 KiB, hashes each block, and links the blocks in a Merkle DAG. The CID NeoDrive stores is the root of that tree. The same bytes always produce the same CID. Change one byte and the CID changes completely.
NeoDrive encrypts the file before that hashing happens, with a new random initialization vector every time. Two uploads of the same document become two different ciphertexts and two different CIDs. The network will not collapse them into one copy. That is what client-side encryption requires, and it is the behavior you want for private files.
Pinning keeps the file
When a node receives content, it lands in the repository. A pin marks it as content the node must keep. Removing the pin releases that obligation. Garbage collection later deletes unpinned blocks and returns disk space. The two events are separate, on Neova and on any Kubo node.
NeoDrive pins on upload and removes the pin on delete. Your quota follows the index, so it updates when you delete the file. The node’s disk follows garbage collection.
Bitswap moves the blocks
Once a CID is known, nodes exchange its blocks with Bitswap. That is the transfer. It works. The difficult question on a private network is the one Bitswap assumes someone else has already answered: which node has this CID?
Why the public directory is off
On public IPFS, a distributed hash table answers that question. The lookup takes several hops across an open network, and participation is public by design.
A Neova swarm is built to be the opposite of that openness.
Every node holds a swarm key. With LIBP2P_FORCE_PNET set, a node that lacks the key fails the handshake and never joins. Traffic stays inside the swarm. This mechanism, swarm key v1, has been the standard way to run a private IPFS network for years, and it does the job it was given: isolation.
It stops there. Anyone who holds the key is treated like every other holder. There is no per-node identity, no role, and no way to revoke one compromised machine without issuing a new key to the entire network.
There is a second consequence, and it is the one that blocks a usable drive. With the public DHT disabled, nothing in stock IPFS can answer “who has this CID?” A private network without a directory is a warehouse with the catalog taken off the wall.
How every Neova node is configured
Each node is Kubo in private mode. Bring-up applies the same baseline:
Public bootstraps are gone. The node does not serve the public DHT. Relays stay off. The node speaks to the Neova swarm.
Beside it, an announcer reads the local pin list about every 30 seconds and pushes new CIDs to the Private Indexer. A full re-announce runs about every 12 hours, which refreshes each record’s lifetime. That sidecar is the reason content on a private swarm can be found at all.
The directory is documented in Private Indexer. The read path is documented in Swarm Accelerator.
From a shared secret to a control plane
Swarm key v1 answers one question: does this node hold the network secret? For a swarm that partners operate, that question is too small. You also need to know which node it is, what it is allowed to do, when its credential expires, and how to remove it.
Swarm Keys v2 is Neova’s open answer, supported by the IPFS Foundation. It is a sidecar control plane on unmodified IPFS nodes:
a signed key carrying a network id, an expiration, and a role;
admission checked when the node joins;
rotation and revocation of one node, while the rest of the swarm keeps running;
roles you can enforce: storage, gateway, accelerator, operator;
a v1-compatible mode, so a live swarm can adopt v2 without a flag day.
The Neova swarm is isolated today with swarm key v1. v2 is the published control plane for identity, policy, and revocation. The grant, the scope, and the deliverables are in Open-source contribution.
The short version
IPFS gives you verifiable bytes and a way to exchange them. The swarm key gives you a closed set of nodes. A fast drive needs both, plus an index for the folders and a directory for the CIDs. NeoDrive is that combination.
Last updated