IPFS Private Networks: Swarm Keys Explained

An IPFS private network is a different, more fundamental restriction than anything else covered in this series: instead of controlling who can find or retrieve specific content, it controls who a node can connect to at the network level at all. A swarm key, a pre-shared secret every peer in the network needs before it can even open a connection, is what enforces that boundary. This is also a useful article for clearing up a common mix-up: pinning content and making a network private are two completely unrelated things.

TL;DR:

• A private IPFS network restricts connections at the transport level using a swarm key, a pre-shared secret (PSK) that every participating peer must have before it can connect to any other peer in that network
• This is enforced by libp2p itself, the networking layer covered earlier in this series, not by anything content-addressing or DHT-specific; a peer without the right key simply can't establish a connection at all
• Joining a private network means placing the shared swarm.key file in a node's repo; a private network also can't rely on the public network's default bootstrap peers, since those aren't part of it, so it needs its own
• Private networking and pinning solve entirely different problems: pinning controls whether content stays available on whichever network a node participates in, a private network controls who can participate in that network to begin with
• AIOZ Pin operates on the public IPFS network by design, since a pinning service's entire value proposition, wide discoverability through the public DHT and gateway access, depends on being reachable by anyone, the opposite goal of a private network

Two Completely Different Kinds of Restriction

Everything else in this series describes mechanisms that assume an open, public IPFS network: any peer can, in principle, connect to any other peer, and the DHT and Bitswap mechanics already covered handle discovery and retrieval on top of that open connectivity. A private network changes the assumption underneath all of it: connectivity itself becomes restricted, so only peers holding the right shared secret can talk to each other at all, regardless of what CIDs they're asking about.

The Swarm Key: A Pre-Shared Secret Per Network

The mechanism is a swarm key, a pre-shared key (PSK) that's the same across every peer meant to participate in one private network. It lives in a swarm.key file in a node's IPFS repository, and a node without the matching key can't establish a libp2p connection to any peer inside that network, full stop. This is enforced beneath the application layer entirely, at the connection-establishment step covered in this series' libp2p article, before any DHT lookup, Bitswap exchange, or content request could even begin. A peer holding the wrong key, or no key, isn't served an error message about a specific CID, it simply can't open a connection in the first place.

Setting One Up: Sharing the Key, Replacing the Bootstrap Peers

Joining an existing private network means getting the swarm.key file from someone already in it and placing it in the correct repo location. One consequence follows directly from the private network's whole purpose: the default bootstrap peers every public IPFS node starts with are, by definition, not part of a private network, so a private deployment can't rely on them to find its first connections and needs its own set of bootstrap peers running inside the same private network instead.

Why This Exists: Permissioned Deployments

The public IPFS network's open connectivity is a feature for the use cases this series has covered throughout, wide discoverability, censorship-resistant hosting, retrieval from any peer willing to serve content. It's the wrong fit for a use case that wants the opposite: an organization running IPFS internally for data that should never be reachable from, or discoverable by, the public internet at all. A private network with a swarm key gives that deployment IPFS's content-addressing, verification, and DAG mechanics, everything else this series covers, without any public connectivity at all, since connectivity itself is gated before any of those mechanics get a chance to run.

The Common Mix-Up: Private Networks vs. Pinning

It's worth being direct about a confusion this topic invites: pinning, covered throughout this series, has nothing to do with who can see or access a file. Pinning controls whether a specific piece of content stays available on whichever network a node is already part of, public or private. A private network controls a completely different question, who can even join that network at all. Pinning a file on the public IPFS network does not make it private; it makes it more likely to stay retrievable by anyone who can already reach the public network, which is the opposite of a private network's goal.

Where This Fits AIOZ Pin

AIOZ Pin runs entirely on the public IPFS network, and that's a deliberate fit for what a pinning service is actually for: the DHT discoverability and gateway access this series has covered throughout only deliver value if the content is reachable by whoever needs it, which is the direct opposite of what a private network with a swarm key is designed to restrict. Someone with a genuine need for permissioned, non-public IPFS connectivity is solving a different problem than AIOZ Pin's persistence and gateway features address, and would be looking at a private-network deployment instead, not a public pinning service.

Frequently Asked Questions

What is an IPFS private network? A deployment where peers can only connect to each other if they hold a shared secret key (the swarm key), restricting connectivity at the network level rather than controlling access to specific content.

What is a swarm key? A pre-shared key (PSK) placed in a node's swarm.key file. Every peer in a private network needs the same key to establish connections with other peers in that network at all.

Does a private network protect specific files, or something else? Something else entirely. It restricts which peers can connect to the network in the first place, at the libp2p connection layer, before any content-specific request happens.

Can a private network use the default IPFS bootstrap peers? No. The default bootstrap peers belong to the public network and aren't part of any private one, so a private deployment needs its own bootstrap peers running inside the same private network.

Does pinning a file on the public network make it private? No. Pinning only affects whether content stays available on whatever network it's on; it has no effect on who can connect to or discover that network in the first place.

Does AIOZ Pin support private IPFS networks? AIOZ Pin operates on the public IPFS network, which is what makes its discoverability and gateway access work. A private, permissioned network is a different deployment model solving a different problem.

Related Reading

• libp2p: The Networking Layer Underneath IPFS - the connection-establishment layer a swarm key restricts before any DHT or Bitswap activity happens
• What Happens When You Unpin a File on IPFS: Garbage Collection Explained - pinning's actual job, which has nothing to do with network-level access control
• How IPFS Finds and Retrieves Your Files: DHT Provider Records and Bitswap Explained - the public-network discovery mechanics a private network deliberately opts out of
• Does IPFS Encrypt Your Files? Privacy on IPFS Explained - the content-level privacy question this article deliberately does not answer, since network access and content secrecy are separate concerns
• Types of IPFS Nodes: The Different Roles, Explained - the bootstrap-node role a private network needs its own replacement for

References

• ipfs/kubo Issue #3313: Private Networks - First Implementation
• IPFS Forums: Private IPFS Swarm with Kubo