Package: umbral
pyUmbral is the reference implementation of theUmbralthreshold proxy re-encryption scheme.
It is open-source, built with Python, and usesOpenSSLandCryptography.io.Using Umbral, Alice (the data owner) candelegate decryption rightsto Bob for
any ciphertext intended to her, through a re-encryption process performed by a
set of semi-trusted proxies orUrsulas. 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 behindnucypher,
a proxy re-encryption network to empower privacy in decentralized systems.UsageKey GenerationAs 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.fromumbralimportSecretKey,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()EncryptionNow let’s encrypt data with Alice’s public key.
Invocation ofpre.encryptreturns both theciphertextand acapsule.
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.fromumbralimportencrypt,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 FragmentsWhen Alice wants to grant Bob access to open her encrypted messages,
she createsre-encryption key fragments, or“kfrags”,
which are next sent to N proxies orUrsulas.fromumbralimportgenerate_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-EncryptionBob asks several Ursulas to re-encrypt the capsule so he can open it.
Each Ursula performs re-encryption on the capsule using thekfragprovided by Alice, obtaining this way a “capsule fragment”, orcfrag.Bob collects the resulting cfrags from several Ursulas.
Bob must gather at leastthresholdcfrags in order to activate the capsule.fromumbralimportreencrypt# Several Ursulas perform re-encryption, and Bob collects the resulting `cfrags`.cfrags=list()# Bob's cfrag collectionforkfraginkfrags[:10]:cfrag=pre.reencrypt(capsule=capsule,kfrag=kfrag)cfrags.append(cfrag)# Bob collects a cfragDecryption by BobFinally, Bob activates the capsule by attaching at leastthresholdcfrags,
and then decrypts the re-encrypted ciphertext.fromumbralimportdecrypt_reencryptedbob_cleartext=pre.decrypt_reencrypted(receiving_sk=bobs_secret_key,delegating_pk=alices_public_key,capsule=capsule,cfrags=cfrags,ciphertext=ciphertext)assertbob_cleartext==plaintextSee more detailed usage examples in thedocsdirectory.Quick InstallationTo install pyUmbral, simply usepip:$pip3installumbralAlternatively, you can checkout the repo and install it from there.
The NuCypher team usespipenvfor managing pyUmbral’s dependencies.
The recommended installation procedure is as follows:$sudopip3installpipenv$pipenvinstallPost-installation, you can activate the project virtual environment
in your current terminal session by runningpipenv shell.For more information onpipenv, find the official documentation here:https://docs.pipenv.org/.Academic WhitepaperThe Umbral scheme academic whitepaper and cryptographic specifications
are available onGitHub.“Umbral: A Threshold Proxy Re-Encryption Scheme”by David Nuñez.https://github.com/nucypher/umbral-doc/blob/master/umbral-doc.pdfSupport & ContributeIssue Tracker:https://github.com/nucypher/pyUmbral/issuesSource Code:https://github.com/nucypher/pyUmbralSecurityIf you identify vulnerabilities with _any_ nucypher code,
please emailsecurity@nucypher.comwith 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.
Emailsecurity@nucypher.comand we will coordinate a communication channel that we’re both comfortable with.