From f2963ffdfbd1cec7a60e87178c327276256f9b18 Mon Sep 17 00:00:00 2001 From: Antoine POPINEAU Date: Fri, 22 Mar 2019 23:03:50 +0100 Subject: [PATCH] Add documentation. --- knox/src/prelude/attribute.rs | 10 ++++ knox/src/prelude/entry.rs | 18 +++++++ knox/src/prelude/vault.rs | 91 +++++++++++++++++++++++++++++++++++ 3 files changed, 119 insertions(+) diff --git a/knox/src/prelude/attribute.rs b/knox/src/prelude/attribute.rs index 65ef044..5570119 100644 --- a/knox/src/prelude/attribute.rs +++ b/knox/src/prelude/attribute.rs @@ -1,12 +1,22 @@ use crate::pb::*; +/// An `Attribute`'s different kinds of value. +/// +/// An attribute's value can be stored in differnet form. This enum abstracts +/// over those different types to provide a unique interface to the values. #[derive(Debug, PartialEq)] pub enum AttributeValue { + /// The typical representation of a standard attribute, a simple UTF-8 string String(String), + /// A binary presentation of a value, used for file contents. Binary(Vec), } impl Attribute { + /// Retrieve an `Attribute`'s value. + /// + /// Extracts a value from an attribute, and return an enum that allows to + /// abstract over the actuel storage representation. pub fn value(&self) -> AttributeValue { if self.file { match String::from_utf8(self.bytes_value.clone()) { diff --git a/knox/src/prelude/entry.rs b/knox/src/prelude/entry.rs index a7eebaa..bf6b8d6 100644 --- a/knox/src/prelude/entry.rs +++ b/knox/src/prelude/entry.rs @@ -10,6 +10,14 @@ use crate::pb::*; use crate::util; impl Entry { + /// Retrieves an entry. + /// + /// This function returns a decrypted `Entry` from its virtual path. + /// + /// # Arguments + /// + /// * **path:** a virtual path to an `Entry`. This will be expanded to the + /// real filesystem file backing the `Entry`. pub fn read

(handle: &VaultContext, path: P) -> Result> where P: AsRef, @@ -20,6 +28,7 @@ impl Entry { Ok(message) } + /// Adds a standard string attribute to an Entry. pub fn add_attribute(&mut self, key: &str, value: &str) { let attribute = Attribute { value: value.to_string(), @@ -29,6 +38,10 @@ impl Entry { self.attributes.insert(key.to_string(), attribute); } + /// Adds a confidential string attribute to an `Entry`. + /// + /// A confidential attribute is just represented by a boolean value and will + /// prevent automatic priting of the value to the console. pub fn add_confidential_attribute(&mut self, key: &str, value: &str) { let attribute = Attribute { value: value.to_string(), @@ -39,6 +52,11 @@ impl Entry { self.attributes.insert(key.to_string(), attribute); } + /// Adds a file attribute to an `Entry`. + /// + /// A file attribute can contain the raw content of a filesystem file (string + /// or binary) and therefore will be encoded differently that string + /// attributes. pub fn add_file_attribute(&mut self, key: &str, value: &[u8]) { let mut attribute = Attribute { file: true, diff --git a/knox/src/prelude/vault.rs b/knox/src/prelude/vault.rs index cb9d5dd..29da9fa 100644 --- a/knox/src/prelude/vault.rs +++ b/knox/src/prelude/vault.rs @@ -16,6 +16,16 @@ pub struct VaultContext { } impl VaultContext { + /// Create a new `Vault`. + /// + /// Initializes a new empty vault, encrypted with the provided GPG + /// identities. + /// + /// # Arguments + /// + /// * `path` - the filesystem path at which to create the vault. + /// * `identities` - a slice if GPG identities, represented by their owner's + /// email address. pub fn create

(path: P, identities: &[String]) -> Result> where P: AsRef, @@ -52,6 +62,14 @@ impl VaultContext { }) } + /// Return a handle to a `Vault` from the filesystem. + /// + /// Opens, decrypt the metadata of, and returns a handle that allows you to + /// manipulate a `Vault`. + /// + /// # Arguments + /// + /// * `path` - filesystem path where the vault is located. pub fn open

