Welcome to umbral-pre’s documentation!

This package contains the Python bindings for the main library written in Rust. It implements the Umbral proxy reencryption scheme.

Usage example

import umbral_pre

# 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.

# Key Generation (on Alice's side)
alice_sk = umbral_pre.SecretKey.random()
alice_pk = alice_sk.public_key()
signing_sk = umbral_pre.SecretKey.random()
signer = umbral_pre.Signer(signing_sk)
verifying_pk = signing_sk.public_key()

# Key Generation (on Bob's side)
bob_sk = umbral_pre.SecretKey.random()
bob_pk = bob_sk.public_key()

# Now let's encrypt data with Alice's public key.
# Invocation of `encrypt()` returns both the ciphertext
# and the encapsulated symmetric key use to encrypt it.
# Note that anyone with Alice's public key
# can perform this operation.

plaintext = b"peace at dawn"
capsule, ciphertext = umbral_pre.encrypt(alice_pk, plaintext)

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

plaintext_alice = umbral_pre.decrypt_original(
    alice_sk, capsule, ciphertext);
assert plaintext_alice == plaintext

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

n = 3 # how many fragments to create
m = 2 # how many should be enough to decrypt

# Split Re-Encryption Key Generation (aka Delegation)
verified_kfrags = umbral_pre.generate_kfrags(
    alice_sk, bob_pk, signer, m, n,
    True, # add the delegating key (alice_pk) to the signature
    True, # add the receiving key (bob_pk) to the signature
)

# 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, thus obtaining
# a "capsule fragment", or cfrag.

# Bob collects the resulting cfrags from several Ursulas.
# Bob must gather at least `m` cfrags
# in order to open the capsule.

# Simulate network transfer
kfrag0 = KeyFrag.from_bytes(bytes(verified_kfrags[0]))
kfrag1 = KeyFrag.from_bytes(bytes(verified_kfrags[1]))

# Ursulas must check that the received kfrags
# are valid and perform the reencryption.

# Ursula 0
verified_kfrag0 = kfrag0.verify(verifying_pk, alice_pk, bob_pk)
verified_cfrag0 = umbral_pre.reencrypt(capsule, kfrags[0])

# Ursula 1
verified_kfrag1 = kfrag1.verify(verifying_pk, alice_pk, bob_pk)
verified_cfrag1 = umbral_pre.reencrypt(capsule, kfrags[1])

# ...

# Simulate network transfer
cfrag0 = CapsuleFrag.from_bytes(bytes(verified_cfrag0))
cfrag1 = CapsuleFrag.from_bytes(bytes(verified_cfrag1))

# Finally, Bob opens the capsule by using at least `m` cfrags,
# and then decrypts the re-encrypted ciphertext.

# Bob must check that cfrags are valid
verified_cfrag0 = cfrag0.verify(capsule, verifying_pk, alice_pk, bob_pk)
verified_cfrag1 = cfrag1.verify(capsule, verifying_pk, alice_pk, bob_pk)

# Decryption by Bob
plaintext_bob = umbral_pre.decrypt_reencrypted(
    bob_sk, alice_pk, capsule, [verified_cfrag0, verified_cfrag1], ciphertext)
assert plaintext_bob == plaintext

API reference

class umbral_pre.SecretKey

An umbral-pre secret key object.

static random() → SecretKey

Generates a new secret key.

public_key() → PublicKey

Returns a public key corresponding to this secret key.

__bytes__() → bytes

Serializes the object into a bytestring.

static from_bytes(data: bytes) → SecretKey

Restores the object from a bytestring.

static serialized_size() → int

Returns the size in bytes of the serialized representation of this object.

class umbral_pre.SecretKeyFactory

A deterministic generator of SecretKey objects.

static random() → SecretKeyFactory

Generates a new random factory.

secret_key_by_label(label: bytes) → SecretKeyFactory

Generates a new SecretKey using label as a seed.

__bytes__() → bytes

Serializes the object into a bytestring.

static from_bytes(data: bytes) → SecretKey

Restores the object from a bytestring.

static serialized_size() → int

Returns the size in bytes of the serialized representation of this object.

class umbral_pre.PublicKey

An umbral-pre public key object.

__bytes__() → bytes

Serializes the object into a bytestring.

static from_bytes(data: bytes) → PublicKey

Restores the object from a bytestring.

static serialized_size() → int

Returns the size in bytes of the serialized representation of this object.

__hash__() → int

Returns a hash of self.

class umbral_pre.Signer(secret_key: SecretKey)

