Skip to content

fix(header): accept non-standard end-of-header values - #2

Open
madalinignisca wants to merge 1 commit into
shadone:developfrom
madalinignisca:fix/accept-nonstandard-end-of-header
Open

madalinignisca wants to merge 1 commit into
shadone:developfrom
madalinignisca:fix/accept-nonstandard-end-of-header

Conversation

@madalinignisca

@madalinignisca madalinignisca commented Aug 14, 2026 •

Copy link
Copy Markdown

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:

Invalid end-of-header value. Length: 0; bytes:

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.

Correction: an earlier version of this description blamed KeePassium. That was wrong — see the comment below. KeePassium writes \r\n\r\n; the empty marker comes from some other implementation I have not identified.

Cause

HeaderReader requires the outer end-of-header field (type 0) to contain exactly \r\n\r\n:

case .endOfHeader:
    if valueData != HeaderFieldType.endOfHeaderValue {
        throw Error.corrupted(reason: "Invalid end-of-header value. ...")
    }

Writers disagree about this field:

Writer end-of-header value
KeePass 2.x \r\n\r\n
KeePassXC \r\n\r\n
KeePassium \r\n\r\n
unidentified empty (length 0)

I 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/Generator lives 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 EndOfHeaderCompatTests covering:

  • the conventional \r\n\r\n marker still parses
  • an empty marker parses
  • an arbitrary marker parses
  • genuinely truncated input still throws

Full 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 to Header and 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.

`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>
@madalinignisca
madalinignisca force-pushed the fix/accept-nonstandard-end-of-header branch from ffca8ec to c6e2e5c Compare August 20, 2026 10:11
@madalinignisca

Copy link
Copy Markdown
Author

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 \r\n\r\n:

Format end-of-header Files
KDBX 4.1 \r\n\r\n main vault + backups KeePassium wrote during the re-key
KDBX 4.0 empty older vault KeePassium had only copied into its backup folder

So KeePassium writes the conventional marker; it had merely backed up a file some other implementation produced. I can't identify that writer — the Meta/Generator field is inside the encrypted payload and it isn't my vault to open.

What this doesn't change: the empty marker is real and it's in a genuine KDBX 4.0 file that develop refuses to open. The fix and the security argument stand unchanged — the header is already covered by the SHA-256 digest and the HMAC, so the marker's contents protect nothing.

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.

@madalinignisca madalinignisca changed the title fix(header): accept non-standard end-of-header values (KeePassium vaults are unreadable) fix(header): accept non-standard end-of-header values Aug 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant