Docs / Data & machines

The encrypted drive and recovery phrase

FrameBuff keeps your files unreadable to anyone who has the disk but not the keys. The 12-word recovery phrase is your way back if every machine is lost.

Two encrypted places

The FrameBuff drive

Shared by every machine you pair. When you approve a new machine, it receives the drive keys.

The personal folder

Belongs to one machine. Its key never leaves that machine, it is never handed to another one and it is never backed up.

Both appear in Files like any other folder. Settings → Encryption holds the controls, and the top bar has Unlock and Lock.

How your files are protected

• Every file is stored encrypted with AES-256-GCM. Each file gets its own key, derived from the drive's master key, and every write uses a fresh nonce.
• The encryption is authenticated, so a file that someone changed on disk is refused when you open it.
• The master key is never written to disk in the clear. It is stored wrapped under a key that belongs to that machine, so a disk carried away holds nothing usable. You can also seal that machine key to the computer's TPM chip.
• Encrypting the drive is not a setting you can switch off. Nothing writes the drive in the clear.

The recovery phrase

The recovery phrase is 12 words. If every machine is lost, the phrase is the one way back into the drive and the credential vault. Until you confirm it, the drive refuses new files.

1. Open Settings → Encryption.
2. Under Recovery phrase, press Set it up now.
3. Write the 12 words on paper.
4. Type back the words it asks for, and press Confirm.

Locking and unlocking

After a restart, a machine starts locked. Press Unlock in the top bar or in Settings → Encryption. Locking drops every key from memory: the drive's, the personal folder's, the credential vault's and the machine's own identity key. While a machine is locked it cannot prove who it is, so it also drops out of the fleet until you unlock it.

• On a machine with no passphrase, you can only unlock at the machine itself.
• Give a machine a passphrase if you often unlock it from elsewhere. Then you can unlock it from anywhere with that passphrase.
• An always-on machine unlocks the drive by itself at start-up, so it keeps serving the shared drive with nobody present. This suits a machine that runs backups. Its personal folder still stays shut until someone unlocks it at the machine.

Rotate the drive key

Rotate the key when a machine is lost, given away or removed from the fleet. Rotation makes a new key, re-encrypts the drive's files with it and hands the new key to every machine that stays. Files written before the rotation still open.

1. Unlock the drive on a machine that holds it.
2. Run the tool crypt.rotate with your recovery phrase. Add remove_device with the id of the machine to drop first. crypt.peers lists the ids.
3. If this machine has a lock phrase, you are asked to type it again first.

framebuff call crypt.rotate remove_device=<id> phrase="<your 12 words>"

A phrase typed on a command line can end up in your command history, so you may prefer the tool from the web page.

The credential vault

The vault keeps the passwords and tokens FrameBuff uses for other services, such as your pCloud account for backups. It is encrypted under the same keys as the drive. Modules ask the vault for a credential each time they need one, and the vault gives it only to modules you granted it to.

Messages you may see

"the FrameBuff drive is locked"

Press Unlock in the top bar, and type the passphrase if this machine has one.

"recovery phrase not confirmed yet"

Set up and confirm the phrase in Settings → Encryption. New files are refused until you do.

"unlock at the machine, or with its passphrase"

You tried to unlock without a passphrase from somewhere else. Unlock at the machine, or give it a passphrase.

"this machine's local key is gone"

Recover with the 12-word phrase, or pair the machine again from one that holds the drive keys.