NuCypher's reference implementation of Umbral (threshold proxy re-encryption) using OpenSSL and Cryptography.io

nucypher, updated 🕥 2022-12-09 05:18:10

.. role:: bash(code) :language: bash

========= pyUmbral =========

.. start-badges

.. |docs| image:: https://readthedocs.org/projects/pyumbral/badge/?style=flat :target: https://readthedocs.org/projects/pyumbral :alt: Documentation Status

.. |discord| image:: https://img.shields.io/discord/411401661714792449.svg?logo=discord :target: https://discord.gg/xYqyEby :alt: Discord

.. |circleci| image:: https://img.shields.io/circleci/project/github/nucypher/pyUmbral.svg?logo=circleci :target: https://circleci.com/gh/nucypher/pyUmbral/tree/master :alt: CircleCI build status

.. |version| image:: https://img.shields.io/pypi/v/umbral.svg :alt: PyPI Package latest release :target: https://pypi.org/project/umbral

.. |commits-since| image:: https://img.shields.io/github/commits-since/nucypher/pyumbral/v0.3.0.svg :alt: Commits since latest release :target: https://github.com/nucypher/pyUmbral/compare/v0.3.0...master

.. end-badges

pyUmbral is the reference implementation of the Umbral_ threshold proxy re-encryption scheme. It is open-source, built with Python, and uses OpenSSL_ and Cryptography.io_.

Using Umbral, Alice (the data owner) can delegate decryption rights to Bob for any ciphertext intended to her, through a re-encryption process performed by a set of semi-trusted proxies or Ursulas. When a threshold of these proxies participate by performing re-encryption, Bob is able to combine these independent re-encryptions and decrypt the original message using his private key.

.. image:: docs/source/.static/umbral.svg :width: 400 px :align: center

pyUmbral is the cryptographic engine behind nucypher_, a proxy re-encryption network to empower privacy in decentralized systems.

.. _Umbral: https://github.com/nucypher/umbral-doc/blob/master/umbral-doc.pdf .. _Cryptography.io: https://cryptography.io/en/latest/ .. _OpenSSL: https://www.openssl.org/ .. _nucypher: https://github.com/nucypher/nucypher

Usage

Key Generation

As in any public-key cryptosystem, users need a pair of public and private keys. Additionally, users that delegate access to their data (like Alice, in this example) need a signing keypair.

.. code-block:: python

from umbral import SecretKey, Signer

# Generate Umbral keys for Alice.
alices_secret_key = SecretKey.random()
alices_public_key = alices_secret_key.public_key()

alices_signing_key = SecretKey.random()
alices_signer = Signer(alices_signing_key)
alices_verifying_key = alices_signing_key.public_key()

# Generate Umbral keys for Bob.
bobs_secret_key = SecretKey.random()
bobs_public_key = bobs_secret_key.public_key()

Encryption

Now let's encrypt data with Alice's public key. Invocation of pre.encrypt returns both the ciphertext and a capsule. Note that anyone with Alice's public key can perform this operation.

Since data was encrypted with Alice's public key, Alice can open the capsule and decrypt the ciphertext with her private key.

.. code-block:: python

from umbral import encrypt, decrypt_original

# Encrypt data with Alice's public key.
plaintext = b'Proxy Re-Encryption is cool!'
capsule, ciphertext = encrypt(alices_public_key, plaintext)

# Decrypt data with Alice's private key.
cleartext = decrypt_original(alices_secret_key, capsule, ciphertext)

Re-Encryption Key Fragments

When Alice wants to grant Bob access to open her encrypted messages, she creates re-encryption key fragments, or "kfrags", which are next sent to N proxies or Ursulas.

.. code-block:: python

from umbral import generate_kfrags

# Alice generates "M of N" re-encryption key fragments (or "KFrags") for Bob.
# In this example, 10 out of 20.
kfrags = generate_kfrags(delegating_sk=alices_secret_key,
                         receiving_pk=bobs_public_key,
                         signer=alices_signer,
                         threshold=10,
                         shares=20)

Re-Encryption

Bob asks several Ursulas to re-encrypt the capsule so he can open it. Each Ursula performs re-encryption on the capsule using the kfrag provided by Alice, obtaining this way a "capsule fragment", or cfrag.

Bob collects the resulting cfrags from several Ursulas. Bob must gather at least threshold cfrags in order to activate the capsule.

.. code-block:: python

from umbral import reencrypt

# Several Ursulas perform re-encryption, and Bob collects the resulting `cfrags`.
cfrags = list()           # Bob's cfrag collection
for kfrag in kfrags[:10]:
    cfrag = pre.reencrypt(capsule=capsule, kfrag=kfrag)
    cfrags.append(cfrag)    # Bob collects a cfrag

