kdbx4

A pure-Dart reader/writer for the KDBX4 (KeePass) database format.

  • Built only on pointycastle for cryptographic primitives (AES, Argon2id/d, ChaCha20, Salsa20, SHA, HMAC) and xml. This library implements the KDBX4 container format on top of those vetted primitives — it does not roll its own crypto.
  • No Flutter dependency. Works in Flutter apps, Dart servers, and CLIs.
  • Writes KDBX 4.0; reads KDBX 4.0 / 4.1. KDBX 3.x is intentionally unsupported.
  • Default KDF: Argon2id (64 MiB, t=3, p=1). AES-KDF supported for reading foreign files.
  • Round-trip interoperable with KeePassXC.

Scope

kdbx4 deliberately does one thing — the KDBX4 format — and keeps a small, focused surface. All cryptographic primitives are delegated to the established PointyCastle library; this package implements only the container format on top. The engine is extracted from a shipping app, is KAT-pinned, and is KeePassXC-interop-tested. If you need KDBX 3.x support or a broader KeePass API, other Dart packages cover that — this one optimizes for a minimal, auditable KDBX4 reader/writer.

Install

dependencies:
  kdbx4: ^0.1.0

Usage

import 'package:kdbx4/kdbx4.dart';

void main() {
  final entry = KdbxEntry(uuid: secureRandomBytes(16), strings: {
    'Title': const KdbxStringValue('GitHub'),
    'UserName': const KdbxStringValue('octocat'),
    'Password': const KdbxStringValue('s3cr3t', protected: true),
  });
  final content = KdbxContent(
    meta: KdbxMeta(databaseName: 'My vault'),
    root: KdbxGroup(uuid: secureRandomBytes(16), name: 'Root', entries: [entry]),
  );

  final db = KdbxDatabase.create(
    content: content,
    kdf: Argon2Kdf.sesameDefault(secureRandomBytes(32)),
    credentials: Credentials.password('correct horse battery staple'),
  );

  final bytes = KdbxFile.serialize(db);          // -> Uint8List; write to a .kdbx file

  final reopened = KdbxFile.open(                // throws WrongCredentialsException on a bad passcode
    bytes: bytes,
    credentials: Credentials.password('correct horse battery staple'),
  );
  print(reopened.content.meta.databaseName);
}

See example/kdbx4_example.dart.

Design

The library is bytes ⇄ model: you provide/receive file bytes, and it parses or serializes the KDBX container. It performs no file I/O itself, so it stays portable. Authentication is checked before decryption (encrypt-then-MAC: the header SHA-256 and HMAC, then the HMAC block stream), so corruption and wrong passcodes are distinguished and there is no padding oracle.

Security

See SECURITY.md for the crypto design, guarantees, known limitations, and how to report a vulnerability.

Status

0.1.0 — pre-1.0; the public API may still change. The KDBX engine is KAT-pinned and interop-tested. See CHANGELOG.md.

License

MIT — see LICENSE.

Libraries

kdbx4
kdbx4 — a pure-Dart reader/writer for the KDBX4 (KeePass) database format.