Crate keepass_ng

keepass-ng

Rust KeePass database file parser for KDB, KDBX3 and KDBX4, with experimental support for KDBX4 writing.

Usage

Open a database

use keepass_ng::{
    db::{node_is_group, with_node, Database, Entry, Group, Node, NodeIterator},
    DatabaseKey, DatabaseOpenError,
};
use std::fs::File;

fn main() -> Result<(), DatabaseOpenError> {
    // Open KeePass database using a password (keyfile is also supported)
    let mut file = File::open("tests/resources/test_db_with_password.kdbx")?;
    let key = DatabaseKey::new().with_password("demopass");
    let db = Database::open(&mut file, key)?;

    // Iterate over all `Group`s and `Entry`s
    for node in NodeIterator::new(&db.root).into_iter() {
        with_node::<Group, _, _>(&node, |group| {
            println!(
                "Saw group '{0}'",
                group.get_title().unwrap_or("(no title)")
            );
        });
        with_node::<Entry, _, _>(&node, |e| {
            let title = e.get_title().unwrap_or("(no title)");
            let user = e.get_username().unwrap_or("(no username)");
            let pass = e.get_password().unwrap_or("(no password)");
            println!("Entry '{0}': '{1}' : '{2}'", title, user, pass);
        });
    }

    Ok(())
}

Save a KDBX4 database (EXPERIMENTAL)

IMPORTANT: The inner XML data structure will be re-written from scratch from the internal object representation of this crate, so any field that is not parsed by the library will be lost in the written output file! Please make sure to back up your database before trying this feature.

You can enable the experimental support for saving KDBX4 databases using the save_kdbx4 feature.

use keepass_ng::{
    db::{with_node_mut, rc_refcell_node, NodePtr, Database, Entry, Group, Node, Value},
    DatabaseConfig, DatabaseKey, 
};
use std::fs::File;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut db = Database::new(DatabaseConfig::default());

    db.meta.database_name = Some("Demo database".to_string());

    let mut entry = Entry::default();
    entry.set_title(Some("Demo entry"));
    entry.set_username(Some("jdoe"));
    entry.set_password(Some("hunter2"));

    let mut group = Group::new("Demo group");
    group.add_child(rc_refcell_node(entry), 0);

    with_node_mut::<Group, _, _>(&db.root, |root| {
        root.add_child(rc_refcell_node(group), 0);
    });

    #[cfg(feature = "save_kdbx4")]
    db.save(&mut File::create("demo.kdbx")?, DatabaseKey::new().with_password("demopass"))?;

    Ok(())
}

Use developer tools

This crate contains several command line tools that can be enabled with the utilities feature flag. See the [[bin]] sections in Cargo.toml for a complete list.

An example command line for running the kp-dump-xml command would be:

cargo run --release --features "utilities" --bin kp-dump-xml -- path/to/database.kdbx

Installation

Add the following to the dependencies section of your Cargo.toml:

[dependencies]
keepass-ng = "*" # TODO replace with current version

Performance Notes

Please set the RUSTFLAGS environment variable when compiling to enable CPU-specific optimizations (this greatly affects the speed of the AES key derivation):

export RUSTFLAGS='-C target-cpu=native'

For best results, also compile in Release mode.

Alternatively, you can add a .cargo/config.toml like in this project to ensure that rustflags are always set.

For AArch64 / ARMv8:

The aes optimizations are not yet enabled on stable rust. If you want a big performance boost you can build using nightly and enabling the armv8 feature of the aes crate:

[dependencies.aes]
# Needs at least 0.7.5 for the feature
version = "0.7.5"
features = ["armv8"]

License

MIT

Modules

db

Types for representing data contained in a KeePass database

Structs

DatabaseConfig

Configuration of how a database should be stored

DatabaseKey

A KeePass key, which might consist of a password and/or a keyfile

NaiveDateTime

ISO 8601 combined date and time without timezone.

Uuid

A Universally Unique Identifier (UUID).

Enums

ChallengeResponseKey

DatabaseIntegrityError

Errors stemming from corrupted databases

DatabaseKeyError

Errors related to the database key

DatabaseOpenError

Errors upon reading a Database

Error

Type Aliases

BoxError

Result