rhdl_dsig_scalable_core/

certificate.rs

//! Versioned, domain-separated Ed25519 batch authentication.
//!
//! The Ed25519 implementation's fixed-64 request signs these exact bytes, not a
//! host-prehashed replacement. Eight little-endian 64-bit words map directly to
//! its `Words512` message; the 16-bit hardware transaction tag is not signed and
//! must never be used as the cryptographic batch identity.
//!
//! # The problem
//!
//! A one-time key is only useful if a verifier can tell it really belongs to
//! the signer. Signing each of millions of keys with Ed25519 would cost as
//! much as signing the messages directly. DSig instead groups 128 keys into a
//! *batch*, builds a Merkle tree over them (see
//! [`BatchTree`](crate::reference::BatchTree)) and signs only the tree root,
//! once per batch, with Ed25519.
//!
//! # The decision: one fixed 64-byte envelope
//!
//! What exactly gets signed must be unambiguous, or a signature made for one
//! purpose could be replayed for another. So the signed message is a fixed
//! 64-byte *envelope*: a domain string, a profile version, the batch size,
//! the never-reused namespace `(epoch, batch_id)`, and the root.
//!
//! ```text
//!  byte  0        8        12       16        24          32                64
//!        ┌────────┬────────┬────────┬─────────┬───────────┬─────────────────┐
//!        │DSIGFP01│profile │ batch  │  epoch  │ batch_id  │   Merkle root   │
//!        │ ASCII  │ u32 LE │ size LE│ u64 LE  │  u64 LE   │    32 bytes     │
//!        │        │  = 1   │ = 128  │         │           │                 │
//!        └────────┴────────┴────────┴─────────┴───────────┴─────────────────┘
//!  word     0          1             2          3          4    5    6    7
//! ```
//!
//! 64 bytes is exactly eight 64-bit words, which is the fixed message size of
//! the Ed25519 hardware core's `Words512` request. So the hardware never has
//! to hash or reshuffle the envelope before signing: [`batch_commitment_words`]
//! packs it straight into those eight words.
//!
//! # Two views of the same bytes
//!
//! * Hardware: [`batch_commitment_words`] is an RHDL `#[kernel]` that the
//!   certificate unit ([`crate::cert_unit`]) and the bridge
//!   ([`crate::ed25519`]) call.
//! * Software: [`BatchCommitment`] and [`BatchCertificate`] are the host-side
//!   oracle used by [`crate::reference`] and the host tools. A test checks
//!   that both views produce the same words for every root bit.
//!
//! The 16-bit routing tag that travels next to the request in hardware is
//! not part of these bytes. It only says which outstanding request a result
//! belongs to.

use ed25519_dalek::{Signature, Signer, SigningKey, VerifyingKey};
use rhdl::prelude::*;

use crate::{BATCH_KEYS, Digest};

/// Domain occupying certificate bytes 0 through 7.
///
/// The fixed ASCII label `DSIGFP01`, so this envelope can never be
/// mistaken for any other 64-byte message signed by the same Ed25519 key.
pub const DOMAIN: [u8; 8] = *b"DSIGFP01";
/// Version/profile identifier for the corrected base-four construction.
///
/// Bytes 8..12, little endian. "Corrected" refers to the complement checksum
/// in [`crate::reference::digits_from_xof`]. A verifier for another profile
/// rejects these envelopes instead of misreading them.
///
/// Profile 1 signs 16-byte messages (`DSIG_MESSAGE_BYTES=16`, the default
/// and the measured profile); profile 2 is the same construction over
/// 64-byte messages. Since the profile is inside the certified envelope, a
/// key of one profile can never pass for the other.
pub const PROFILE_ID: u32 = if crate::MESSAGE_BYTES == 16 { 1 } else { 2 };
/// Envelope word 1: profile (bytes 8..12) and batch size 128 (bytes 12..16).
const PROFILE_WORD: b64 = b64(0x0000_0080_0000_0000 | PROFILE_ID as u128);

