commonware-cryptography 2026.9.0

//! Timelock Encryption (TLE) over BLS12-381.
//!
//! This crate implements Timelock Encryption (TLE) over BLS12-381 using
//! Identity-Based Encryption (IBE) with the Boneh-Franklin scheme. TLE enables
//! encrypting messages that can only be decrypted when a valid signature over
//! a specific target (e.g., timestamp or round number) becomes available.
//!
//! # Security
//!
//! To achieve CCA-security (resistance against chosen-ciphertext attacks), this
//! implementation employs the Fujisaki-Okamoto transform, which converts the
//! underlying CPA-secure IBE scheme into a CCA-secure scheme through:
//!
//! * Deriving encryption randomness deterministically from the message and a
//!   random value (sigma)
//! * Including integrity checks to detect ciphertext tampering
//!
//! # Architecture
//!
//! The encryption process involves (for [crate::bls12381::primitives::variant::MinPk]):
//! 1. Generating a random sigma value
//! 2. Deriving encryption randomness r = H3(sigma || message)
//! 3. Computing the ciphertext components:
//!    - U = r * G (commitment in G1)
//!    - V = sigma ⊕ H2(e(P_pub, Q_id)^r) (masked random value)
//!    - W = M ⊕ H4(sigma) (masked message)
//!
//! Where Q_id = H1(target) maps the target to a point in G2.
//!
//! # Example
//!
//! _It is recommended to use a threshold signature scheme to generate decrypting
//! signatures in production (where no single party owns the private key)._
//!
//! ```rust
//! use commonware_cryptography::bls12381::{
//!     tle::{encrypt, decrypt, Block},
//!     primitives::{
//!         ops::{keypair, sign_message},
//!         variant::MinPk,
//!     },
//! };
//! use commonware_utils::test_rng;
//!
//! let mut rng = test_rng();
//!
//! // Generate keypair
//! let (master_secret, master_public) = keypair::<_, MinPk>(&mut rng);
//!
//! // Define a target (e.g., a timestamp or round number)
//! let target = 12345u64.to_be_bytes();
//!
//! // Create a 32-byte message
//! let message_bytes = b"This is a secret message 32bytes";
//! let message = Block::new(*message_bytes);
//!
//! // Encrypt the message for the target
//! let ciphertext = encrypt::<_, MinPk>(
//!     &mut rng,
//!     master_public,
//!     (b"_TLE_", &target),
//!     &message,
//! )
//! .expect("encryption should succeed");
//!
//! // Later, when someone has a signature over the target...
//! let signature = sign_message::<MinPk>(&master_secret, b"_TLE_", &target);
//!
//! // They can decrypt the message
//! let decrypted = decrypt::<MinPk>(&signature, &ciphertext)
//!     .expect("Decryption should succeed with valid signature");
//!
//! assert_eq!(message.as_ref(), decrypted.as_ref());
//! ```
//!
//! # Acknowledgements
//!
//! The following resources were used as references when implementing this crate:
//!
//! * <https://crypto.stanford.edu/~dabo/papers/bfibe.pdf>: Identity-Based Encryption from the Weil Pairing
//! * <https://eprint.iacr.org/2023/189>: tlock: Practical Timelock Encryption from Threshold BLS
//! * <https://github.com/thibmeu/tlock-rs>: tlock-rs: Practical Timelock Encryption/Decryption in Rust
//! * <https://github.com/drand/tlock> tlock: Timelock Encryption/Decryption Made Practical

use crate::{
    bls12381::primitives::{
        group::{DST, GT, Scalar},
        ops::hash_with_namespace,
        variant::Variant,
    },
    sha256::Digest,
};
#[cfg(not(feature = "std"))]
use alloc::vec::Vec;
use bytes::{Buf, BufMut};
use commonware_codec::{EncodeSize, FixedSize, Read, ReadExt, Write};
use commonware_math::algebra::{Additive, CryptoGroup};
use commonware_utils::sequence::FixedBytes;
use rand_core::CryptoRng;
use thiserror::Error;
use zeroize::Zeroizing;

/// Domain separation tag for hashing the `h3` message to a scalar.
const DST: DST = b"TLE_BLS12381_XMD:SHA-256_SSWU_RO_H3_";

/// Block size for encryption operations.
const BLOCK_SIZE: usize = Digest::SIZE;

/// Block type for IBE.
pub type Block = FixedBytes<BLOCK_SIZE>;

/// Errors returned while encrypting a message.
#[derive(Debug, Error, PartialEq, Eq)]
pub enum Error {
    /// The master public key is the group identity.
    #[error("master public key is the group identity")]
    InvalidPublicKey,
}

