keepassxc-client 0.1.0

KeePassXC browser native-messaging protocol client (associate, get-logins, set-login, ...)
Documentation

keepassxc-client

A Rust client for the KeePassXC browser native-messaging protocol — the same protocol the official KeePassXC-Browser extension speaks. It performs the crypto_box key exchange, association, and the credential operations over the local socket (Unix domain socket on Linux/macOS; named pipe on Windows is a stub).

[dependencies]
keepassxc-client = "0.1"

What it does

  • Key exchange (change-public-keys) and encrypted transport (crypto_box, per-connection session keys, nonce+1 verification).
  • Association — request approval once (associate), then persist the idKey keypair + association id and re-verify silently (test-associate).
  • Credentials — get-logins, set-login.
  • Lock/unlock signals — database-locked / database-unlocked.

Example

use keepassxc_client::{KxcClient, IdKeyPair, transport::unix::UnixTransport};

# async fn demo() -> Result<(), keepassxc_client::KxcError> {
let t = UnixTransport::connect_auto().await?;
let mut kxc = KxcClient::new(t);
kxc.change_public_keys().await?;

let id_key = IdKeyPair::generate();          // persist secret_bytes() in a keyring!
let assoc = kxc.associate(&id_key).await?;   // user approves the popup once
let entries = kxc.get_logins("https://vault.example.com").await?;
# Ok(()) }

Enable Browser Integration in KeePassXC (Settings → Browser Integration) before connecting.

Security notes

  • The association idKey secret is the long-term identity for silent re-association — store it in an OS keyring, not on disk in the clear.
  • All socket traffic after the key exchange is encrypted; the transport verifies the nonce+1 on responses.

Status

0.1 — extracted from the Vaultferry project, where it is live-validated against real KeePassXC. Linux socket transport works; the Windows named-pipe transport is a stub.

License

Copyright (c) 2026 gaffa fix <gaffa@mafix.cc>

Licensed under either of MIT or Apache-2.0 at your option.