reach_encryption/

public_key.rs

// SPDX-FileCopyrightText: 2023—2025 eaon <eaon@posteo.net>
// SPDX-License-Identifier: EUPL-1.2

//! Public key encryption using the X-Wing hybrid KEM, along with SIGMA-I-style
//! authenticated encryption.

use std::ops::Deref;

use chacha20poly1305::{KeyInit, XChaCha20Poly1305, XNonce, aead::Aead};
use ecdh_omr::{Blind, TakeTheHint};
use hmac::Mac;
use hmac::digest::{MacError, core_api::CoreWrapper};
use ml_kem::EncodedSizeUser;
use ml_kem::kem::{Decapsulate, Encapsulate};
use rand_core::CryptoRngCore;
use reach_signatures::{Sign, VerifyingKeys};
use sha3::{Digest, Sha3_256, Sha3_512, Sha3_512Core};
use zeroize::Zeroizing;

use reach_aliases::{
    BlindedPublicKey, Ed25519Signature, EnvelopeIdHint, EnvelopeIdHints, FnDsaSignature,
    MlKemCiphertext, MlKemPublic, MlKemSecret, X25519Public, X25519Secret, XChaChaKey,
};
use reach_core::{
    ParticipantPublicKeys, ProstDecode, ProstEncode, error,
    memory::{Credentials, HintedEnvelopeId, Key, MessageVaultPassport},
    wire::{CredentialVault, EnvelopeSeed, Salts, SealedEnvelopeId, SealedMessageVaultId},
};
use reach_signatures::{Digestible, Signatures, Verifier, verify_digest};

use crate::{Ciphertext, Decryptable, Encryptable, Nonce, aliases::*, decrypt};

/// Provides access to both elliptic curve and post-quantum secret keys.
///
/// Abstracts over different participant types that hold the secret keys needed
/// for X-Wing hybrid KEM decryption operations.
pub trait ParticipantSecretKeys {
    /// Access to a type's X25519 elliptic curve secret key.
    fn ec_secret_key(&self) -> &X25519Secret;
    /// Access to a type's ML-KEM post-quantum secret key.
    fn pq_secret_key(&self) -> &MlKemSecret;
}

/// Encrypted with hybrid public key cryptography.
///
/// Provides access to both the ephemeral elliptic curve public key and the
/// post-quantum KEM ciphertext that together form the hybrid encryption.
pub trait PublicKeyEncrypted {
    /// Access to the ephemeral X25519 public key used for encryption.
    fn ec_public_key(&self) -> &X25519Public;
    /// Access to the ML-KEM ciphertext containing the encapsulated key.
    fn pq_ciphertext(&self) -> &MlKemCiphertext;
}

impl<T> Nonce for T
where
    T: PublicKeyEncrypted,
{
    fn nonce(&self) -> &XNonce {
        XNonce::from_slice(&self.ec_public_key().as_bytes()[..24])
    }
}

impl<T> Nonce for Vec<T>
where
    T: Ciphertext,
{
    fn nonce(&self) -> &XNonce {
        XNonce::from_slice(
            &self
                .last()
                .expect("Can't derive a nonce from an empty Vec")
                .ciphertext()[..24],
        )
    }
}

/// Constructed type from public key encryption components.
///
/// Allows encrypted data structures to be built from their parts: the ephemeral
/// public key, an ephemeral KEM ciphertext, and the actual encrypted data.
pub trait PublicKeyEncryptedFromParts {
    /// Construct an encrypted data structure from its components.
    fn from_parts(
        ec_public_key: X25519Public,
        pq_ciphertext: MlKemCiphertext,
        public_key_ciphertext: Vec<u8>,
    ) -> Self;
}

macro_rules! public_key_encrypted {
    ($type_name:ident, $ciphertext:ident) => {
        public_key_encrypted!($type_name, ec_public_key, pq_ciphertext, $ciphertext);
    };
    (
        $type_name:ident,
        $ec_public_key:ident,
        $pq_ciphertext:ident,
        $ciphertext:ident
    ) => {
        impl PublicKeyEncrypted for $type_name {
            fn ec_public_key(&self) -> &X25519Public {
                &self.$ec_public_key
            }

            fn pq_ciphertext(&self) -> &MlKemCiphertext {
                &self.$pq_ciphertext
            }
        }

        impl Ciphertext for $type_name {
            fn ciphertext(&self) -> &[u8] {
                self.$ciphertext.as_slice()
            }
        }

        impl PublicKeyEncryptedFromParts for $type_name {
            fn from_parts(
                $ec_public_key: X25519Public,
                $pq_ciphertext: MlKemCiphertext,
                $ciphertext: Vec<u8>,
            ) -> Self {
                Self {
                    $ec_public_key,
                    $pq_ciphertext,
                    $ciphertext,
                }
            }
        }
    };
}