impl From<Digest> for Block {
    fn from(digest: Digest) -> Self {
        Block::new(digest.0)
    }
}

/// Encrypted message.
#[derive(Hash, Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct Ciphertext<V: Variant> {
    /// First group element U = r * Public::generator().
    pub u: V::Public,
    /// Encrypted random value V = sigma XOR H2(e(P_pub, Q_id)^r).
    pub v: Block,
    /// Encrypted message W = M XOR H4(sigma).
    pub w: Block,
}

impl<V: Variant> Write for Ciphertext<V> {
    fn write(&self, buf: &mut impl BufMut) {
        self.u.write(buf);
        buf.put_slice(self.v.as_ref());
        buf.put_slice(self.w.as_ref());
    }
}

impl<V: Variant> Read for Ciphertext<V> {
    type Cfg = ();

    fn read_cfg(buf: &mut impl Buf, _: &()) -> Result<Self, commonware_codec::Error> {
        let u = V::Public::read(buf)?;
        let v = Block::read(buf)?;
        let w = Block::read(buf)?;
        Ok(Self { u, v, w })
    }
}

impl<V: Variant> EncodeSize for Ciphertext<V> {
    fn encode_size(&self) -> usize {
        self.u.encode_size() + self.v.encode_size() + self.w.encode_size()
    }
}

#[cfg(feature = "arbitrary")]
impl<V: Variant> arbitrary::Arbitrary<'_> for Ciphertext<V>
where
    V::Public: for<'a> arbitrary::Arbitrary<'a>,
{
    fn arbitrary(u: &mut arbitrary::Unstructured<'_>) -> arbitrary::Result<Self> {
        let ge = u.arbitrary()?;
        let v = FixedBytes::new(<[u8; BLOCK_SIZE]>::arbitrary(u)?);
        let w = FixedBytes::new(<[u8; BLOCK_SIZE]>::arbitrary(u)?);
        Ok(Self { u: ge, v, w })
    }
}

/// Hash functions for IBE.
mod hash {
    use super::*;
    use crate::{Hasher, Sha256};

    /// H2: GT -> Block
    ///
    /// Used to mask the random sigma value.
    pub fn h2(gt: &GT) -> Block {
        let gt = Zeroizing::new(gt.as_slice());
        Sha256::hash(&[b"h2", gt.as_ref()]).into()
    }

    /// H3: (sigma, M) -> Scalar
    ///
    /// Used to derive the random scalar r using RFC9380 hash-to-field.
    pub fn h3(sigma: &Block, message: &[u8]) -> Scalar {
        // Combine sigma and message
        let mut combined = Zeroizing::new(Vec::with_capacity(sigma.len() + message.len()));
        combined.extend_from_slice(sigma.as_ref());
        combined.extend_from_slice(message);

        // Map the combined bytes to a scalar via RFC9380 hash-to-field.
        Scalar::map(DST, &combined)
    }

    /// H4: sigma -> Block
    ///
    /// Used to mask the message.
    pub fn h4(sigma: &Block) -> Block {
        Sha256::hash(&[b"h4", sigma.as_ref()]).into()
    }
}

/// XOR two [Block]s together.
#[inline]
fn xor(a: &Block, b: &Block) -> Block {
    let a = a.as_ref();
    let b = b.as_ref();
    Block::new(core::array::from_fn(|i| a[i] ^ b[i]))
}

