kpdb/
lib.rs

1// Copyright (c) 2016-2017 Martijn Rijkeboer <mrr@sru-systems.com>
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9//! Library for reading and writing KeePass 2 and KeePassX databases.
10//!
11//! # Usage
12//!
13//! To use this crate, add the following to your Cargo.toml:
14//!
15//! ```toml
16//! [dependencies]
17//! rust-kpdb = "0.5"
18//! ```
19//!
20//! And the following to your crate root:
21//!
22//! ```rust
23//! extern crate kpdb;
24//! ```
25//!
26//! # Examples
27//!
28//! Create a new database adding two groups and two entries:
29//!
30//! ```rust
31//! use kpdb::{CompositeKey, Database, Entry, Group};
32//!
33//! // Create a new database.
34//! let key = CompositeKey::from_password("password");
35//! let mut db = Database::new(&key);
36//!
37//! // Create a new group named Email.
38//! let mut email_group = Group::new("Email");
39//! let email_group_uuid = email_group.uuid;
40//!
41//! // Create an entry for ProtonMail and add it to the Email group.
42//! let mut protonmail = Entry::new();
43//! let protonmail_uuid = protonmail.uuid;
44//! protonmail.set_title("ProtonMail");
45//! protonmail.set_username("mailuser");
46//! protonmail.set_password("mailpass");
47//! protonmail.set_url("https://mail.protonmail.com");
48//! email_group.add_entry(protonmail);
49//!
50//! // Create a new group named VPN.
51//! let mut vpn_group = Group::new("VPN");
52//!
53//! // Create an entry for ProtonVPN and add it to the VPN group.
54//! let mut protonvpn = Entry::new();
55//! protonvpn.set_title("ProtonVPN");
56//! protonvpn.set_username("vpnuser");
57//! protonvpn.set_password("vpnpass");
58//! protonvpn.set_url("https://prontvpn.com");
59//! vpn_group.add_entry(protonvpn);
60//!
61//! // Add the Email and VPN groups to the Root group.
62//! db.root_group.add_group(email_group);
63//! db.root_group.add_group(vpn_group);
64//!
65//! // Find groups matching "email".
66//! let groups = db.find_groups("email");
67//! assert_eq!(groups.len(), 1);
68//!
69//! // Find entries matching "proton".
70//! let entries = db.find_entries("proton");
71//! assert_eq!(entries.len(), 2);
72//!
73//! // Retrieve a group by its UUID.
74//! let group = db.get_group(email_group_uuid).unwrap();
75//! assert_eq!(group.name, "Email");
76//!
77//! // Retrieve an entry by its UUID.
78//! let entry = db.get_entry(protonmail_uuid).unwrap();
79//! assert_eq!(entry.title(), Some("ProtonMail"));
80//! assert_eq!(entry.username(), Some("mailuser"));
81//! assert_eq!(entry.password(), Some("mailpass"));
82//! assert_eq!(entry.url(), Some("https://mail.protonmail.com"));
83//! assert_eq!(entry.notes(), None);
84//! ```
85//!
86//! Open the existing KeePass database passwords.kdbx using the password
87//! "password", print it and save it to new.kdbx:
88//!
89//! ```rust,no_run
90//! use kpdb::{CompositeKey, Database};
91//! use std::fs::File;
92//!
93//! let mut file = File::open("passwords.kdbx").unwrap();
94//! let key = CompositeKey::from_password("password");
95//! let db = Database::open(&mut file, &key).unwrap();
96//!
97//! println!("{:?}", db);
98//!
99//! let mut file = File::create("new.kdbx").unwrap();
100//! db.save(&mut file).unwrap();
101//! ```
102//!
103//! Open the existing KeePass database passwords.kdbx using both the password
104//! "password" and the key file passwords.key, print it and save it to new.kdbx:
105//!
106//! ```rust,no_run
107//! use kpdb::{CompositeKey, Database, KeyFile};
108//! use std::fs::File;
109//!
110//! let mut file = File::open("passwords.key").unwrap();
111//! let key_file = KeyFile::open(&mut file).unwrap();
112//! let key = CompositeKey::from_both("password", key_file);
113//!
114//! let mut file = File::open("passwords.kdbx").unwrap();
115//! let db = Database::open(&mut file, &key).unwrap();
116//!
117//! println!("{:?}", db);
118//!
119//! let mut file = File::create("new.kdbx").unwrap();
120//! db.save(&mut file).unwrap();
121//! ```
122//!
123//!
124//! # Not Implemented
125//!
126//! The following features are currently not implemented:
127//!
128//! - KeePass 1 databases.
129
130extern crate crypto as rust_crypto;
131extern crate xml as rust_xml;
132
133pub use crate::types::Association;
134pub use crate::types::BinariesMap;
135pub use crate::types::BinaryId;
136pub use crate::types::BinaryKey;
137pub use crate::types::BinaryValue;
138pub use crate::types::Comment;
139pub use crate::types::CompositeKey;
140pub use crate::types::Compression;
141pub use crate::types::CustomDataMap;
142pub use crate::types::CustomIconUuid;
143pub use crate::types::CustomIconsMap;
144pub use crate::types::Database;
145pub use crate::types::DbType;
146pub use crate::types::Entry;
147pub use crate::types::EntryUuid;
148pub use crate::types::Error;
149pub use crate::types::Group;
150pub use crate::types::GroupUuid;
151pub use crate::types::KeyFile;
152pub use crate::types::KeyFileType;
153pub use crate::types::MasterCipher;
154pub use crate::types::Result;
155pub use crate::types::StreamCipher;
156pub use crate::types::StringKey;
157pub use crate::types::StringValue;
158pub use crate::types::StringsMap;
159pub use crate::types::Times;
160pub use crate::types::TransformRounds;
161pub use crate::types::Version;
162pub use crate::types::{Color, ColorError};
163pub use crate::types::{Icon, IconError};
164pub use crate::types::{Obfuscation, ObfuscationError};
165
166mod common;
167mod compression;
168mod crypto;
169mod format;
170mod io;
171mod types;
172mod utils;
173
174#[cfg(test)]
175#[macro_use]
176extern crate quickcheck;
kpdb/lib.rs

kpdb/
lib.rs
