Encrypt at rest

By default your destination key sits on disk in the clear. Anyone who can read the ./i2p-keys folder can copy eepsite.dat and impersonate your service. For most people that is fine, because the folder is on a machine they control. If you want a second lock, i2pforge can wrap the key in a passphrase.

What it protects against

Encryption at rest protects the key while it is sitting on disk. If someone steals your drive, seizes the machine, or copies the folder, they get an encrypted blob they cannot use without your passphrase. It does not protect the key while the service is running, because the router needs the real key in memory to work. That is the correct trade: the risk you are guarding against is theft of the stored file, not a live compromise of a running container.

How it works

The key is wrapped in an envelope. The passphrase is stretched into an encryption key using scrypt, a slow, memory-hard function that makes guessing expensive. The key is then encrypted with ChaCha20-Poly1305, an authenticated cipher that also detects tampering. Both of these stay strong even against a future quantum computer, as long as your passphrase has enough entropy. Use a long one: six or more random words is a good target.

When the container starts, it reads the passphrase from a file you mount as a secret, decrypts the key into a temporary in-memory area, and runs from there. The plaintext key never touches the persistent folder. On disk you only ever have the encrypted eepsite.dat.i2pfk1.

Turning it on

The easiest way is the wizard or the desktop installer, which both have an encrypt step. Pick "encrypt the key on disk" and type a passphrase.

To do it by hand on an existing plaintext key:

./scripts/i2pforge encrypt-key --delete-plaintext

This wraps eepsite.dat into eepsite.dat.i2pfk1 and securely removes the plaintext. From then on, every time you start the stack you must supply the passphrase, by mounting it as a file and pointing the container at it with the I2P_KEY_PASSPHRASE_FILE setting. The generated compose file does this for you when you choose encryption in the wizard.

Backing up an encrypted key

Two things now matter, and you should store them apart:

• The encrypted key folder (./i2p-keys).
• The passphrase.

If you back them up together, you have undone the encryption. Keep the passphrase somewhere separate, such as a password manager, so that a single stolen backup is useless on its own.

If a migration is interrupted

Turning encryption on has to move the key from plaintext to encrypted safely, even if the power fails halfway. i2pforge does this in a careful order: it writes the encrypted copy and confirms it decrypts back to exactly the original before it removes the plaintext. If a crash interrupts the process, the next start notices the leftover plaintext, checks it against the encrypted copy, and finishes the job only if they match. If they do not match, it stops and asks you to look, rather than delete a key it cannot account for. You will never silently lose your key to a bad migration.