/// Encrypt a message for a given target.
///
/// # Steps
/// 1. Generate random sigma
/// 2. Derive encryption randomness r = H3(sigma || message)
/// 3. Create commitment U = r * G
/// 4. Mask sigma with the pairing result
/// 5. Mask the message with H4(sigma)
///
/// # Arguments
/// * `rng` - Random number generator
/// * `public` - Master public key
/// * `target` - Tuple of (namespace, payload) over which a signature will decrypt the message
/// * `message` - Message to encrypt
///
/// # Returns
/// * `Result<Ciphertext<V>, Error>` - The encrypted ciphertext, or an encryption error
pub fn encrypt<R: CryptoRng, V: Variant>(
    rng: &mut R,
    public: V::Public,
    target: (&[u8], &[u8]),
    message: &Block,
) -> Result<Ciphertext<V>, Error> {
    // An identity master key makes the pairing mask independent of the secret key.
    if public == V::Public::zero() {
        return Err(Error::InvalidPublicKey);
    }

    // Hash target to get Q_id in signature group using the variant's message DST
    let (namespace, target) = target;
    let q_id = hash_with_namespace::<V>(V::MESSAGE, namespace, target);

    // Generate random sigma
    let mut sigma_array = Zeroizing::new([0u8; BLOCK_SIZE]);
    rng.fill_bytes(sigma_array.as_mut());
    let sigma = Zeroizing::new(Block::new(*sigma_array));

    // Derive scalar r from sigma and message
    let r = hash::h3(&sigma, message.as_ref());

    // Compute U = r * Public::generator()
    let mut u = V::Public::generator();
    u *= &r;

    // Compute e(P_pub, Q_id)^r = e(r * P_pub, Q_id).
    //
    // The latter expression is more efficient to compute.
    let mut r_pub = public;
    r_pub *= &r;
    let gt = V::pairing(&r_pub, &q_id);

    // Compute V = sigma XOR H2(e(P_pub, Q_id)^r)
    let h2_value = Zeroizing::new(hash::h2(&gt));
    let v = xor(&sigma, &h2_value);

    // Compute W = M XOR H4(sigma)
    let h4_value = Zeroizing::new(hash::h4(&sigma));
    let w = xor(message, &h4_value);

    Ok(Ciphertext { u, v, w })
}

