Encryption

Penombre can seal file bytes at rest with a key you hold, but start with disk-level encryption on DATA_DIR: for a stolen or decommissioned drive it covers strictly more, because it also covers the database. Application-level encryption then adds one thing disk encryption cannot: file bytes that stay sealed when they are copied off the server.

#What each layer protects

Neither hides sizes, file counts, folder shape or modification times. Names live in the database, never in the sealed bytes: disk encryption is what protects them.

#Disk encryption first

By default everything Penombre writes lives under DATA_DIR (see Storage): file bytes and thumbnails under STORAGE_PATH, and the SQLite database under DATA_DIR/db. The database holds names, email addresses, password hashes, two-factor secrets, API keys and OAuth client secrets, so it needs the same protection as the files.

Put DATA_DIR on an encrypted block device or filesystem before Penombre ever writes to it:

• LUKS (Linux): encrypt the block device the volume is mounted from.
• ZFS native encryption: zfs create -o encryption=on ....
• FileVault (macOS): whole-disk encryption for a Mac used as a server.
• Your cloud provider's encrypted-volume option, for a mounted cloud disk.

A Postgres database (DATABASE_URL) and mounted volumes (VOLUME_<NAME>_PATH, see Volumes) live outside DATA_DIR: encrypt the disks they sit on too.

#Sealing file bytes

Set ENCRYPTION_KEY to 32 random bytes in base64, on the app and on any external worker:

openssl rand -base64 32

Or keep it in a file and point ENCRYPTION_KEY_FILE at it, which is the recommended way: a Docker secret mounted outside DATA_DIR means a backup of /data never carries its own key.

services:
  penombre:
    environment:
      ENCRYPTION_KEY_FILE: /run/secrets/penombre_encryption_key
    secrets:
      - penombre_encryption_key
secrets:
  penombre_encryption_key:
    file: ./encryption.key

Lose the key and every sealed file is gone. There is no recovery without it. Back it up the way you back up a password manager's master key, somewhere other than the backups of DATA_DIR.

Every file is sealed with AES-256-GCM under its own random key, which is itself wrapped by ENCRYPTION_KEY and stored in the file's header. Previews, waveforms, streaming with seeking, zips, shares, public links and office editing all keep working: the app and the worker decrypt as they read.

#Turning it on for an existing instance

1. Back up DATA_DIR, and keep the key out of that backup.
2. Set the key on the app and on any external worker, then restart.
3. New uploads are sealed at once; older files stay readable meanwhile.
4. A background sweep seals the existing files a batch at a time. It needs free space for one copy of the largest file. The log reports its progress.
5. Temporary zips in STORAGE_PATH/.tmp expire within an hour.

Encryption does not reach back in time: old backups, snapshots and the blocks an SSD has not reclaimed yet still hold plaintext.

#What it covers

• Personal and shared drives: sealed as soon as a key is set, existing files included.
• Mounted volumes: plaintext by default. VOLUME_<NAME>_ENCRYPT=true seals what Penombre writes there (uploads, saves, copies, thumbnails). Files already on the volume, or dropped in by other tools, are never rewritten. It cannot be combined with VOLUME_<NAME>_READONLY.
• Simple mode is not supported: its root is a library other tools read, and sealing it would turn it into ciphertext for them. The app refuses to start with both set.

Nothing binds a sealed file to its path: someone with write access to the disk can swap two sealed files between accounts. Disk encryption and ordinary filesystem permissions are the answer to that attacker.

#Once it is on

The first boot with a key records its id in the database. From then on the app refuses to start without a key that can open the files: removing ENCRYPTION_KEY, or replacing it with another one, stops the boot with a message naming the key it expects.

#Rotating the key

1. Move the current key to ENCRYPTION_KEY_PREVIOUS (comma-separated if there are several) and set a new ENCRYPTION_KEY, on the app and on any external worker. Restart.
2. The sweep rewrites each file's header under the new key; the bytes keep their own file key. It also moves what Penombre sealed on mounted volumes.
3. Once the log says ENCRYPTION_KEY_PREVIOUS can be removed, remove it.

A rotation does not re-encrypt the content: someone who holds both the old key and an old copy of a file can still read that copy.

#Recovering files without Penombre

The worker binary opens a sealed file on its own, with the same variables:

ENCRYPTION_KEY_FILE=./encryption.key penombre-worker -decrypt path/to/file > out
ENCRYPTION_KEY_FILE=./encryption.key penombre-worker -encrypt-check /data/storage

-decrypt writes the plaintext to stdout (plaintext files pass through); -encrypt-check counts plaintext, sealed and unreadable files under a directory. Neither needs the database, so a copy of STORAGE_PATH and the key are enough to get every file back.

#Performance

AES is hardware accelerated on any recent x86 or ARM server. A Raspberry Pi 4 has no crypto extensions and manages roughly 50 to 100 MB/s, which is felt when streaming large video.