Crate self_encryption [−] [src]
A file content self-encryptor.
This library provides convergent encryption on file-based data and produce a DataMap
type and
several chunks of data. Each chunk is up to 1MB in size and has a name. This name is the
SHA3-256 hash of the content, which allows the chunks to be self-validating. If size and hash
checks are utilised, a high degree of certainty in the validity of the data can be expected.
Use
To use this library you must implement a storage trait (a key/value store) and associated
storage error trait. These provide a place for encrypted chunks to be put to and got from by
the SelfEncryptor
.
The storage trait should be flexible enough to allow implementation as an in-memory map, a disk-based database, or a network-based DHT for example.
Examples
This is a simple setup for a memory-based chunk store. A working implementation can be found in the "examples" folder of this project.
use futures::{future, Future}; use std::error::Error; use std::fmt::{self, Display, Formatter}; use self_encryption::{Storage, StorageError}; #[derive(Debug, Clone)] struct SimpleStorageError {} impl Display for SimpleStorageError { fn fmt(&self, formatter: &mut Formatter) -> fmt::Result { write!(formatter, "Failed to get data from SimpleStorage") } } impl Error for SimpleStorageError { fn description(&self) -> &str { "SimpleStorage::get() error" } } impl StorageError for SimpleStorageError {} struct Entry { name: Vec<u8>, data: Vec<u8> } struct SimpleStorage { entries: Vec<Entry> } impl SimpleStorage { fn new() -> SimpleStorage { SimpleStorage { entries: vec![] } } } impl Storage for SimpleStorage { type Error = SimpleStorageError; fn get(&self, name: &[u8]) -> Box<Future<Item=Vec<u8>, Error=Self::Error>> { let result = match self.entries.iter().find(|ref entry| entry.name == name) { Some(entry) => Ok(entry.data.clone()), None => Err(SimpleStorageError {}), }; Box::new(future::result(result)) } fn put(&mut self, name: Vec<u8>, data: Vec<u8>) -> Box<Future<Item=(), Error=Self::Error>> { self.entries.push(Entry { name: name, data: data, }); Box::new(future::ok(())) } }
Using this SimpleStorage
, a self-encryptor can be created and written to/read from:
use futures::Future; use self_encryption::{DataMap, SelfEncryptor}; fn main() { let storage = SimpleStorage::new(); let mut encryptor = SelfEncryptor::new(storage, DataMap::None).unwrap(); let data = vec![0, 1, 2, 3, 4, 5]; let mut offset = 0; encryptor.write(&data, offset).wait().unwrap(); offset = 2; let length = 3; assert_eq!(encryptor.read(offset, length).wait().unwrap(), vec![2, 3, 4]); let data_map = encryptor.close().wait().unwrap().0; assert_eq!(data_map.len(), 6); }
The close()
function returns a DataMap
which can be used when creating a new encryptor to
access the content previously written. Storage of the DataMap
is outwith the scope of this
library and must be implemented by the user.
Structs
ChunkDetails |
Holds pre- and post-encryption hashes as well as the original (pre-compression) size for a given chunk. |
SelfEncryptor |
This is the encryption object and all file handling should be done using this object as the low level mechanism to read and write content. This library has no knowledge of file metadata. |
SequentialEncryptor |
An encryptor which only permits sequential writes, i.e. there is no ability to specify an offset
in the |
Enums
DataMap |
Holds the information that is required to recover the content of the encrypted file. Depending
on the file size, this is held as a vector of |
SelfEncryptionError |
Errors which can arise during self-encryption or -decryption. |
Constants
COMPRESSION_QUALITY |
Controls the compression-speed vs compression-density tradeoffs. The higher the quality, the slower the compression. Range is 0 to 11. |
MAX_CHUNK_SIZE |
The maximum size (before compression) of an individual chunk of the file, defined as 1MB. |
MAX_FILE_SIZE |
The maximum size of file which can be self-encrypted, defined as 1GB. |
MIN_CHUNK_SIZE |
The minimum size (before compression) of an individual chunk of the file, defined as 1kB. |
Traits
Storage |
Trait which must be implemented by storage objects to be used in self-encryption. Data is
passed to the storage object encrypted with |
StorageError |
Trait inherited from |