ecdh_omr/

hint.rs

// SPDX-FileCopyrightText: 2024-2026 eaon <eaon@posteo.net>
// SPDX-License-Identifier: EUPL-1.2

use std::marker::PhantomData;
use std::ops::Add;

use aead::{Aead, AeadCore, KeyInit, Payload};
#[cfg(feature = "rustcrypto-ec")]
use elliptic_curve::{
    Curve, CurveArithmetic,
    point::PointCompression,
    sec1::{CompressedPoint, CompressedPointSize, FromSec1Point, ModulusSize, ToSec1Point},
};
use hybrid_array::ArraySize;
use rand_core::CryptoRng;
use typenum::{Sum, Unsigned};

#[cfg(feature = "dalek-ristretto255")]
use crate::{
    DalekRistretto255, blind_dalek_ristretto255, checked_decompress_ristretto255_public_key,
    dalek_ristretto255, random_blind_dalek_ristretto255,
};
#[cfg(feature = "dalek-x25519")]
use crate::{
    DalekX25519, blind_dalek_x25519, checked_x25519_public_key, random_blind_dalek_x25519,
};
#[cfg(feature = "rustcrypto-ec")]
use crate::{EllipticCurve, blind_rcec, random_blind_rcec};
use crate::{error::*, *};

/// Semi generic implementations to create new [`Hint`]s
pub trait Hinting<K: KeyPair, L: ArraySize>: Sized {
    /// Byte length of a serialized [`Hint`]: public key + ciphertext + tag.
    type HintSize: ArraySize;

    /// Create a new [`Hint`].
    fn new(
        blinded_public_key: &BlindedPublicKey<K>,
        message: &Array<u8, L>,
        context: &[u8],
        csprng: &mut impl CryptoRng,
    ) -> Result<Self>;

    /// Create a new [`Hint`] using a blinding factor secret.
    fn from_blinding_factor_secret(
        blinding_factor_secret: &K::SecretKey,
        blinded_public_key: &BlindedPublicKey<K>,
        message: &Array<u8, L>,
        context: &[u8],
    ) -> Result<Self>;

    /// Deserialize from byte slice
    ///
    /// # Security
    ///
    /// Implementers **must** validate the deserialized blinded blinding factor and reject
    /// small-order and identity points with [`Error::InvalidPoint`].
    fn from_bytes(bytes: &[u8]) -> Result<Self>;

    /// Serialize to byte array
    fn to_bytes(self) -> Array<u8, Self::HintSize>;
}

type HintCiphertextSize<A, L> = Sum<<A as AeadCore>::TagSize, L>;
type HintSize<K, A, L> = Sum<<K as KeyPair>::PublicKeySize, HintCiphertextSize<A, L>>;

/// Provides compile-time size information for [`Hint`] serialization.
///
/// The associated types give access to the ciphertext and total hint sizes,
/// computed from the key pair, AEAD algorithm, and message length.
pub trait HintSized<K: KeyPair, A: AeadCore, L: ArraySize>: Sized {
    /// Ciphertext size: AEAD tag size plus message length.
    type CiphertextSize: ArraySize;
    /// Total hint size: public key size plus ciphertext size.
    type Size: ArraySize;
}

impl<K: KeyPair, A: Aead + KeyInit, L: ArraySize> HintSized<K, A, L> for Hint<K, A, L>
where
    <A as AeadCore>::TagSize: Add<L>,
    <<A as AeadCore>::TagSize as Add<L>>::Output: ArraySize,
    <K as KeyPair>::PublicKeySize: Add<HintCiphertextSize<A, L>>,
    <<K as KeyPair>::PublicKeySize as Add<HintCiphertextSize<A, L>>>::Output: ArraySize,
{
    type CiphertextSize = HintCiphertextSize<A, L>;
    type Size = HintSize<K, A, L>;
}

