End-to-End Encryption Setup

Every project is encrypted by default with a hub-held key (Security covers the model). End-to-end (E2E) encryption is a stronger, opt-in tier: the project key is wrapped to each member's own device keypair and never reaches Swarmfile's servers in plaintext, so the service cannot read your file contents at all.

This page is the operational how-to - how to turn it on, set up recovery, and what to know before you do. For the cryptographic model and what E2E does and doesn't protect, read the E2E section of Security first; the short version is that it's content-only (filenames, folder structure, and sizes stay server-visible so search, ACLs, browse, and quota keep working).

Before you turn it on#

Three things are worth internalizing before you create your first E2E project, because two of them are irreversible:

The tier is immutable per project. A project is either managed-key or E2E, chosen at creation and never changed. You can't convert an existing managed project to E2E (the hub has already seen its key) or an E2E project back. To move existing data under E2E, create a new E2E project and migrate into it.
Server-side previews are disabled on E2E content. Thumbnails, video posters, scrubbable proxies, and point-cloud previews are all generated server-side, which an E2E project's server can't do because it can't decrypt. E2E files show a generic icon in the dashboard. This is the single biggest day-to-day cost - see File Previews.
"E2E with recovery" is not zero-knowledge-absolute. If you set up an org recovery key (strongly recommended, below), a quorum of your admins can reconstruct a project key. That's a deliberate, enterprise-grade tradeoff - the alternative is that a lost password means permanently lost data. Choose consciously and tell your security reviewer plainly: recovery-enabled E2E means "Swarmfile can't read it, but your own admin quorum can."

We'd suggest piloting on a single non-critical project first. It's the newest tier, and the immutability means a hasty rollout is expensive to walk back.

Step 1 - Set up the org recovery key first#

Do this before creating any E2E project. When you create an E2E project, its key is wrapped to your org recovery key if one already exists at that moment. A project created before the recovery key exists has no recovery wrap - losing every member's device would then mean losing that project's data with no way back. Order matters.

As owner, open the Recovery Key tab in the dashboard (owner-only). Creating a recovery key:

Generates an org recovery keypair and splits the private half with Shamir secret sharing into N shares with a t-of-N threshold (the default is 2-of-3). Any t shares can reconstruct it; any t−1 reveal nothing.
Returns the share strings exactly once, on creation. They are never retrievable again. The view is print-friendly on purpose.

Distribute the shares to different people and different physical locations - a safe, a vault, an HSM, separate offices. The whole point of the threshold is that no single lost or compromised share exposes anything, and no single person can unilaterally decrypt. Store them the way you'd store the master keys to anything else that matters.

Rotating (creating a new key) or revoking is done from the same tab. Note that rotation applies to projects created afterward - it does not retroactively re-wrap projects created under a previous recovery key.

Step 2 - Create an E2E project#

Create a project as usual (Projects → New), and choose the E2E encryption tier instead of the default managed tier. The creation dialog states the tradeoff at the point of choice - previews disabled, recovery via the org key only, immutable after creation. E2E projects carry an E2E badge in the project list so the tier is never ambiguous.

Step 3 - Members enroll automatically#

There's no manual key ceremony for ordinary members. When a member signs in on a machine, the engine enrolls that device: it registers the device's public key with the hub, while the private key is derived on the device and never leaves it. No admin action, no per-device setup screen.

Granting a member access to an E2E project happens client-side: an existing member's client wraps the project key to the new member's public key. The consequence worth knowing is timing - a newly added member sees an E2E project's contents only once another member's client has been online to complete that wrap. Add someone while the rest of the team is offline and their access is pending until someone with a key comes online. (An always-on key-granter service exists to close this gap so grants don't wait on a human being online; per-org enablement of it is operator-managed today rather than self-serve - contact us if pending-grant latency is a problem for your team.)

Multiple devices for one person#

A member who works on more than one machine transfers their key between devices directly - a one-time, time-limited transfer code links a new device to an already-enrolled one and moves the wrapped project keys across, without the private key ever touching the hub. Enrollment on the new device is otherwise the same automatic flow as the first.

Recovering a project key#

If a member is locked out and their access can't be re-granted the ordinary way, an owner recovers the project key from the Recovery Key tab's recover flow: gather a quorum of at least t shares from wherever you distributed them, enter them together with the project, and the dashboard reconstructs that project's plaintext key. This is a break-glass procedure - it requires the physical cooperation of your threshold of share-holders by design, and it's the reason the shares are stored apart in the first place.

A share link on an E2E project still works for an external reviewer with no account: the key needed to decrypt travels in the link's URL fragment, which browsers never send to the server, so the hub serves only ciphertext and the recipient's browser decrypts locally. The hub limits that link's raw-block access to the shared file's own blocks, so a recipient can fetch only the file you shared - not the rest of the project. (The link does carry the project key, so treat sharing as a real trust decision and use expiry/revocation; the deeper key-custody detail is in Security Architecture.) Image and PDF previews work this way; video proxies don't (the server can't transcode what it can't decrypt), consistent with the in-app preview limits above.

What lives where#

Key operations are web-and-automatic: enrollment and key-granting happen in the engine without user action, and the owner-facing admin - the recovery key, its shares, and the recover flow - lives in the web dashboard. The desktop tray and the swarmfile CLI have no key-management commands; there's nothing to configure there. If a document tells you to manage E2E keys from the tray, it's wrong - that surface doesn't exist.

The bottom line for a security review#

Contents are unreadable to Swarmfile; metadata (names, structure, sizes) is not.
Recovery is your own admin quorum, not the vendor - and only if you set the recovery key up before creating projects.
Previews and server-side proxies are off for E2E content, by necessity.
Set-up is irreversible per project; pilot before you commit a flagship project to it.

If E2E is a hard procurement requirement, raise it early and we'll walk your reviewer through the envelope format and the recovery threat model directly.