/// Build the Ed25519 fixed-64 message in RHDL, without hashing on the host.
///
/// The background scheduler supplies a completed 128-key Merkle root and its
/// durably allocated namespace. The result maps directly to the Ed25519 core's
/// `SignRequest.message.words`. This adapter is pure packing: it neither signs
/// nor validates a certificate, and it does not authorize cache admission.
///
/// Inputs: `epoch` and `batch_id` (64 bits each), `root` (32 bytes, in hash
/// output order). Output: eight 64-bit words; word `i` holds envelope bytes
/// `8i..8i + 8` in little-endian order. Timing: purely combinational (no
/// registers, zero cycles of latency); it is wires plus constants.
#[kernel]
#[allow(clippy::needless_range_loop)]
pub fn batch_commitment_words(epoch: b64, batch_id: b64, root: [b8; 32]) -> [b64; 8] {
    // The eight output words, filled in envelope order.
    let mut words = [b64(0); 8];
    // ASCII DSIGFP01, then little-endian profile and batch_size=128.
    words[0] = b64(0x3130_5046_4749_5344);
    words[1] = PROFILE_WORD;
    words[2] = epoch;
    words[3] = batch_id;
    // Words 4..8: the root, eight bytes per word, byte 0 in the low bits.
    // RHDL needs literal loop bounds, hence the fixed 0..4 and 0..8.
    for word in 0..4 {
        // Accumulates one 64-bit word from eight root bytes.
        let mut value = b64(0);
        for byte in 0..8 {
            // Widen the byte to 64 bits and shift it to its lane.
            value = value | (root[8 * word + byte].resize::<64>() << (8 * byte) as u128);
        }
        words[word + 4] = value;
    }
    words
}

/// Unambiguous 64-byte message authenticated by the background Ed25519 core.
///
/// Only the variable fields are stored; domain, profile and batch size are
/// constants added by [`BatchCommitment::to_bytes`].
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct BatchCommitment {
    /// Durably allocated, never-reused epoch under this signing identity.
    pub epoch: u64,
    /// Monotonic batch number within the epoch.
    pub batch_id: u64,
    /// BLAKE3 Merkle root of exactly 128 one-time public-key commitments.
    pub root: Digest,
}

impl BatchCommitment {
    /// Encode domain8, profile4, batch-size4, epoch8, batch-id8, root32.
    ///
    /// The number after each field name is its size in bytes; all integers
    /// are little endian.
    #[must_use]
    pub fn to_bytes(self) -> [u8; 64] {
        let mut bytes = [0; 64];
        bytes[..8].copy_from_slice(&DOMAIN);
        bytes[8..12].copy_from_slice(&PROFILE_ID.to_le_bytes());
        bytes[12..16].copy_from_slice(&(BATCH_KEYS as u32).to_le_bytes());
        bytes[16..24].copy_from_slice(&self.epoch.to_le_bytes());
        bytes[24..32].copy_from_slice(&self.batch_id.to_le_bytes());
        bytes[32..].copy_from_slice(&self.root);
        bytes
    }

    /// Parse only this exact profile and batch size; reject cross-profile data.
    #[must_use]
    pub fn from_bytes(bytes: &[u8; 64]) -> Option<Self> {
        if bytes[..8] != DOMAIN
            || bytes[8..12] != PROFILE_ID.to_le_bytes()
            || bytes[12..16] != (BATCH_KEYS as u32).to_le_bytes()
        {
            return None;
        }
        Some(Self {
            epoch: u64::from_le_bytes(bytes[16..24].try_into().ok()?),
            batch_id: u64::from_le_bytes(bytes[24..32].try_into().ok()?),
            root: bytes[32..64].try_into().ok()?,
        })
    }

