Skip to content
NuCypher's reference implementation of Umbral (threshold proxy re-encryption) using OpenSSL and
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Bump version: 0.1.3-alpha.0 → 0.1.3-alpha.1 Feb 22, 2019
tests Remove copyright notice from individual files Feb 22, 2019
umbral Bump version: 0.1.3-alpha.0 → 0.1.3-alpha.1 Feb 22, 2019
.bumpversion.cfg Bump version: 0.1.3-alpha.0 → 0.1.3-alpha.1 Feb 22, 2019
.gitignore Add Code of Conduct and Contribution Guide Feb 17, 2019
CONTRIBUTING.rst Add GPLv3 license, this software is Free as in Freedom. Mar 21, 2018
Pipfile.lock Set sphinx_rtd_theme in the docs Feb 20, 2019
README.rst Bump version: 0.1.3-alpha.0 → 0.1.3-alpha.1 Feb 22, 2019
mypy.ini Remove copyright notice from individual files Feb 22, 2019



PyPI Package latest release CircleCI build status Commits since latest release Documentation Status Discord

pyUmbral is the reference implementation of the Umbral threshold proxy re-encryption scheme. It is open-source, built with Python, and uses OpenSSL and

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.


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.

from umbral import pre, keys, signing

# Generate Umbral keys for Alice.
alices_private_key = keys.UmbralPrivateKey.gen_key()
alices_public_key = alices_private_key.get_pubkey()

alices_signing_key = keys.UmbralPrivateKey.gen_key()
alices_verifying_key = alices_signing_key.get_pubkey()
alices_signer = signing.Signer(private_key=alices_signing_key)

# Generate Umbral keys for Bob.
bobs_private_key = keys.UmbralPrivateKey.gen_key()
bobs_public_key = bobs_private_key.get_pubkey()


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.

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

# Decrypt data with Alice's private key.
cleartext = pre.decrypt(ciphertext=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.

# Alice generates "M of N" re-encryption key fragments (or "KFrags") for Bob.
# In this example, 10 out of 20.
kfrags = pre.generate_kfrags(delegating_privkey=alices_private_key,


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.

# Several Ursulas perform re-encryption, and Bob collects the resulting `cfrags`.
# He must gather at least `threshold` `cfrags` in order to activate the capsule.


cfrags = list()           # Bob's cfrag collection
for kfrag in kfrags[:10]:
  cfrag = pre.reencrypt(kfrag=kfrag, capsule=capsule)
  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.

# Bob activates and opens the capsule
for cfrag in cfrags:

bob_cleartext = pre.decrypt(ciphertext=ciphertext,
assert bob_cleartext == plaintext

See more detailed usage examples in the docs directory.

Quick Installation

To install pyUmbral, simply use pip:

$ 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:

$ 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:

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.

Support & Contribute


If you identify vulnerabilities with _any_ nucypher code, please email 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 and we will coordinate a communication channel that we're both comfortable with.

You can’t perform that action at this time.