keepassxc-client 0.1.0

KeePassXC browser native-messaging protocol client (associate, get-logins, set-login, ...)
Documentation
// SPDX-License-Identifier: MIT OR Apache-2.0
// Copyright (c) 2026 gaffa fix <gaffa@mafix.cc>

//! crypto_box (X25519 + XSalsa20-Poly1305) session layer, matching the
//! KeePassXC-Browser protocol ("NaCl box").
//!
//! - A fresh *session* keypair is generated per connection (`SessionCrypto::new`).
//! - The *identification* keypair (`IdKeyPair`) is permanent and identifies our
//!   association across restarts (stored in the OS keyring by the app layer).
//! - Nonces are 24 bytes, random per request; KeePassXC replies with
//!   `increment_nonce(request_nonce)` (little-endian +1, libsodium semantics).

use crypto_box::{
    aead::{Aead, AeadCore, OsRng},
    PublicKey, SalsaBox, SecretKey,
};
use zeroize::Zeroize;

use crate::error::{KxcError, Result};

pub const NONCE_LEN: usize = 24;
pub const KEY_LEN: usize = 32;

pub mod b64 {
    use base64::{engine::general_purpose::STANDARD, Engine};

    pub fn enc(data: &[u8]) -> String {
        STANDARD.encode(data)
    }

    pub fn dec(data: &str) -> Result<Vec<u8>, base64::DecodeError> {
        STANDARD.decode(data)
    }
}

/// Generate a random 24-byte nonce.
pub fn generate_nonce() -> [u8; NONCE_LEN] {
    let n = SalsaBox::generate_nonce(&mut OsRng);
    let mut out = [0u8; NONCE_LEN];
    out.copy_from_slice(n.as_slice());
    out
}

/// libsodium `sodium_increment`: treat the nonce as a little-endian number and add 1.
pub fn increment_nonce(nonce: &[u8; NONCE_LEN]) -> [u8; NONCE_LEN] {
    let mut out = *nonce;
    let mut carry: u16 = 1;
    for byte in out.iter_mut() {
        let sum = *byte as u16 + carry;
        *byte = (sum & 0xff) as u8;
        carry = sum >> 8;
        if carry == 0 {
            break;
        }
    }
    out
}

/// Permanent identification keypair ("idKey" in the protocol).
/// The public half is sent in `associate` / `test-associate`; the private half
/// never leaves this process and is what proves we are the associated client.
pub struct IdKeyPair {
    secret: SecretKey,
}

impl IdKeyPair {
    pub fn generate() -> Self {
        Self {
            secret: SecretKey::generate(&mut OsRng),
        }
    }

    /// Restore from the 32 raw secret bytes (e.g. loaded from the OS keyring).
    pub fn from_secret_bytes(mut bytes: [u8; KEY_LEN]) -> Self {
        let secret = SecretKey::from(bytes);
        bytes.zeroize();
        Self { secret }
    }

    pub fn secret_bytes(&self) -> [u8; KEY_LEN] {
        self.secret.to_bytes()
    }

    pub fn public_b64(&self) -> String {
        b64::enc(self.secret.public_key().as_bytes())
    }
}

/// Per-connection encryption state.
pub struct SessionCrypto {
    secret: SecretKey,
    peer: Option<PublicKey>,
}

impl SessionCrypto {
    /// Fresh session keypair (call once per socket connection).
    pub fn new() -> Self {
        Self {
            secret: SecretKey::generate(&mut OsRng),
            peer: None,
        }
    }

    pub fn public_key_b64(&self) -> String {
        b64::enc(self.secret.public_key().as_bytes())
    }

    /// Store KeePassXC's session public key from the `change-public-keys` reply.
    pub fn set_peer_public_key_b64(&mut self, key_b64: &str) -> Result<()> {
        let raw = b64::dec(key_b64)?;
        let arr: [u8; KEY_LEN] = raw
            .try_into()
            .map_err(|_| KxcError::Crypto)?;
        self.peer = Some(PublicKey::from(arr));
        Ok(())
    }

    pub fn has_peer(&self) -> bool {
        self.peer.is_some()
    }

    fn boxed(&self) -> Result<SalsaBox> {
        let peer = self.peer.as_ref().ok_or(KxcError::NoPeerKey)?;
        Ok(SalsaBox::new(peer, &self.secret))
    }

