Every KeePass password database, whether it was saved by KeePass, KeePassXC, KeePassium, Strongbox or OpenVireo, is a .kdbx file. The format has existed for more than fifteen years, and it’s simple enough that you can read the start of it with xxd and a pen.
I’ve spent a lot of this year inside it. OpenVireo started as a fork of KeePassXC, and later I wrote a KDBX reader and writer from scratch in Rust (ov-kdbx) so that the web app, the iPhone app and the desktop app all handle the files with the same code. This series is what I wish I’d had before I started: the format taken apart one layer at a time, with a small parser that grows with each post.
This first part covers everything before the encryption starts: the signature, the version, and the outer header. That’s the part anyone can read, with or without the password.
The layers
A .kdbx file is a set of nested layers. Each layer tells you how to open the next one.
| Layer | Readable without the key? | Part |
|---|---|---|
| Signature and version: 12 bytes | yes | 1 |
| Outer header: type-length-value fields naming the cipher and KDF | yes | 1 |
| Header hash and HMAC (KDBX 4): proof the header wasn’t changed | the hash, yes; the HMAC needs the key to check | 3 |
| Payload: AES-256 or ChaCha20, then gzip | no | 2, 3 |
| Inner header (KDBX 4): inner stream key, attachments | no | 4 |
| XML document: groups, entries, history | no | 5 |
| Protected values: passwords XOR-ed with a second keystream | no | 4 |
The series follows roughly that order:
- Anatomy (this post): the signature, version and outer header.
- From password to key: how a password and key file become a 32-byte key, and why a parser must refuse some KDF settings.
- Checking and decrypting: the header HMAC, the HMAC block stream and the ciphers.
- The inner header and protected values: why passwords are encrypted twice, and the ordering bug almost everyone writes once.
- The XML payload: groups, entries, history, tombstones and some odd timestamp encodings.
- Writing it back safely: round trips, fuzzing, and making the output byte for byte identical.
A first look at the bytes
Here are the first 48 bytes of the KDBX 4 sample from the repo:
00000000: 03d9 a29a 67fb 4bb5 0000 0400 0210 0000 ....g.K.........00000010: 00d6 038a 2b8b 6f4c b5a5 2433 9a31 dbb5 ....+.oL..$3.1..00000020: 9a03 0400 0000 0100 0000 0420 0000 0012 ........... ....That doesn’t look like much yet. By the end of this post you’ll be able to read every byte of it. If you’d rather click than read, the explorer below parses the header live. It can also open one of your own files, entirely in your browser.
Interactive header explorer: needs JavaScript. Run `cargo run -- header samples/sample-kdbx4.kdbx` from the companion repo for the same breakdown in a terminal.
The signature: two magic numbers
Every KeePass 2.x file starts with two little-endian 32-bit numbers:
| Offset | Bytes | As u32 (LE) | Meaning |
|---|---|---|---|
| 0 | 03 d9 a2 9a | 0x9AA2D903 | “This is a KeePass file” |
| 4 | 67 fb 4b b5 | 0xB54BFB67 | “…and it’s KeePass 2.x (KDBX)” |
The second number tells the generations apart. KeePass 1.x .kdb files use the same first signature but 0xB54BFB65 as the second, and their layout is completely different. A good reader checks for it and gives a specific error instead of “corrupt file”, because “you’ve opened a KeePass 1 database” is something a user can act on.
Everything in KDBX is little-endian. If you remember one thing about the format, make it that.
The version: minor first
The next four bytes are the format version, stored as one little-endian u32: 0x00040000 for KDBX 4.0, 0x00040001 for 4.1, 0x00030001 for 3.1. Read as two u16s, that puts the minor version first:
00 00 04 00 → minor 0, major 4 → KDBX 4.001 00 03 00 → minor 1, major 3 → KDBX 3.1The split matters for compatibility. The major version changes when the layout changes, so a reader must refuse a major version it doesn’t know. Minor versions add optional features that older readers can skip: KDBX 4.1 (KeePass 2.48) only added things inside the XML, such as group tags and previous-parent references. The header layout is the same as 4.0.
In practice you’ll meet three versions:
| Version | Written by | Header length field | KDFs |
|---|---|---|---|
| 3.1 | KeePass before 2.35 (and later versions until 2.57, when nothing newer was needed), KeePassXC with AES-KDF | u16 | AES-KDF |
| 4.0 | KeePass 2.35+, most modern apps | u32 | AES-KDF, Argon2d, Argon2id |
| 4.1 | KeePass 2.48+, KeePassXC 2.7+ | u32 | same as 4.0 |
KeePassXC still writes 3.1 when a database uses AES-KDF and needs nothing newer. That’s why the repo has a 3.1 sample made by a KeePassXC-based CLI in 2026. Since 2.57, KeePass itself only writes 4.x.
The outer header: a list of TLVs
After the 12 bytes of signature and version comes the outer header: a list of type-length-value fields, terminated by a field with id 0.
┌────┬───────────────┬──────────────────────┐│ id │ length │ value ││ u8 │ u16 (3.1) │ `length` bytes ││ │ u32 (4.x) │ │└────┴───────────────┴──────────────────────┘That’s the only layout difference between the two versions: KDBX 4 made the length field wider, from 2 bytes to 4. Back to our sample at offset 0x0c:
02 id 2 = CipherID10 00 00 00 length 16 (u32, because this is KDBX 4)d6 03 8a 2b 8b 6f 4c b5 a5 24 33 9a 31 db b5 9a the cipher UUID: ChaCha20Then field 3 (03 04000000 01000000: compression = 1, gzip), field 4 (32 bytes of master seed), and so on until 00 04000000 0d0a0d0a: id 0, length 4, value \r\n\r\n. The value of the end marker doesn’t mean anything. KeePass writes those four bytes and every reader ignores them.
The fields
| Id | Name | Version | Value |
|---|---|---|---|
| 0 | EndOfHeader | both | \r\n\r\n, ignored |
| 1 | Comment | both | free text, almost never present |
| 2 | CipherID | both | 16-byte UUID of the payload cipher |
| 3 | CompressionFlags | both | u32: 0 none, 1 gzip |
| 4 | MasterSeed | both | 32 random bytes, new on every save |
| 5 | TransformSeed | 3.1 | AES-KDF seed |
| 6 | TransformRounds | 3.1 | u64 AES-KDF rounds |
| 7 | EncryptionIV | both | IV or nonce: 16 bytes (AES), 12 (ChaCha20) |
| 8 | ProtectedStreamKey | 3.1 | key for the inner stream cipher |
| 9 | StreamStartBytes | 3.1 | the first 32 plaintext bytes, to detect a wrong key |
| 10 | InnerRandomStreamID | 3.1 | u32: 2 = Salsa20 |
| 11 | KdfParameters | 4.x | VariantDictionary (below) |
| 12 | PublicCustomData | 4.x | VariantDictionary for plugins |
The 3.1-only fields tell the story of KDBX 4:
- 5 and 6 became field 11. KDBX 3.1 had exactly one KDF, so its seed and round count got their own fields. KDBX 4 added Argon2, which needs more parameters, so the KDF moved into a small typed dictionary that can describe any KDF.
- 8, 9 and 10 moved inside the encryption. The inner stream key now lives in the encrypted inner header (part 4), where an attacker can’t see it. StreamStartBytes, the old “is the key right?” check, was replaced by an HMAC over the header (part 3).
Cipher UUIDs
Algorithms are named by UUIDs rather than small numbers, so anyone can add one without a central registry. These are written as their raw 16 bytes, with no endian swapping:
| UUID | Cipher |
|---|---|
31c1f2e6-bf71-4350-be58-05216afc5aff | AES-256-CBC |
d6038a2b-8b6f-4cb5-a524-339a31dbb59a | ChaCha20 |
ad68f29f-576f-4bb9-a36a-d47af965346c | Twofish-CBC (a KeePass plugin; KeePassXC supports it) |
VariantDictionary: the KDF parameters
Field 11 is a small serialised key-value map called a VariantDictionary. It starts with a u16 version (0x0100), then repeats type, key length, key, value length, value until a type byte of 0:
00 01 version 1.042 type 0x42 = byte array05 00 00 00 24 55 55 49 44 key "$UUID"10 00 00 00 9e 29 8b 19 … 16-byte value: Argon2id42 01 00 00 00 53 20 00 00 00 89 ec d5 … "S" = 32-byte salt04 01 00 00 00 50 04 00 00 00 02 00 00 00 "P" = 2 (u32)05 01 00 00 00 4d 08 00 00 00 00 00 00 04 00 00 00 00 "M" = 64 MiB (u64)05 01 00 00 00 49 08 00 00 00 03 00 00 00 … "I" = 3 (u64)04 01 00 00 00 56 04 00 00 00 13 00 00 00 "V" = 0x1300 endThere are seven types: 0x04 u32, 0x05 u64, 0x08 bool, 0x0C i32, 0x0D i64, 0x18 UTF-8 string and 0x42 bytes. The keys are single letters defined by each KDF:
| KDF | $UUID | Keys |
|---|---|---|
| AES-KDF | c9d9f39a-628a-4460-bf74-0d08c18a4fea | R rounds, S seed |
| Argon2d | ef636ddf-8c29-444b-91f7-a9a403e30a0c | S salt, M memory in bytes, I iterations, P lanes, V version, optional K secret and A associated data |
| Argon2id | 9e298b19-56db-4773-b23d-fc3ec6f0a1e6 | same as Argon2d |
Two traps here. First, M is in bytes, but the Argon2 libraries you’ll call take KiB, so divide by 1024. Second, AES-KDF has a second UUID in the wild (7c02bb82-79a7-4ac0-927d-114a00648238, from KeePassXC), so a reader should accept both.
The parser
Here is the whole part 1 reader, lightly trimmed from src/header.rs. It has no dependencies. First a cursor that reads little-endian values and never reads past the end:
pub struct Cursor<'a> { data: &'a [u8], pos: usize,}
impl<'a> Cursor<'a> { pub fn bytes(&mut self, n: usize) -> Result<&'a [u8], Error> { let end = self.pos.checked_add(n).filter(|&end| end <= self.data.len()); let Some(end) = end else { return Err(Error::Truncated { at: self.data.len(), needed: n - (self.data.len() - self.pos) }); }; let out = &self.data[self.pos..end]; self.pos = end; Ok(out) }
pub fn u16(&mut self) -> Result<u16, Error> { Ok(u16::from_le_bytes(self.bytes(2)?.try_into().unwrap())) }
pub fn u32(&mut self) -> Result<u32, Error> { Ok(u32::from_le_bytes(self.bytes(4)?.try_into().unwrap())) }}Then the header itself:
pub fn read_outer_header(data: &[u8]) -> Result<OuterHeader, Error> { let mut c = Cursor::new(data); if c.u32()? != SIGNATURE_1 { return Err(Error::NotKeePass); } match c.u32()? { SIGNATURE_2 => {} SIGNATURE_2_KDB => return Err(Error::KeePass1), _ => return Err(Error::NotKeePass), } // The minor version comes first: the file stores one little-endian u32 0x000M_mmmm. let minor = c.u16()?; let major = c.u16()?; if major != 3 && major != 4 { return Err(Error::UnsupportedVersion { major, minor }); }
let mut fields = Vec::new(); loop { let offset = c.position(); let id = c.u8()?; // The one layout change between the two versions: KDBX 4 widened the length from u16 to u32. let size = if major >= 4 { c.u32()? as usize } else { usize::from(c.u16()?) }; let value = c.bytes(size)?.to_vec(); fields.push(Field { offset, id, value }); if id == END_OF_HEADER { break; } } Ok(OuterHeader { version: Version { major, minor }, fields, len: c.position() })}Running it on both samples:
samples/sample-kdbx4.kdbx: 2009 bytes0x0000 signature 9aa2d903 b54bfb67 KeePass 2.x (KDBX)0x0008 version 4.00x000c 2 CipherID d6038a2b-8b6f-4cb5-a524-339a31dbb59a = ChaCha200x0021 3 CompressionFlags 1 = gzip0x002a 4 MasterSeed 126c6a769ada60ae747fb78df511c4eac88933805cea53a76885fcbc1755b5e1 (32 bytes)0x004f 7 EncryptionIV 7e6e2cda272711596fdd744b (12 bytes)0x0060 11 KdfParameters VariantDictionary, 6 items (Argon2id) $UUID 9e298b1956db4773b23dfc3ec6f0a1e6 (16 bytes) S 89ecd5560745da99d69e3aabf15ad008fa13fb5c92eddbec371016bdc6daa910 (32 bytes) P 2 (u32) M 67108864 (u64) I 3 (u64) V 19 (u32)0x00f0 0 EndOfHeader 0d0a0d0a (marker, always \r\n\r\n)0x00f9 end of outer header; 1760 encrypted bytes followsamples/sample-kdbx31.kdbx: 1902 bytes0x0000 signature 9aa2d903 b54bfb67 KeePass 2.x (KDBX)0x0008 version 3.10x000c 2 CipherID 31c1f2e6-bf71-4350-be58-05216afc5aff = AES-256-CBC0x001f 3 CompressionFlags 1 = gzip0x0026 4 MasterSeed 975c96d5282ea067d635ea74548c6926c7963c959818dfc98f3b617a98bbb81c (32 bytes)0x0049 5 TransformSeed b58750e17b54dcf3700bfc76e9207696bfde5b0a8e9f868a08b8682d131d0e32 (32 bytes)0x006c 6 TransformRounds 12096774 rounds0x0077 7 EncryptionIV 47aedeb864b17cbba0ea55a69c1da0cd (16 bytes)0x008a 8 ProtectedStreamKey d6097e012a4b82ef2ae787dae25eb27a902b2f03c2928aa290856182a939772b (32 bytes)0x00ad 9 StreamStartBytes 19b321ab92a3cc8f4f7029cb94c7798205c6d8b73981885e1c4fc83a908e2dac (32 bytes)0x00d0 10 InnerRandomStreamID 2 = Salsa200x00d7 0 EndOfHeader 0d0a0d0a (marker, always \r\n\r\n)0x00de end of outer header; 1680 encrypted bytes followThe same database, saved two ways: the KDBX 4 header is 249 bytes, the 3.1 header 222.
Three rules for parsing an untrusted header
The header is short and simple, but it’s also the first thing your code reads from a file someone else may have crafted. Three rules from writing ov-kdbx:
1. Never trust a length. In KDBX 4 a field’s length is a u32, so one byte flip turns a 16-byte UUID into a claimed 4 GB value. The cursor above checks every read against the bytes actually present (with checked_add, so a huge length can’t overflow on a 32-bit target) and returns Truncated instead of panicking or allocating. The repo has tests for exactly that: every prefix of a real file must fail cleanly, and so must a u32::MAX length. ov-kdbx goes further and runs the header parser under a fuzzer.
2. Keep what you don’t understand. The reader above collects every field, including ids it has never heard of. That’s deliberate. If a newer app adds header field 13 and your app rewrites the file without it, you’ve silently thrown away someone’s data. ov-kdbx keeps unknown fields in Header::unknown_fields and writes them back on save. The same rule applies inside the XML in part 5.
3. Remember who chose the parameters. A KDBX 4 header can ask you to run Argon2 with 4 TiB of memory and a billion iterations. When you open a file you made yourself, that’s your problem. When a web app or a sync server opens a file someone uploaded, it’s a denial-of-service attack in eight bytes. Part 2 covers the limits ov-kdbx enforces before it derives anything.
What the header gives away
Everything above is readable without the password, and that’s by design. A reader has to know which KDF and cipher to use before it can try a key. Hiding them wouldn’t add real security: there are only a handful of options, and an attacker would just try them all.
It does mean that anyone holding a copy of your database learns exactly how expensive each password guess will be. The sample above says “Argon2id, 64 MiB, 3 iterations”, so an attacker can work out a guessing budget before spending a cent. The header is honest about the cost, so make the cost high: a strong master password, and a KDF setting your slowest device can still bear. We’ll put numbers on that in part 2.
What the header doesn’t reveal is anything about the contents: no entry count, no names, no database title (that lives in the encrypted XML). The only size you learn is the file size.
The header isn’t protected against tampering either, at least not yet. Someone could change the KDF parameters in a stored file, and nothing in the header would notice. KDBX 4 fixes this with the 64 bytes that come straight after the end marker: a SHA-256 of the header, and an HMAC that only the right key can produce. KDBX 3.1 stores the header’s hash inside the encrypted XML instead, so tampering only shows up after decryption. That’s where part 3 picks up.
Next: from password to key
We can now read everything a KDBX file says in public. Next we turn a password (and maybe a key file) into the key that opens the rest: how composite keys work, how AES-KDF and Argon2 are run, and what limits to set before you run a KDF that a stranger configured.
References
- KeePass, KDBX file format specification, and the change notes for KDBX 4 and KDBX 4.1.
- KeePassXC,
src/format/:KeePass2.cpp,Kdbx3Reader.cppandKdbx4Reader.cpp. ov-kdbx, the full reader and writer used by OpenVireo (MIT or Apache-2.0).- The companion repo, bongani-m/kdbx-from-scratch, at tag
part-1.