Skip to content

perf(AESKDF): reuse the AES key schedule across rounds (~5x on AES-KDF vaults) - #1

Open
madalinignisca wants to merge 1 commit into
shadone:developfrom
madalinignisca:perf/aes-kdf-key-schedule-reuse
Open

madalinignisca wants to merge 1 commit into
shadone:developfrom
madalinignisca:perf/aes-kdf-key-schedule-reuse

Conversation

@madalinignisca

Copy link
Copy Markdown

Hi! First off — thanks for building this. I went looking for a KDBX library with
serious secret hygiene (mlock, scoped reveal, zero-on-deinit) and this is the
only Swift one I found that takes it seriously. I'm using it as the foundation
for a small macOS CLI that unlocks a vault via Touch ID.

While benchmarking my unlock path I found the AES-KDF inner loop was costing far
more than it should, and traced it to something fixable.

The problem

AESKDF.derive calls AES.permute(_:key:) once per 16-byte half, per round:

for _ in 0..<rounds {
    try! AES.permute(&left, key: key)
    try! AES.permute(&right, key: key)
}

AES.permute takes a SymmetricKey per call, and in swift-crypto that lands in
permuteBlock → CCryptoBoringSSL_AES_set_encrypt_key on every invocation
(Block Function.swift#L92-L105).

So the key schedule is rebuilt once per block per round. My vault is a KDBX 4.1
file using AES-KDF with 47,619,048 rounds — that's ~95.2M key expansions, and the
expansion ends up costing several times the AES work it exists to support.

Vaults using Argon2 are unaffected; this only bites AES-KDF, which is admittedly
the legacy choice, but KeePassXC and KeePassium both still produce it and it's
what my daily-driver vault happens to use.

The change

Create one CCCryptorRef up front and reuse it for every round.

ECB encrypts each 16-byte block independently, so a single 32-byte update covers
both halves in one call and is exactly equivalent to permuting them separately —
that also halves the per-round call overhead.

Kept deliberately conservative:

  • The existing AES.permute loop stays verbatim as the fallback, so
    non-CommonCrypto platforms are byte-for-byte unchanged.
  • The fast path returns Bool. If CCCryptorCreate or any CCCryptorUpdate
    declines, we fall back rather than continue — a failure degrades to slow,
    never to a wrong key.
  • The ping-pong scratch buffer holds key material and is zeroed on exit, matching
    the surrounding conventions.
  • No algorithm, format, or public API change.

Measurements

M3 MacBook Air, release build, unlocking the 47.6M-round vault:

before after
KDF cost 4.72s 1.07s

Inner loop in isolation, 1,000,000 rounds, both halves:

time
AES.permute per block per round 0.116s
reused cryptor 0.021s

5.4x on the loop, 4.4x end-to-end, byte-identical output (verified by
comparing the 32-byte result of both paths directly, not just by tests passing).

1.07s is close to the hardware AES throughput floor for this round count, so
what remains is inherent to the parameters rather than to the code.

Testing

  • Full suite: 473 tests across 73 suites, all passing.
  • Both code paths produce identical output for the same inputs.
  • Exercised against real KeePassXC- and KeePassium-written KDBX 4.0/4.1 vaults
    (AES-256 and ChaCha20).

A note on how this was written

This patch was written by me working with Claude Code — I see from your
CLAUDE.md that you use a similar workflow, so I hope that's welcome rather than
a red flag. Everything above was verified by execution rather than asserted: the
root cause was traced by reading swift-crypto's source, the numbers are from
actual runs on real vaults, and the equivalence claim is from comparing outputs
of both paths. Happy to share the benchmark harness if useful.

Also glad to rework any of this — split the CommonCrypto path into its own file,
drop the fallback restructuring, adjust naming to taste, whatever fits how you'd
like the KDF layer to look. And if a portable (non-Apple) fast path matters to
you, I'm happy to look at that as a follow-up.

AES-KDF calls `AES.permute(_:key:)` once per 16-byte half per round.
That API takes a `SymmetricKey` on every call and internally calls
`AES_set_encrypt_key` each time, so the key schedule is recomputed once
per block per round rather than once per derivation.

For a real-world KDBX 4.1 vault using AES-KDF with 47,619,048 rounds,
that is ~95.2M key expansions, and the expansion dominates the AES work
it exists to support.

This adds a CommonCrypto fast path that creates one `CCCryptorRef` up
front and reuses it for every round. ECB encrypts each 16-byte block
independently, so a single 32-byte update covers both halves at once and
is exactly equivalent to permuting them separately. The existing
`AES.permute` loop is kept verbatim as the fallback for platforms
without CommonCrypto, and is also used if CommonCrypto declines at any
point, so a failure degrades to slow rather than to a wrong key.

Measured on an M3 MacBook Air, release build, unlocking the vault above:

    before   4.72s
    after    1.07s     4.4x

Inner-loop microbenchmark over 1,000,000 rounds:

    AES.permute      0.116s
    reused cryptor   0.021s    5.4x    (byte-identical output)

1.07s is close to the hardware AES floor for this round count, so the
remaining cost is inherent to the parameters rather than the code.

No algorithm or format change. Full suite passes: 473 tests, 73 suites.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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