Crate umbral_pre

source ·
Expand description

umbral-pre is the Rust implementation of the Umbral threshold proxy re-encryption scheme.

Using umbral-pre, 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.

Available feature flags

  • default-rng - adds methods that use the system RNG (default).
  • default-serialization - adds methods for default binary serialization that matches the serialization in the bindings. MessagePack, serde-based.
  • serde-support - implements serde-based serialization and deserialization.
  • bindings-python - adds a bindings_python submodule allowing dependent crates to use and re-export some of the Python-wrapped Umbral types.
  • bindings-wasm - adds a bindings_wasm submodule allowing dependent crates to use and re-export some of the WASM-wrapped Umbral types.

Usage

use 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)
let alice_sk = SecretKey::random();
let alice_pk = alice_sk.public_key();
let signer = Signer::new(SecretKey::random());
let verifying_pk = signer.verifying_key();

// Key Generation (on Bob's side)
let bob_sk = SecretKey::random();
let bob_pk = bob_sk.public_key();

// Now let's encrypt data with Alice's public key.
// Invocation of `encrypt()` returns both the ciphertext and a capsule.
// Note that anyone with Alice's public key can perform this operation.

let plaintext = b"peace at dawn";
let (capsule, ciphertext) = encrypt(&alice_pk, plaintext).unwrap();

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

let plaintext_alice = decrypt_original(&alice_sk, &capsule, &ciphertext).unwrap();
assert_eq!(&plaintext_alice as &[u8], 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 `shares` proxies or Ursulas.

let shares = 3; // how many fragments to create
let threshold = 2; // how many should be enough to decrypt
let verified_kfrags = generate_kfrags(&alice_sk, &bob_pk, &signer, threshold, shares, true, true);

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

// Simulate network transfer
let kfrag0 = verified_kfrags[0].clone().unverify();
let kfrag1 = verified_kfrags[1].clone().unverify();

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

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

// Ursula 0
let verified_kfrag0 = kfrag0.verify(&verifying_pk, Some(&alice_pk), Some(&bob_pk)).unwrap();
let verified_cfrag0 = reencrypt(&capsule, verified_kfrag0);

// Ursula 1
let verified_kfrag1 = kfrag1.verify(&verifying_pk, Some(&alice_pk), Some(&bob_pk)).unwrap();
let verified_cfrag1 = reencrypt(&capsule, verified_kfrag1);

// ...

// Simulate network transfer
let cfrag0 = verified_cfrag0.clone().unverify();
let cfrag1 = verified_cfrag1.clone().unverify();

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

// Bob must check that cfrags are valid
let verified_cfrag0 = cfrag0
    .verify(&capsule, &verifying_pk, &alice_pk, &bob_pk)
    .unwrap();
let verified_cfrag1 = cfrag1
    .verify(&capsule, &verifying_pk, &alice_pk, &bob_pk)
    .unwrap();

let plaintext_bob = decrypt_reencrypted(
    &bob_sk, &alice_pk, &capsule, [verified_cfrag0, verified_cfrag1], &ciphertext).unwrap();
assert_eq!(&plaintext_bob as &[u8], plaintext);

Modules

serde_bytesserde-support
Utility functions for efficient bytestring serialization with serde (by default they are serialized as vectors of integers).

Structs

Capsule
Encapsulated symmetric key used to encrypt the plaintext.
CapsuleFrag
A reencrypted fragment of a Capsule created by a proxy.
KeyFrag
A fragment of the encrypting party’s key used to create a CapsuleFrag.
PublicKey
A public key.
SecretBox
A container for secret data. Makes the usage of secret data explicit and easy to track, prevents the secret data from being put on stack, and zeroizes the contents on drop.
SecretKey
A secret key.
SecretKeyFactory
This class handles keyring material for Umbral, by allowing deterministic derivation of SecretKey objects based on labels.
Signature
ECDSA signature object.
Signer
An object used to sign messages. For security reasons cannot be serialized.
VerifiedCapsuleFrag
Verified capsule fragment, good for dencryption. Can be serialized, but cannot be deserialized directly. It can only be obtained from CapsuleFrag::verify or CapsuleFrag::skip_verification.
VerifiedKeyFrag
Verified key fragment, good for reencryption. Can be serialized, but cannot be deserialized directly. It can only be obtained from KeyFrag::verify or KeyFrag::skip_verification.

Enums

CapsuleFragVerificationError
Possible errors that can be returned by CapsuleFrag::verify.
DecryptionError
Errors that can happend during symmetric decryption.
EncryptionError
Errors that can happen during symmetric encryption.
KeyFragVerificationError
Possible errors that can be returned by KeyFrag::verify.
OpenReencryptedError
Errors that can happen when opening a Capsule using reencrypted CapsuleFrag objects.
ReencryptionError
Errors that can happen when decrypting a reencrypted ciphertext.

Traits

DefaultDeserializedefault-serialization
Default deserialization of an object that is used in all the bindings. Uses MessagePack format.
DefaultSerializedefault-serialization
Default serialization of an object that is used in all the bindings. Uses MessagePack format.

Functions

decrypt_original
Attempts to decrypt the ciphertext using the receiver’s secret key.
decrypt_reencrypted
Decrypts the ciphertext using previously reencrypted capsule fragments.
encryptdefault-rng
A synonym for encrypt with the default RNG.
encrypt_with_rng
Encrypts the given plaintext message using a DEM scheme, and encapsulates the key for later reencryption. Returns the KEM Capsule and the ciphertext.
generate_kfragsdefault-rng
A synonym for generate_kfrags_with_rng with the default RNG.
generate_kfrags_with_rng
Creates shares fragments of delegating_sk, which will be possible to reencrypt to allow the creator of receiving_pk decrypt the ciphertext encrypted with delegating_sk.
reencryptdefault-rng
A synonym for reencrypt_with_rng with the default RNG.
reencrypt_with_rng
Reencrypts a Capsule object with a key fragment, creating a capsule fragment.