README

crumbl-js

GitHub tag (latest by date) npm GitHub last commit GitHub issues NPM

crumbl-js is a JavaScript client developed in TypeScript for generating secure data storage with trusted signing third-parties using the Crumbl™ technology patented by Cyril Dever for Edgewhere.

If you're interesting in using the library, please contact us.

Formal description

For details on the mathematical and protocol foundations, you might want to check out our white paper.

Process

The whole process could be divided into two major steps:

create the crumbl from a source data;
extract the data out of a crumbl.

The first step involves at least two stakeholders, but preferably four for optimal security and sustainability:

at least one "owner" of the data, ie. the stakeholder that needs to securely store it;
three signing trusted third-parties who shall remain unaware of the data.

Creation

To create the crumbl, one would need the data and the public keys of all the stakeholders, as well as the encryption algorithm used by them. Currently, two encryption algorithms are allowed by the system: ECIES and RSA.

Once created, the crumbl could be stored by anyone: any stakeholder or any outsourced data storage system. The technology guarantees that the crumbl can't be deciphered without the presence of the signing stakeholders, the number of needed stakeholders depending on how many originally signed it, but a data owner must at least be present. In fact, only a data owner will be able to fully recover the original data from the crumbl.
Extraction

To extract the data from a crumbl is a multi-step process:
- First, the data owner should ask the signing trusted third-parties to decipher the parts (the "crumbs") they signed;
- Each signing trusted third-party should use their own keypair (private and public keys) along with the crumbl, and then return the result (the "partial uncrumbs") to the data owner;
- After, collecting all the partial uncrumbs, the data owner should inject them in the system along with the crumbl and his own keypair to get the fully-deciphered data.

All these steps could be done building an integrated app utilizing the TypeScript library server-side, or the JavaScript library in the browser.

Usage

JavaScript library

npm i crumbl-js

The code below should display a new crumbl from the passed credential strings of the stakeholders:

import { BrowserWorker, CREATION, ECIES_ALGORITHM, hash } from 'crumbl-js'

function main(owner_pubkey, trustee1_pubkey, trustee2_pubkey) {
  const source = document.getElementById('source').innerHTML;
  hash(source).then(hashedSource => {
    // Feed with the signers' credentials
    const owner = {
        encryptionAlgorithm: ECIES_ALGORITHM,
        publicKey: Buffer.from(owner_pubkey, 'hex') // ECIES hexadecimal string representation of the decompressed public key
    };
    const trustee1 = {
        encryptionAlgorithm: ECIES_ALGORITHM,
        publicKey: Buffer.from(trustee1_pubkey, 'hex')
    };
    const trustee2 = {
        encryptionAlgorithm: ECIES_ALGORITHM,
        publicKey: Buffer.from(trustee2_pubkey, 'hex')
    };

    const workerCreator = new BrowserWorker({
        mode: CREATION,
        data: [source],
        verificationHash: hashedSource,
        htmlElement: document.getElementById('crumbled')
    });
    workerCreator.create([owner], [trustee1, trustee2]).then(crumbled => {
        // At this point, the crumbled value would have been assigned to the passed HTML element.
        // But you may want to do something else with it here.
        console.log(crumbled);
    }):
  });
}

Following the above situation, using the crumbled data and two "partial uncrumbs" gathered from the trusted signing third-parties, the code below shows how to recover the original source data as a data owner:

const workerExtractor = new BrowserWorker({
    mode: EXTRACTION,
    data: [crumbled, partialUncrumb1, partialUncrumb2],
    verificationHash: '580fb8a91f05833200dea7d33536aaec9d7ceb256a9858ee68e330e126ba409d',
});
workerExtractor.extract(owner, true).then(result => {
  console.assert(result === source, 'Something wrong happened: are you sure you used the right items?');
});

If the extracting stakeholder is not the data owner, the result would be a "partial uncrumb" to give to the data owner for processing the complete operation. For maximum security and sustainability, we recommend the involvement of at least three trusted signing third-parties in the process in addition to the data owner. Please contact us for a complete implementation.

Dependencies

This library relies on the following peer dependencies:

ecies-geth and feistel-cipher provided by Cyril Dever for Edgewhere;
buffer-xor;
seedrandom.js.

Besides, to run the tests, you would need to install live-server:

npm i -g live-server

Go Library

You might want to check out the Go implementation for the Crumbl™: crumbl-exe, an executable and a Go client for generating secure data storage with trusted signing third-parties using the Crumbl™ technology patented by Cyril Dever for Edgewhere.

Scala Library

You might also want to check out the Scala implementation for the Crumbl™: crumbl-jar, a Scala client for the JVM and an executable JAR as well.

License

The use of the Crumbl™ library is subject to fees for commercial purposes and to the respect of the BSD-2-Clause-Patent License. All technologies are protected by patents owned by Edgewhere SAS. Please contact us to get further information.

Usage no npm install needed!