[−][src]Crate self_encryption
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 self_encryption::Storage; use tiny_keccak::sha3_256; use async_trait::async_trait; use self_encryption::SelfEncryptionError; struct Entry { name: Vec<u8>, data: Vec<u8> } struct SimpleStorage { entries: Vec<Entry> } impl SimpleStorage { fn new() -> SimpleStorage { SimpleStorage { entries: vec![] } } } #[async_trait] impl Storage for SimpleStorage { async fn get(&mut self, name: &[u8]) -> Result<Vec<u8>, SelfEncryptionError> { match self.entries.iter().find(|ref entry| entry.name == name) { Some(entry) => Ok(entry.data.clone()), None => Err(SelfEncryptionError::Storage), } } async fn put(&mut self, name: Vec<u8>, data: Vec<u8>) -> Result<(), SelfEncryptionError> { self.entries.push(Entry { name: name, data: data, }); Ok(()) } async fn generate_address(&self, data: &[u8]) -> Result<Vec<u8>, SelfEncryptionError> { Ok(sha3_256(data).to_vec()) } }
Using this SimpleStorage
, a self_encryptor can be created and written to/read from:
use self_encryption::{DataMap, SelfEncryptor}; #[tokio::main] async fn main() { let storage = SimpleStorage::new(); let encryptor = SelfEncryptor::new(storage, DataMap::None).unwrap(); let data = vec![0, 1, 2, 3, 4, 5]; let mut offset = 0; encryptor.write(&data, offset).await.unwrap(); offset = 2; let length = 3; assert_eq!(encryptor.read(offset, length).await.unwrap(), vec![2, 3, 4]); let data_map = encryptor.close().await.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 inherited from |