Security whitepaper

Cryptographic primitives

All cryptography goes through one module of the app. No other part of the app calls a crypto library for vault data.

Key hierarchy

1. You enter a code: a pattern, a PIN or a password. The code type is part of what is hashed, so the same characters entered as a PIN and as a password give different keys and open different vaults.
2. The code, together with a secret that is made on first launch and never leaves this iPhone, goes through Argon2id with 64 MiB of memory. The number of passes is calibrated once per device so that one derivation takes between 0.5 and 1.0 seconds, and it is never lowered afterwards.
3. The result is the access key.
4. From the access key come the locator, which names the vault's header file, and the header key.
5. The header key opens the header, which holds the master key. The master key is random and belongs to one vault.
6. From the master key come the index key, which opens the index database, and the backup key, which protects what goes to iCloud. Each file and each thumbnail has its own random file key, which is kept in the index.

The recovery phrase and Face ID are two other ways to reach the same master key. They are described below.

Vault headers

Each vault has a header of one fixed size. It holds the master key and is encrypted with a key that comes from the code. Lockveil also keeps dummy headers made of random data, which look the same as real ones to anyone who does not have a key.

To sign in, Lockveil derives the locator from the code and looks for the header with that name. A missing file and a failed decryption are handled in the same way, so nothing tells a code that opens nothing apart from a file that does not exist. The slow key derivation always runs first.

Slot padding is the plan to keep a minimum number of header and database files on the iPhone at all times, mixed with dummies, so that counting files tells nothing. It is planned but not guaranteed: we decided it as something we should do, not something we promise (see limitation 3). We will not describe Hidden mode as hiding how many vaults you have until slot padding is in place.

Changing a code is built to survive a crash at any point: the new header is written first, the old one is removed afterwards, and the master key and the files are not touched.

Sign-in and lockout

Lockveil offers three code types: a pattern of at least 6 dots with a change of direction, a PIN of 4 to 12 digits, and a password of at least 8 characters. Every vault has its own code type, and the sign-in screen lets you switch between them without any cost or failed attempt.

In Classic mode, wrong codes are slowed down. Failures 1 to 4 have no delay. The 5th failure locks sign-in for 30 seconds, failures 6 to 9 lock it for 30 seconds each, and the 10th and every later failure locks it for 5 minutes. The counter resets after a correct code. It is stored on the device and survives restarts.

Hidden mode never shows an error, never delays and never takes an intruder photo, because any of these would show that the mode is on.

Sign-in modes

• Classic is the default and the recommended mode. An unknown code shows an error, and Pro adds an optional photo of the person who typed it. The first vault you create is the main vault. It sets up the decoy vault, the panic passcode, the attempt log and the Share Sheet inbox. It cannot open, list or count any other vault.
• Hidden treats every vault the same. An unknown code opens a new empty vault that exists only in memory until you add something to it. There is no decoy role, no attempt log and no intruder photo.

One code opens exactly one vault. No vault holds another vault's keys, locators or identifiers. In Classic mode, decoy and standard vaults are sandboxed: settings changed inside them stay inside them and have no effect on the rest of the device.

Decoy vault and panic passcode

A decoy vault is a separate vault with its own code, its own master key and its own recovery phrase. It is made from the main vault, which keeps only a flag that a decoy exists, and never its keys or contents. Face ID can never be turned on for a decoy.

The panic passcode opens a target vault, in the same way and at the same speed as a normal sign-in. In the background it then erases the other vaults from this iPhone: their headers, databases and files, and the Face ID record if it belongs to another vault. The panic passcode never deletes anything in iCloud, so erased vaults stay recoverable with their recovery phrases. A copy of the iPhone taken earlier is not affected (see limitation 7).

Face ID

Face ID works for one vault per device. Lockveil makes a key inside the Secure Enclave and uses it to seal that vault's keys. When you use Face ID, iOS releases the Secure Enclave key and the vault opens. If someone adds a new face to the iPhone, the key becomes unusable. Lockveil then turns Face ID off, tells you once, and asks for your code. Face ID is not offered for decoy vaults or for panic targets. See also limitation 5.

Recovery phrase

Every vault has one recovery phrase at a time, and you choose its kind:

• 12 words, the default. They are random and come from a standard word list, so they are strong enough to need no slow function.
• Your own phrase, typed twice. It is never stored anywhere, so it can be replaced but never shown again. Because people choose guessable phrases, it always goes through Argon2id. See limitation 10.

Nobody else holds a copy of either kind. If you change the phrase, the old one stops working. A recovery header is kept on the iPhone, so a forgotten code can be reset without a network, and a matching record goes into your backup, so a new iPhone can restore the vault.

Backup

Only encrypted data leaves the iPhone. File contents are uploaded as the same ciphertext split into blocks of one fixed size, 4 MiB, and the last block is padded with random bytes, so iCloud never sees real file sizes. Everything goes into the private database of your own iCloud account. The keys never leave your devices, and uploads work while the vault is locked, because everything is encrypted at the moment it changes. Backup is never deleted when Pro ends and is never touched by the panic passcode. See limitation 9 for what Apple can still see.

iOS device backups

This is separate from Lockveil's own backup. Vault headers, indexes and recovery records are always included in iOS device backups. The encrypted files are left out while Lockveil's own iCloud backup is on and up to date, and included otherwise. So with Lockveil backup off, your encrypted files are part of your iPhone's regular device backup. We chose this so that moving to a new iPhone keeps working for people who turned our backup off, and so that people who use it do not pay for their iCloud storage twice.

Readable data on storage

Decrypted content is not written to storage, with two kinds of exception. The first is a system hand-off when you import: the temporary file that the photo picker, the document picker or the camera gives the app. The second is a copy you ask for: exporting, sharing, or opening a file in another app. These temporary copies get the strongest iOS file protection, are left out of backups and are deleted as soon as the operation ends, with a sweep at the next launch as a safety net. Viewing photos, playing video, reading documents and notes, and drawing thumbnails all happen in memory.

Locking and screen privacy

The app locks as soon as you leave it, with a choice of delays, and on an incoming call. Locking closes the session, wipes the keys, closes the database and drops decoded images. A privacy cover hides the app in the app switcher and while the screen is being recorded or mirrored. Screenshots cannot be blocked on iOS (see limitation 1).

Memory and logging

Keys live only in dedicated key types, buffers from the crypto library are wiped after use, and what you type as a code is cleared right after the key is derived. Lockveil never logs keys, codes, phrases, locators, file names, folder names, note text or the number of items in a vault. Recovery words are shown as text that cannot be selected or copied. Swift cannot promise that no temporary copy remains in memory (see limitation 8).

Tests and independent audit

The crypto code is designed to be tested before anything else. The required tests are known-answer tests against published test vectors, sample files that were frozen once and must open forever, negative tests that damage a header or a chunk and expect a clean failure, round-trip tests with random file sizes, tests for both recovery phrase kinds, and a scan showing that one vault's keys and identifiers never appear in another vault's data.

An independent audit of the cryptography is planned before public release. The auditor has not been chosen yet. This page will say so when that changes, and will link to the audit report once it exists.