pyUmbral¶
pyUmbral is the reference implementation of the Umbral threshold proxy re-encryption scheme. It is open-source, built with Python, and uses OpenSSL via Cryptography.io, and libsodium via PyNaCl.
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¶
Build from source code¶
pyUmbral is maintained on GitHub: https://github.com/nucypher/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¶
Elliptic Curves¶
The matter of which curve to use is the subject of some debate. If you aren’t sure, you might start here: https://safecurves.cr.yp.to/
A number of curves are available in the Cryptography.io library, on which pyUmbral depends.
You can find them in the cryptography.hazmat.primitives.asymmetric.ec
module.
Important
Be careful when choosing a curve - the security of your application depends on it.
We provide curve SECP256K1
as a default because it is the basis for a number of crypto-blockchain projects;
we don’t otherwise endorse its security.
We additionally support curves SECP256R1
(also known as “NIST P-256”) and SECP384R1
(“NIST P-384”), but they cannot currently be selected via the public API.
Encryption¶
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 SecretKey, Signer
>>> alices_secret_key = SecretKey.random()
>>> alices_public_key = alices_secret_key.public_key()
>>> alices_signing_key = SecretKey.random()
>>> alices_verifying_key = alices_signing_key.public_key()
>>> alices_signer = Signer(alices_signing_key)
Encrypt with a public key¶
Now let’s encrypt data with Alice’s public key.
Invocation of umbral.encrypt()
returns both a capsule
and a ciphertext
.
Note that anyone with Alice’s public key can perform this operation.
>>> from umbral import encrypt
>>> plaintext = b'Proxy Re-encryption is cool!'
>>> capsule, ciphertext = 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.
>>> from umbral import decrypt_original
>>> cleartext = decrypt_original(alices_secret_key, capsule, ciphertext)
Threshold Re-Encryption¶
Bob Exists¶
>>> bobs_secret_key = SecretKey.random()
>>> bobs_public_key = bobs_secret_key.public_key()
Alice grants access to Bob by generating kfrags¶
When Alice wants to grant Bob access to view her encrypted data, she creates re-encryption key fragments, or “kfrags”, which are next sent to N proxies or Ursulas.
Alice must specify shares
(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.
>>> from umbral import generate_kfrags
>>> kfrags = generate_kfrags(delegating_sk=alices_secret_key,
... receiving_pk=bobs_public_key,
... signer=alices_signer,
... threshold=10,
... shares=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 = decrypt_original(delegating_sk=bobs_secret_key,
... capsule=capsule,
... ciphertext=ciphertext)
Traceback (most recent call last):
...
ValueError
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.
Bob collects the resulting cfrags from several Ursulas.
Bob must gather at least threshold
cfrags in order to open the capsule.
>>> import random
>>> kfrags = random.sample(kfrags, # All kfrags from above
... 10) # M - Threshold
>>> from umbral import reencrypt
>>> cfrags = list() # Bob's cfrag collection
>>> for kfrag in kfrags:
... cfrag = reencrypt(capsule=capsule, kfrag=kfrag)
... cfrags.append(cfrag) # Bob collects a cfrag
Decryption¶
Bob checks the capsule fragments¶
If Bob received the capsule fragments in serialized form, he can verify that they are valid and really originate from Alice, using Alice’s public keys.
>>> from umbral import CapsuleFrag
>>> suspicious_cfrags = [CapsuleFrag.from_bytes(bytes(cfrag)) for cfrag in cfrags]
>>> cfrags = [cfrag.verify(capsule,
... verifying_pk=alices_verifying_key,
... delegating_pk=alices_public_key,
... receiving_pk=bobs_public_key,
... )
... for cfrag in suspicious_cfrags]
Bob opens the capsule¶
Finally, Bob decrypts the re-encrypted ciphertext using his key.
>>> from umbral import decrypt_reencrypted
>>> cleartext = decrypt_reencrypted(receiving_sk=bobs_secret_key,
... delegating_pk=alices_public_key,
... capsule=capsule,
... verified_cfrags=cfrags,
... ciphertext=ciphertext)
Public API¶
Keys¶
-
class
umbral.
SecretKey
[source]¶ Bases:
umbral.serializable.SerializableSecret
,umbral.serializable.Deserializable
Umbral secret (private) key.
-
class
umbral.
PublicKey
[source]¶ Bases:
umbral.serializable.Serializable
,umbral.serializable.Deserializable
Umbral public key.
Created using
SecretKey.public_key()
.
-
class
umbral.
SecretKeyFactory
[source]¶ Bases:
umbral.serializable.SerializableSecret
,umbral.serializable.Deserializable
This class handles keyring material for Umbral, by allowing deterministic derivation of
SecretKey
objects based on labels.Don’t use this key material directly as a key.
-
classmethod
from_secure_randomness
(seed: bytes) → umbral.keys.SecretKeyFactory[source]¶ Creates a secret key factory using the given random bytes (of size
seed_size()
).Warning
Make sure the given seed has been obtained from a cryptographically secure source of randomness!
-
make_factory
(label: bytes) → umbral.keys.SecretKeyFactory[source]¶ Creates a
SecretKeyFactory
deterministically from the given label.
-
make_key
(label: bytes) → umbral.keys.SecretKey[source]¶ Creates a
SecretKey
deterministically from the given label.
-
classmethod
seed_size
()[source]¶ Returns the seed size required by
from_secure_randomness()
.
-
classmethod
-
class
umbral.
Signer
(secret_key: umbral.keys.SecretKey)[source]¶ An object possessing the capability to create signatures. For safety reasons serialization is prohibited.
-
class
umbral.
Signature
[source]¶ Bases:
umbral.serializable.Serializable
,umbral.serializable.Deserializable
Wrapper for ECDSA signatures.
Intermediate objects¶
-
class
umbral.
Capsule
[source]¶ Bases:
umbral.serializable.Serializable
,umbral.serializable.Deserializable
Encapsulated symmetric key.
-
class
umbral.
KeyFrag
[source]¶ Bases:
umbral.serializable.Serializable
,umbral.serializable.Deserializable
A signed fragment of the delegating key.
-
verify
(verifying_pk: umbral.keys.PublicKey, delegating_pk: Optional[umbral.keys.PublicKey] = None, receiving_pk: Optional[umbral.keys.PublicKey] = None) → umbral.key_frag.VerifiedKeyFrag[source]¶ Verifies the validity of this fragment.
If the delegating and/or receiving key were not signed in
generate_kfrags()
, but are given to this function, they are ignored.
-
-
class
umbral.
VerifiedKeyFrag
[source]¶ Bases:
umbral.serializable.Serializable
Verified kfrag, good for reencryption. Can be cast to
bytes
, but cannot be deserialized from bytes directly. It can only be obtained fromKeyFrag.verify()
.-
classmethod
from_verified_bytes
(data) → umbral.key_frag.VerifiedKeyFrag[source]¶ Restores a verified keyfrag directly from serialized bytes, skipping
KeyFrag.verify()
call.Intended for internal storage; make sure that the bytes come from a trusted source.
-
classmethod
-
class
umbral.
CapsuleFrag
[source]¶ Bases:
umbral.serializable.Serializable
,umbral.serializable.Deserializable
Re-encrypted fragment of
Capsule
.
-
class
umbral.
VerifiedCapsuleFrag
[source]¶ Bases:
umbral.serializable.Serializable
Verified capsule frag, good for decryption. Can be cast to
bytes
, but cannot be deserialized from bytes directly. It can only be obtained fromCapsuleFrag.verify()
.-
classmethod
from_verified_bytes
(data) → umbral.capsule_frag.VerifiedCapsuleFrag[source]¶ Restores a verified capsule frag directly from serialized bytes, skipping
CapsuleFrag.verify()
call.Intended for internal storage; make sure that the bytes come from a trusted source.
-
classmethod
Encryption, re-encryption and decryption¶
-
umbral.
encrypt
(delegating_pk: umbral.keys.PublicKey, plaintext: bytes) → Tuple[umbral.capsule.Capsule, bytes][source]¶ Generates and encapsulates a symmetric key and uses it to encrypt the given plaintext.
Returns the KEM Capsule and the ciphertext.
-
umbral.
decrypt_original
(delegating_sk: umbral.keys.SecretKey, capsule: umbral.capsule.Capsule, ciphertext: bytes) → bytes[source]¶ Opens the capsule using the delegator’s key used for encryption and gets what’s inside. We hope that’s a symmetric key, which we use to decrypt the ciphertext and return the resulting cleartext.
-
umbral.
generate_kfrags
(delegating_sk: umbral.keys.SecretKey, receiving_pk: umbral.keys.PublicKey, signer: umbral.signing.Signer, threshold: int, shares: int, sign_delegating_key: bool = True, sign_receiving_key: bool = True) → List[umbral.key_frag.VerifiedKeyFrag][source]¶ Generates
shares
key fragments to pass to proxies for re-encryption. At leastthreshold
of them will be needed for decryption. Ifsign_delegating_key
orsign_receiving_key
areTrue
, the corresponding keys will have to be provided toKeyFrag.verify()
.
-
umbral.
reencrypt
(capsule: umbral.capsule.Capsule, kfrag: umbral.key_frag.VerifiedKeyFrag) → umbral.capsule_frag.VerifiedCapsuleFrag[source]¶ Creates a capsule fragment using the given key fragment. Capsule fragments can later be used to decrypt the ciphertext.
-
umbral.
decrypt_reencrypted
(receiving_sk: umbral.keys.SecretKey, delegating_pk: umbral.keys.PublicKey, capsule: umbral.capsule.Capsule, verified_cfrags: Sequence[umbral.capsule_frag.VerifiedCapsuleFrag], ciphertext: bytes) → bytes[source]¶ Decrypts the ciphertext using the original capsule and the reencrypted capsule fragments.
Utilities¶
-
class
umbral.
VerificationError
[source]¶ Bases:
Exception
Integrity of the data cannot be verified, see the message for details.
-
class
umbral.serializable.
HasSerializedSize
[source]¶ A base serialization mixin, denoting a type with a constant-size serialized representation.
-
class
umbral.serializable.
Serializable
[source]¶ Bases:
umbral.serializable.HasSerializedSize
A mixin for composable serialization.
-
class
umbral.serializable.
SerializableSecret
[source]¶ Bases:
umbral.serializable.HasSerializedSize
A mixin for composable serialization of objects containing secret data.
-
class
umbral.serializable.
Deserializable
[source]¶ Bases:
umbral.serializable.HasSerializedSize
A mixin for composable deserialization.
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
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 security@nucypher.com 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 security@nucypher.com and we will coordinate a communication channel that we’re both comfortable with.