Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/decentralized-identity/fuzzy-encryption

A variant of a Fuzzy Vault cryptographic scheme designed for encrypting data with better human recovery features.
https://github.com/decentralized-identity/fuzzy-encryption

wg-id

Last synced: about 2 months ago
JSON representation

A variant of a Fuzzy Vault cryptographic scheme designed for encrypting data with better human recovery features.

Awesome Lists containing this project

README 

        
# Fuzzy Encryption



Introduction



Fuzzy Vault Key Recovery is a library that provides an alternative for unmemorable user-controlled cryptographic keys composed of secret long strings of random numbers and letters. This project presents a scheme where a user is expected to remember/securely protect a passphrase alone. This passphrase is used to generate cryptographic key material that is used to generate as well as recover cryptographic key(s). Configuration information (returned as a payload) is created by the scheme and used to generate the cryptographic key material from the passphrase.  This payload can be stored in a public place as long as it is not modified, and is necessary to enter when recovering keys. If the configuration inputs are modified, the generated secret can no longer be recovered.



This distribution contains a C++ and a Python implementation of the Fuzzy Vault Key Recovery scheme. The Python version is included as a demonstration to help understand the C++ implementation. The Python version will not receive support for general use. The C++ code is intended for general use.



The full algorithm is described in detail in the [whitepaper](https://github.com/decentralized-identity/fuzzy-encryption/blob/master/fuzzy-encryption-construction.pdf).



- For C++ build and usage instructions see [C++ README](./src/c++/README.md)

- For Python build and usage instructions see [Python README](./src/python/README.md)



## Table of Contents

- [Usage](#fuzzy-vault-key-recovery-usage)

- [Properties](#properties)

- [Corpus and word selection](#corpus-and-word-selection)



## Fuzzy Vault Key Recovery Usage

### Set Up

Setting up a new Fuzzy Vault with a passphrase requires two steps as shown in the images below.

1. **Generate Parameters:**

    This call allows the application to select parameters for the passphrase and generates a JSON object that will be used to initialize a vault. This step can be completed once by the application and the JSON parameter object can then be reused for generating secrets for different passphrases.

    

    The three parameters set by the application are `setSize`, `correctThreshold`, and `corpusSize`. `setSize` determines the number of words in the passphrase, while `correctThreshold` is the minimum number of those words that must be submitted correctly to retrieve the keys. `corpusSize` is the size of the corpus from which the words in the passphrase will be selected. See the section on [corpus and word selection](#corpus-and-word-selection) for further details.



![fuzzyencryption_genparams](https://user-images.githubusercontent.com/16085124/107101589-ad18b900-67cc-11eb-990b-25c1da83911a.png)



2. **Generate Secret:** This step establishes a secret based on a specific passphrase. Taking the parameters object, and a set of words in the passphrase (via their [indices within the corpus](#corpus-and-word-selection)) as inputs, a payload is returned. This payload encodes a commitment to the specific passphrase and other parameters, and is required for recovery of cryptographic keys. Words in the passphrase are to be selected randomly from the corpus by the application. 



_**Note:** the "secret payload" does not reveal any secret information about the passphrase and thus can be stored in any location where it will not be modified. Storage of this payload is left up to the application and can be backed up as needed to ensure it is available at the time of key recovery._



![fuzzyencryption_gensecret](https://user-images.githubusercontent.com/16085124/107101592-af7b1300-67cc-11eb-92f0-dbd61c986a1f.png)



### Key Generation and Recovery

Once the Fuzzy Vault is set up with the given parameters and passphrase, cryptographic keys can be generated by executing the final step:



3. **Generate Keys:** This call unlocks the vault to return a set of cryptographic keys that have been securely generated from the passphrase and payload file in Step 2 above. If the words of the passphrase entered here meet the specified minimum threshold for correctness, the set of cryptographic keys will be returned. The number of keys returned is set with the `keyCount` parameter in this call. The generation of keys is deterministic and will be the same every time for the given passphrase and payload. 



![fuzzyencryption_keygen](https://user-images.githubusercontent.com/16085124/106983952-96fef000-671b-11eb-929b-340553cc3761.png)



## Properties

This key recovery scheme enables harnessing of the entropy in human-memorizable sets and

generates strong cryptographic keys from it, while tolerating a small number of errors. The properties of this technology are:

1. **No cryptographic secret to memorize:** The goal of this scheme is to be usable without any need to remember or protect cryptographic secrets. This means, a user is expected to remember/securely protect her pass-phrase only. Any state information generated by the scheme in order to generate the cryptographic key material from the pass-phrase can be stored in any public repository where it can be retrieved for key recovery. Modification or loss of this state information will prevent recovery of the keys.

2. **Secure recovery:** Only a correct passphrase (tolerating a small number of errors) will be able to recover the cryptographic key. The error tolerance threshold is a system parameter. Any passphase that has more than that many errors should fail to recover the cryptographic key or any partial information about it.

3. **Reusability of passphrases:** A user should be able to reuse her passphrase to generate multiple cryptographic keys. For example, if a user generates a cryptographic key using a passphrase and the key gets compromised, she needs to generate a new cryptographic key. We want her to be able to re-use her passphrase to generate a second fresh cryptographic key. Keys are generated deterministically by this scheme and will be returned in the same order within the set of keys.

4. **Non-iterability:** A pass-phrase will consist of a set of elements, like a collection of words. We want to have the following property: an adversary who has the public state information will be able to validate its guess for a complete pass-phrase using the state information (by checking if the secret key recovery fails or not), but it should not be able to validate its guess for individual elements in the pass-phrase. For example, an adversary guesses just one word, say, forbidden. It should not be able to learn whether the guessed word belongs to the pass-phrase or not.



## Corpus and word selection

This implementation of the key recovery scheme is agnostic to the corpus from which passphrase words will be selected. Given this, it is left to the application developer to:

1. Select a corpus of suitable size. Many typically used corpora of at least 7000 words can be used, like https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt. 

2. Establish a deterministic mapping of each word in the corpus to a number between 1 and the size of the corpus, such as an index.

3. Select words for a passphrase at random from the corpus. Allowing end users to select words can reduce entropy of the passphrase, and should be considered carefully if done.



The words set as the passphrase in the set up steps must be entered by their indices within the corpus. This allows the application developer to choose a corpus that will be suitable for their users. The size of the corpus used must also be entered as a set up parameter. 



For a full explanation of how these passphrase word indices are used to generate the cryptographic keys, see the [whitepaper](https://github.com/decentralized-identity/fuzzy-encryption/blob/master/fuzzy-encryption-construction.pdf).