/// Message encrypted by a third party, decryptable by an anonymous recipient that doesn't know
/// whether it is addressed to them or not.
#[derive(Debug, Clone)]
pub struct Hint<K: KeyPair, A: Aead + KeyInit, L: ArraySize>
where
    Self: HintSized<K, A, L>,
{
    /// Two thirds of a three part secret used to encrypt the hint's underlying message.
    ///
    /// The blinding factor of a [`BlindedPublicKey`] is blinded itself, allowing the entire hint
    /// to be randomized.
    pub(crate) blinded_blinding_factor: K::PublicKey,
    /// Ciphertext decryptable by trial decryption.
    pub(crate) ciphertext: Array<u8, <Self as HintSized<K, A, L>>::CiphertextSize>,
    /// Marker to allow us to generically use AEAD implementations
    _aead: PhantomData<A>,
}

fn encrypt<A: Aead + KeyInit>(
    shared_secret: &[u8],
    blinded_blinding_factor: &[u8],
    message: &[u8],
) -> Result<Vec<u8>> {
    let cipher = cipher_from_shared_secret::<A>(shared_secret)?;
    let nonce = nonce::<A>(blinded_blinding_factor)?;
    let ciphertext = cipher.encrypt(
        &nonce,
        Payload {
            msg: message,
            aad: blinded_blinding_factor,
        },
    )?;

    Ok(ciphertext)
}

impl<K: KeyPair, A: Aead + KeyInit, L: ArraySize> TryFrom<&[u8]> for Hint<K, A, L>
where
    Self: Hinting<K, L> + HintSized<K, A, L>,
{
    type Error = Error;

    fn try_from(bytes: &[u8]) -> Result<Self> {
        Self::from_bytes(bytes)
    }
}

#[cfg(any(feature = "dalek-ristretto255", feature = "dalek-x25519"))]
macro_rules! dalek_hinting {
    (
        $construct:ident,
        (
            $curve:ty,
            $public:ty,
            $secret:ty,
            $random_blind:ident,
            $blind:ident,
            $checked_public_key:expr,
            $secret_to_bytes:expr,
            $public_to_bytes:expr $(,)?
        ) $(,)?
    ) => {
        fn $construct<A: Aead + KeyInit, L: ArraySize>(
            blinded_blinding_factor: $public,
            blinding_factor_secret: &$secret,
            blinded_public_key_inner: &$public,
            message: &Array<u8, L>,
            context: &[u8],
        ) -> Result<Hint<$curve, A, L>>
        where
            Hint<$curve, A, L>: HintSized<$curve, A, L>,
        {
            let raw_shared_secret = blinding_factor_secret.diffie_hellman(blinded_public_key_inner);

            let blinded_blinding_factor_bytes = $public_to_bytes(&blinded_blinding_factor);
            let raw_shared_secret_bytes = $secret_to_bytes(&raw_shared_secret);

            let shared_secret = shared_secret(
                &raw_shared_secret_bytes,
                &blinded_blinding_factor_bytes,
                context,
            );

            let ciphertext = encrypt::<A>(
                &shared_secret,
                &blinded_blinding_factor_bytes,
                message.as_ref(),
            )?
            .into_iter()
            .collect();

            Ok(Hint {
                blinded_blinding_factor,
                ciphertext,
                _aead: PhantomData,
            })
        }

        impl<A: Aead + KeyInit, L: ArraySize> Hinting<$curve, L> for Hint<$curve, A, L>
        where
            Self: HintSized<$curve, A, L>,
        {
            type HintSize = <Self as HintSized<$curve, A, L>>::Size;

            fn new(
                blinded_public_key: &BlindedPublicKey<$curve>,
                message: &Array<u8, L>,
                context: &[u8],
                csprng: &mut impl CryptoRng,
            ) -> Result<Self> {
                let (blinded_blinding_factor, blinding_factor_secret) =
                    $random_blind(&blinded_public_key.blinding_factor, csprng);

                $construct(
                    blinded_blinding_factor,
                    &blinding_factor_secret,
                    &blinded_public_key.inner,
                    message,
                    context,
                )
            }

            fn from_blinding_factor_secret(
                blinding_factor_secret: &$secret,
                blinded_public_key: &BlindedPublicKey<$curve>,
                message: &Array<u8, L>,
                context: &[u8],
            ) -> Result<Self> {
                let blinded_blinding_factor =
                    $blind(&blinded_public_key.blinding_factor, blinding_factor_secret);

                $construct(
                    blinded_blinding_factor,
                    blinding_factor_secret,
                    &blinded_public_key.inner,
                    message,
                    context,
                )
            }

            fn from_bytes(bytes: &[u8]) -> Result<Self> {
                if bytes.len() != <Self as HintSized<$curve, A, L>>::Size::USIZE {
                    return Err(Error::Decoding);
                }

                let public_size = <$curve as KeyPair>::PublicKeySize::USIZE;
                let blinded_blinding_factor_bytes = bytes
                    .iter()
                    .take(public_size)
                    .copied()
                    .collect::<Array<u8, <$curve as KeyPair>::PublicKeySize>>();
                let blinded_blinding_factor =
                    $checked_public_key(blinded_blinding_factor_bytes.into())?;
                let ciphertext = bytes.iter().skip(public_size).copied().collect();

                Ok(Self {
                    blinded_blinding_factor,
                    ciphertext,
                    _aead: PhantomData,
                })
            }

            fn to_bytes(self) -> Array<u8, Self::HintSize> {
                $public_to_bytes(&self.blinded_blinding_factor)
                    .into_iter()
                    .chain(self.ciphertext)
                    .collect()
            }
        }
    };
}