Decryption by Bob

Finally, Bob activates the capsule by attaching at least threshold cfrags, and then decrypts the re-encrypted ciphertext.

.. code-block:: python

from umbral import decrypt_reencrypted

bob_cleartext = pre.decrypt_reencrypted(receiving_sk=bobs_secret_key,
                                        delegating_pk=alices_public_key,
                                        capsule=capsule,
                                        cfrags=cfrags,
                                        ciphertext=ciphertext)
assert bob_cleartext == plaintext

See more detailed usage examples in the docs_ directory.

.. _docs : https://github.com/nucypher/pyUmbral/tree/master/docs

Quick Installation

To install pyUmbral, simply use pip:

.. code-block:: bash

$ pip3 install umbral

Alternatively, you can checkout the repo and install it from there. The NuCypher team uses pipenv for managing pyUmbral's dependencies. The recommended installation procedure is as follows:

.. code-block:: bash

$ sudo pip3 install pipenv
$ pipenv install

Post-installation, you can activate the project virtual environment in your current terminal session by running pipenv shell.

For more information on pipenv, find the official documentation here: https://docs.pipenv.org/.

Academic Whitepaper

The Umbral scheme academic whitepaper and cryptographic specifications are available on GitHub_.

"Umbral: A Threshold Proxy Re-Encryption Scheme" by David Nuñez. https://github.com/nucypher/umbral-doc/blob/master/umbral-doc.pdf

.. _GitHub: https://github.com/nucypher/umbral-doc/

Support & Contribute

Issue Tracker: https://github.com/nucypher/pyUmbral/issues
Source Code: https://github.com/nucypher/pyUmbral

Security

If you identify vulnerabilities with any nucypher code, please email [email protected] with relevant information to your findings. We will work with researchers to coordinate vulnerability disclosure between our partners and users to ensure successful mitigation of vulnerabilities.

Throughout the reporting process, we expect researchers to honor an embargo period that may vary depending on the severity of the disclosure. This ensures that we have the opportunity to fix any issues, identify further issues (if any), and inform our users.

Sometimes vulnerabilities are of a more sensitive nature and require extra precautions. We are happy to work together to use a more secure medium, such as Signal. Email [email protected] and we will coordinate a communication channel that we're both comfortable with.

Issues

Bump certifi from 2021.5.30 to 2022.12.7

opened on 2022-12-09 05:18:10 by dependabot[bot]

Bumps certifi from 2021.5.30 to 2022.12.7.

Commits

9e9e840 2022.12.07
b81bdb2 2022.09.24
939a28f 2022.09.14
aca828a 2022.06.15.2
de0eae1 Only use importlib.resources's new files() / Traversable API on Python ≥3.11 ...
b8eb5e9 2022.06.15.1
47fb7ab Fix deprecation warning on Python 3.11 (#199)
b0b48e0 fixes #198 -- update link in license
9d514b4 2022.06.15
4151e88 Add py.typed to MANIFEST.in to package in sdist (#196)
Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) - `@dependabot use these labels` will set the current labels as the default for future PRs for this repo and language - `@dependabot use these reviewers` will set the current reviewers as the default for future PRs for this repo and language - `@dependabot use these assignees` will set the current assignees as the default for future PRs for this repo and language - `@dependabot use this milestone` will set the current milestone as the default for future PRs for this repo and language You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/nucypher/pyUmbral/network/alerts).

Bump ipython from 7.24.1 to 7.31.1

opened on 2022-01-21 18:59:17 by dependabot[bot]

Bumps ipython from 7.24.1 to 7.31.1.

Commits

e321e76 release 7.31.1
67ca2b3 Merge pull request from GHSA-pq7m-3gw7-gq5x
2794330 back to dev
be343e7 release 7.31.0
0fcf2c4 Merge pull request #13428 from meeseeksmachine/auto-backport-of-pr-13427-on-7.x
b8db9b1 Backport PR #13427: wn 731
7f253dc Merge pull request #13412 from bnavigator/backport-inspect
4f26796 fix xxlimited_35 import name
77ca4a6 don't run nose-based iptest on py310, only pytest
533e509 back to decorator skip
Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options

Why there is no correctness_keys in result=capsule.to_bytes()

opened on 2020-05-30 00:48:31 by Himan000

For capsule, when in Re-Encryption,

``` capsule.set_correctness_keys(delegating=alices_public_key, receiving=bobs_public_key, verifying=alices_verifying_key)

cfrags = list()
for kfrag in kfrags[:10]: cfrag = pre.reencrypt(kfrag=kfrag, capsule=capsule) cfrags.append(cfrag) ```