public_key_encrypted!(CredentialVault, credentials_ciphertext);
public_key_encrypted!(SealedEnvelopeId, envelope_id_ciphertext);
public_key_encrypted!(SealedMessageVaultId, message_vault_id_ciphertext);

/// Construct type from a wrapped value and authentication components.
///
/// Allows authenticated wrapper types to be built from their constituent parts:
/// the wrapped data, dual signatures, and MAC for verifying key authenticity.
pub trait AuthenticatingWrapperFromParts<W>
where
    W: Sized,
{
    /// Construct an authenticated wrapper from its components.
    fn from_parts(
        inner: W,
        ec_signature: Ed25519Signature,
        pq_signature: FnDsaSignature,
        verifying_keys_mac: Vec<u8>,
    ) -> Self;
}

impl AuthenticatingWrapperFromParts<Key> for Credentials {
    fn from_parts(
        key: Key,
        ec_signature: Ed25519Signature,
        pq_signature: FnDsaSignature,
        verifying_keys_mac: Vec<u8>,
    ) -> Self {
        Self {
            key,
            ec_signature,
            pq_signature,
            verifying_keys_mac,
        }
    }
}

/// Blind a participant's public key.
///
/// Blinding allows a third party to send encrypted hints without knowing the
/// specific identity of the recipient, enabling anonymous message retrieval.
pub fn blind_public_key<P>(participant: &P, csprng: &mut impl CryptoRngCore) -> BlindedPublicKey
where
    P: ParticipantPublicKeys,
{
    participant.ec_public_key().blind(csprng)
}

fn mac_shared_secret(
    pq_shared_secret: &MlKemSharedSecret,
    ec_shared_secret: &X25519SharedSecret,
    ec_ciphertext: &X25519Public,
    ec_public_key: &X25519Public,
    salt: &[u8],
) -> Zeroizing<[u8; 32]> {
    let xwing_shared_secret = xwing_shared_secret(
        pq_shared_secret,
        ec_shared_secret,
        ec_ciphertext,
        ec_public_key,
    );

    salt_hash_digest(xwing_shared_secret.as_slice(), salt)
}

/// Generate cipher and cryptographic material for public key encryption.
///
/// Creates all the components needed for X-Wing hybrid KEM encryption:
/// ephemeral keys, shared secrets, and the resulting cipher instance.
pub fn cipher_and_material_for(
    ec_public_key: &X25519Public,
    pq_public_key: &MlKemPublic,
    salt: &[u8],
    mac_salt: Option<&[u8]>,
    csprng: &mut impl CryptoRngCore,
) -> (
    XChaCha20Poly1305,
    Option<Zeroizing<[u8; 32]>>,
    XNonce,
    X25519Public,
    MlKemCiphertext,
) {
    let ephemeral_ec_secret_key = X25519Ephemeral::random_from_rng(&mut *csprng);
    let ephemeral_ec_public_key = X25519Public::from(&ephemeral_ec_secret_key);
    let ec_shared_secret = ephemeral_ec_secret_key.diffie_hellman(ec_public_key);
    let (pq_ciphertext, pq_shared_secret) = pq_public_key
        .encapsulate(csprng)
        .expect("Encapsulating ML-KEM keys is infallible");

    let mac_shared_secret = mac_salt.map(|mac_salt| {
        mac_shared_secret(
            &pq_shared_secret,
            &ec_shared_secret,
            &ephemeral_ec_public_key,
            ec_public_key,
            mac_salt,
        )
    });

    (
        cipher_for(
            &pq_shared_secret,
            &ec_shared_secret,
            &ephemeral_ec_public_key,
            ec_public_key,
            salt,
        ),
        mac_shared_secret,
        XNonce::clone_from_slice(&ephemeral_ec_public_key.as_bytes()[..24]),
        ephemeral_ec_public_key,
        pq_ciphertext,
    )
}