#[cfg(feature = "dalek-ristretto255")]
dalek_hinting!(
    construct_dalek_ristretto255_hint,
    (
        DalekRistretto255,
        dalek_ristretto255::PublicKey,
        dalek_ristretto255::StaticSecret,
        random_blind_dalek_ristretto255,
        blind_dalek_ristretto255,
        checked_decompress_ristretto255_public_key,
        |ss: &dalek_ristretto255::SharedSecret| ss.to_bytes(),
        |pk: &dalek_ristretto255::PublicKey| pk.to_bytes(),
    ),
);

#[cfg(feature = "dalek-x25519")]
dalek_hinting!(
    construct_dalek_x25519_hint,
    (
        DalekX25519,
        x25519_dalek::PublicKey,
        x25519_dalek::StaticSecret,
        random_blind_dalek_x25519,
        blind_dalek_x25519,
        checked_x25519_public_key,
        |ss: &x25519_dalek::SharedSecret| *ss.as_bytes(),
        |pk: &x25519_dalek::PublicKey| *pk.as_bytes(),
    ),
);

#[cfg(feature = "rustcrypto-ec")]
fn construct_rustcrypto_ec_hint<A, C, L: ArraySize>(
    blinded_blinding_factor: elliptic_curve::PublicKey<C>,
    blinding_factor_secret: &elliptic_curve::SecretKey<C>,
    blinded_public_key_inner: &elliptic_curve::PublicKey<C>,
    message: &Array<u8, L>,
    context: &[u8],
) -> Result<Hint<EllipticCurve<C>, A, L>>
where
    A: Aead + KeyInit,
    C: CurveArithmetic + PointCompression,
    <C as Curve>::FieldBytesSize: ModulusSize,
    <C as CurveArithmetic>::AffinePoint: ToSec1Point<C> + FromSec1Point<C>,
    Hint<EllipticCurve<C>, A, L>: HintSized<EllipticCurve<C>, A, L>,
{
    let raw_shared_secret = elliptic_curve::ecdh::diffie_hellman(
        blinding_factor_secret.to_nonzero_scalar(),
        blinded_public_key_inner.as_affine(),
    );

    let blinded_blinding_factor_cp = CompressedPoint::<C>::from(&blinded_blinding_factor);

    let shared_secret = shared_secret(
        raw_shared_secret.raw_secret_bytes(),
        blinded_blinding_factor_cp.as_slice(),
        context,
    );

    let ciphertext = encrypt::<A>(
        &shared_secret,
        blinded_blinding_factor_cp.as_slice(),
        message,
    )?
    .into_iter()
    .collect();

    Ok(Hint {
        blinded_blinding_factor,
        ciphertext,
        _aead: PhantomData,
    })
}

