[][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.

Project GitHub page.

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};
use tiny_keccak::sha3_256;

#[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<dyn 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<dyn Future<Item=(), Error=Self::Error>> {
       self.entries.push(Entry {
           name: name,
           data: data,
       });

       Box::new(future::ok(()))
   }

   fn generate_address(&self, data: &[u8]) -> Vec<u8> {
        sha3_256(data).to_vec()
   }
}

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 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 write() call; all data is appended sequentially.

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 ChunkDetails, or as raw data.

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 name being the SHA3-256 hash of data. Storage could be implemented as an in-memory HashMap or a disk-based container for example.

StorageError

Trait inherited from std::error::Error representing errors which can be returned by the Storage object.