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.