Encryption

Encryption

Photosphere can encrypt your media database so that all files (assets, thumbnails, display versions, and .db/ metadata) are stored in an encrypted format. This is useful when storing a database in the cloud or on untrusted storage.

How encryption works

• Key files: You use a private key file (e.g. my-photos.key) and an associated public key (e.g. my-photos.key.pub). The public key is stored in the database as .db/encryption.pub so that the database is clearly marked as encrypted.
• Default key: The first key you provide in any command is the default key. It is used to write new encrypted data and must match the public key in .db/encryption.pub. Other keys in the list are used only for reading files that were encrypted with different keys (see “Multiple keys” below).
• Setting the default key: The default key is set when you first create an encrypted database with psi init, psi replicate (to an encrypted destination), or psi encrypt. After that, the only way to change the default key is to run psi encrypt again (to re-encrypt with a new key) or psi decrypt (which removes encryption).

Encrypted file format

Encrypted files use one of two formats:

• New format (current): A 44-byte header (4-byte tag PSEN, format version, encryption type, 32-byte public-key hash) followed by the encrypted payload (RSA-wrapped AES key, IV, AES-256-CBC ciphertext). The key hash in the header identifies which key was used to encrypt the file.
• Legacy format: No header; the file starts directly with the encrypted payload. Decryption uses the default key. Old databases created before this format remain readable.

New writes always use the new format. Reading supports both formats so existing encrypted databases keep working.

Multiple keys (key map)

Commands that accept --key or --dest-key accept a comma-separated list of key file paths. These are merged into a single key map:

• The first key in the list is the default key (used for writing and for reading legacy-format files).
• Every key is also registered under the SHA-256 hash of its public key, so files encrypted with different keys in the same database can be decrypted as long as you provide all the relevant keys.

Example: if your database has some files encrypted with key1 and others with key2, you can run:

psi verify --db ~/photos --key key1.key,key2.key --yes

The first key (key1.key) is the default and must match .db/encryption.pub if you are writing; both keys are available for reading.

Basic usage

1. Create an encrypted database (init)

Generate a key and create a new encrypted database:

psi init --db ~/photos --key my-photos.key --generate-key

The key is stored at the path you give (often in ~/.config/photosphere/keys/ or the current directory). Use the same key for all subsequent operations on that database.

2. Use the key for everyday operations

Refer to the key by path or by name (if it’s in the Photosphere config directory):

psi add --db ~/photos ~/new-photos/ --key my-photos.key
psi list --db ~/photos --key my-photos.key
psi export --db ~/photos <asset-id> ./output.jpg --key my-photos.key

3. Replicate to an encrypted destination

To create an encrypted copy (e.g. in the cloud), use --dest-key and optionally --generate-key:

psi replicate --db ~/photos --dest s3:my-bucket/my-photos --dest-key backup.key --generate-key

4. Encrypt or re-encrypt in place (psi encrypt)

psi encrypt transforms the database in place at --db (there is no destination path). Use it to:

• Plain → encrypted: Turn a plain database into an encrypted one. Use --key (and optionally --generate-key).
• Re-encrypt with a new key: The database is already encrypted; put the new default key first in --key, followed by any existing keys needed to read the current database. The new public key is written to .db/encryption.pub only after the entire database has been re-encrypted.
• Same key / format conversion: You can also run psi encrypt with the same key to rewrite older encrypted files into the current format.

# Plain → encrypted (in place)
psi encrypt --db ~/photos --key my-photos.key --generate-key --yes

# Re-encrypt with a new key (in place)
psi encrypt --db ~/photos --key new.key,old.key --yes

# Rewrite using the same key (for example, to convert to the current format)
psi encrypt --db ~/photos --key my.key --yes

Options: --db, --key (comma-separated key list; first key is the write/default key), --generate-key, --yes. No --dest.

5. Decrypt in place (psi decrypt)

To make an encrypted database plain in place (remove encryption from the database at --db):

psi decrypt --db ~/encrypted-photos --key my-photos.key --yes

All files are rewritten as plain; .db/encryption.pub is removed. Use --key to supply the key(s) needed to read the encrypted database. There is no destination path; the database at --db is decrypted in place.

Key sources

Each value passed to --key (or --dest-key, --source-key) is resolved in order:

1. File path — if the value is a path to an existing file, the PEM is read from disk (e.g. --key /path/to/my-photos.key).
2. Vault secret name — if no file exists at that path, Photosphere looks up a vault secret with that name (e.g. --key my-photos). Use psi secrets list to see available secrets.

PSI_ENCRYPTION_KEY environment variable

Set PSI_ENCRYPTION_KEY to a file path or vault secret name to avoid passing -k on every command:

export PSI_ENCRYPTION_KEY=my-photos   # vault secret name
export PSI_ENCRYPTION_KEY=/path/to/my-photos.key   # file path

An explicit -k flag takes priority over PSI_ENCRYPTION_KEY. If a database entry in databases.json has a linked encryption key, that takes priority over PSI_ENCRYPTION_KEY as well.

Important

• Do not lose your encryption key. If you lose it, you cannot decrypt the database.
• Back up your key (e.g. in a password manager) as soon as you generate it.
• Commands that need to write to an encrypted database require the default key (first in the list) to match the public key stored in .db/encryption.pub.