kdbx_rs/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
#![deny(missing_docs)]

//! Module to read and write KDBX (Keepass 2) databases.
//!
//! The main types in this crate are:
//!
//! * [`Database`] which represents a password database
//! * [`Kdbx`] which represents a database archive, including encryption options
//!
//! # Opening a database
//!
//! Databases can be read with the [`kdbx_rs::open`] function. This provides
//! access to header information. It can then be unlocked by providing a [`CompositeKey`]
//! to the [`Kdbx.unlock`] method to access any encrypted data.
//!
//! ```
//! # fn main() -> Result<(), kdbx_rs::Error> {
//! use kdbx_rs::CompositeKey;
//!
//! # let file_path = "./res/test_input/kdbx4-argon2d.kdbx";
//! let kdbx = kdbx_rs::open(file_path)?;
//! let key = CompositeKey::from_password("kdbxrs");
//! let unlocked = kdbx.unlock(&key)?;
//! # Ok(())
//! # }
//! ```
//!
//! Alternatively, [`kdbx_rs::from_reader`] can be used to open a database
//! from a non file source (such as in-memory or a network stream)
//!
//! # Generating a new password database
//!
//! A database can be created in memory by using the [`Database::default()`]
//! method. This will create an empty database which you can then populate.
//!
//! ```
//! use kdbx_rs::database::{Database, Entry};
//!
//! let mut database = Database::default();
//! database.set_name("My First Database");
//! database.set_description("Created with kdbx-rs");
//!
//! let mut entry = Entry::default();
//! entry.set_password("password1");
//! entry.set_url("https://example.com");
//! entry.set_username("User123");
//!
//! database.add_entry(entry);
//! ```
//!
//! # Saving a database to a file
//!
//! To save a database to a file, you first need to create
//! a [`Kdbx`] instance from that database, for example with
//! [`Kdbx::from_database`]. This will generate encryption options using
//! salts and random values from the OS's secure RNG. These can be customised,
//! or you can save the database as is.
//!
//! Before saving a new database for the first time, you'll need to set the user
//! credentials to save your database. This can be done with [`Kdbx.set_key`].
//! Provide a [`CompositeKey`] instance, which can be created the same way as for
//! unlocking database. This will then be used to generate the remaining keys
//! allowing you to save the database using [`Kdbx.write()`]
//!
//! ```rust
//! use kdbx_rs::{CompositeKey, Kdbx};
//! # use kdbx_rs::Database;
//! # use std::fs::File;
//!
//! # fn main() -> Result<(), kdbx_rs::Error> {
//! # let mut database = Database::default();
//! # let file_path = "/tmp/kdbx-rs-example.kdbx";
//! let mut kdbx = Kdbx::from_database(database);
//! kdbx.set_key(CompositeKey::from_password("foo123"))?;
//!
//! let mut file = File::create(file_path).unwrap();
//! kdbx.write(&mut file)?;
//! # Ok(())
//! # }
//! ```
//!
//! # Database operations
//!
//! See the [`database`][crate::database] module-level documentation for examples
//! of database operations.
//!
//! [`CompositeKey`]: crate::CompositeKey
//! [`Database`]: crate::Database
//! [`Database::default()`]: crate::Database#method.default
//! [`kdbx_rs::from_reader`]: crate::from_reader
//! [`kdbx_rs::open`]: crate::open
//! [`Kdbx`]: crate::Kdbx
//! [`Kdbx.from_database`]: crate::Kdbx#method.from_database
//! [`Kdbx.set_key`]: crate::Kdbx#method.set_key
//! [`Kdbx.unlock`]: crate::Kdbx#method.unlock
//! [`Kdbx.write`]: crate::Kdbx#method.write

pub mod binary;
mod crypto;
pub mod database;
pub mod errors;
mod stream;
pub mod utils;
pub mod xml;

pub use crate::database::Database;
pub use binary::{from_reader, open, Kdbx};
pub use crypto::CompositeKey;
pub use errors::Error;