Read and write KeePass 2 (KDBX 4) databases from Swift.
Page-locked secrets, KeePassXC-tested round-trips, and streaming
attachments that keep peak memory bounded regardless of vault size.

KDBXKit is a Swift library for reading and writing KeePass 2 / KDBX 4 password-manager databases — the format used by KeePass, KeePassXC, Strongbox, and similar clients. It handles the full file format (cryptographic envelope, KDF, inner XML, attachments) and exposes a typed Swift API with secure-memory primitives so consumers don't have to roll their own.

import KDBXKit

// Open
let data = try Data(contentsOf: url)
let unlock = UnlockData(masterPassword: "hunter2")
let content = try KDBXReader.parse(data, unlockData: unlock)

// Walk
content.database.visitEntries(in: content.database.root.group) { entry in
    print(entry.uuid, entry.strings.map(\.key))
}

// Save
let bytes = try KDBXWriter().write(content, unlockData: unlock)
try bytes.write(to: url)

• Swift: 6.1+
• macOS: 15+
• iOS: 18+
• Linux: Swift 6.1 toolchain + zlib

Add KDBXKit to your Package.swift:

dependencies: [
    .package(url: "https://github.com/shadone/KDBXKit.git", from: "1.0.0"),
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "KDBXKit", package: "KDBXKit"),
        ]
    ),
]

On Linux you also need zlib development headers:

sudo apt-get install zlib1g-dev    # Debian/Ubuntu
sudo dnf install zlib-devel        # Fedora

The basic open / walk / save flow is in the intro snippet above. A runnable end-to-end example lives in Examples/HelloKDBX/ — open it with swift run HelloKDBX for a working .kdbx reader in ~70 lines. The sections below cover the less obvious bits.

let header = try KDBXReader.parseHeader(data)
print(header.formatVersion)        // .v4_1
print(header.kdfParameters)        // .argon2id(...)
print(header.encryptionAlgorithm)  // .AES256CBC / .ChaCha20

// Password + key file
let unlock = UnlockData(masterPassword: "p", keyFile: keyFileBytes)

// Key file alone
let unlock = UnlockData(keyFile: keyFileBytes)

// Rehydrate from a Keychain-stored 32-byte pre-hash (biometric unlock)
let unlock = UnlockData(rawKeyData: keychainBytes)

The 32-byte pre-hash is the same authority as the password — protect it with appropriate access control on the storage side.

For vaults whose attachments shouldn't sit resident from unlock to lock, open metadata-only and stream binaries on demand. openMetadataOnly runs the full decrypt + inner-header parse but drops the binary bytes; the returned LazyKDBXContent keeps a handle to the source so individual binaries can be re-streamed without holding all of them in memory.

let lazy = try KDBXReader.openMetadataOnly(from: .file(url), unlockData: unlock)

// Stream a specific binary into the destination of your choice.
var sink = try URLSink(writingTo: destination)  // or DataSink() / SecureBytesSink()
try KDBXReader.streamBinary(from: lazy, at: index, into: &sink)

To save without ever materializing all binaries in process memory, drive the streaming writer with LazyBinarySource (re-streamed from the source vault) and/or DataBinarySource (newly-added attachments still on the heap):

let content = KDBXContent(database: lazy.database, header: lazy.header, innerHeader: lazy.innerHeader)
let binaries: [any BinarySource] = lazy.binaries.indices.map { LazyBinarySource(lazy, at: $0) }
try KDBXWriter.streamingWrite(to: destinationURL, content: content, binaries: binaries, unlockData: unlock)

Peak save memory is one attachment plus the pipeline buffers (~64 KB gzip + ≤16 B AES + 1 MB HMAC block) — independent of total attachment bytes.

Any cleartext key material crossing the library boundary is in SecureBytes (page-locked via mlock, zeroed via memset_s / explicit_bzero on deinit). Protected entry fields use a scoped-reveal pattern instead of returning raw strings:

// Find the entry's Password field — strings is [ProtectedString].
if let password = entry.strings.first(where: { $0.key == "Password" })?.value {
    password.withRevealedString { plaintext in
        // plaintext is a String that's about to leave scope; copy into the
        // platform secret store and return.
        Keychain.set(plaintext, for: entry.uuid)
    }
}

KDBXReader.Error and KDBXWriter.Error are typed enums with exhaustive cases — caller-facing doc comments on each case explain when it fires:

do {
    _ = try KDBXReader.parse(data, unlockData: unlock)
} catch KDBXReader.Error.wrongCredentials {
    // bad password / key file
} catch KDBXReader.Error.unsupportedFormatVersion(let major, let minor) {
    // file is KDBX \(major).\(minor) — outside our supported range
} catch KDBXReader.Error.corruptedHMAC(let reason) {
    // file failed integrity check
}

External (all versioned, Apple-blessed, cross-platform):

• swift-crypto — SHA/HMAC, AES.
• swift-log — logging facade.
• swift-argument-parser — used by the companion CLI.

Vendored (in-tree, no network fetch):

• P-H-C reference Argon2 in Sources/CArgon2/ (pin: upstream commit f57e61e). CC0 / Apache 2.0 dual-licensed. See Sources/CArgon2/UPSTREAM.md.

System:

• zlib (linked via -lz, exposed to Swift via the Sources/CZlib/ module). Ships with macOS; install zlib1g-dev or equivalent on Linux.

The repo also ships a kdbx executable — a small debugging and scripting tool, also useful as a worked example of using the library.

swift run kdbx db info     <file.kdbx>                       # header-only, no creds needed
swift run kdbx entry ls    <file.kdbx> --password-stdin
swift run kdbx entry show  <file.kdbx> /Banking/Chase --password-stdin
swift run kdbx attach extract <file.kdbx> /Banking/Chase logo.png --password-stdin

Credentials never come from argv. Resolution order: --password-stdin → KDBX_PASSWORD env → --key-file <path> → no-echo TTY prompt. See Sources/KDBXCLICore/ for the full subcommand tree and how the credential plumbing is structured.

swift build
swift test
swift test --filter HeaderTests

mint runs the Swift CLI tools listed in Mintfile.

brew install mint
mint bootstrap
mint run swiftformat --lint .   # check
mint run swiftformat .          # apply

You don't need a Linux machine — scripts/test-linux.sh runs the build and tests inside the same container CI uses. Requires Docker (Docker Desktop, Colima, or OrbStack).

./scripts/test-linux.sh                         # full build + test, Linux/arm64
./scripts/test-linux.sh --filter Header         # forwards args to `swift test`
SWIFT=6.2 ./scripts/test-linux.sh               # different toolchain
PLATFORM=linux/amd64 ./scripts/test-linux.sh    # x86_64 under qemu (slow)

Linux build artifacts land in .build-linux/ (gitignored) so they don't collide with your macOS .build/; you can interleave runs freely.

Closer-to-CI alternative with act:

brew install act
act -j linux            # run the workflow's Linux job locally

• Dominik Reichl and the KeePass project for the KDBX 4 format specification and the canonical XML schema (Sources/KDBXKit/Database/KDBX_XML.xsd).
• Alex Biryukov, Daniel Dinu, Dmitry Khovratovich for the Argon2 algorithm (winner of the Password Hashing Competition), and Dinu / Khovratovich / Aumasson / Neves for the reference C implementation we vendor in Sources/CArgon2/.
• The KeePassXC project — both for being a high-quality client we test interop against, and for the keepassxc-cli tool that makes round-trip testing tractable.
• Apple's Swift Crypto team for swift-crypto, which carries all of our SHA / HMAC / AES work cross-platform.

BSD 2-Clause. See LICENSE.