    /// Map directly to the Ed25519 fixed-64 core's little-endian words.
    #[must_use]
    ///
    /// Software twin of [`batch_commitment_words`]; tests compare the two.
    pub fn to_ed25519_words(self) -> [u64; 8] {
        let bytes = self.to_bytes();
        core::array::from_fn(|word| {
            u64::from_le_bytes(bytes[word * 8..word * 8 + 8].try_into().expect("word"))
        })
    }
}

/// Public batch commitment and its Ed25519 signature.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct BatchCertificate {
    /// Exact message signed, including domain/profile and lifetime namespace.
    pub commitment: BatchCommitment,
    /// Canonical Ed25519 `R || S` bytes.
    pub signature: [u8; 64],
}

impl BatchCertificate {
    /// Software oracle for the hardware certificate service, not hardware work.
    ///
    /// Signs `commitment.to_bytes()` with `ed25519-dalek`. Ed25519 is
    /// deterministic, so the hardware core must produce the same 64 bytes.
    #[must_use]
    pub fn sign_reference(commitment: BatchCommitment, key: &SigningKey) -> Self {
        Self {
            signature: key.sign(&commitment.to_bytes()).to_bytes(),
            commitment,
        }
    }

    /// Authenticate against a caller-supplied trusted signer identity.
    ///
    /// Uses dalek's `verify_strict`, which also rejects weak (small-order)
    /// keys and signature points. The caller supplies the trusted key; the
    /// certificate does not carry one, so it cannot vouch for itself.
    #[must_use]
    pub fn verify_strict(&self, trusted_signer: &VerifyingKey) -> bool {
        trusted_signer
            .verify_strict(
                &self.commitment.to_bytes(),
                &Signature::from_bytes(&self.signature),
            )
            .is_ok()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// For each of the 256 root bits set alone, the RHDL kernel and the byte
    /// serializer give identical words.
    #[test]
    fn rhdl_message_packing_matches_ed25519_fixed64_bytes() {
        for bit in 0..256 {
            let mut root = [0u8; 32];
            root[bit / 8] = 1 << (bit % 8);
            let commitment = BatchCommitment {
                epoch: 0x0123_4567_89ab_cdef,
                batch_id: 0xfedc_ba98_7654_3210,
                root,
            };
            let packed = batch_commitment_words(
                b64(commitment.epoch as u128),
                b64(commitment.batch_id as u128),
                root.map(|byte| b8(byte as u128)),
            );
            assert_eq!(
                packed.map(|word| word.raw() as u64),
                commitment.to_ed25519_words()
            );
        }
    }

    /// Sign, verify, reject a wrong key, round-trip the bytes, and show that
    /// flipping any one bit of the envelope breaks either parsing (bytes
    /// 0..16, the constants) or verification (bytes 16..64).
    #[test]
    fn fixed64_certificate_binds_every_field() {
        let signing = SigningKey::from_bytes(&[19; 32]);
        let commitment = BatchCommitment {
            epoch: 0x0102_0304_0506_0708,
            batch_id: 42,
            root: [0x69; 32],
        };
        let certificate = BatchCertificate::sign_reference(commitment, &signing);
        assert!(certificate.verify_strict(&signing.verifying_key()));
        assert!(!certificate.verify_strict(&SigningKey::from_bytes(&[20; 32]).verifying_key()));
        let encoded = commitment.to_bytes();
        assert_eq!(BatchCommitment::from_bytes(&encoded), Some(commitment));
        let words = commitment.to_ed25519_words();
        for (i, word) in words.iter().enumerate() {
            assert_eq!(&encoded[i * 8..i * 8 + 8], &word.to_le_bytes());
        }
        for i in 0..64 {
            let mut changed = encoded;
            changed[i] ^= 1;
            if let Some(commitment) = BatchCommitment::from_bytes(&changed) {
                assert!(
                    !BatchCertificate {
                        commitment,
                        ..certificate.clone()
                    }
                    .verify_strict(&signing.verifying_key())
                );
            } else {
                assert!(i < 16);
            }
        }
    }
}