/// Decrypt a ciphertext with a signature over the target specified
/// during [encrypt].
///
/// # Steps
/// 1. Recover sigma from the pairing
/// 2. Recover the message
/// 3. Recompute r = H3(sigma || message)
/// 4. Verify that U = r * G matches the ciphertext
///
/// # Arguments
/// * `signature` - Signature over the target payload
/// * `ciphertext` - Ciphertext to decrypt
///
/// # Returns
/// * `Option<Block>` - The decrypted message
pub fn decrypt<V: Variant>(signature: &V::Signature, ciphertext: &Ciphertext<V>) -> Option<Block> {
    // An identity signature collapses the pairing to a public constant and bypasses target binding.
    if signature == &V::Signature::zero() {
        return None;
    }

    // Compute e(U, signature)
    let gt = V::pairing(&ciphertext.u, signature);

    // Recover sigma = V XOR H2(e(U, signature))
    let h2_value = hash::h2(&gt);
    let sigma = xor(&ciphertext.v, &h2_value);

    // Recover M = W XOR H4(sigma)
    let h4_value = hash::h4(&sigma);
    let message = xor(&ciphertext.w, &h4_value);

    // Recompute r and verify U = r * Public::generator()
    let r = hash::h3(&sigma, &message);
    let mut expected_u = V::Public::generator();
    expected_u *= &r;
    if ciphertext.u != expected_u {
        return None;
    }

    Some(message)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::bls12381::primitives::{
        ops,
        variant::{MinPk, MinSig},
    };
    use commonware_math::algebra::Random as _;
    use commonware_utils::test_rng;

    fn identity_signature_cannot_decrypt<V: Variant>() {
        let sigma = Block::new([1; BLOCK_SIZE]);
        let message = Block::new([2; BLOCK_SIZE]);
        let r = hash::h3(&sigma, message.as_ref());

        let mut u = V::Public::generator();
        u *= &r;
        let identity_pairing = V::pairing(&V::Public::zero(), &V::Signature::generator());
        let ciphertext = Ciphertext {
            u,
            v: xor(&sigma, &hash::h2(&identity_pairing)),
            w: xor(&message, &hash::h4(&sigma)),
        };

        assert!(decrypt::<V>(&V::Signature::zero(), &ciphertext).is_none());
    }

    #[test]
    fn test_identity_signature_cannot_decrypt() {
        identity_signature_cannot_decrypt::<MinPk>();
        identity_signature_cannot_decrypt::<MinSig>();
    }

    fn identity_public_key_cannot_encrypt<V: Variant>() {
        let result = encrypt::<_, V>(
            &mut test_rng(),
            V::Public::zero(),
            (b"test", b"target"),
            &Block::new([0; BLOCK_SIZE]),
        );
        assert_eq!(result, Err(Error::InvalidPublicKey));
    }

    #[test]
    fn test_identity_public_key_cannot_encrypt() {
        identity_public_key_cannot_encrypt::<MinPk>();
        identity_public_key_cannot_encrypt::<MinSig>();
    }

    #[test]
    fn test_encrypt_decrypt_minpk() {
        let mut rng = test_rng();

        // Generate master keypair
        let (master_secret, master_public) = ops::keypair::<_, MinPk>(&mut rng);

        // Target and message
        let target = 10u64.to_be_bytes();
        let message = b"Hello, IBE! This is exactly 32b!"; // 32 bytes

        // Generate signature over the target
        let signature = ops::sign_message::<MinPk>(&master_secret, b"_TLE_", &target);

        // Encrypt
        let ciphertext = encrypt::<_, MinPk>(
            &mut rng,
            master_public,
            (b"_TLE_", &target),
            &Block::new(*message),
        )
        .expect("encryption should succeed");

        // Decrypt
        let decrypted =
            decrypt::<MinPk>(&signature, &ciphertext).expect("Decryption should succeed");

        assert_eq!(message.as_ref(), decrypted.as_ref());
    }

    #[test]
    fn test_encrypt_decrypt_minsig() {
        let mut rng = test_rng();

        // Generate master ops::keypair
        let (master_secret, master_public) = ops::keypair::<_, MinSig>(&mut rng);

        // Target and message
        let target = 20u64.to_be_bytes();
        let message = b"Testing MinSig variant - 32 byte";

        // Generate signature over the target
        let signature = ops::sign_message::<MinSig>(&master_secret, b"_TLE_", &target);

        // Encrypt
        let ciphertext = encrypt::<_, MinSig>(
            &mut rng,
            master_public,
            (b"_TLE_", &target),
            &Block::new(*message),
        )
        .expect("encryption should succeed");

        // Decrypt
        let decrypted =
            decrypt::<MinSig>(&signature, &ciphertext).expect("Decryption should succeed");

        assert_eq!(message.as_ref(), decrypted.as_ref());
    }

    #[test]
    fn test_wrong_private_key() {
        let mut rng = test_rng();

        // Generate two different master ops::keypairs
        let (_, master_public1) = ops::keypair::<_, MinPk>(&mut rng);
        let (master_secret2, _) = ops::keypair::<_, MinPk>(&mut rng);

        let target = 30u64.to_be_bytes();
        let message = b"Secret message padded to 32bytes";

        // Encrypt with first master public key
        let ciphertext = encrypt::<_, MinPk>(
            &mut rng,
            master_public1,
            (b"_TLE_", &target),
            &Block::new(*message),
        )
        .expect("encryption should succeed");

        // Try to decrypt with signature from second master
        let wrong_signature = ops::sign_message::<MinPk>(&master_secret2, b"_TLE_", &target);
        let result = decrypt::<MinPk>(&wrong_signature, &ciphertext);

        assert!(result.is_none());
    }

    #[test]
    fn test_tampered_ciphertext() {
        let mut rng = test_rng();

        let (master_secret, master_public) = ops::keypair::<_, MinPk>(&mut rng);
        let target = 40u64.to_be_bytes();
        let message = b"Tamper test padded to 32 bytes.."; // 32 bytes

        // Generate signature over the target
        let signature = ops::sign_message::<MinPk>(&master_secret, b"_TLE_", &target);

        // Encrypt
        let ciphertext = encrypt::<_, MinPk>(
            &mut rng,
            master_public,
            (b"_TLE_", &target),
            &Block::new(*message),
        )
        .expect("encryption should succeed");

        // Tamper with ciphertext by creating a modified w
        let mut w_bytes = [0u8; BLOCK_SIZE];
        w_bytes.copy_from_slice(ciphertext.w.as_ref());
        w_bytes[0] ^= 0xFF;
        let tampered_ciphertext = Ciphertext {
            u: ciphertext.u,
            v: ciphertext.v,
            w: Block::new(w_bytes),
        };

        // Try to decrypt
        let result = decrypt::<MinPk>(&signature, &tampered_ciphertext);
        assert!(result.is_none());
    }

    #[test]
    fn test_encrypt_decrypt_with_namespace() {
        let mut rng = test_rng();

        // Generate master ops::keypair
        let (master_secret, master_public) = ops::keypair::<_, MinPk>(&mut rng);

        // Target and namespace
        let namespace = b"example.org";
        let target = 80u64.to_be_bytes();
        let message = b"Message with namespace - 32 byte"; // 32 bytes

        // Generate signature over the namespaced target
        let signature = ops::sign_message::<MinPk>(&master_secret, namespace, &target);

        // Encrypt with namespace
        let ciphertext = encrypt::<_, MinPk>(
            &mut rng,
            master_public,
            (namespace, &target),
            &Block::new(*message),
        )
        .expect("encryption should succeed");

        // Decrypt
        let decrypted =
            decrypt::<MinPk>(&signature, &ciphertext).expect("Decryption should succeed");

        assert_eq!(message.as_ref(), decrypted.as_ref());
    }

    #[test]
    fn test_namespace_variance() {
        let mut rng = test_rng();

        // Generate master ops::keypair
        let (master_secret, master_public) = ops::keypair::<_, MinPk>(&mut rng);

        let namespace1 = b"example.org";
        let namespace2 = b"other.org";
        let target = 100u64.to_be_bytes();
        let message = b"Namespace vs no namespace - 32by"; // 32 bytes

        // Generate signature with namespace1
        let signature_ns1 = ops::sign_message::<MinPk>(&master_secret, namespace1, &target);

        // Generate signature with namespace2
        let signature_ns2 = ops::sign_message::<MinPk>(&master_secret, namespace2, &target);

        // Encrypt with namespace1
        let ciphertext_ns1 = encrypt::<_, MinPk>(
            &mut rng,
            master_public,
            (namespace1, &target),
            &Block::new(*message),
        )
        .expect("encryption should succeed");

        // Encrypt with namespace2
        let ciphertext_ns2 = encrypt::<_, MinPk>(
            &mut rng,
            master_public,
            (namespace2, &target),
            &Block::new(*message),
        )
        .expect("encryption should succeed");

        // Try to decrypt namespace1 ciphertext with namespace2 signature - should fail
        let result1 = decrypt::<MinPk>(&signature_ns2, &ciphertext_ns1);
        assert!(result1.is_none());

        // Try to decrypt namespace2 ciphertext with namespace1 signature - should fail
        let result2 = decrypt::<MinPk>(&signature_ns1, &ciphertext_ns2);
        assert!(result2.is_none());

        // Correct decryptions should succeed
        let decrypted_ns1 = decrypt::<MinPk>(&signature_ns1, &ciphertext_ns1)
            .expect("Decryption with matching namespace should succeed");
        let decrypted_ns2 = decrypt::<MinPk>(&signature_ns2, &ciphertext_ns2)
            .expect("Decryption with matching namespace should succeed");

        assert_eq!(message.as_ref(), decrypted_ns1.as_ref());
        assert_eq!(message.as_ref(), decrypted_ns2.as_ref());
    }

    #[test]
    fn test_cca_modified_v() {
        let mut rng = test_rng();

        let (master_secret, master_public) = ops::keypair::<_, MinPk>(&mut rng);
        let target = 110u64.to_be_bytes();
        let message = b"Another CCA test message 32bytes"; // 32 bytes

        // Generate signature over the target
        let signature = ops::sign_message::<MinPk>(&master_secret, b"_TLE_", &target);

        // Encrypt
        let ciphertext = encrypt::<_, MinPk>(
            &mut rng,
            master_public,
            (b"_TLE_", &target),
            &Block::new(*message),
        )
        .expect("encryption should succeed");

        // Modify V component (encrypted sigma)
        let mut v_bytes = [0u8; BLOCK_SIZE];
        v_bytes.copy_from_slice(ciphertext.v.as_ref());
        v_bytes[0] ^= 0x01;
        let tampered_ciphertext = Ciphertext {
            u: ciphertext.u,
            v: Block::new(v_bytes),
            w: ciphertext.w,
        };

        // Try to decrypt - should fail due to verification
        let result = decrypt::<MinPk>(&signature, &tampered_ciphertext);
        assert!(result.is_none());
    }

    #[test]
    fn test_cca_modified_u() {
        let mut rng = test_rng();

        let (master_secret, master_public) = ops::keypair::<_, MinPk>(&mut rng);
        let target = 70u64.to_be_bytes();
        let message = b"CCA security test message 32 byt"; // 32 bytes

        // Generate signature over the target
        let signature = ops::sign_message::<MinPk>(&master_secret, b"_TLE_", &target);

        // Encrypt
        let mut ciphertext = encrypt::<_, MinPk>(
            &mut rng,
            master_public,
            (b"_TLE_", &target),
            &Block::new(*message),
        )
        .expect("encryption should succeed");

        // Modify U component (this should make decryption fail due to FO transform)
        let mut modified_u = ciphertext.u;
        modified_u *= &Scalar::random(&mut rng);
        ciphertext.u = modified_u;

        // Try to decrypt - should fail
        let result = decrypt::<MinPk>(&signature, &ciphertext);
        assert!(result.is_none());
    }

    #[cfg(feature = "arbitrary")]
    mod conformance {
        use super::*;
        use commonware_codec::conformance::CodecConformance;

        commonware_conformance::conformance_tests! {
            CodecConformance<Ciphertext<MinPk>>,
        }
    }
}