if serialize capsule to file using,

save_file(capsule_path, capsule.to_bytes())

no correctness_keys serialize to bytes,

def to_bytes(self) -> bytes: e, v, s = self.components() return e.to_bytes() + v.to_bytes() + s.to_bytes()

but Decryption by Bob need correctness_keys.

``` for cfrag in cfrags: capsule.attach_cfrag(cfrag)

bob_cleartext = pre.decrypt(ciphertext=ciphertext, capsule=capsule, decrypting_key=bobs_private_key) assert bob_cleartext == plaintext

```

my code is,

``` def re_encryption(a_public_key_path, verifying_key_path, capsule_path, k_frags_path, b_public_key_path, target_path="data"): a_public_key = UmbralPublicKey.from_bytes(load_file(a_public_key_path)) capsule = Capsule.from_bytes(load_file(capsule_path), a_public_key.params) b_public_key = UmbralPublicKey.from_bytes(load_file(b_public_key_path)) verifying_key = UmbralPublicKey.from_bytes(load_file(verifying_key_path)) k_frags = KFrag.from_bytes(load_file(k_frags_path)) k_frags_list = [k_frags] capsule.set_correctness_keys(delegating=a_public_key, receiving=b_public_key, verifying=verifying_key)

c_frags = list()
for rk_frag in k_frags_list:
    c_frag = pre.reencrypt(kfrag=rk_frag, capsule=capsule)
    c_frags.append(c_frag)

alice = os.path.basename(a_public_key_path)
if alice.endswith(".pub"):
    alice = alice[0:alice.index(".pub")]
bob = os.path.basename(b_public_key_path)
if bob.endswith(".pub"):
    bob = bob[0:bob.index(".pub")]

save_file(os.path.join(target_path, "c_frags_" + alice + "2" + bob), c_frags[0].to_bytes())
save_file(capsule_path, capsule.to_bytes())

def re_decryption(c_frags_path, cipher_text_path, capsule_path, b_private_key_path, target_path="data"): c_frags = CapsuleFrag.from_bytes(load_file(c_frags_path)) c_frags_list = [c_frags] b_private_key = UmbralPrivateKey.from_bytes(load_file(b_private_key_path)) cipher_text = load_file(cipher_text_path) capsule = Capsule.from_bytes(load_file(capsule_path), b_private_key.params)

for c_frag in c_frags_list:
    capsule.attach_cfrag(c_frag)

b_plaintext = pre.decrypt(ciphertext=cipher_text,
                          capsule=capsule,
                          decrypting_key=b_private_key)
file_name = get_file_name(cipher_text_path)
if file_name.endswith(".ct"):
    file_name = file_name[0:file_name.index(".ct")]
save_file(os.path.join(target_path, file_name), b_plaintext)

if name == 'main': gen_keys("alice", target_path="keys/alice", is_gen_sig=True) gen_keys("bob", target_path="keys/bob", is_gen_sig=False) encrypt("keys/alice/alice.pub", "keys/alice/m.txt", "keys/alice") decrypt("keys/alice/m.txt.ct", "keys/alice/m.txt.csl", "keys/alice/alice.key") gen_rk("keys/alice/alice.key", "keys/alice/alice.sig", "keys/bob/bob.pub", "keys/alice") re_encryption("keys/alice/alice.pub", "keys/alice/alice.vrf", "keys/alice/m.txt.csl", "keys/alice/k_frags_alice2bob", "keys/bob/bob.pub", "keys/alice") re_decryption("keys/alice/c_frags_alice2bob", "keys/alice/m.txt.ct", "keys/alice/m.txt.csl", "keys/bob/bob.key", "keys/bob")

```

So, how to serialize capsule with correctness_keys to bytes? Thanks.

possible documentation typo error

opened on 2020-04-04 08:03:20 by hallazzang

https://github.com/nucypher/pyUmbral/blob/2ef43a6df5a47d29d2902e1416553a05d1e6b7d9/umbral/pre.py#L216-L230

The documentation says "Creates a re-encryption key from Alice's delegating public key...", shouldn't it be "Creates a re-encryption key from Alice's delegating private key..."?

Optimize reencryption_benchmark

opened on 2019-02-15 12:15:05 by cygnusv

Currently, the reencryption_benchmark task in the CircleCI build takes most of the build time. Find a way to have a good metric for reencryption time without wasting so much time.

Add umbral version to test vectors

opened on 2018-12-12 21:53:38 by cygnusv None

NuCypher

GitHub Repository Homepage