Public API

Keys

class umbral.SecretKey

Bases: umbral.serializable.SerializableSecret, umbral.serializable.Deserializable

Umbral secret (private) key.

public_key() → umbral.keys.PublicKey

Returns the associated public key.

classmethod random() → umbral.keys.SecretKey

Generates a random secret key and returns it.

classmethod serialized_size()

Returns the size in bytes of the serialized representation of this object (obtained with bytes() or to_secret_bytes()).

to_secret_bytes() → bytes

Serializes the object into bytes. This bytestring is secret, handle with care!

class umbral.PublicKey

Bases: umbral.serializable.Serializable, umbral.serializable.Deserializable

Umbral public key.

Created using SecretKey.public_key().

__eq__(other)

Return self==value.

__hash__() → int

Return hash(self).

classmethod serialized_size()

Returns the size in bytes of the serialized representation of this object (obtained with bytes() or to_secret_bytes()).

class umbral.SecretKeyFactory

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

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

Creates a SecretKeyFactory deterministically from the given label.

make_key(label: bytes) → umbral.keys.SecretKey

Creates a SecretKey deterministically from the given label.

classmethod random() → umbral.keys.SecretKeyFactory

Creates a random factory.

classmethod seed_size()

Returns the seed size required by from_secure_randomness().

classmethod serialized_size()

Returns the size in bytes of the serialized representation of this object (obtained with bytes() or to_secret_bytes()).

to_secret_bytes() → bytes

Serializes the object into bytes. This bytestring is secret, handle with care!

class umbral.Signer(secret_key: umbral.keys.SecretKey)

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

sign(message: bytes) → umbral.signing.Signature

Hashes and signs the message.

verifying_key() → umbral.keys.PublicKey

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

class umbral.Signature

Bases: umbral.serializable.Serializable, umbral.serializable.Deserializable

Wrapper for ECDSA signatures.

__eq__(other)

Return self==value.

__hash__() → int

Return hash(self).

classmethod serialized_size()

Returns the size in bytes of the serialized representation of this object (obtained with bytes() or to_secret_bytes()).

verify(verifying_pk: umbral.keys.PublicKey, message: bytes) → bool

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

Intermediate objects

class umbral.Capsule

Bases: umbral.serializable.Serializable, umbral.serializable.Deserializable

Encapsulated symmetric key.

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

class umbral.KeyFrag

Bases: umbral.serializable.Serializable, umbral.serializable.Deserializable

A signed fragment of the delegating key.

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

verify(verifying_pk: umbral.keys.PublicKey, delegating_pk: Optional[umbral.keys.PublicKey] = None, receiving_pk: Optional[umbral.keys.PublicKey] = None) → umbral.key_frag.VerifiedKeyFrag

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

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 from KeyFrag.verify().

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

classmethod from_verified_bytes(data) → umbral.key_frag.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.

classmethod serialized_size()

Returns the size in bytes of the serialized representation of this object (obtained with bytes() or to_secret_bytes()).

class umbral.CapsuleFrag

Bases: umbral.serializable.Serializable, umbral.serializable.Deserializable

Re-encrypted fragment of Capsule.

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

classmethod serialized_size()

Returns the size in bytes of the serialized representation of this object (obtained with bytes() or to_secret_bytes()).

verify(capsule: umbral.capsule.Capsule, verifying_pk: umbral.keys.PublicKey, delegating_pk: umbral.keys.PublicKey, receiving_pk: umbral.keys.PublicKey) → umbral.capsule_frag.VerifiedCapsuleFrag

Verifies the validity of this fragment.

class umbral.VerifiedCapsuleFrag

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 from CapsuleFrag.verify().

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

classmethod from_verified_bytes(data) → umbral.capsule_frag.VerifiedCapsuleFrag

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 serialized_size()

Returns the size in bytes of the serialized representation of this object (obtained with bytes() or to_secret_bytes()).

Encryption, re-encryption and decryption

umbral.encrypt(delegating_pk: umbral.keys.PublicKey, plaintext: bytes) → Tuple[umbral.capsule.Capsule, bytes]

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

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]

Generates shares key fragments to pass to proxies for re-encryption. At least threshold of them will be needed for decryption. If sign_delegating_key or sign_receiving_key are True, the corresponding keys will have to be provided to KeyFrag.verify().

umbral.reencrypt(capsule: umbral.capsule.Capsule, kfrag: umbral.key_frag.VerifiedKeyFrag) → umbral.capsule_frag.VerifiedCapsuleFrag

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

Decrypts the ciphertext using the original capsule and the reencrypted capsule fragments.

Utilities

class umbral.VerificationError

Bases: Exception

Integrity of the data cannot be verified, see the message for details.

class umbral.serializable.HasSerializedSize

A base serialization mixin, denoting a type with a constant-size serialized representation.

classmethod serialized_size() → int

Returns the size in bytes of the serialized representation of this object (obtained with bytes() or to_secret_bytes()).

class umbral.serializable.Serializable

Bases: umbral.serializable.HasSerializedSize

A mixin for composable serialization.

__bytes__()

Serializes the object into bytes.

class umbral.serializable.SerializableSecret

Bases: umbral.serializable.HasSerializedSize

A mixin for composable serialization of objects containing secret data.

to_secret_bytes()

Serializes the object into bytes. This bytestring is secret, handle with care!

class umbral.serializable.Deserializable

Bases: umbral.serializable.HasSerializedSize

A mixin for composable deserialization.

classmethod from_bytes(data: bytes) → Self

Restores the object from serialized bytes.