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-argon2.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;