#[cfg(feature = "rustcrypto-ec")]
impl<A: Aead + KeyInit, C: CurveArithmetic + PointCompression, L: ArraySize>
    Hinting<EllipticCurve<C>, L> for Hint<EllipticCurve<C>, A, L>
where
    <C as Curve>::FieldBytesSize: ModulusSize,
    <C as CurveArithmetic>::AffinePoint: ToSec1Point<C> + FromSec1Point<C>,
    Self: HintSized<EllipticCurve<C>, A, L>,
{
    type HintSize = <Self as HintSized<EllipticCurve<C>, A, L>>::Size;

    fn new(
        blinded_public_key: &BlindedPublicKey<EllipticCurve<C>>,
        message: &Array<u8, L>,
        context: &[u8],
        csprng: &mut impl CryptoRng,
    ) -> Result<Self> {
        let (blinded_blinding_factor, blinding_factor_secret) =
            random_blind_rcec(&blinded_public_key.blinding_factor, csprng);

        construct_rustcrypto_ec_hint(
            blinded_blinding_factor,
            &blinding_factor_secret,
            &blinded_public_key.inner,
            message,
            context,
        )
    }

    fn from_blinding_factor_secret(
        blinding_factor_secret: &elliptic_curve::SecretKey<C>,
        blinded_public_key: &BlindedPublicKey<EllipticCurve<C>>,
        message: &Array<u8, L>,
        context: &[u8],
    ) -> Result<Self> {
        let blinded_blinding_factor =
            blind_rcec(&blinded_public_key.blinding_factor, blinding_factor_secret);

        construct_rustcrypto_ec_hint(
            blinded_blinding_factor,
            blinding_factor_secret,
            &blinded_public_key.inner,
            message,
            context,
        )
    }

    fn from_bytes(bytes: &[u8]) -> Result<Self> {
        if bytes.len() != <Self as HintSized<EllipticCurve<C>, A, L>>::Size::USIZE {
            return Err(Error::Decoding);
        }

        let public_size = CompressedPointSize::<C>::USIZE;
        let blinded_blinding_factor =
            elliptic_curve::PublicKey::<C>::from_sec1_bytes(&bytes[..public_size])
                .map_err(|_| Error::Decoding)?;
        let ciphertext = bytes.iter().skip(public_size).copied().collect();

        Ok(Self {
            blinded_blinding_factor,
            ciphertext,
            _aead: PhantomData,
        })
    }

    fn to_bytes(self) -> Array<u8, Self::HintSize> {
        CompressedPoint::<C>::from(&self.blinded_blinding_factor)
            .into_iter()
            .chain(self.ciphertext)
            .collect()
    }
}

/// Pairing of message contents and the [`BlindedPublicKey`] of its recipient.
///
/// Hint seeds are used to create [`Hints`](crate::Hints).
#[derive(Debug, Clone)]
pub struct HintSeed<K: KeyPair, L: ArraySize> {
    /// Blinded Public Key
    pub blinded_public_key: BlindedPublicKey<K>,
    /// Message
    pub message: Array<u8, L>,
}

impl<K: KeyPair, L: ArraySize> HintSeed<K, L> {
    /// Pair [`BlindedPublicKey`] with message contents.
    pub fn new(blinded_public_key: BlindedPublicKey<K>, message: Array<u8, L>) -> Self {
        Self {
            blinded_public_key,
            message,
        }
    }
}

impl<K: KeyPair, L: ArraySize> Decoy for HintSeed<K, L> {
    fn random_decoy(csprng: &mut impl CryptoRng) -> Self {
        Self {
            blinded_public_key: BlindedPublicKey {
                inner: K::PublicKey::random_decoy(csprng),
                blinding_factor: K::PublicKey::random_decoy(csprng),
            },
            message: Array::default(),
        }
    }
}