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.

Project GitHub page.


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.


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::{Hasher, Sha3};
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![] }
impl Storage for SimpleStorage {
   async fn get(&mut self, name: &[u8]) -> Result<Vec<u8>, SelfEncryptionError> {
       match self.entries.iter().find(|ref entry| == name) {
           Some(entry) => Ok(,
           None => Err(SelfEncryptionError::Storage("Chunk not found".into())),


    async fn delete(&mut self, name: &[u8]) -> Result<(), SelfEncryptionError> {
       self.entries.retain(|entry| != name );


   async fn put(&mut self, name: Vec<u8>, data: Vec<u8>) -> Result<(),
   SelfEncryptionError> {
       self.entries.push(Entry {
           name: name,
           data: data,

   async fn generate_address(&self, data: &[u8]) -> Result<Vec<u8>, SelfEncryptionError> {
        let mut hasher = Sha3::v256();
        let mut output = [0; 32];
        hasher.finalize(&mut output);

Using this SimpleStorage, a self_encryptor can be created and written to/read from:

use self_encryption::{DataMap, SelfEncryptor};

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!(, 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.



Holds pre- and post-encryption hashes as well as the original (pre-compression) size for a given chunk.


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.


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.



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.


Errors which can arise during self_encryption or -decryption.



Controls the compression-speed vs compression-density tradeoffs. The higher the quality, the slower the compression. Range is 0 to 11.


The maximum size (before compression) of an individual chunk of the file, defined as 1MB.


The maximum size of file which can be self_encrypted, defined as 1GB.


The minimum size (before compression) of an individual chunk of the file, defined as 1kB.



Trait inherited from std::error::Error representing errors which can be returned by the Storage object. 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.