# Locked encryption

Source: https://frameleaf.app/docs/using/locked-encryption/

[Locked](https://frameleaf.app/docs/using/private-content/) hides sensitive photos and videos inside Frameleaf. **Locked encryption** goes one step further: it encrypts the files themselves, on the server's disk. Someone who opens the server's shared folder, pulls out a drive, or browses the library's folders sees scrambled data instead of your photos.

It's optional and off by default. Only you can turn it on, for your own Locked items. Administrators can't turn it on or off for you, and can't open your encrypted files.

[![The Locked encryption page while encryption is off: Your Locked files aren't encrypted, a Turn on button, and a What it does list of what is and isn't protected.](https://frameleaf.app/shots/docs/locked-encryption-off-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-off-2026-11.jpg)

:::caution[Choose Advanced Security if you're seriously worried about someone getting your files]
With the PIN option, a six-digit PIN protects your files. That keeps out anyone casually browsing the server, but someone who takes a copy of the disk or a backup has time on their side, and **can work through every six-digit PIN in hours to days on ordinary computers**, faster with more hardware. Assume a determined person with your disk *will* open PIN-protected files.

**Advanced Security** protects your files with a passphrase instead. A good passphrase can't be guessed in any practical amount of time, even by someone with the disk and powerful hardware. If your concern is theft, a lost backup or anyone with real skill and time, **use Advanced Security**. [Compare the two](#pin-or-advanced-security).
:::

## What gets encrypted

| | Encrypted? |
| --- | --- |
| The original file of each of your Locked photos and videos | Yes |
| Every file made from it: thumbnails, previews, full-size versions, converted videos, edits, sidecar files, Studio and restoration outputs | Yes |
| Files [Library care](https://frameleaf.app/docs/using/damaged-and-missing-files/#photos-in-locked) keeps for it: the damaged file kept after a repair, and a file moved aside when a restore is undone | Yes. Photos already in Locked are covered by themselves |
| Your photos and videos that aren't Locked | No, they stay exactly as they are |
| Other people's Locked items | Only if they turn encryption on for themselves |
| What the database knows about each photo: dates, places, camera details, faces, people's names, tags, descriptions, text found in photos, file names and search data | **No.** Search, Memories and people need it. See [What encryption doesn't protect](#what-encryption-doesnt-protect). |
| Locked items in a folder Frameleaf can't change, such as an [external library](https://frameleaf.app/docs/admin/external-libraries/) or a read-only source | No. The settings page counts them separately: "3 Locked items are in a folder Frameleaf can't change, so they stay unencrypted." |
| Items a [partner](#items-a-partner-shares-with-you) shares with you that are in your Locked folder | Only if the partner encrypts them. They're the partner's files, so your setting doesn't encrypt them. The settings page counts them: "2 items shared with you by a partner aren't encrypted by your setting." |

Once encryption is on, everything you add to Locked later is encrypted too: items you lock, uploads straight into Locked, photos [detection](https://frameleaf.app/docs/using/private-content/#automatic-detection) locks, items your [Locked rules](https://frameleaf.app/docs/using/private-content/#locked-rules) hide, and Studio exports that take a lock from their sources.

Inside Frameleaf, nothing looks different. Encrypted items are still in their albums, stacks, tags and memories, and they open, play and download as usual once your key is open.

## PIN or Advanced Security

You choose how your files are protected when you turn encryption on, and you can switch at any time without anything being encrypted again.

| | **Use my Locked PIN** | **Advanced Security** |
| --- | --- | --- |
| What opens your files | Your six-digit Locked PIN | A passphrase of at least 12 characters |
| Something new to remember | No | Yes, a passphrase |
| After the server restarts | Type your PIN, as usual, when you open Locked | Type your passphrase once in Settings, then your PIN opens Locked as usual |
| Asked again while the server keeps running | When your Locked session ends | After a set time: 8, 24 or 72 hours (the default), or only after a restart |
| Someone browsing the server's files or a shared folder | Protected | Protected |
| An administrator using Frameleaf | Protected | Protected |
| Someone with a copy of the disk or a backup | **Weak.** Every possible PIN can be tried in hours to days | **Strong.** Protected by your passphrase |
| Someone in control of the running server while your key is open | Not protected | Not protected. The ask-again time limits how long that window lasts |
| Partners | Open shared items with their own PIN | Must also type your passphrase |

### Why a PIN can be guessed and a passphrase can't

Inside Frameleaf, wrong guesses are limited. After 5 wrong attempts you wait a minute, after 10 an hour, and after 15 a whole day. So nobody can guess your PIN by typing into Frameleaf.

Someone who copies the server's whole disk doesn't go through Frameleaf. A PIN-protected key needs two things from the disk: your key file, and a small secret file the server keeps with its identity key (see [The server's PIN secret](#the-servers-pin-secret)). A full copy of the disk usually holds both. With them, guesses can be tried against the key file directly, as fast as their computers allow, with no limits. Frameleaf makes each guess deliberately slow and memory-hungry: about half a second and 128 MB of memory for every try. That's harmless when you type your PIN once, but a six-digit PIN has only a million possibilities. A few ordinary computers working together get through all of them in hours to days.

A passphrase has vastly more possibilities. Four or five random, unrelated words, such as `orbit kettle lantern fossil cove`, give trillions upon trillions of combinations. At the same half-second per guess, trying them all would take far longer than anyone could wait, even with a room full of hardware.

**A passphrase is only as strong as it is unpredictable.** Song lyrics, quotes, names, dates, your Wi-Fi password, or anything you use elsewhere can be guessed much faster. Pick words at random, don't make them a sentence, and don't use the passphrase anywhere else.

### Restarts and the iPhone comparison

An iPhone asks for your passcode after it restarts, because its key is lost from memory when it turns off. Frameleaf works the same way in Advanced Security: your key lives only in the server's memory, so a restart, the ask-again time or **Lock now** throws it away. Until you type your passphrase again, your files can't be opened by anyone, including the server itself.

The difference is that an iPhone has a security chip that limits guesses even against someone holding the phone. A server's disk has nothing like that once it's out of the server. That's why the PIN on its own can't stop someone with the disk, and the passphrase can.

## Turn on encryption

1. Go to **Settings**, then **Your sign-in & privacy**, then **Locked encryption**. You need a [Locked PIN](https://frameleaf.app/docs/using/private-content/#set-up-your-pin) first.
2. Select **Turn on…**.
3. Under **Encrypt your Locked files**, choose how your files are protected: **Use my Locked PIN** or **Advanced Security: add a passphrase**, then select **Continue**.

   [![The Encrypt your Locked files dialog with two choices, Use my Locked PIN and Advanced Security: add a passphrase, each with a short explanation, and Cancel and Continue buttons.](https://frameleaf.app/shots/docs/locked-encryption-choose-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-choose-2026-11.jpg)

4. For Advanced Security, choose your passphrase and type it twice. It must be at least 12 characters.
5. Read **Before you encrypt**. Tick that you understand:
   - that losing your PIN or passphrase *and* your recovery key means losing these photos;
   - that an administrator can't reset your PIN while encryption is on.

   Then select **I understand, continue**.

   [![The Before you encrypt step for Advanced Security: a warning that without your passphrase or recovery key nobody can open your Locked photos, three notes about encrypting, backups and turning it off later, and two boxes to tick.](https://frameleaf.app/shots/docs/locked-encryption-before-you-encrypt-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-before-you-encrypt-2026-11.jpg)

6. Confirm a second time by typing your PIN, then select **Encrypt now**.
7. **Save your recovery key** before you go on. **Continue** stays unavailable until you tick **I've saved my recovery key somewhere other than this server**. See [Your recovery key](#your-recovery-key).

Encrypting runs in the background, oldest items first, and the page shows how many are done. You can keep using Frameleaf, close the page, or restart the server; it carries on where it left off. Each file is encrypted to a new file next to it, checked against the original, and only then put in its place, so an interruption never leaves a half-encrypted photo.

When it finishes, the page says **Your Locked files are encrypted**, with how many items are encrypted and the controls described below.

[![The Locked encryption page with the PIN option on: Your Locked files are encrypted, 6 encrypted, backups still encrypted, then How they're protected with Add a passphrase, the Recovery key section, If this server stops working with the recovery tool steps, and Turn off.](https://frameleaf.app/shots/docs/locked-encryption-on-pin-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-on-pin-2026-11.jpg)

## Your recovery key

When you turn encryption on, Frameleaf shows a recovery key once. It looks like `FLRK-ABCD-EFGH-…`. Frameleaf never shows it again, and doesn't keep a readable copy.

[![The Save your recovery key step: a recovery key starting FLRK with Download, Copy and Print buttons, and a box to tick saying it's saved somewhere other than this server before Continue.](https://frameleaf.app/shots/docs/locked-encryption-recovery-key-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-recovery-key-2026-11.jpg)

The recovery key:

- resets a forgotten PIN or passphrase;
- opens your files with the [recovery tool](#recover-your-files-without-the-server) if the server stops working;
- is the **only** way back in if you forget your PIN or passphrase. Nobody else can reset it for you: not an administrator, not Frameleaf.

Keep it safe:

- **Download** saves it as a small text file named after you. Move that file off the server.
- **Copy** puts it on your clipboard, for a password manager.
- **Print** opens a page to print and store somewhere safe.

Keep it **somewhere other than the server**. A recovery key saved in your Frameleaf library is lost along with the library. A password manager, a printed copy in a drawer, or both, work well.

Anyone with your recovery key *and* a copy of your library can open your encrypted files, so treat it like the key to a safe.

### Make a new recovery key

Lost track of it, or worried someone saw it? On the Locked encryption page select **Make a new key…**, and type your PIN or passphrase. You get a new key to save, and the old one stops working straight away. Your files aren't encrypted again.

## Everyday use

### With the PIN option

Nothing changes. Unlock Locked with your PIN, as usual, and your encrypted items open. When your Locked session ends, your key is put away until you type your PIN again.

### With Advanced Security

After the server restarts, the Locked encryption page says **Type your passphrase to open Locked**, and opening Locked asks **Type your passphrase**. Type it once. From then on your PIN opens Locked as usual, until:

- the ask-again time passes (72 hours by default);
- you select **Lock now**;
- or the server restarts.

[![The Type your passphrase prompt over the Locked view: your Locked files need your passphrase before your PIN can open them, you'll be asked again in 72 hours, a Passphrase field, a reminder to use your recovery key if you forgot it, and Not now and Unlock buttons.](https://frameleaf.app/shots/docs/locked-encryption-passphrase-prompt-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-passphrase-prompt-2026-11.jpg)

Set the ask-again time under **Ask for my passphrase again after**: 8 hours, 24 hours, 72 hours, or **Only after a restart**. Shorter is safer if the server might be in someone else's hands while it's running; longer is more convenient.

- **A shorter time** applies straight away, including to Locked if it's open now. For example, if your passphrase was typed an hour ago and you switch from 72 to 8 hours, you're asked again 8 hours from now, not in 71.
- **A longer time**, or **Only after a restart**, keeps Locked open longer, so Frameleaf first asks **Type your passphrase to keep Locked open longer**. Type it and select **Keep open longer**. If you cancel, or the passphrase doesn't work, the setting goes back to what it was.

[![The Locked encryption page with Advanced Security on: your passphrase is typed and Locked opens with your PIN until a set time, the Ask for my passphrase again after choice of 8 hours, 24 hours, 72 hours or Only after a restart, and the Change passphrase and Lock now buttons.](https://frameleaf.app/shots/docs/locked-encryption-on-advanced-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-on-advanced-2026-11.jpg)

Until you type your passphrase:

- Your Locked items can't be viewed, played, downloaded or taken out of Locked. Trying to opens the passphrase prompt.
- **You can still add to Locked.** Locking an item or uploading into Locked works as usual, and the new files are encrypted as they arrive, without your passphrase.
- Work that needs to read the files, such as making new thumbnails after a model change, waits until you type it, then carries on by itself.

### Taking an item out of Locked

When you unlock an item, Frameleaf decrypts its files first and only then takes it out of Locked. It stays hidden for the few seconds that takes, so it's never visible while still encrypted, or encrypted while visible. Your key must be open: with Advanced Security, type your passphrase first.

Files Library care keeps for the item are opened again too. If one is on a drive that's away at the time, it stays encrypted until Frameleaf opens it later, the next time your key is open. Until then it can't be downloaded, and a fix that needs it can't be undone. See [Photos in Locked](https://frameleaf.app/docs/using/damaged-and-missing-files/#photos-in-locked).

## Change how your files are protected

Everything here is on the Locked encryption page. None of it encrypts your files again; only the key that opens them changes.

- **Add a passphrase…** switches from the PIN option to Advanced Security. Choose a passphrase, then type your PIN.
- **Use my PIN instead…** switches back. Type your passphrase, then your PIN. Your PIN then opens the files directly, with the [weaknesses above](#why-a-pin-can-be-guessed-and-a-passphrase-cant).
- **Change passphrase** asks for your current passphrase and a new one, twice.

  [![The Change passphrase dialog: fields for the current passphrase, a new passphrase of at least 12 characters with a strength bar, and Type it again, with Cancel and Save.](https://frameleaf.app/shots/docs/locked-encryption-change-passphrase-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-change-passphrase-2026-11.jpg)

- **Change your PIN** as usual in **Locked PIN**. With the PIN option, the key that opens your files moves to the new PIN at the same moment.

## If you forget your PIN or passphrase

Under **Forgot your PIN or passphrase?** on the Locked encryption page, select **Use recovery key…**. Type your recovery key, then choose a new PIN (with the PIN option) or a new passphrase (with Advanced Security), and select **Set new PIN** or **Set new passphrase**.

[![The Use your recovery key dialog for the PIN option: a Recovery key field starting FLRK, boxes for a new six-digit PIN and for typing it again, and Cancel and Set new PIN buttons.](https://frameleaf.app/shots/docs/locked-encryption-recover-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-recover-2026-11.jpg)

While encryption is on:

- **Forgot your PIN?** with your account password no longer clears your PIN, because that would leave your files unopenable. Use your recovery key instead.
- An administrator can't clear your PIN. Their option is turned off, with a note saying why.

If you've lost **both** your PIN or passphrase **and** your recovery key, your encrypted files can't be opened by anyone. There's no back door.

## Partners

If you share your library with a [partner](https://frameleaf.app/docs/using/sharing/#locked-items), their copies of your Locked items point at your files, which are now encrypted. How they open them depends on your choice:

- **You use the PIN option:** your partner opens them with **their own PIN**, like their own Locked items. Your PIN is never shared. A new partner, or a partner who has only just set a PIN, sees **Not ready yet** and **Opens after *your name* next opens Locked**, until you next unlock Locked.
- **You use Advanced Security:** your partner must type **your passphrase** as well as their own PIN. They see **Type *your name*'s passphrase** when they open one of your items. Typing your own passphrase doesn't open your items for your partner; each partner types it themselves, and it lasts for your ask-again time.

So with Advanced Security, sharing your Locked items with a partner means telling them your passphrase. If you'd rather not, keep those items out of what you share.

While you're [turning encryption off](#turn-off-encryption), a partner can't open your items with your passphrase. Once decrypting finishes, your items are ordinary files again and open for them as they did before encryption.

When a partnership ends, the former partner can no longer open the content of your encrypted items, including the copies they kept.

### Items a partner shares with you

Your encryption covers your own files. Items a partner shares with you are their files, so they're encrypted only when **the partner** has Locked encryption on and the item is Locked for them too. If you've put some of them in your Locked folder and they aren't encrypted, the Locked encryption page counts them, for example "2 items shared with you by a partner aren't encrypted by your setting."

## Backups

[Cloud Backup and Buddy Backup](https://frameleaf.app/docs/admin/backup-and-restore/#cloud-backup-and-buddy-backup) keep running while encryption is on. They copy your encrypted files **as they are, still encrypted**, and never decrypt them. Nobody holding the backup can see them without your PIN, passphrase or recovery key. The same strength applies: a backup of PIN-protected files can be guessed open by whoever has it; a backup of Advanced Security files can't.

Each person's key file is backed up with the files. It's stored locked by your PIN, passphrase and recovery key, so backing it up reveals nothing. It's also **essential**: without the key file, nothing can decrypt your files, not even your recovery key. If you back up your server yourself, include the `UPLOAD_LOCATION/locked-keys` folder along with the rest of `UPLOAD_LOCATION`. Include the server's identity folder too (`UPLOAD_LOCATION/frameleaf/identity` unless your administrator moved it): with the PIN option, a PIN only opens your files on a server that has [the server's PIN secret](#the-servers-pin-secret) from that folder. Your passphrase and your recovery key work without it. See [Which files to back up](https://frameleaf.app/docs/admin/backup-and-restore/#which-files-to-back-up).

Because the key file matters so much, a Cloud or Buddy backup that finds encrypted files without their current key file stops instead of saving an incomplete copy. This can happen if someone turns encryption on or off while the backup runs; the next backup includes the key file.

After restoring:

- Your encrypted items open again with your PIN, passphrase or recovery key.
- If you turned encryption off and on again since the backup, some restored items may be encrypted with your older key. Activity says how many: "2 restored Locked items are encrypted with an older key and can't be opened here." Your old recovery key and the [recovery tool](#recover-your-files-without-the-server) can still open them from the backup that has your older key file.
- Items encrypted with an older key don't stop later backups. Cloud and Buddy Backup copy them as they are and carry on.

## Turn off encryption

Turning off decrypts your Locked files back to ordinary files. They stay Locked and hidden in Frameleaf.

1. On the Locked encryption page, select **Turn off…**. With Advanced Security, type your passphrase first if Locked is asking for it.
2. Read **Your Locked files will be readable on the disk again**, tick **I understand my Locked files won't be encrypted any more**, and select **Continue**.
3. Confirm a second time with your PIN or passphrase, then select **Decrypt and turn off**.

[![The Turn off Locked encryption dialog: a warning that your Locked files will be readable on the disk again, notes that decrypting runs in the background, your recovery key stops working, new backups hold ordinary copies and an administrator can clear your PIN again, and a box to tick before Continue.](https://frameleaf.app/shots/docs/locked-encryption-turn-off-2026-11.jpg)](https://frameleaf.app/shots/docs/locked-encryption-turn-off-2026-11.jpg)

Decrypting runs in the background, with the same safe file-by-file steps as encrypting. Your key stays open until it's done, so **Lock now** is unavailable meanwhile, and partners can't open your items with your passphrase. If the server restarts part-way, the page says **Type your PIN to finish turning off encryption** (or **Type your passphrase to finish turning off encryption**), and decrypting carries on once you do.

When it finishes:

- Your recovery key stops working. You'll get a new one if you turn encryption on again. With Advanced Security your key file is deleted. With the PIN option, Frameleaf keeps a key opened only by your PIN, which encrypts nothing of yours; it lets you go on opening encrypted items partners share with you.
- An administrator can clear your PIN again.
- Backups made from now on hold ordinary copies, protected only by the backup's own encryption.

If some files are missing, for example deleted outside Frameleaf, the page says how many, and turning off finishes once they're back. Restore them from a backup.

## Recover your files without the server

If the server stops working, the Frameleaf command-line tool can decrypt your files from a copy of the library, with no server, no database and no internet connection. It works on a copy of the library folder, such as a backup or a disk taken out of the server, and **never changes the library**.

You need:

- a copy of the library folder (`UPLOAD_LOCATION`), including its `locked-keys` folder;
- your PIN, passphrase or recovery key;
- the [Frameleaf CLI](https://frameleaf.app/docs/admin/api-and-cli/#before-you-begin). This command needs no API key or sign-in.

```bash
frameleaf locked decrypt --library /path/to/library --to /path/to/recovered
```

- If several people on the server use encryption, the tool asks whose files to recover. Pick one with `--user <name or ID>`.
- The `--to` folder must be outside the library folder. The tool never writes anything into the library.
- It asks for your PIN, passphrase or recovery key. What you type isn't shown.
- A PIN also needs the server's PIN secret, the file `locked-pin-pepper.key` in the server's identity folder. A copy of the library that holds `frameleaf/identity/locked-pin-pepper.key` is read by itself. If the identity folder was kept somewhere else, pass the file with `--pepper-file /path/to/locked-pin-pepper.key`. A passphrase or a recovery key needs no such file.
- Originals are written to the `--to` folder under their real file names. When two have the same name, the second becomes `name (2).jpg`, and so on.
- Add `--all` to also write thumbnails and other derived files, under `derived/<item ID>/`.
- With your own key, the tool also decrypts items a partner using the PIN option shared with you.

Every file is checked as it's decrypted. A damaged or incomplete file is listed and skipped, and the tool carries on with the rest. It finishes with exit code `0` when everything decrypted, `1` if any file failed, and `2` for a wrong PIN, passphrase or recovery key, or a missing key file.

Recovered files are ordinary, unencrypted files. Keep them somewhere private.

## What encryption doesn't protect

Locked encryption protects the **files**. Be clear about what it doesn't cover:

- **Information about your photos in the database.** Dates, places and GPS, camera details, faces and people's names, tags, descriptions, text read from photos, file names and search data stay readable to someone with the database, because search, Memories and people depend on them. Someone with the database could learn that you have a Locked photo taken at a certain place and time, with certain people, without seeing the photo itself.
- **Copies made before you turned encryption on.** Older backups, disk snapshots and copies elsewhere still hold the plain files, and an SSD can keep traces of deleted data. Encryption can't reach them. Replace or delete old backups you don't want to keep.
- **A short window after uploading into Locked.** A new upload is stored as an ordinary file while Frameleaf makes its thumbnails and reads its details, then it's encrypted, usually within moments.
- **Short-lived working copies in memory.** To make thumbnails, convert a video, read a photo's details or apply an edit, Frameleaf decrypts a temporary copy of the file into the server's memory, never onto its disk, and deletes it as soon as the work is done. Encrypted items are never sent to [Cloud GPU](https://frameleaf.app/docs/cloud/cloud-gpu/) jobs, whose inputs and results are kept on disk.
- **Someone in control of the running server while your key is open.** While Locked is unlocked (PIN option) or your passphrase is typed (Advanced Security), the key is in the server's memory, and someone who controls the server at that moment could use it. Advanced Security's ask-again time and **Lock now** keep that window short.
- **Matching copies.** If someone else on the server has the very same file, they keep their own readable copy, and the database can still tell the two are identical.
- **Your devices.** Photos you download, or that a phone or computer keeps after viewing, are outside the server's encryption.

For the strongest protection, combine Advanced Security with full-disk encryption on the server, strong account passwords, HTTPS, and careful control of who can reach the server.

## How it works

For the curious, here's what happens underneath.

### Your key

- When you turn encryption on, Frameleaf creates a key pair just for you (X25519). The **public key** can only lock files. The **private key** opens them.
- The private key is never stored as is. It's sealed (AES-256-GCM) with a key made from your PIN or passphrase using **scrypt**, a deliberately slow, memory-hard method (2¹⁷ rounds, about 128 MB per try). A second copy is sealed with your recovery key, which is 160 random bits. With the PIN option the file holds the PIN and recovery copies; with Advanced Security, the passphrase and recovery copies, and **never** a PIN copy.
- These sealed copies live in your **key file**, `UPLOAD_LOCATION/locked-keys/<your user ID>.json`, readable only by the server. The database holds only your settings and progress, never any key.
- The PIN copy is also tied to a random secret the server keeps outside the key file, so the key file alone isn't enough to try PINs. See [The server's PIN secret](#the-servers-pin-secret).
- When you type your PIN or passphrase, the private key is opened into the server's memory and nowhere else: not the disk, not the database, not logs, not backups. When it's put away, the memory is wiped.

Because the public key is enough to lock files, Frameleaf can encrypt new Locked items while your key is put away. That's how uploads into Locked work before you've typed your passphrase.

### Each file

- Every encrypted file gets its own random key, so no two files share one.
- The file's key is sealed for each person allowed to open it: you, and with the PIN option, each partner who receives your Locked items.
- The file is encrypted in 64 KB pieces, each sealed with AES-256-GCM. Each piece is checked as it's read, so tampering, truncation or reordering is detected. This lets videos play and skip around without decrypting the whole file, and adds about 0.02% to the file's size.
- An encrypted file starts with `FLLK`, and keeps its name and location. A small encrypted note inside it records the original file name, so the recovery tool can restore it.

### Keeping your files safe while they change

- Encrypting and decrypting write to a temporary file beside the original, check the result, and only then swap it in. If the server stops part-way, nothing is lost, and the work picks up where it stopped.
- Library health checks and repair tools never mark, move or delete an encrypted file because they can't read it.
- If an encrypted item shared a file with someone else's identical photo, Frameleaf gives your item its own copy before encrypting it, so their copy stays readable. Encrypted files are never shared this way again. That costs one extra copy of the file.
- Viewing, playing and downloading decrypt the file as it's sent, piece by piece, without making a copy. Work that needs a whole file, such as thumbnails, video conversion, reading details, edits and exports, gets a temporary decrypted copy in a memory-backed folder, readable only by the server, and deleted as soon as the work finishes. A copy left behind by a crash is cleared when the server next starts.

## For server administrators

Locked encryption needs no setup, but a few things on the server affect it.

### Memory for working copies

The temporary decrypted copies described [above](#keeping-your-files-safe-while-they-change) go in `/dev/shm/frameleaf-locked`, which is in memory. Docker gives a container only 64 MB there by default, too little for most videos and RAW files, so the Compose files that come with Frameleaf give the server container 2 GB:

```yaml
services:
  frameleaf-server:
    shm_size: 2gb
```

- **If you use your own Compose file**, add `shm_size` to the server container, as above. Lower it on a NAS with little memory; raise it if you keep very large videos in Locked.
- **Memory exports need room for the whole ZIP.** An [exported memory](https://frameleaf.app/docs/using/memories/#export-a-memory) that holds encrypted items is put together here before it's saved encrypted, so it must fit in full. Raise `shm_size` if people export large memories of Locked items.
- **If a file doesn't fit**, Frameleaf doesn't fall back to the ordinary disk. That piece of work fails with a message naming the folder, how much space was free and how much the file needed, and suggesting a larger `shm_size`.
- **If the folder isn't in memory** (for example, you point it at an ordinary disk), no decrypted copies are made at all, and work on encrypted files waits until that's fixed.
- **On Synology**, the Frameleaf package doesn't set a larger shared-memory size yet, so work on large encrypted videos or RAW files may fail there with that message.

Two [environment variables](https://frameleaf.app/docs/admin/environment-variables/) change this:

| Variable | What it does | Default |
| --- | --- | --- |
| `FRAMELEAF_LOCKED_TMP` | The folder for temporary decrypted copies. It must be in memory (tmpfs) | `/dev/shm/frameleaf-locked` |
| `FRAMELEAF_LOCKED_TMP_ALLOW_DISK` | Set to `true` to allow that folder on an ordinary disk. Decrypted copies are then written to that disk, so use it only for development and testing, never on a server with real Locked files | Off |

### The server's PIN secret

A six-digit PIN has only a million possibilities, so Frameleaf mixes a random secret into every PIN-protected key. The secret is one small file, `locked-pin-pepper.key`, made the first time it's needed and kept in the server's identity folder (`FRAMELEAF_IDENTITY_DIR`, by default `UPLOAD_LOCATION/frameleaf/identity`). Passphrases and recovery keys don't use it.

- **Someone with the key files but not this file can't try PINs at all.** The only way left is typing into Frameleaf, where wrong guesses are limited. By default the identity folder sits inside the library folder, so a copy of the whole library carries both. To make the PIN option stronger against a stolen media drive or a copied share, set [`FRAMELEAF_IDENTITY_DIR`](https://frameleaf.app/docs/admin/environment-variables/#frameleaf-cloud) to persistent storage on another volume.
- **Back the file up, and never replace it.** If it's lost or damaged, nobody's PIN opens their encrypted files. Frameleaf doesn't make a new one in its place; people see a message that the server's Locked pepper is missing and that an administrator must restore it from a backup. Each person's recovery key still opens Locked, and a passphrase still works.
- **Moving to a new server**, bring the identity folder along with `locked-keys`.

### Don't go back to an older Frameleaf version

Frameleaf versions from before Locked encryption can't read encrypted files. While anyone on the server has encryption turned on, don't switch the server back to an older version: their Locked items, thumbnails and videos won't open. If you must go back, ask each person to [turn encryption off](#turn-off-encryption) and wait for decrypting to finish first.

### Deleting a person

When an account is [permanently removed](https://frameleaf.app/docs/admin/users/#delete-an-account), at the end of its recovery period or straight away, its key file is deleted along with its files. Keep a backup that holds the key file if you might need that person's encrypted files later.

## Common questions

**Can my administrator see my encrypted photos?**
Not through Frameleaf, and not by opening the files. They can see that you have encryption turned on, and the information in the database described [above](#what-encryption-doesnt-protect). Someone who controls the running server while your key is open is a different matter; Advanced Security keeps that window short.

**Does encryption slow Frameleaf down?**
Hardly. Thumbnails and details are prepared before encrypting, and decrypting while you view is fast. Encrypted videos play as one file rather than in streamed pieces, so very large videos can take a moment longer to start.

**What happens if I forget everything?**
If you've lost your PIN or passphrase and your recovery key, your encrypted files can't be recovered by anyone. That's what makes them safe from everyone else, too.

**Is the PIN option worth using at all?**
Yes, against casual access: someone browsing the server's shared folder, another person on a shared NAS, or an administrator poking around the library. It isn't enough against someone with a copy of the disk and time. For that, use Advanced Security.

**Can I use a short passphrase?**
It must be at least 12 characters, but length alone isn't strength. Four or five random words are far stronger than a short phrase you'd naturally say.
