blindfold 1.0.0

Categories of Encryption Keys

This library uses the attributes of a key object (instantiated using an appropriate constructor) to determine what protocol to use when encrypting a plaintext. Keys fall into one of two categories:

1. SecretKey/PublicKey: Keys in this category support operations within a single node or across multiple nodes. These contain cryptographic material for encryption, decryption, and other operations. Notably, a SecretKey instance includes cryptographic material (such as symmetric keys) that a client should not share with the cluster. Using a SecretKey instance helps ensure that a client can retain exclusive access to a plaintext even if all servers in a cluster collude.

2. ClusterKey: Keys in this category represent cluster configurations but do not contain cryptographic material. These can be used only when working with multiple-node clusters. Unlike SecretKey and PublicKey instances, ClusterKey instances do not incorporate additional cryptographic material. This means each node in a cluster has access to a raw secret share of the plaintext and, therefore, the plaintext is only protected if the nodes in the cluster do not collude.

Supported Protocols

The table below summarizes the data encryption protocols that this library makes available (and which a developer may leverage by creating a key object with the appropriate attributes). The table also specifies which operation involving ciphertexts is supported by each protocol. Support for summation of encrypted values implies support both for subtraction of encrypted values from other encrypted values and for multiplication of encrypted values by a plaintext signed integer scalar.

More Details on Secret Sharing

When working with multiple-node clusters and encrypting data for compatibility with the store operation using a SecretKey instance, each secret share is encrypted using a symmetric key (the material for which is stored inside the SecretKey instance). However, when encrypting for compatibility with the sum operation (without or with a threshold), each secret share is instead masked via multiplication with a secret nonzero scalar (with one secret scalar per node stored in the SecretKey instance). While this ensures that the secret-shared plaintexts encrypted in this way are compatible with addition and scalar multiplication, users should use this feature only if they have a thorough understanding of the privacy and security trade-offs involved.

Threshold secret sharing is supported when encrypting for multiple-node clusters (with the exception of encrypting for compatibility with the match operation). A threshold specifies the minimum number of nodes required to reconstruct the original data. Shamir’s secret sharing is employed when encrypting with support for a threshold, ensuring that encrypted data can be decrypted if the required number of shares is available.

Ciphertext Overheads

The table below presents tight upper bounds on ciphertext sizes (in bytes) for each supported protocol when it is used to encrypt a plaintext having k bytes (where a 32-bit integer plaintext is represented using 4 bytes). For multiple-node protocols, the size of the ciphertext delivered to an individual node is reported (excluding any overheads associated with the container type within which separate ciphertext components such as the share index and value reside). The upper bounds below are checked within the testing script.

Examples

Extensive documentation, examples, and developer tools that can assist anyone interested in using this library are available in the Nillion Docs on Private Storage with nilDB. Numerous examples can also be found within docstrings in the library’s source code and in its testing script.

The example below generates a SecretKey instance for encrypting data to be stored within a single-node cluster:

>>> cluster = {'nodes': [{}]}
>>> secret_key = blindfold.SecretKey.generate(cluster, {'store': True})

The example below generates a ClusterKey instance for converting data into secret shares (such that summation on secret-shared data is supported) to be stored in a three-node cluster with a two-share decryption threshold:

>>> cluster = {'nodes': [{}, {}, {}]}
>>> cluster_key = blindfold.ClusterKey.generate(cluster, {'sum': True}, threshold=2)

The example below encrypts and decrypts a string:

>>> secret_key = blindfold.SecretKey.generate({'nodes': [{}]}, {'store': True})
>>> plaintext = 'abc'
>>> ciphertext = blindfold.encrypt(secret_key, plaintext)
>>> decrypted = blindfold.decrypt(secret_key, ciphertext)
>>> assert plaintext == decrypted

The example below generates three secret shares of an integer and then reconstructs that integer using only two of the shares:

>>> secret_key = blindfold.SecretKey.generate(
...     {'nodes': [{}, {}, {}]},
...     {'sum': True},
...     threshold=2
... )
>>> plaintext = 123
>>> (share_a, share_b, share_c) = blindfold.encrypt(secret_key, plaintext)
>>> decrypted = blindfold.decrypt(secret_key, [share_a, share_c])
>>> assert plaintext == decrypted

Documentation

The documentation can be generated automatically from the source files using Sphinx:

python -m pip install ".[docs]"
cd docs
sphinx-apidoc -f -E --templatedir=_templates -o _source .. && make html

Testing and Conventions

All unit tests are executed and their coverage is measured when using pytest (see the pyproject.toml file for configuration details):

python -m pip install ".[test]"
python -m pytest

The subset of the unit tests included in the module itself and can be executed using doctest:

python src/blindfold/blindfold.py -v

Style conventions are enforced using Pylint:

python -m pip install ".[lint]"
python -m pylint src/blindfold test/test_blindfold.py

Contributions

In order to contribute to the source code, open an issue or submit a pull request on the GitHub page for this library.

Versioning

The version number format for this library and the changes to the library associated with version number increments conform with Semantic Versioning 2.0.0.

Publishing

This library can be published as a package on PyPI via the GitHub Actions workflow found in .github/workflows/build-publish-sign-release.yml that follows the recommendations found in the Python Packaging User Guide.

Ensure that the correct version number appears in pyproject.toml, and that any links in this README document to the Read the Docs documentation of this package (or its dependencies) have appropriate version numbers. Also ensure that the Read the Docs project for this library has an automation rule that activates and sets as the default all tagged versions.

To publish the package, create and push a tag for the version being published (replacing ?.?.? with the version number):

git tag ?.?.?
git push origin ?.?.?