/// Create a cipher instance using secret keys and encrypted material.
///
/// Used during decryption to recreate the same cipher that was used for
/// encryption by deriving the shared secret from the recipient's secret keys
/// and the sender's ephemeral material.
pub fn cipher_with_secrets(
    ec_secret_key: &X25519Secret,
    ec_public_key: &X25519Public,
    pq_secret_key: &MlKemSecret,
    pq_ciphertext: &MlKemCiphertext,
    salt: &[u8],
) -> XChaCha20Poly1305 {
    let ec_shared_secret = ec_secret_key.diffie_hellman(ec_public_key);
    let pq_shared_secret = pq_secret_key
        .decapsulate(pq_ciphertext)
        .expect("Decapsulation for ML-KEM is infallible");

    cipher_for(
        &pq_shared_secret,
        &ec_shared_secret,
        ec_public_key,
        &X25519Public::from(ec_secret_key),
        salt,
    )
}

pub(crate) fn cipher_for(
    pq_shared_secret: &MlKemSharedSecret,
    ec_shared_secret: &X25519SharedSecret,
    ec_ciphertext: &X25519Public,
    ec_public_key: &X25519Public,
    salt: &[u8],
) -> XChaCha20Poly1305 {
    let shared_secret = salt_hash_digest(
        xwing_shared_secret(
            pq_shared_secret,
            ec_shared_secret,
            ec_ciphertext,
            ec_public_key,
        )
        .as_ref(),
        salt,
    );
    let key = XChaChaKey::from_slice(shared_secret.as_ref());

    XChaCha20Poly1305::new(key)
}