(path: P) -> Result> where P: AsRef, @@ -73,6 +91,13 @@ impl VaultContext { }) } + /// Write the vault metadata. + /// + /// Persists all changes to the vault's metadata into the `_knox.meta` file + /// containing the encrypted mapping between virtual (user) secret paths and + /// filesystem paths. + /// + /// This mapping collection is called the index.. pub fn write(&self) -> Result<(), Box> { create_dir_all(util::normalize_path(self, &""))?; @@ -86,6 +111,15 @@ impl VaultContext { Ok(()) } + /// Add an entry to the index. + /// + /// Adds an entry to the index of a vault, allowing to retrieve a filesystem + /// path from a virtual path. This does not manage the secret itself. + /// + /// # Arguments + /// + /// * `path` - virtual path to the entry. + /// * `destination` - physical filesystem path to the entry. pub fn add_index(&mut self, path: &str, destination: &str) { self .vault @@ -93,10 +127,27 @@ impl VaultContext { .insert(path.to_string(), destination.to_string()); } + /// Remove an entry from the index. + /// + /// Removes an entry to the index of a vault, allowing to retrieve a + /// filesystem path from a virtual path. This does not manage the secret + /// itself. + /// + /// # Arguments + /// + /// * `path` - virtual path to the entry pub fn remove_index(&mut self, path: &str) { self.vault.mut_index().remove(path); } + /// Read an `Entry`. + /// + /// Takes a virtual path and returns the decrypted `Entry` from the vault, if + /// it exists. + /// + /// # Arguments + /// + /// * `path` - the virtual path to the entry. pub fn read_entry(&self, path: &str) -> Result> { if !self.vault.get_index().contains_key(path) { return Err(VaultError::throw("no entry was found at this path")); @@ -108,6 +159,15 @@ impl VaultContext { Ok(entry) } + /// Persist an `Entry`. + /// + /// Encrypts and writes an `Entry` to its physical location as described in + /// the vault's index. The entry must exist in the index beforehand. + /// + /// # Arguments + /// + /// * `path` - the virtual path to the entry. + /// * `entry` - the `Entry` to be written. pub fn write_entry(&mut self, path: &str, entry: &Entry) -> Result<(), Box> { let hash = util::hash_path(self.vault.get_index().get(path)); @@ -127,6 +187,14 @@ impl VaultContext { Ok(()) } + /// Delete an `Entry`. + /// + /// Deletes an entry both from its backing filesystem location and from the + /// index. + /// + /// # Arguments + /// + /// * `path` - the virtual path to the entry. pub fn delete_entry(&mut self, path: &str) -> Result<(), Box> { if let Some(salt) = self.vault.get_index().get(path) { let hash = util::hash_path(Some(salt)); @@ -151,6 +219,11 @@ impl VaultContext { )) } + /// Check if a file exists under the vault's directory. + /// + /// # Arguments + /// + /// * - `path` - a path relative to the vault's root directory. pub fn has_pack

(&self, path: P) -> bool where P: AsRef, @@ -158,10 +231,28 @@ impl VaultContext { Path::new(&util::normalize_path(self, &path)).exists() } + /// Add an identity to the vault + /// + /// Saves a new identity to the vault's metadata. This does not touch any + /// existing secrets, which should be re-encrypted for the new identity to + /// be used. + /// + /// # Arguments + /// + /// * `identity` - the GPG identity pub fn add_identity(&mut self, identity: &str) { self.vault.mut_identities().push(identity.to_string()); } + /// Remove an identity from the vault. + /// + /// Removes an existing identity from the vault's metadata. This does not + /// touch any existing secrets, which should be re-encrypted for the + /// removed identity to be unable de decrypt them. + /// + /// # Arguments + /// + /// * `identity` - the GPG identity pub fn remove_identity(&mut self, identity: &str) { let identities = self .vault