The file vault In the app
A file on a stick holding seeds, wallets, entries, notes, and GPG and Secure Boot keys, under Argon2id, with a key file or a YubiKey's secret as an option. It is the vault to use for anything more than one secret on paper.
A vault keeps your secrets encrypted under a passphrase, so a copy can sit on a stick or on paper and nobody can read it without the passphrase.
Faraday's vault is a file. It holds everything you keep in Faraday. The app also makes two codes, Krux's KEF and the QR vault, because a file cannot do one job: keep a single seed on paper, as a QR code you can print. A third code, a proposal, is not in the app. A code has little room, so each of the three trades size against how hard a stolen copy is to guess.
The file vault Its format Size and memory Sealing What it promises Other programs Faraday's own Security How it is checked The forms compared Krux's KEF The QR vault A proposal
Four forms, one for everything and three for a single secret on paper.
A file on a stick holding seeds, wallets, entries, notes, and GPG and Secure Boot keys, under Argon2id, with a key file or a YubiKey's secret as an option. It is the vault to use for anything more than one secret on paper.
A small code, 33 × 33 for 24 words, that a Krux device can also read. For when a code has to open on a device with very little memory. It uses PBKDF2, which costs no memory, so it asks more of the passphrase.
A large code, 77 × 77, holding one item under Argon2id, in standard formats other programs open. For when one secret on paper should cost a guesser memory, and should open without Faraday.
A code about the size of a SeedQR, 29 × 29, under Argon2id. Nobody can choose this one: it is a draft with test vectors and a Rust implementation by the same authors (a library, a command line and a desktop test app), with no outside one, and it stays out of the app until it has been reviewed.
Each form's facts are from its specification: the file vault and the QR vault, KEF, the proposal.
What keeps secrets safe, and what lays the file out.
The passphrase, Argon2id, ChaCha20 and HMAC-SHA-256. This is what keeps secrets safe. All of it is published, and each algorithm comes from an established library: argon2, chacha20, sha2 and hmac.
The code that lays the file out, reads it back and decides which field holds what. Most of what is Faraday's own is here. A bug here usually means a file that does not open. The exception is under Security.
KDBX 4.0, as KeePass's specification says.
.kdbx. A file is recognised by its contents, whatever its name.| Item | How it is kept |
|---|---|
| Entries | KeePass entries, with their title, user name, password, address, notes and TOTP code |
| Bitcoin keys | BIP-39 words or a BIP-32 seed in a protected field, with the BIP-39 passphrase only where the person chose to keep it there |
| Wallets | A BIP-388 wallet policy, or a descriptor |
| Notes and recovery sheets | Text, and a descriptor with its note |
| GPG keys | The armored secret key, the public certificate and the revocation certificate |
| Secure Boot keys | The owner GUID, and each key and certificate as PEM |
| Shares and passphrases | Wallet shares, codex32 shares and BIP-39 passphrases, each with what it belongs to |
Each of Faraday's items is a KeePass entry whose custom data names its kind. Custom data is part of KDBX 4, inside the encryption: any KDBX reader with the passphrase reads it. An item that is damaged does not refuse the file: it is named as Unreadable, never loaded or used, and written back as it was read.
.keyx) holding 32 random bytes, written to the Outbox, or takes any file from a stick. If it is lost or changed, the vault cannot be opened.keepassxc-cli and pykeepass; the YubiKey's response is checked against kdbxweb, KeeWeb's library, and not yet against KeePassXC's own test file.A file vault grows by itself. Its memory step is chosen when it is made and can be changed on an open vault, taking effect at the next seal.
There is no size to choose. A new vault holds 32 KiB of contents, and each seal pads them to the smallest multiple of 32 KiB that holds what the vault holds, up to 128 MiB. It shrinks the same way when it holds less.
| Vault | Contents | File |
|---|---|---|
| New, or small | 32,768 B | 33,153 B, for keys, wallets and a few entries |
| Larger | a multiple of 32,768 B | that, plus 313 B of header and 36 B for each 1 MiB block and the empty block after them |
| The largest | 134,217,728 B (128 MiB) | 134,222,685 B, a KDBX file with its attachments |
Faraday pads with line feeds after the document's closing tag, which XML allows, so a file Faraday sealed says by its length only how much it holds, to within 32 KiB. A KeePass app's save drops the padding, so the length of a file saved there says more until Faraday seals it again. A file with contents up to 128 MiB opens, whatever its length.
Memory comes before size. Faraday checks what the computer has free before it reads a file from a stick, before an unlock, once the contents are decrypted and before a seal, and says so instead of starting. A seal that does not fit stops a lock: the vault stays open with its changes and the Lock sheet names what is short.
| Memory | Bits added | Memory free to open | Opens on |
|---|---|---|---|
| 64 MiB | ≈17.6 | 165 MiB | anything, a 512 MB Pi Zero 2 W included |
| 128 MiB | ≈18.6 | 229 MiB | a Pi Zero 2 W and anything larger |
| 256 MiB, the default | ≈19.6 | 357 MiB | a 1 GB Raspberry Pi 3 and anything larger |
| 512 MiB | ≈20.6 | 613 MiB | a 1 GB Pi 3 with little else running; any PC |
| 1 GiB | ≈21.6 | 1,125 MiB | a Pi 4 or 5 with 2 GB or more; a PC with 2 GB or more |
The memory free to open is for a new vault's 32 KiB file: Argon2id's memory, twice the file and 100 MiB, and each further MiB of the file adds two. Bits added is log2(memory in KiB × passes), an estimate that counts work only. The Pi 3 image is 32-bit, where one allocation of 512 MiB or 1 GiB may fail even with the memory free.
A machine without the memory cannot open the vault at any speed; a slow machine opens it slowly. So the step is chosen for the weakest machine the vault will ever be opened on. Faraday says when a vault does not fit, before the passphrase is typed.
Doubling the memory is worth one bit of passphrase strength, and the five steps span four bits. One more word from the EFF long list is 12.9 bits. A six-word dice passphrase, 77.5 bits, is out of reach at any step here; a short or reused passphrase is not protected by any step here.
RFC 9580 recommends Argon2id with 3 passes, 4 lanes and 64 MiB where 2 GiB cannot be spared, and RFC 9106 gives the same choice. The steps above 64 MiB keep its passes and lanes and raise its memory. Lanes do not change the work of a guess.
Sealing writes the open vault back as a file, at every lock.
Every seal draws a new master seed, encryption IV, Argon2 salt and inner stream key from the system's randomness, mixed with whatever the person added through Add randomness. Argon2id runs again. A seal waits for the randomness it needs and never stretches less.
Every seal is a new file, so an open vault's passphrase, memory step and key file can each be changed. Copies sealed before keep theirs.
The file is opened again under the keys it was made under, and its contents must be the ones written. A file that fails is not given, and the vault stays open with its changes.
The count and the time of the last seal are in the database's custom data, inside the encryption. The app keeps the highest count it has seen of each vault. Opening an older copy stops at a dialog, Open this copy?, which names the vault and the copy it saw.
The sealed file is written beside the original and read back byte for byte before the original is deleted. FAT has no atomic replace: if a visit finds both, it keeps the original when it reads back whole and discards the new file; otherwise the new file is the vault and takes the original's name. A file of the same name that is not an earlier copy of the vault stays, and the seal goes beside it as name-2.kdbx.
And what it does not.
A vault is a standard file. It is meant to be opened in Faraday, on the offline device.
pykeepass, keepassxc-cli and keepass-rs open what Faraday writes. KeePass, KeePassDX and Strongbox read the format and have not yet been tried on it.
Unlocking a vault on a phone or computer connected to the internet shows its seed on that machine. It is a last resort, if Faraday is gone and the seed is needed back: do it once, move the funds to a new seed, and treat the old one as exposed.
| Setting | Faraday writes | Faraday reads |
|---|---|---|
| Version | 4.0 | 4.0 and 4.1 |
| Cipher | ChaCha20 | ChaCha20, AES-256 (CBC) |
| Key derivation | Argon2id | Argon2id, Argon2d |
| Compression | None | None, gzip |
| Inner random stream | ChaCha20 | ChaCha20 |
| Key | The passphrase, and a key file if the person adds one | The passphrase, with a key file or a YubiKey's secret or both |
The format and the algorithms are published. These pieces are not.
| Piece | What it does | What could replace it | Why it is not taken |
|---|---|---|---|
| KDBX reader and writer | Reads and writes the file vault | The keepass crate (keepass-rs) | It drops XML elements it does not model, which would disturb what a KeePass app wrote, and it draws a save's randomness itself, with no way to pass the session's in. It is used in the tests as an outside reader and writer, never in what ships. |
| Faraday's names inside the vault | Which field holds a seed's words, a wallet or a GPG key, and the faraday.* custom data | Nothing: there is no standard for Bitcoin seeds in KeePass | Unavoidable. An item the reader does not expect is named Unreadable and never used. |
| Padding after the XML | Keeps file sizes fixed | None in KDBX | It uses what XML already allows. |
| OpenPGP code for the QR vault | Writes and reads its three packets | rPGP (pgp), or Sequoia | Each brings every algorithm OpenPGP has had: rPGP needs 61 required crates, each to vet, for a message that uses AES and OCB alone. rPGP is audited. |
| HKDF | Turns one key into others, in the QR vault only | The hkdf crate | It leaves the intermediate key and each output block in freed memory unwiped; Faraday's own wipes them. |
| The QR vault's contents | The 226 bytes of padded TOML inside the code | Nothing: no standard exists for an encrypted seed QR other tools read | Unavoidable. |
What each custom part means for the secrets in a vault.
An attacker with the file faces Argon2id at the vault's memory step, then ChaCha20. None of that is Faraday's design.
The device reads files from outside. A reader bug could crash, hang, or wrongly accept or refuse a file. The guards: limits checked before any work (memory 8 MiB to 1 GiB, passes 1 to 100, lanes 1 to 64); an XML reader that refuses a DOCTYPE and unknown entities; a fuzz target for each reader.
If Faraday's code reused a value it should draw fresh, a nonce say, the file would still open everywhere, so opening it elsewhere would not notice, but the encryption would be weaker. A library carries the same risk in its own code. The guard: every seal draws its bytes from one call for the session's randomness, and the specification counts every byte that call returns.
A large library is more code Faraday did not write and more to vet, looked at by others. A small piece of Faraday's own is less code and nothing extra to vet, looked at by Faraday and its tests.
Against published vectors and a reader Faraday did not write.
keepassxc-cli both ways: each opens Faraday's files with every field, group and attachment, Faraday opens theirs with the same fields, and each refuses a wrong passphrase and a changed byte. KeePassXC ends a protected value at its first NUL, which Faraday keeps: a known difference, counted. The area also compares the payload layouts, a passphrase's NFC form and Argon2id with outside code, and reads key files against keepassxc-cli and pykeepass.sq, by rPGP and by a judge over PyCA cryptography, and what they make is opened by Faraday. sq cannot seal one, as it writes only the older OpenPGP packets, so the area checks that Faraday refuses what sq writes. The judge's framing is Faraday's own second version, not another program's.From here on the page is about the three codes. The file vault is in the table for comparison.
| Krux's KEF | QR vault | AQRV, a proposal | File vault | |
|---|---|---|---|---|
| Passphrase protection | PBKDF2-HMAC-SHA-256, no memory cost | Argon2id, 64 MiB to 1 GiB | Argon2id, 64 MiB to 1 GiB | Argon2id, 64 MiB to 1 GiB |
| Cipher and check | AES-256, by default GCM with its tag cut to 4 bytes | AES-256 in OCB mode, 16-byte tags | ChaCha20, HMAC-SHA-256 cut to 4 or 8 bytes | ChaCha20, HMAC-SHA-256 in full |
| A 24-word seed | 61 bytes, 33 × 33 at medium error correction | 396 bytes, 77 × 77 at medium | 53 bytes, 29 × 29 at low; or 62 bytes, 33 × 33 at medium | A file of 32 KiB or more, not a code |
| Shows what it holds | Its length: 12 or 24 words can be told apart | No: every code is one size | No, within a size | Only how much it holds, to within 32 KiB |
| Memory to open | Little: it runs on microcontrollers | 64 MiB to 1 GiB for Argon2id | 64 MiB to 1 GiB for Argon2id | 64 MiB to 1 GiB for Argon2id, and about 100 MiB more |
| Standing | One project's published specification, in use on its devices | RFC 9580, a Proposed Standard, which several outside programs open | A draft: a Rust implementation by the same authors, no outside one, no review | KeePass's published format |
| In the app | Yes | Yes | No, and not before an outside review | Yes |
The Krux project's encrypted code: small enough for 33 × 33, opened by a Krux device or by Faraday.
KEF, the Krux Encryption Format, is an envelope for encrypted bytes: a label, a version, a PBKDF2 count and an AES payload. Krux publishes its specification, with its own code as the reference.
The cryptography is standard. The format is one project's: it is not a BIP, a SLIP or an RFC, no other implementation was found, and no outside review of it is known.
len_id | id | version | count | payload
The key is PBKDF2-HMAC-SHA-256 of the passphrase, with the id as the salt, 32 bytes, always for AES-256. The id, the version and the count are in the clear. Krux's default id is the wallet's fingerprint.
Reads and writes all twelve versions as Krux v26.09.0 does, and writes version 20 by default with a random 8-byte id, not the fingerprint: a fingerprint on a printed code says which wallet it opens, and gives every code of a seed under one passphrase and count the same key. The default count is 100,000, Krux's, and 10,000 to 500,000 is offered. Versions 0 and 1 are written as legacy.
Reads a code as raw bytes or as hex, base32, base43 or base64 text. Writes base43 at medium error correction for anything that fits one code, and refuses larger contents. The passphrase on writing is printable ASCII, 1 to 200 characters, stricter than the vault's, since a code has to open on a device with a small keypad. Left out: Krux's seeds.json store, and a passphrase that is itself a KEF code.
Faraday scans a code and makes one from a seed or in Tools. It is checked both ways against Krux's own code, in every version, running in software. It is not checked on a Krux device, since the project has none: that a device's AES engine gives the same first 4 tag bytes rests on Krux's claim of compatibility.
| Version | AES mode | IV | Padding | Compressed | Check |
|---|---|---|---|---|---|
| 0, legacy | ECB | None | NUL | No | 16 bytes of SHA-256 of the plaintext, encrypted |
| 1, legacy | CBC | 16 bytes | NUL | No | 16 bytes of SHA-256 of the plaintext, encrypted |
| 5 | ECB | None | NUL | No | 3 bytes of SHA-256 over the version, plaintext and key, in the clear |
| 6 | ECB | None | PKCS#7 | No | 4 bytes of SHA-256 of the plaintext, encrypted |
| 7 | ECB | None | PKCS#7 | Yes | 4 bytes of SHA-256 of the compressed bytes, encrypted |
| 10 | CBC | 16 bytes | NUL | No | 4 bytes of SHA-256 over the version, IV, plaintext and key, in the clear |
| 11 | CBC | 16 bytes | PKCS#7 | No | 4 bytes of SHA-256 of the plaintext, encrypted |
| 12 | CBC | 16 bytes | PKCS#7 | Yes | 4 bytes of SHA-256 of the compressed bytes, encrypted |
| 15 | CTR | 12 bytes | None | No | 4 bytes of SHA-256 of the plaintext, encrypted |
| 16 | CTR | 12 bytes | None | Yes | 4 bytes of SHA-256 of the compressed bytes, encrypted |
| 20, Krux's default | GCM | 12 bytes | None | No | GCM's tag cut to 4 bytes, in the clear |
| 21 | GCM | 12 bytes | None | Yes | GCM's tag cut to 4 bytes, in the clear |
| Versions | For | Against |
|---|---|---|
| 20, 21 (GCM) | Everything; Krux's default. The only family with a keyed check over the ciphertext | The 4-byte tag |
| 15, 16 (CTR) | Devices without GCM | The check is an unkeyed hash inside the ciphertext. Someone who knows the plaintext can change the code to say anything else and fix the check, without the passphrase |
| 10, 11, 12 (CBC) | Devices without GCM | Larger: a 16-byte IV |
| 5, 6, 7 (ECB) | The smallest code: 29 × 29 for 12 words at medium | No IV. Under one key, equal 16-byte blocks of plaintext give equal blocks of ciphertext, and one plaintext gives one code each time. So under one passphrase, id and count, two codes of a seed are the same code. A random id gives each code its own key, which removes that case |
| 0, 1 | Reading older codes | Marked legacy by the specification, which points to 5 and 10 |
| Holds | Version | Bytes | Base43 characters | Code, at medium error correction |
|---|---|---|---|---|
| 12 words | 5 | 32 | 47 | 29 × 29 |
| 12 words | 20 | 45 | 66 | 33 × 33 |
| 24 words | 5 | 48 | 70 | 33 × 33 |
| 24 words | 20 | 61 | 90 | 33 × 33 |
| 24 words | 10 | 65 | 95 | 37 × 37 |
Each with an 8-byte id. Version 5 can be written at low error correction, which makes 12 words 25 × 25 and 24 words 29 × 29, and tolerates about half the damage. Krux shows a mnemonic as base43 text, which fits a code's alphanumeric mode and which a person can copy by hand.
A guess costs count runs of HMAC-SHA-256, which specialised hardware does very quickly, and it needs no memory. Krux's default of 100,000 adds about 16.6 bits to a passphrase as work, and 500,000 about 18.9. Argon2id at 64 MiB to 1 GiB adds about 17.6 to 21.6 by the same count, and also needs its memory for every guess, which that count does not show. OWASP asks for 600,000 for PBKDF2-HMAC-SHA-256, more than Krux's setting allows.
| Passphrase | Bits | To try them all on one graphics card, at 100,000 |
|---|---|---|
| 6 dice words | 77.5 | about 76 billion years |
| 4 dice words | 51.7 | about 1,300 years; on 1,000 cards, about 16 months |
| 8 random lower-case letters | 37.6 | about 27 days |
| One dice word and 4 digits | 26.2 | about 15 minutes |
Worked out from a published hashcat benchmark of one high-end graphics card at stock clocks: 8,865.7 kH/s for PBKDF2-HMAC-SHA256 at 999 iterations, about 88,000 guesses a second at 100,000. A guess finds the passphrase in half this time on average. A person-chosen passphrase can be far weaker than any row. The specification says it plainly: "KEF offers no expectation of security for a weak user-supplied key."
A check of 3 or 4 bytes says the passphrase was probably right. A wrong one passes about 1 time in 16,777,216 (version 5) or 4,294,967,296 (the 4-byte versions), and what comes out is random bytes. Sixteen or 32 random bytes are a valid seed, so the person compares the wallet's fingerprint with what they wrote down.
KEF has no padding: Krux has to be able to read the contents as they are. A code's size says whether it holds 12 or 24 words, and a note's size says its length.
A short code, opened by a Krux device or by Faraday, including on a device with very little memory. A code can be copied unnoticed and attacked for ever, so the passphrase is the whole of the protection.
One item at 77 × 77, memory-hard, in standard formats outside programs read.
Every guess costs Argon2id's memory, 64 MiB to 1 GiB. Every code has full 16-byte tags, not a cut check. It is padded to one size, so a code does not show what it holds, or whether it holds anything. And it opens without Faraday.
It holds one 12- or 24-word seed, one codex32 share, one BIP-39 passphrase with the fingerprint of its key, or a short note.
A QR vault is an RFC 9580 OpenPGP message under a passphrase: one SKESK v6 packet with the Argon2 string-to-key, and one SEIPD v2 packet with AES-256 in OCB mode, holding a literal data packet. OCB is the one AEAD RFC 9580 requires every implementation to have.
The contents are a TOML v1.0.0 document padded to 226 bytes. Which keys it uses is Faraday's own rule, since no standard exists for this. The message is 396 bytes: QR version 15, 77 by 77 modules, at medium error correction.
A QR vault has to fit a code a phone reads off a small screen or a print. The smallest KDBX file holding the same seed is about 1,140 bytes, QR version 28, 129 by 129 modules. So the code uses RFC 9580, and the file vault KDBX.
Every seal is a new code. A code printed before still opens, to what it held when it was sealed, so a new code means destroying the old one.
Sequoia's sq, GopenPGP, OpenPGP.js and rPGP open it. GnuPG does not, since it follows LibrePGP rather than RFC 9580.
On a computer, save the code as its bytes with zbarimg --raw -Sbinary code.png > vault.pgp, then sq decrypt vault.pgp. Read as text, the bytes are mangled and Sequoia refuses them.
On Android, the camera app and Google Lens read a code as text. A scanner that gives raw bytes and an app that reads RFC 9580 are both needed, and no mainstream Android app is known to read RFC 9580.
One tool in Tools makes and opens a code. A file vault's item, a seed, a codex32 share, a passphrase or a note, also offers Save as a QR vault. A code is never kept open: to change what it holds, a new one is made. Faraday Starter has no such tool.
A code scanned where a SeedQR is scanned, or a .pgp file chosen in Files, opens to a passphrase typed once, with its cost checked before the work starts. A seed's words go to the seed sheet, a share to Add a key, a passphrase to the key it belongs to and a note to an open file vault.
The picture is a PNG saved to the Outbox, labelled with "QR vault", the vault's name and the date, never what it holds. A code of 77 × 77 is not copied by hand: its paper is that PNG, printed from a computer with a printer.
A large code: 77 × 77 cannot be copied by hand, and it needs a good print or screen. It needs 64 MiB or more to open, so a microcontroller signing device cannot read it.
OCB does not commit to its key, so a code made by someone else could be built to open to two contents under two passphrases. Faraday makes every QR vault under one.
A memory-hard code the size of a SeedQR. A draft: it has test vectors and a Rust implementation by the same authors, with no outside one, and it is not in the app.
Krux's KEF fits a seed in a small code under PBKDF2, which needs no memory. The Argon QR Vault (AQRV) is the same idea under a memory-hard function: one small secret under a passphrase, with Argon2id at 3 passes, 4 lanes and 64 MiB to 1 GiB, ChaCha20 and HMAC-SHA-256 cut short.
It is proposed as an open format. It carries no name of Faraday's and depends on nothing of it.
A BIP-39 seed of any length, a codex32 string, a BIP-39 passphrase, a short note or a raw 32-byte key. The kind is not stored and the rest of the room is random, so a code does not show which it holds, within a size.
It does not make a weak passphrase safe: a code can be photographed and attacked offline. It does not open on most microcontroller signing devices, which lack 64 MiB. Its tag is too short to prove that an item is the one sealed, so a reader shows the wallet's fingerprint where the kind has one. KEF stays the form for small devices, and an OpenPGP code the form with outside readers.
| Envelope | Code | Room for the item | Tag | A wrong passphrase gets past the check |
|---|---|---|---|---|
| 32 bytes | 25 × 25 at low error correction, carried as text | 16 bytes | 4 bytes | 1 time in 1.4 billion |
| 53 bytes | 29 × 29 at low error correction | 32 bytes | 4 bytes | 1 time in 477 million |
| 62 bytes | 33 × 33 at medium error correction | 37 bytes | 8 bytes | 1 time in 2 × 1018 |
The length says which size it is, and enters the tag. The longer tag is a better check for a person and a better test for a guesser, so at that size the passphrase has to stand alone.
A wrong passphrase that gets past the check does not open what the code holds, which stays encrypted. It decrypts to random bytes, and those usually read as a valid but different seed, so the person compares the wallet's fingerprint with the one they wrote down.
Every primitive is published. The composition with a short tag is not a named standard, and that is the first thing a reviewer is asked about.
Answers of "this is wrong" are wanted most of all. The specification lists all eleven.
A review that finds the 4-byte tag unacceptable ends the small size, not the aim. Comments go to the repository's issues.