Architecture

This is the architecture documentation for libkeepass, a C++17 library for importing and exporting KeePass password databases.

It complements the generated API reference (Doxygen) by explaining how the pieces fit together.

Documents

• Key Derivation Process — how passwords / key files are turned into cryptographic keys (AES-KDF, Argon2, composite keys).
• Encryption Flow — how the database payload is encrypted, framed and integrity-protected (AES/Twofish/ChaCha20, hashed/HMAC blocks).
• KDBX Parsing Pipeline — the byte-level file format, header parsing, XML parsing and export.
• Streaming Parsing Evaluation — where the pipeline streams (HMAC/decrypt) and where it buffers (pugixml DOM), plus the load benchmark.
• Third-party Interoperability — verified KeePassXC/Strongbox interop and known provider divergences.
• Hardware Tokens / YubiKey — a documented decision to keep hardware-token support out of scope and leave the Key extension point open.
• Format and feature support matrix — which formats, ciphers, KDFs and object-model features are read and written.
• Worked examples — stream round-trips, attachments, tags, recycle bin, history and resource limits.
• `kpx` output schemas — stable text/JSON/CSV shapes, error categories and exit codes.
• Migration 0.2 → 0.3 — the secure_string migration, C++17 baseline and other breaking changes.
• Object ownership and aliasing — who owns the database tree, parent/child weak references, moving, deleting and trashing.
• ABI and API stability policy — versioning, shared-library ABI expectations, deprecation and the route to a stable 1.0 surface.
• Extension points — registering format codecs, block ciphers and KDFs.
• C ABI — the stable C surface for language bindings (header), plus the OSS-Fuzz recipe and WASM demo.

High-level flow

A KDBX database is a layered file: a header with format parameters, followed by an authenticated, encrypted payload whose plaintext is (optionally compressed) XML.

                   Import                        Export
           +--------------------+         +--------------------+
password   |                    |         |                    |
+ keyfile  v                    |         |                    v
  Key  --derive->  transformed_key   -->   transformed_key   (AES-KDF / Argon2)
                      |                        ^
                      +--> final_key = SHA-256(master_seed || transformed_key)
                           |                           |   HMAC key (KDBX4)
file bytes ------> header parse ------> decrypt ------> XML (pugixml)
                          .                              |   Database
                    encrypted payload ---------> encrypt |

Module reference

Source layout:

src/
├── include/libkeepass/   public headers (Doxygen-documented API)
├── aes_ni.cc             AES-NI accelerated AES-KDF core loop
├── cipher_*.cc           block/stream ciphers (AES, Twofish, Salsa20, ChaCha20)
├── entry.cc              Entry, Attachment, AutoType, history
├── group.cc              Group tree and ToJson() serialization
├── binary.cc             materialized/lazy Binary payload access
├── binary_source.cc      shared-buffer source for lazy attachments
├── cipher_registry.cc    registrable block-cipher factories
├── exception.cc          error categories and exception implementation
├── format_codec.cc       registrable DatabaseSerializer/format codecs
├── io.cc                 endian-aware read/write helpers (consume/conserve)
├── kdf_registry.cc       registrable KDF factories
├── mapped_file.cc        read-only mmap/CreateFileMapping input for Open(path)
├── kdb_fields.cc         KDB 1.x header/field codec
├── kdb_import.cc         legacy KDB 1.x importer
├── kdb_export.cc         legacy KDB 1.x exporter
├── kdbx_import.cc        KDBX 3/4 importer
├── kdbx_export.cc        KDBX 3/4 exporter
├── kdbx_xml_*.cc         KDBX XML meta/group/entry serializers
├── key.cc                user key handling and key derivation (AES-KDF, Argon2)
├── metadata.cc           Metadata (database meta, binaries, icons, custom data)
├── random.cc             inner random stream obfuscator (Salsa20 / ChaCha20)
├── stream.cc             streambufs: hashed blocks, HMAC blocks, gzip
├── totp.cc               KeePass TOTP field parsing and code generation
├── util.cc               time formatting, UUID generation
└── variantdictionary.cc  KDBX 4 KDF parameter dictionary

The optional C ABI wrapper (libkeepass-c) is in capi/; the browser demo and fuzzing recipes are in wasm/ and oss-fuzz/.

Key entry points:

Entry point	Purpose
keepass::KdbxFile::Import / Export	KDBX file → Database and back
keepass::KdbFile::Import / Export	legacy KDB format
keepass::Key	password / keyfile / KDF handling

The graphical kpx CLI in cli/ is a full consumer of the library and a good starting point for examples.

Layering

            +------------------+
            | Database / Group |
            |  / Entry / Meta  |   public object model
            +------------------+
                    |
      +---------------------------------+
      | kdbx_import.cc / kdbx_export.cc |
      | kdb.cc                          |   format import/export
      +---------------------------------+
                       |
+-------------------+-------------------+
| cipher.cc | stream.cc | key.cc /        |
|           | gzip      | random.cc       |   crypto & I/O
+-------------------+--------------------+
                    |
OpenSSL | zlib | pugixml | Argon2 | AES-NI

Dependencies (provided via Conan): OpenSSL (ciphers, hashes, HMAC), zlib (gzip), pugixml (XML), Argon2, Google Test (unit tests only).