> For the complete documentation index, see [llms.txt](https://docs.neova.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neova.io/neova/peer-to-peer-network/private-ipfs-and-swarm-keys.md).

# 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:

```bash
ipfs bootstrap rm --all
ipfs config Routing.Type dhtclient
ipfs config --bool Swarm.RelayClient.Enabled false
ipfs config --bool Swarm.RelayService.Enabled false
```

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.