Document rustcryptfs-lib

rustcryptfs-lib/src/error.rs

@@ -4,6 +4,7 @@ use crate::{config::ConfigError, content::ContentCipherError, filename::Filename
 
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// An error that wrap all the errors in this lib.
 #[derive(Debug, Error)]
 pub enum Error {
     #[error(transparent)]

rustcryptfs-lib/src/filename/dir_filename_cipher.rs

@@ -2,6 +2,9 @@ use cipher::{block_padding::Pkcs7, Iv, Key, KeyIvInit};
 
 use super::{EmeCipher, EncodedFilename, FilenameCipherError, IntoDecodable};
 
+/// DirFilenameCipher allow you to cipher and decipher filenames in a directory.
+///
+/// TODO : document structure of a gocryptfs dir or put a link.
 pub struct DirFilenameCipher<'a, 'b> {
     filename_key: &'a Key<EmeCipher>,
     iv: &'b Iv<EmeCipher>,
@@ -12,6 +15,9 @@ impl<'a, 'b> DirFilenameCipher<'a, 'b> {
         Self { filename_key, iv }
     }
 
+    /// Decipher a filename.
+    ///
+    /// Name muste be the name of the file if it is a short filename, or the content of the long .name file otherwise.
     pub fn decode_filename<S>(&self, name: S) -> Result<String, FilenameCipherError>
     where
         S: IntoDecodable,
@@ -26,6 +32,7 @@ impl<'a, 'b> DirFilenameCipher<'a, 'b> {
         Ok(String::from_utf8_lossy(filename_decoded).to_string())
     }
 
+    /// Cipher a filename.
     pub fn encrypt_filename(
         &self,
         plain_text_name: &str,

rustcryptfs-lib/src/filename/filename_encoded.rs

@@ -1,6 +1,9 @@
 use sha2::{Digest, Sha256};
 
-/// EncodedFilename
+/// Represent an encrypted filename.
+/// 
+/// An encrypted filename can have two forms : long or short.
+/// TODO: Document
 #[derive(Debug, PartialEq, Eq)]
 pub enum EncodedFilename {
     ShortFilename(String),
@@ -9,8 +12,18 @@ pub enum EncodedFilename {
 
 #[derive(Debug, PartialEq, Eq)]
 pub struct LongFilename {
-    pub filename: String,
+    filename: String,
-    pub filename_content: String,
+    filename_content: String,
+}
+
+impl LongFilename {
+    pub fn filename(&self) -> &str {
+        self.filename.as_ref()
+    }
+
+    pub fn filename_content(&self) -> &str {
+        self.filename_content.as_ref()
+    }
 }
 
 impl From<String> for EncodedFilename {

rustcryptfs-lib/src/filename/mod.rs

@@ -1,3 +1,5 @@
+//! Utilities for filename encryption.
+//!
 use aes::Aes256;
 use cipher::{Iv, Key};
 use eme_mode::DynamicEme;
@@ -6,18 +8,20 @@ use hkdf::Hkdf;
 pub(crate) type EmeCipher = DynamicEme<Aes256>;
 
 mod dir_filename_cipher;
-mod filename_encoded;
 mod error;
+mod filename_encoded;
 
 pub use dir_filename_cipher::*;
-pub use filename_encoded::*;
 pub use error::*;
+pub use filename_encoded::*;
 
+/// FilenameCipher allow you to retrieve a DirFilenameCipher, used to cipher and decipher filenames.
 pub struct FilenameCipher {
     filename_key: Key<Aes256>,
 }
 
 impl FilenameCipher {
+    /// Create a new FilenameCipher, from the master key.
     pub fn new(master_key: &[u8]) -> Result<Self, FilenameCipherError> {
         let mut key = [0u8; 32];
         let hdkf = Hkdf::<sha2::Sha256>::new(None, master_key);
@@ -28,6 +32,7 @@ impl FilenameCipher {
         })
     }
 
+    /// Get the cipher for a directory, allowing you to decipher files in this dir.
     pub fn get_cipher_for_dir<'a, 'b>(&'a self, iv: &'b [u8]) -> DirFilenameCipher<'a, 'b> {
         let iv = Iv::<EmeCipher>::from_slice(iv);
         DirFilenameCipher::new(&self.filename_key, iv)

rustcryptfs-lib/src/lib.rs

@@ -52,7 +52,7 @@ impl GocryptFs {
         })
     }
 
-    /// Get the [`filename decoder`](struct@FilenameDecoder) attached to this GocryptFs.
+    /// Get the [`filename decoder`](struct@FilenameCipher) attached to this GocryptFs.
     pub fn filename_decoder(&self) -> &FilenameCipher {
         &self.filename_decoder
     }