An object possessing the capability to create signatures. For safety reasons serialization is prohibited.

sign(message: bytes) → Signature

Hashes and signs the message.

verifying_key() → PublicKey

Returns the public verification key corresponding to the secret key used for signing.

class umbral_pre.Signature

Wrapper for ECDSA signatures.

verify(verifying_key: PublicKey, message: bytes) → bool

Returns True if the message was signed by someone possessing the secret counterpart to verifying_key.

__bytes__() → bytes

Serializes the object into a bytestring.

static from_bytes(data: bytes) → Signature

Restores the object from a bytestring.

static serialized_size() → int

Returns the size in bytes of the serialized representation of this object.

class umbral_pre.Capsule

An encapsulated symmetric key.

__bytes__() → bytes

Serializes the object into a bytestring.

static from_bytes(data: bytes) → Capsule

Restores the object from a bytestring.

__bytes__() → bytes

Serializes the object into a bytestring.

static from_bytes(data: bytes) → Capsule

Restores the object from a bytestring.

static serialized_size() → int

Returns the size in bytes of the serialized representation of this object.

__hash__() → int

Returns a hash of self.

umbral_pre.encrypt(delegating_pk: PublicKey, plaintext: bytes) → Tuple[Capsule, bytes]

Creates a symmetric key, encrypts plaintext with it, and returns the encapsulated symmetric key along with the ciphertext. delegating_pk is the public key of the delegator.

umbral_pre.decrypt_original(delegating_sk: SecretKey, capsule: Capsule, ciphertext: bytes) → bytes

Decrypts ciphertext with the secret key of the delegator.

umbral_pre.generate_kfrags(delegating_sk: SecretKey, receiving_pk: PublicKey, signer: Signer, threshold: int, num_kfrags: int, sign_delegating_key: bool, sign_receiving_key: bool) → List[VerifiedKeyFrag]

Generates num_kfrags key fragments that can be used to reencrypt the capsule for the holder of the secret key corresponding to receiving_pk. threshold fragments will be enough for decryption.

If sign_delegating_key or sign_receiving_key are True, include these keys in the signature allowing proxies to verify the fragments were created with a given key or for a given key, respectively.

umbral_pre.reencrypt(capsule: Capsule, kfrag: VerifiedKeyFrag) → VerifiedCapsuleFrag

Reencrypts a capsule using a key fragment.

umbral_pre.decrypt_reencrypted(receiving_sk: SecretKey, delegating_pk: PublicKey, capsule: Capsule, cfrags: Sequence[VerifiedCapsuleFrag], ciphertext: bytes) → Optional[bytes]

Attempts to decrypt the plaintext using the original capsule and reencrypted capsule fragments (at least threshold of them, see generate_kfrags()).

class umbral_pre.KeyFrag

A fragment of a public key used by proxies during reencryption.

verify(verifying_pk: PublicKey, delegating_pk: Optional[PublicKey], receiving_pk: Optional[PublicKey]) → VerifiedKeyFrag:

Verifies the integrity of the fragment using the signing key and, optionally, the delegating and the receiving keys (if they were included in the signature in generate_kfrags()).

__bytes__() → bytes

Serializes the object into a bytestring.

static from_bytes(data: bytes) → KeyFrag

Restores the object from a bytestring.

static serialized_size() → int

Returns the size in bytes of the serialized representation of this object.

__hash__() → int

Returns a hash of self.

class umbral_pre.VerifiedKeyFrag

A verified key fragment, good for reencryption.

from_verified_bytes(data: bytes) → VerifiedKeyFrag

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.

__bytes__() → bytes

Serializes the object into a bytestring.

static serialized_size() → int

Returns the size in bytes of the serialized representation of this object.

class umbral_pre.CapsuleFrag

A reencrypted fragment of an encapsulated symmetric key.

verify(capsule: Capsule, verifying_pk: PublicKey, delegating_pk: PublicKey, receiving_pk: PublicKey) → VerifiedCapsuleFrag

Verifies the integrity of the fragment.

__bytes__() → bytes

Serializes the object into a bytestring.

static from_bytes(data: bytes) → CapsuleFrag

Restores the object from a bytestring.

static serialized_size() → int

Returns the size in bytes of the serialized representation of this object.

__hash__() → int

Returns a hash of self.

class umbral_pre.VerifiedCapsuleFrag

A verified capsule fragment, good for decryption.

__bytes__() → bytes

Serializes the object into a bytestring.

static serialized_size() → int

Returns the size in bytes of the serialized representation of this object.

Indices and tables