# TNO MPC Lab - Encryption Schemes - Templates
The TNO MPC lab consists of generic software components, procedures, and
functionalities developed and maintained on a regular basis to facilitate and
aid in the development of MPC solutions. The lab is a cross-project initiative
allowing us to integrate and reuse previously developed MPC functionalities to
boost the development of new protocols and solutions.
The package tno.mpc.encryption_schemes.templates is part of the TNO Python
Toolbox.
Generic frameworks for encryption schemes. Currently includes support for:
- Generic encryption scheme (encryption_scheme.py);
- Asymmetric encryption scheme (asymmetric_encryption_scheme.py);
- Symmetric encryption scheme (symmetric_encryption_scheme.py);
- Support for precomputation of randomness (randomized_encryption_scheme.py).
_Limitations in (end-)use: the content of this software package may solely be
used for applications that comply with international export control laws._
_This implementation of cryptographic software has not been audited. Use at your
own risk._
## Documentation
Documentation of the tno.mpc.encryption_schemes.templates package can be found
[here](https://docs.mpc.tno.nl/encryption_schemes/templates/4.1.2).
## Install
Easily install the tno.mpc.encryption_schemes.templates package using pip:
```console
$ python -m pip install tno.mpc.encryption_schemes.templates
```
### Note:
A significant performance improvement can be achieved by installing the GMPY2
library.
```console
$ python -m pip install 'tno.mpc.encryption_schemes.templates[gmpy]'
```
If you wish to run the tests you can use:
```console
$ python -m pip install 'tno.mpc.encryption_schemes.templates[tests]'
```
## Generating prepared randomness for RandomizedEncryptionSchemes
In the encryption process, `RandomizedEncryptionScheme`s require a random
number. A typical encryption process generates a large random number, processes
it in a way that is specific for (the private key of) the encryption scheme, and
used the prepared random value to encrypt a plaintext message. A similarly
prepared random value is required to rerandomize a ciphertext. This process of
generating and preparing randomness consumes a lot of time and processing power.
Fortunately, the randomness depends only on the encryption scheme and not on the
message that is to be encrypted. This makes it possible to prepare randomness a
priori. Our library facilitates this process by the concept of "randomness
sources". Three specific sources are shipped with the library, but you may
define your own `RandomnessSource` by implementing the
`tno.mpc.encryption_schemes.templates._randomness_manager.RandomnessSource`
protocol. The default sources are:
- `ContextlessSource`, which yields randomness from a source that does not need
to be opened or closed (e.g. a list, tuple, function-call, ...).
- `FileSource`, which creates a thread to read a file, store the values in RAM
and yield values on request.
- `ProcessSource`, which creates one or more processes that all perform function
calls to store a predefined number of return values in RAM and yield on
request.
A `RandomizedEncryptionScheme` is configured with a `ContextlessSource` that
calls its generating function. However, it is often more efficient to start
generating a known amount of randomness earlier in the program execution. For
this, one may call `RandomizedEncryptionScheme.boot_generation` which internally
initializes and starts a `ProcessSource`, or requests an existing source to
generate more randomness (see also below). Other sources can be configured
through `RandomizedEncryptionScheme.register_randomness_source`.
### Storing randomness for later use
Naturally, a maximum speed-up during runtime of your main protocol is achieved
by generating random values a priori. This looks as follows. First, the
key-generating party generates a public-private keypair and shares the public
key with the other participants. Now, every player pregenerates the amount of
randomness needed for her part of the protocol and stores it in a file. For
example, this can be done overnight or during the weekend. When the main
protocol is executed, every player uses the same scheme (public key) as
communicated before, configures the scheme to use the pregenerated randomness
from file, and runs the main protocol without the need to generate randomness
for encryption at that time. A minimal example is provided below.
```py
from itertools import count
from pathlib import Path
from tno.mpc.encryption_schemes.templates.random_sources import FileSource
from tno.mpc.encryption_schemes.templates.randomized_encryption_scheme import (
RandomizedEncryptionScheme,
)
counter = count()
class MyRandomizedEncryptionScheme(RandomizedEncryptionScheme):
@staticmethod
def _generate_randomness() -> int:
"""Dummy randomness generator + preprocessing."""
return next(counter)
# --- empty definitions for all abstract methods ---
@classmethod
def from_security_parameter(cls, *args, **kwargs):
pass
@classmethod
def generate_key_material(cls, *args, **kwargs):
pass
@classmethod
def id_from_arguments(cls, *args, **kwargs):
pass
def encode(self, plaintext):
pass
def decode(self, encoded_plaintext):
pass
def _unsafe_encrypt_raw(self, plaintext):
pass
def _decrypt_raw(self, ciphertext):
pass
def __eq__(self, *args, **kwargs):
pass
def pregenerate_randomness_in_weekend(amount: int, path: Path):
# Initialize scheme, usually with parameters
generating_scheme = MyRandomizedEncryptionScheme()
# Generate randomness with two processes
generating_scheme.boot_randomness_generation(amount, max_workers=2)
# Save randomness to comma-separated csv
with open(path, "w") as file:
for _ in range(amount):
file.write(f"{generating_scheme.get_randomness()},")
# Shut down scheme to gracefully close source
generating_scheme.shut_down()
def use_pregenerated_randomness(amount: int, path: Path):
# Initialize scheme WITH THE SAME PARAMETERS!
consuming_scheme = MyRandomizedEncryptionScheme()
# Configure file as randomness source
consuming_scheme.register_randomness_source(FileSource(path))
# Consume randomness from file
for _ in range(amount):
print(consuming_scheme.get_randomness())
# Shut down scheme to gracefully close source
consuming_scheme.shut_down()
if __name__ == "__main__":
AMOUNT = 24
FILE_PATH = Path("randomness.csv")
pregenerate_randomness_in_weekend(AMOUNT, FILE_PATH)
use_pregenerated_randomness(AMOUNT, FILE_PATH)
# result (possibly not in this order): 0 0 1 1 2 2 3 3 4 4 5 5 6 6 7 7 8 8 9 9 10 10 11 11
```
Raw data
{
"_id": null,
"home_page": "",
"name": "tno.mpc.encryption-schemes.templates",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "TNO MPC Lab <mpclab@tno.nl>",
"keywords": "TNO,MPC,multi-party computation,encryption schemes,templates",
"author": "",
"author_email": "TNO MPC Lab <mpclab@tno.nl>",
"download_url": "https://files.pythonhosted.org/packages/cd/3f/4c7831773edd2b263fe77913a1148f343f6116e4e8afc8a876022d102672/tno.mpc.encryption_schemes.templates-4.1.2.tar.gz",
"platform": "any",
"description": "# TNO MPC Lab - Encryption Schemes - Templates\n\nThe TNO MPC lab consists of generic software components, procedures, and\nfunctionalities developed and maintained on a regular basis to facilitate and\naid in the development of MPC solutions. The lab is a cross-project initiative\nallowing us to integrate and reuse previously developed MPC functionalities to\nboost the development of new protocols and solutions.\n\nThe package tno.mpc.encryption_schemes.templates is part of the TNO Python\nToolbox.\n\nGeneric frameworks for encryption schemes. Currently includes support for:\n\n- Generic encryption scheme (encryption_scheme.py);\n- Asymmetric encryption scheme (asymmetric_encryption_scheme.py);\n- Symmetric encryption scheme (symmetric_encryption_scheme.py);\n- Support for precomputation of randomness (randomized_encryption_scheme.py).\n\n_Limitations in (end-)use: the content of this software package may solely be\nused for applications that comply with international export control laws._ \n_This implementation of cryptographic software has not been audited. Use at your\nown risk._\n\n## Documentation\n\nDocumentation of the tno.mpc.encryption_schemes.templates package can be found\n[here](https://docs.mpc.tno.nl/encryption_schemes/templates/4.1.2).\n\n## Install\n\nEasily install the tno.mpc.encryption_schemes.templates package using pip:\n\n```console\n$ python -m pip install tno.mpc.encryption_schemes.templates\n```\n\n### Note:\n\nA significant performance improvement can be achieved by installing the GMPY2\nlibrary.\n\n```console\n$ python -m pip install 'tno.mpc.encryption_schemes.templates[gmpy]'\n```\n\nIf you wish to run the tests you can use:\n\n```console\n$ python -m pip install 'tno.mpc.encryption_schemes.templates[tests]'\n```\n\n## Generating prepared randomness for RandomizedEncryptionSchemes\n\nIn the encryption process, `RandomizedEncryptionScheme`s require a random\nnumber. A typical encryption process generates a large random number, processes\nit in a way that is specific for (the private key of) the encryption scheme, and\nused the prepared random value to encrypt a plaintext message. A similarly\nprepared random value is required to rerandomize a ciphertext. This process of\ngenerating and preparing randomness consumes a lot of time and processing power.\n\nFortunately, the randomness depends only on the encryption scheme and not on the\nmessage that is to be encrypted. This makes it possible to prepare randomness a\npriori. Our library facilitates this process by the concept of \"randomness\nsources\". Three specific sources are shipped with the library, but you may\ndefine your own `RandomnessSource` by implementing the\n`tno.mpc.encryption_schemes.templates._randomness_manager.RandomnessSource`\nprotocol. The default sources are:\n\n- `ContextlessSource`, which yields randomness from a source that does not need\n to be opened or closed (e.g. a list, tuple, function-call, ...).\n- `FileSource`, which creates a thread to read a file, store the values in RAM\n and yield values on request.\n- `ProcessSource`, which creates one or more processes that all perform function\n calls to store a predefined number of return values in RAM and yield on\n request.\n\nA `RandomizedEncryptionScheme` is configured with a `ContextlessSource` that\ncalls its generating function. However, it is often more efficient to start\ngenerating a known amount of randomness earlier in the program execution. For\nthis, one may call `RandomizedEncryptionScheme.boot_generation` which internally\ninitializes and starts a `ProcessSource`, or requests an existing source to\ngenerate more randomness (see also below). Other sources can be configured\nthrough `RandomizedEncryptionScheme.register_randomness_source`.\n\n### Storing randomness for later use\n\nNaturally, a maximum speed-up during runtime of your main protocol is achieved\nby generating random values a priori. This looks as follows. First, the\nkey-generating party generates a public-private keypair and shares the public\nkey with the other participants. Now, every player pregenerates the amount of\nrandomness needed for her part of the protocol and stores it in a file. For\nexample, this can be done overnight or during the weekend. When the main\nprotocol is executed, every player uses the same scheme (public key) as\ncommunicated before, configures the scheme to use the pregenerated randomness\nfrom file, and runs the main protocol without the need to generate randomness\nfor encryption at that time. A minimal example is provided below.\n\n```py\nfrom itertools import count\nfrom pathlib import Path\n\nfrom tno.mpc.encryption_schemes.templates.random_sources import FileSource\nfrom tno.mpc.encryption_schemes.templates.randomized_encryption_scheme import (\n RandomizedEncryptionScheme,\n)\n\ncounter = count()\n\n\nclass MyRandomizedEncryptionScheme(RandomizedEncryptionScheme):\n @staticmethod\n def _generate_randomness() -> int:\n \"\"\"Dummy randomness generator + preprocessing.\"\"\"\n return next(counter)\n\n # --- empty definitions for all abstract methods ---\n @classmethod\n def from_security_parameter(cls, *args, **kwargs):\n pass\n\n @classmethod\n def generate_key_material(cls, *args, **kwargs):\n pass\n\n @classmethod\n def id_from_arguments(cls, *args, **kwargs):\n pass\n\n def encode(self, plaintext):\n pass\n\n def decode(self, encoded_plaintext):\n pass\n\n def _unsafe_encrypt_raw(self, plaintext):\n pass\n\n def _decrypt_raw(self, ciphertext):\n pass\n\n def __eq__(self, *args, **kwargs):\n pass\n\n\ndef pregenerate_randomness_in_weekend(amount: int, path: Path):\n # Initialize scheme, usually with parameters\n generating_scheme = MyRandomizedEncryptionScheme()\n # Generate randomness with two processes\n generating_scheme.boot_randomness_generation(amount, max_workers=2)\n # Save randomness to comma-separated csv\n with open(path, \"w\") as file:\n for _ in range(amount):\n file.write(f\"{generating_scheme.get_randomness()},\")\n # Shut down scheme to gracefully close source\n generating_scheme.shut_down()\n\ndef use_pregenerated_randomness(amount: int, path: Path):\n # Initialize scheme WITH THE SAME PARAMETERS!\n consuming_scheme = MyRandomizedEncryptionScheme()\n # Configure file as randomness source\n consuming_scheme.register_randomness_source(FileSource(path))\n # Consume randomness from file\n for _ in range(amount):\n print(consuming_scheme.get_randomness())\n # Shut down scheme to gracefully close source\n consuming_scheme.shut_down()\n\n\nif __name__ == \"__main__\":\n AMOUNT = 24\n FILE_PATH = Path(\"randomness.csv\")\n\n pregenerate_randomness_in_weekend(AMOUNT, FILE_PATH)\n use_pregenerated_randomness(AMOUNT, FILE_PATH)\n # result (possibly not in this order): 0 0 1 1 2 2 3 3 4 4 5 5 6 6 7 7 8 8 9 9 10 10 11 11\n```\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Generic templates for different types of Encryption Schemes",
"version": "4.1.2",
"project_urls": {
"Documentation": "https://docs.mpc.tno.nl/encryption_schemes/templates/4.1.2",
"Homepage": "https://mpc.tno.nl/",
"Source": "https://github.com/TNO-MPC/encryption_schemes.templates"
},
"split_keywords": [
"tno",
"mpc",
"multi-party computation",
"encryption schemes",
"templates"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31c7809da55a2869a01377b58bbcf328352b635f86041a69d79a9d8ee59e7c21",
"md5": "8c3e6090bd2f4153d07f6ae2fac16965",
"sha256": "a127030fac4de3f0767b2fba11cf495490a3aee70a0f487d95b9aa854adbf048"
},
"downloads": -1,
"filename": "tno.mpc.encryption_schemes.templates-4.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c3e6090bd2f4153d07f6ae2fac16965",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 43917,
"upload_time": "2023-06-05T09:22:54",
"upload_time_iso_8601": "2023-06-05T09:22:54.101864Z",
"url": "https://files.pythonhosted.org/packages/31/c7/809da55a2869a01377b58bbcf328352b635f86041a69d79a9d8ee59e7c21/tno.mpc.encryption_schemes.templates-4.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cd3f4c7831773edd2b263fe77913a1148f343f6116e4e8afc8a876022d102672",
"md5": "87a0313badac8ae447428afc9853fcd6",
"sha256": "ac2dd406aa11704dd3b8ead90fbb33052fbfca287d0711e05f481215806b7c0b"
},
"downloads": -1,
"filename": "tno.mpc.encryption_schemes.templates-4.1.2.tar.gz",
"has_sig": false,
"md5_digest": "87a0313badac8ae447428afc9853fcd6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 36133,
"upload_time": "2023-06-05T09:22:55",
"upload_time_iso_8601": "2023-06-05T09:22:55.887103Z",
"url": "https://files.pythonhosted.org/packages/cd/3f/4c7831773edd2b263fe77913a1148f343f6116e4e8afc8a876022d102672/tno.mpc.encryption_schemes.templates-4.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-05 09:22:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TNO-MPC",
"github_project": "encryption_schemes.templates",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tno.mpc.encryption-schemes.templates"
}
JSON
