6 min read - Posted 17 Apr 19

NuCypher - PyUmbral

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.

This article is adapted from the pyUmbral documentation

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.

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

Installing pyUmbral


Using pip

The easiest way to install pyUmbral is using pip: $ pip3 install umbral ###Build from source code

pyUmbral is maintained on GitHub: pyUmbral

Clone the repository to download the source code. $ git clone https://github.com/nucypher/pyUmbral.git Once you have acquired the source code, you can…

…embed pyUmbral modules into your own codebase… from umbral import pre, keys, config …install pyUmbral with pipenv… $ pipenv install . …or install it with python-pip… $ pip3 install . ###Install dependencies The NuCypher team uses pipenv for managing pyUmbral’s dependencies. The recommended installation procedure is as follows: $ sudo pip3 install pipenv $ pipenv install Post-installation, you can activate the pyUmbral’s virtual environment in your current terminal session by running pipenv shell.

If your installation is successful, the following command will succeed without error. $ pipenv run python >>> import umbral For more information on pipenv, The official documentation is located here: https://docs.pipenv.org/.

Development Installation

If you want to participate in developing pyUmbral, you’ll probably want to run the test suite and / or build the documentation, and for that, you must install some additional development requirements. $ pipenv install --dev --three To build the documentation locally: $ pipenv run make html --directory=docs

Using pyUmbral

article image


Setting the default curve

The best way to start using pyUmbral is to decide on an elliptic curve to use and set it as your default. >>> from umbral import config >>> from umbral.curve import SECP256K1 >>> config.set_default_curve(SECP256K1) For more information on curves, see Choosing and Using Curves.


Generate an Umbral key pair

First, let’s generate two asymmetric key pairs for Alice: A delegating key pair and a signing key pair. ``` >>> from umbral import keys, signing

alicesprivatekey = keys.UmbralPrivateKey.gen_key() alicespublickey = alicesprivatekey.get_pubkey()

alicessigningkey = keys.UmbralPrivateKey.gen_key() alicesverifyingkey = alicessigningkey.get_pubkey() alicessigner = signing.Signer(privatekey=alicessigningkey) ``` Encrypt with a public key

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. >>> from umbral import pre >>> plaintext = b'Proxy Re-encryption is cool!' >>> ciphertext, capsule = pre.encrypt(alices_public_key, plaintext) Decrypt with a private key

Since data was encrypted with Alice’s public key, Alice can open the capsule and decrypt the ciphertext with her private key. >>> cleartext = pre.decrypt(ciphertext=ciphertext, capsule=capsule, decrypting_key=alices_private_key)

Threshold Re-encryption

Bob Exists

>>> from umbral import keys
>>> bobs_private_key = keys.UmbralPrivateKey.gen_key()
>>> bobs_public_key = bobs_private_key.get_pubkey()

Alice grants access to Bob by generating kfrags

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.

Alice must specify N (the total number of kfrags), and a threshold (the minimum number of kfrags needed to activate a capsule). In the following example, Alice creates 20 kfrags, but Bob needs to get only 10 re-encryptions to activate the capsule. >>> kfrags = pre.generate_kfrags(delegating_privkey=alices_private_key, ... signer=alices_signer, ... receiving_pubkey=bobs_public_key, ... threshold=10, ... N=20)

Bob receives a capsule

Next, let’s generate a key pair for Bob, and pretend to send him the capsule through a side channel like S3, IPFS, Google Cloud, Sneakernet, etc. # Bob receives the capsule through a side-channel: IPFS, Sneakernet, etc. capsule = <fetch the capsule through a side-channel>

Bob fails to open the capsule

If Bob attempts to open a capsule that was not encrypted for his public key, or re-encrypted for him by Ursula, he will not be able to open it. >>> fail = pre.decrypt(ciphertext=ciphertext, ... capsule=capsule, ... decrypting_key=bobs_private_key) Traceback (most recent call last): ... cryptography.exceptions.InvalidTag Ursulas perform 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. Let’s mock a network or transport layer by sampling threshold random kfrags, one for each required Ursula. Note that each Ursula must prepare the received capsule before re-encryption by setting the proper correctness keys.

Bob collects the resulting cfrags from several Ursulas. Bob must gather at least threshold cfrags in order to activate the capsule. ``` >>> import random >>> kfrags = random.sample(kfrags, # All kfrags from above ... 10) # M - Threshold

capsule.setcorrectnesskeys(delegating=alicespublickey, ... receiving=bobspublickey, ... verifying=alicesverifyingkey) (True, True, True)

cfrags = list() # Bob's cfrag collection for kfrag in kfrags: ... cfrag = pre.reencrypt(kfrag=kfrag, capsule=capsule) ... cfrags.append(cfrag) # Bob collects a cfrag ``` Bob attaches cfrags to the capsule

Bob attaches at least threshold cfrags to the capsule, which has to be prepared in advance with the necessary correctness keys. Only then it can become activated. ``` >>> capsule.setcorrectnesskeys(delegating=alicespublickey, ... receiving=bobspublickey, ... verifying=alicesverifyingkey) (False, False, False)

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

Bob activates and opens the capsule

Finally, Bob decrypts the re-encrypted ciphertext using the activated capsule. >>> cleartext = pre.decrypt(ciphertext=ciphertext, capsule=capsule, decrypting_key=bobs_private_key)

Created with Sketch.Content is"CC-BY-SA 4.0" licensed
Article On-chain
Article Author

Kauri Team




Related Articles
Data Privacy with the NuCypher Network

The NuCypher network uses the Umbral threshold proxy re-encryption scheme to provide cryptographic access controls for distributed apps and protocols. This article is adapted from the NuCypher documentationOverview Alice, the data owner, grants access to her encrypted data to anyone she wants by creating a policy and uploading it to the NuCypher network. Using her policy’s public key, any entity can encrypt data on Alice’s behalf. This entity could be an IoT device in her car, a collaborator ass

Kauri Team

06 Jun 19

The Secure Bulletin Board System (SBBS) implementation in Beam

Beam is built on Mimblewimble protocol¹, a wonderful piece of technology that achieves confidentiality while significantly improving blockchain scalability. However, this comes with a significant caveat. In Mimblewimble there are no addresses, and transactions need to be built interactively by the participating parties. That poses a challenge: if Alice wants to send money to Bob, both their wallets have to connect and perform the necessary actions. Creating a direct socket connection every time