Repository navigation
fix(header): accept non-standard end-of-header values - #2
madalinignisca wants to merge 1 commit into
Conversation
`HeaderReader` required the outer header's end-of-header field (type 0)
to contain exactly `\r\n\r\n`, and threw `corrupted` otherwise.
Implementations disagree about this field. KeePass 2.x, KeePassXC and
KeePassium all write `\r\n\r\n`, but KDBX 4.0 files carrying an empty
value turn up in the wild, and they are valid in every other respect.
Reproduced against such a file (KDBX 4.0, ChaCha20, Argon2id), which
fails on develop with:
Invalid end-of-header value. Length: 0; bytes:
The check also buys no security. The header bytes are already covered by
the header SHA-256 digest and by the HMAC, so tampering is detected
regardless of this field's contents — it is a legacy sanity marker, not
integrity data. Enforcing it only rejects otherwise-conforming files.
Non-standard values are now accepted and logged at debug level. Nothing
else about header validation changes; a truncated header still throws.
Adds EndOfHeaderCompatTests covering the conventional marker, an empty
marker, an arbitrary value, and that real corruption is still rejected.
Full suite: 477 tests, 74 suites, all passing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ffca8ec to
c6e2e5c
Compare
|
Correction — I misattributed the empty end-of-header marker to KeePassium, and that was wrong. I've amended the commit and updated the description. Since the original text is still in the thread, here's what changed and why. My reproducer was a KDBX 4.0 file found in KeePassium's backup directory, and I inferred from its location that KeePassium had written it. That inference was wrong. Today the same user re-keyed their main vault through KeePassium (KDBX 4.1, ChaCha20, Argon2id). I checked the bytes it produced, and every file KeePassium demonstrably serialised writes
So KeePassium writes the conventional marker; it had merely backed up a file some other implementation produced. I can't identify that writer — the What this doesn't change: the empty marker is real and it's in a genuine KDBX 4.0 file that What it does change: the severity. I framed this as "every KeePassium-written vault is unreadable," which would have made it urgent. It isn't. It affects files from some less common writer, so treat it as ordinary robustness rather than something to rush. Apologies for the noise. I should have verified the writer rather than inferring it from the directory the file was sitting in. |
Following on from #1 — this one is a compatibility bug rather than a performance one, and it has a fairly wide blast radius.
Symptom
KDBXKit cannot open certain real-world KDBX 4.0 vaults:
Reproduced against a real KDBX 4.0 vault (ChaCha20, Argon2id). Every other part of the file parses correctly; it fails on the very last header field.
Cause
HeaderReaderrequires the outer end-of-header field (type 0) to contain exactly\r\n\r\n:Writers disagree about this field:
\r\n\r\n\r\n\r\n\r\n\r\nI checked a spread of vaults on my machine; the empty marker appears only in KDBX 4.0 files whose writer I cannot determine, since
Meta/Generatorlives inside the encrypted payload.Why loosening it is safe
The check isn't protecting anything. The header bytes are already covered by the header SHA-256 digest and by the HMAC, so any tampering — including with this field — is caught by machinery that runs regardless. The marker is a legacy sanity value, not integrity data.
So enforcing its contents can only reject conforming writers, which is what's happening here.
The change
Accept any value, log a debug line when it isn't the conventional one. Nothing else about header validation moves — a truncated header still throws, and there's a test asserting that specifically so this doesn't quietly become a blanket loosening.
Added
EndOfHeaderCompatTestscovering:\r\n\r\nmarker still parsesFull suite: 477 tests across 74 suites, all passing.
One thing worth your judgement
The writer still emits
\r\n\r\n, so a read-modify-write of such a vault will normalise the marker. That seemed right to me — writing the conventional value is the safer default — but if you'd rather round-trip the original bytes exactly, that's a small change toHeaderand I'm happy to do it.How this was written
Same as #1: me working with Claude Code, with everything verified by execution. The failing vault is real, the writer comparison came from inspecting actual files rather than from documentation, and the security argument is why I was comfortable loosening a check rather than special-casing a length of 0.