pub(crate) fn xwing_shared_secret(
    pq_shared_secret: &MlKemSharedSecret,
    ec_shared_secret: &X25519SharedSecret,
    ec_ciphertext: &X25519Public,
    ec_public_key: &X25519Public,
) -> Zeroizing<[u8; 32]> {
    let mut hasher = <Sha3_256 as Digest>::new();
    hasher.update(br"\.//^\");
    hasher.update(pq_shared_secret.as_slice());
    hasher.update(ec_shared_secret.as_bytes());
    hasher.update(ec_ciphertext.as_bytes());
    hasher.update(ec_public_key.as_bytes());
    Zeroizing::new(hasher.finalize().into())
}

pub(crate) fn salt_hash_digest(hash_digest: &[u8], salt: &[u8]) -> Zeroizing<[u8; 32]> {
    let mut hasher = <Sha3_256 as Digest>::new();
    hasher.update(hash_digest);
    hasher.update(salt);
    Zeroizing::new(hasher.finalize().into())
}

/// Decrypts public key encrypted data.
///
/// Provides the decryption interface for participants who hold the secret keys
/// needed to decrypt public key encrypted data structures.
pub trait PublicKeyDecrypter<A>
where
    A: PublicKeyEncrypted + Ciphertext,
    Self: ParticipantSecretKeys,
{
    /// Decrypt hybrid encrypted data using participant's secret keys.
    ///
    /// Returns the decrypted and decoded data structure.
    fn decrypt<D>(&self, encrypted: &A, salts: &Salts) -> Result<D, error::CryptError>
    where
        D: ProstDecode + Decryptable<A>,
    {
        let cipher = cipher_with_secrets(
            self.ec_secret_key(),
            encrypted.ec_public_key(),
            self.pq_secret_key(),
            encrypted.pq_ciphertext(),
            &salts.shared_secret,
        );

        decrypt(&cipher, encrypted.nonce(), encrypted.ciphertext())
    }

    /// Generate the MAC shared secret for verifying key authenticity.
    ///
    /// This secret is used to verify that the sender's verifying keys are authentic
    /// and haven't been tampered with during transmission.
    fn mac_shared_secret(&self, encrypted: &A, salts: &Salts) -> Zeroizing<[u8; 32]> {
        let ec_shared_secret = &self
            .ec_secret_key()
            .diffie_hellman(encrypted.ec_public_key());
        let pq_shared_secret = &self
            .pq_secret_key()
            .decapsulate(encrypted.pq_ciphertext())
            .expect("Decapsulation for ML-KEM is infallible");

        mac_shared_secret(
            pq_shared_secret,
            ec_shared_secret,
            encrypted.ec_public_key(),
            &X25519Public::from(self.ec_secret_key()),
            &salts.verifying_keys_mac,
        )
    }
}

/// Generates and verifies HMAC tags for key authentication.
pub trait VerifiableMac {
    /// Generate an HMAC instance using the provided shared secret.
    fn mac(&self, mac_shared_secret: &Zeroizing<[u8; 32]>) -> impl Mac;

    /// Verify an HMAC tag against the expected value.
    fn verify_mac(
        &self,
        mac_shared_secret: &Zeroizing<[u8; 32]>,
        tag: &[u8],
    ) -> Result<(), MacError>;

    /// Generate a finalized HMAC tag as a byte vector.
    fn finalized_mac(&self, mac_shared_secret: &Zeroizing<[u8; 32]>) -> Vec<u8> {
        self.mac(mac_shared_secret).finalize().into_bytes().to_vec()
    }
}

impl<T> VerifiableMac for T
where
    T: Verifier,
{
    fn mac(&self, mac_shared_secret: &Zeroizing<[u8; 32]>) -> impl Mac {
        let mut mac = <HmacSha3_256 as Mac>::new_from_slice(mac_shared_secret.as_slice())
            .expect("Hmac can take keys of any size.");
        mac.update(self.ec_verifying_key().as_bytes());
        mac.update(self.pq_verifying_key());

        mac
    }

    fn verify_mac(
        &self,
        mac_shared_secret: &Zeroizing<[u8; 32]>,
        tag: &[u8],
    ) -> Result<(), MacError> {
        self.mac(mac_shared_secret).verify_slice(tag)
    }
}

/// Cryptographic bind ephemeral material and participant keys.
///
/// Generates a SIGMA-I-style binding digest for authenticated encryption to
/// prove that the material involved belong to the same cryptographic operation:
///
/// - Ephemeral cryptographic material (EC public key + PQ ciphertext)
/// - The data being authenticated
/// - The participant public keys
///
/// This prevents substitution attacks where valid components are mixed and
/// matched in unauthorized ways.
pub fn binding_digest<P>(
    ephemeral_ec_public_key: &X25519Public,
    pq_ciphertext: &MlKemCiphertext,
    hashable_bytes: Vec<Box<dyn AsRef<[u8]> + '_>>,
    participant: &P,
) -> CoreWrapper<Sha3_512Core>
where
    P: ParticipantPublicKeys,
{
    let mut hasher = <Sha3_512 as Digest>::new();
    hasher.update(ephemeral_ec_public_key.as_bytes());
    hasher.update(pq_ciphertext);
    for bytes in hashable_bytes {
        hasher.update(bytes.deref());
    }
    hasher.update(participant.ec_public_key().as_bytes());
    hasher.update(participant.pq_public_key().as_bytes());

    hasher
}

/// Encryptable using SIGMA-I-style authenticated public key encryption.
///
/// Provides authenticated encryption that combines X-Wing hybrid KEM encryption
/// with digital signatures, ensuring both confidentiality and authenticity.
pub trait PublicKeyEncryptable<W> {
    /// Encrypt this data using SIGMA-I-style authenticated encryption.
    ///
    /// Provides confidentiality (via X-Wing) and authenticity (via digital
    /// signatures and MAC verification) with cryptographic binding to prevent
    /// component substitution attacks.
    fn authenticated_encrypt<S, V, R, A>(
        self,
        signing_keys: &S,
        verifier: &V,
        recipient: &R,
        salts: &Salts,
        csprng: &mut impl CryptoRngCore,
    ) -> Result<A, error::CryptError>
    where
        S: Sign + VerifyingKeys<V>,
        V: Verifier,
        A: PublicKeyEncryptedFromParts,
        R: ParticipantPublicKeys,
        W: AuthenticatingWrapperFromParts<Self> + Decryptable<A> + ProstEncode,
        Self: Digestible + Sized,
    {
        let (cipher, mac_shared_secret, nonce, ec_public_key, pq_ciphertext) =
            cipher_and_material_for(
                recipient.ec_public_key(),
                recipient.pq_public_key(),
                &salts.shared_secret,
                Some(&salts.verifying_keys_mac),
                csprng,
            );

        let verifier_mac =
            verifier.finalized_mac(&mac_shared_secret.expect("Infallible due to last call"));

        let context = std::any::type_name::<Self>().as_bytes();
        let digest = binding_digest(
            &ec_public_key,
            &pq_ciphertext,
            self.hashable_bytes(),
            recipient,
        );
        let (ec_signature, pq_signature) = signing_keys.sign_digest(context, digest, csprng);

        let wrapper = W::from_parts(self, ec_signature, pq_signature, verifier_mac);

        Ok(A::from_parts(
            ec_public_key,
            pq_ciphertext,
            cipher.encrypt(&nonce, wrapper.encode_to_vec().as_slice())?,
        ))
    }
}

impl PublicKeyEncryptable<Credentials> for Key {}

/// Authenticates encrypted data using SIGMA-I-style verification.
///
/// Provides the authentication verification for SIGMA-I-style authenticated
/// encryption, ensuring the signatures are valid for the cryptographic binding
/// of ephemeral material and participant public keys.
pub trait Authenticate<T>
where
    T: PublicKeyEncryptable<Self>,
    Self: Sized,
{
    /// Verify the authentication of encrypted data.
    ///
    /// Reconstructs the SIGMA-I-style binding digest using the encrypted data's
    /// ephemeral material and verifies both the Ed25519 and FN-DSA signatures
    /// against it. This proves the ephemeral material and authenticating keys
    /// were bound together by the original sender.
    ///
    /// Both signatures need to be valid for the reconstructed binding digest to
    /// authenticate the encrypted data.
    fn authenticate<E, R, V>(&self, encrypted: &E, recipient: &R, verifier: &V) -> bool
    where
        E: PublicKeyEncrypted,
        R: ParticipantPublicKeys,
        V: Verifier + ?Sized,
        Self: Decryptable<E> + Signatures + Digestible,
    {
        let digest = binding_digest(
            encrypted.ec_public_key(),
            encrypted.pq_ciphertext(),
            self.hashable_bytes(),
            recipient,
        );

        let context = std::any::type_name::<T>().as_bytes();

        verify_digest(
            verifier,
            context,
            digest,
            self.ec_signature(),
            self.pq_signature(),
        )
    }
}

impl Authenticate<Key> for Credentials {}

/// Secret keys that "take" (decrypt) hints using ECDH-OMR.
pub trait HintTaker {
    /// Decrypt a single envelope ID hint.
    fn take_the_hint(
        &self,
        envelope_id_hint: &EnvelopeIdHint,
        salts: &Salts,
    ) -> Result<HintedEnvelopeId, error::CryptError>
    where
        Self: ParticipantSecretKeys,
    {
        let decrypted_bytes = self
            .ec_secret_key()
            .take_the(envelope_id_hint, &salts.shared_secret)?;

        Ok(HintedEnvelopeId::decode(decrypted_bytes)?)
    }

    /// Decrypt a set of envelope ID hints.
    fn take_all_the_hints(
        &self,
        envelope_id_hints: &EnvelopeIdHints,
        salts: &Salts,
    ) -> Result<Vec<HintedEnvelopeId>, error::DecodeError>
    where
        Self: ParticipantSecretKeys,
    {
        self.ec_secret_key()
            .take_all_the(envelope_id_hints, &salts.shared_secret)
            .iter()
            .map(HintedEnvelopeId::decode)
            .collect()
    }
}

/// Encrypt a symmetric encryption key for multiple recipients using
/// SIGMA-I-style authenticated encryption.
///
/// Creates individual [`CredentialVault`]s for each recipient, allowing them to
/// decrypt the shared key while maintaining authentication.
pub fn authenticated_encrypt_key<S, V>(
    key: &Key,
    signing_keys: &S,
    verifier: &V,
    recipients: &[impl ParticipantPublicKeys],
    salts: &Salts,
    csprng: &mut impl CryptoRngCore,
) -> Result<Vec<CredentialVault>, error::CryptError>
where
    S: Sign + VerifyingKeys<V>,
    V: Verifier,
{
    recipients
        .iter()
        .map(|p| key.authenticated_encrypt(signing_keys, verifier, p, salts, csprng))
        .collect()
}

/// Build an [`EnvelopeSeed`] containing all components needed for secure
/// message delivery.
///
/// Assembles the complete envelope seed structure that includes
/// [`BlindedPublicKey`]s for anonymous messaging, [`CredentialVault`]s for key
/// distribution, and the encrypted [`MessageVaultPassport`].
pub fn build_envelope_seed(
    message_vault_passport: MessageVaultPassport,
    participants: &[impl ParticipantPublicKeys],
    key: &Key,
    credential_vaults: Vec<CredentialVault>,
    csprng: &mut impl CryptoRngCore,
) -> Result<EnvelopeSeed, error::CryptError> {
    let blinded_public_keys = participants
        .iter()
        .map(|p| blind_public_key(p, csprng))
        .collect();

    let (nonce, message_vault_passport_ciphertext) =
        message_vault_passport.encrypt_owned(key, csprng)?;

    Ok(EnvelopeSeed {
        blinded_public_keys,
        credential_vaults,
        nonce,
        message_vault_passport_ciphertext,
    })
}