kdbx_rs/lib.rs
1#![deny(missing_docs)]
2
3//! Module to read and write KDBX (Keepass 2) databases.
4//!
5//! The main types in this crate are:
6//!
7//! * [`Database`] which represents a password database
8//! * [`Kdbx`] which represents a database archive, including encryption options
9//!
10//! # Opening a database
11//!
12//! Databases can be read with the [`kdbx_rs::open`] function. This provides
13//! access to header information. It can then be unlocked by providing a [`CompositeKey`]
14//! to the [`Kdbx.unlock`] method to access any encrypted data.
15//!
16//! ```
17//! # fn main() -> Result<(), kdbx_rs::Error> {
18//! use kdbx_rs::CompositeKey;
19//!
20//! # let file_path = "./res/test_input/kdbx4-argon2d.kdbx";
21//! let kdbx = kdbx_rs::open(file_path)?;
22//! let key = CompositeKey::from_password("kdbxrs");
23//! let unlocked = kdbx.unlock(&key)?;
24//! # Ok(())
25//! # }
26//! ```
27//!
28//! Alternatively, [`kdbx_rs::from_reader`] can be used to open a database
29//! from a non file source (such as in-memory or a network stream)
30//!
31//! # Generating a new password database
32//!
33//! A database can be created in memory by using the [`Database::default()`]
34//! method. This will create an empty database which you can then populate.
35//!
36//! ```
37//! use kdbx_rs::database::{Database, Entry};
38//!
39//! let mut database = Database::default();
40//! database.set_name("My First Database");
41//! database.set_description("Created with kdbx-rs");
42//!
43//! let mut entry = Entry::default();
44//! entry.set_password("password1");
45//! entry.set_url("https://example.com");
46//! entry.set_username("User123");
47//!
48//! database.add_entry(entry);
49//! ```
50//!
51//! # Saving a database to a file
52//!
53//! To save a database to a file, you first need to create
54//! a [`Kdbx`] instance from that database, for example with
55//! [`Kdbx::from_database`]. This will generate encryption options using
56//! salts and random values from the OS's secure RNG. These can be customised,
57//! or you can save the database as is.
58//!
59//! Before saving a new database for the first time, you'll need to set the user
60//! credentials to save your database. This can be done with [`Kdbx.set_key`].
61//! Provide a [`CompositeKey`] instance, which can be created the same way as for
62//! unlocking database. This will then be used to generate the remaining keys
63//! allowing you to save the database using [`Kdbx.write()`]
64//!
65//! ```rust
66//! use kdbx_rs::{CompositeKey, Kdbx};
67//! # use kdbx_rs::Database;
68//! # use std::fs::File;
69//!
70//! # fn main() -> Result<(), kdbx_rs::Error> {
71//! # let mut database = Database::default();
72//! # let file_path = "/tmp/kdbx-rs-example.kdbx";
73//! let mut kdbx = Kdbx::from_database(database);
74//! kdbx.set_key(CompositeKey::from_password("foo123"))?;
75//!
76//! let mut file = File::create(file_path).unwrap();
77//! kdbx.write(&mut file)?;
78//! # Ok(())
79//! # }
80//! ```
81//!
82//! # Database operations
83//!
84//! See the [`database`][crate::database] module-level documentation for examples
85//! of database operations.
86//!
87//! [`CompositeKey`]: crate::CompositeKey
88//! [`Database`]: crate::Database
89//! [`Database::default()`]: crate::Database#method.default
90//! [`kdbx_rs::from_reader`]: crate::from_reader
91//! [`kdbx_rs::open`]: crate::open
92//! [`Kdbx`]: crate::Kdbx
93//! [`Kdbx.from_database`]: crate::Kdbx#method.from_database
94//! [`Kdbx.set_key`]: crate::Kdbx#method.set_key
95//! [`Kdbx.unlock`]: crate::Kdbx#method.unlock
96//! [`Kdbx.write`]: crate::Kdbx#method.write
97
98pub mod binary;
99mod crypto;
100pub mod database;
101pub mod errors;
102mod stream;
103pub mod utils;
104pub mod xml;
105
106pub use crate::database::Database;
107pub use binary::{from_reader, open, Kdbx};
108pub use crypto::CompositeKey;
109pub use errors::Error;