    pub fn encrypt(&self, plaintext: &[u8], nonce: &[u8; NONCE_LEN]) -> Result<Vec<u8>> {
        self.boxed()?
            .encrypt(nonce.into(), plaintext)
            .map_err(|_| KxcError::Crypto)
    }

    pub fn decrypt(&self, ciphertext: &[u8], nonce: &[u8; NONCE_LEN]) -> Result<Vec<u8>> {
        self.boxed()?
            .decrypt(nonce.into(), ciphertext)
            .map_err(|_| KxcError::Crypto)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Simulate the KeePassXC side with its own keypair.
    struct FakeServer {
        secret: SecretKey,
    }

    impl FakeServer {
        fn new() -> Self {
            Self { secret: SecretKey::generate(&mut OsRng) }
        }
        fn public_b64(&self) -> String {
            b64::enc(self.secret.public_key().as_bytes())
        }
        fn decrypt(&self, client_pub_b64: &str, ct: &[u8], nonce: &[u8; NONCE_LEN]) -> Vec<u8> {
            let raw = b64::dec(client_pub_b64).unwrap();
            let arr: [u8; 32] = raw.try_into().unwrap();
            let bx = SalsaBox::new(&PublicKey::from(arr), &self.secret);
            bx.decrypt(nonce.as_slice().into(), ct).unwrap()
        }
        fn encrypt(&self, client_pub_b64: &str, pt: &[u8], nonce: &[u8; NONCE_LEN]) -> Vec<u8> {
            let raw = b64::dec(client_pub_b64).unwrap();
            let arr: [u8; 32] = raw.try_into().unwrap();
            let bx = SalsaBox::new(&PublicKey::from(arr), &self.secret);
            bx.encrypt(nonce.as_slice().into(), pt).unwrap()
        }
    }

    #[test]
    fn round_trip_client_to_server_and_back() {
        let mut client = SessionCrypto::new();
        let server = FakeServer::new();
        client.set_peer_public_key_b64(&server.public_b64()).unwrap();

        // client -> server
        let nonce = generate_nonce();
        let ct = client.encrypt(b"{\"action\":\"associate\"}", &nonce).unwrap();
        let pt = server.decrypt(&client.public_key_b64(), &ct, &nonce);
        assert_eq!(pt, b"{\"action\":\"associate\"}");

        // server -> client with incremented nonce (protocol behaviour)
        let reply_nonce = increment_nonce(&nonce);
        let reply_ct = server.encrypt(&client.public_key_b64(), b"{\"success\":\"true\"}", &reply_nonce);
        let reply_pt = client.decrypt(&reply_ct, &reply_nonce).unwrap();
        assert_eq!(reply_pt, b"{\"success\":\"true\"}");
    }

    #[test]
    fn tampered_ciphertext_fails() {
        let mut client = SessionCrypto::new();
        let server = FakeServer::new();
        client.set_peer_public_key_b64(&server.public_b64()).unwrap();
        let nonce = generate_nonce();
        let mut ct = client.encrypt(b"secret", &nonce).unwrap();
        ct[0] ^= 0xff;
        assert!(matches!(
            server_try_decrypt(&server, &client.public_key_b64(), &ct, &nonce),
            None
        ));
    }

    fn server_try_decrypt(
        server: &FakeServer,
        client_pub: &str,
        ct: &[u8],
        nonce: &[u8; NONCE_LEN],
    ) -> Option<Vec<u8>> {
        let raw = b64::dec(client_pub).ok()?;
        let arr: [u8; 32] = raw.try_into().ok()?;
        let bx = SalsaBox::new(&PublicKey::from(arr), &server.secret);
        bx.decrypt(nonce.as_slice().into(), ct).ok()
    }

    #[test]
    fn nonce_increment_le_with_carry() {
        let mut n = [0u8; NONCE_LEN];
        assert_eq!(increment_nonce(&n)[0], 1);

        n[0] = 0xff;
        let inc = increment_nonce(&n);
        assert_eq!(inc[0], 0x00);
        assert_eq!(inc[1], 0x01);

        // full wrap-around
        let all_ff = [0xffu8; NONCE_LEN];
        assert_eq!(increment_nonce(&all_ff), [0u8; NONCE_LEN]);
    }

    #[test]
    fn idkey_round_trips_through_bytes() {
        let id = IdKeyPair::generate();
        let restored = IdKeyPair::from_secret_bytes(id.secret_bytes());
        assert_eq!(id.public_b64(), restored.public_b64());
    }
}