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, --dest-key, or --source-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). Omit --source-key.
• Re-encrypt with a new key: The database is already encrypted; you want to re-encrypt everything with a different key. Use --key for the new key and --source-key for the key(s) that can 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: If you run encrypt with the same key as the source (e.g. --key my.key --source-key my.key), the command exits early—nothing to do. The database is already encrypted with that key.

# 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 --source-key old.key --yes

# Same key: exits early, no changes
psi encrypt --db ~/photos --key my.key --source-key my.key --yes

Options: --db, --key (destination key(s), comma-separated), --source-key (source key(s) when the database is already encrypted), --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 (and optionally --source-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 file locations

• You can pass a full path to the key file: --key /path/to/my-photos.key.
• If you pass only a filename (no path), Photosphere looks in ~/.config/photosphere/keys/ first, then the current directory. So --key my-photos.key often suffices if the key is in the config directory.

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.