rhdl_dsig_scalable_core/

slice_model.rs

//! Bit-exact software model of every compression a slice issues.
//!
//! # Why this file exists
//!
//! The hardware never calls "BLAKE3 of this message". It feeds one 64-byte
//! *compression* at a time into its BLAKE3 lane, and it has to choose every
//! chaining value, counter, length and flag itself. One wrong flag bit gives
//! a different hash, and a key that no verifier accepts. The high-level
//! software [`reference`](crate::reference) cannot help locate such a bug,
//! because it calls a BLAKE3 library that hides those details.
//!
//! So this file sits in between. It rebuilds a whole key out of the same
//! single compressions the hardware issues, written as plain Rust, one
//! function per kind of request. A test proves the result equals the
//! reference. After that, this file is the readable specification of what
//! the RTL must send, and RTL tests can compare against it request by request.
//!
//! ```text
//!   reference (BLAKE3 library)  ══ test: equal ══  slice_model (single compressions)
//!                                                         ║ RTL tests: equal, request by request
//!                                                  slice_factory / slice_signer (hardware)
//! ```
//!
//! # What it models
//!
//! Each function below returns the exact BLAKE3 request (chaining value,
//! block, counter, length, flags) that one [`Op`](crate::slice_schedule::Op)
//! sends into a slice's BLAKE3 lane. [`model_key`] builds a complete one-time
//! key using only these requests, [`compress`], [`dsig_chain`] and the
//! [`packer`](crate::packer) stream layout. A test proves the result equals
//! the high-level [`reference`](crate::reference), so:
//!
//! * the flags, counters and lengths in this file are the *specification* the
//!   RTL must follow, one function per op, and
//! * RTL tests can compare against [`model_key`] request by request.
//!
//! ```text
//!   host: prefix_cv = BLAKE3-derive-key(context) ∘ (master ‖ signer)   [once per run]
//!   Seed      cv=prefix_cv  block=epoch‖batch‖index (20 B)  CHUNK_END|ROOT|DERIVE_KEY_MATERIAL
//!   PkNonce   cv=IV         block=LE32(0x5eed)‖seed (36 B)  single-block root
//!   Nonce     cv=IV         block=LE32(0xc0ca)‖seed (36 B)  single-block root
//!   Xof(t)    cv=IV         block=seed (32 B), counter t     single-block root
//!   Chunk0(j) cv=IV or CV   block=stream[64j..]   counter 0  START on j=0, END on j=15
//!   Chunk1(m) cv=IV or CV   block=stream[1024+64m..] ctr 1   START on m=0, END on m=3 (24 B)
//!   Parent    cv=IV         block=CV0‖CV1                    PARENT|ROOT  → pk_hash
//!   Merkle    cv=IV         block=left‖right                 single-block root
//!   Message   cv=IV         block=pk_hash‖nonce‖message      single-block root → digits
//! ```
//!
//! Per key that is 1 seed + 2 nonces + 20 XOF + 20 commitment blocks + 1
//! parent = 44 requests (the test checks this count). `Merkle` and `Message`
//! are not part of one key: they serve the subtree and the signer.
//!
//! # The story of one key, in data
//!
//! ```text
//!   seed ──▶ pk_nonce, nonce
//!     └───▶ XOF 20 × 64 B = 1,280 B ──▶ 68 chain secrets of 18 B (1,224 B used)
//!             position 0 ──Haraka──▶ position 1 ──▶ position 2 ──▶ position 3 (chain end)
//!             (all four positions of all 68 chains go to the key cache)
//!   pk_nonce ‖ 68 chain ends = 1,240 B ──▶ chunk 0 (16 blocks) + chunk 1 (4 blocks)
//!                                     ──▶ Parent(CV0, CV1) = pk_hash (the Merkle leaf)
//! ```
//!
//! 1,240 bytes is more than one 1,024-byte BLAKE3 chunk, so BLAKE3 hashes
//! it as two chunks and one parent node. That is standard BLAKE3; the model
//! just spells it out.
//!
//! The master seed never enters the FPGA: the trusted host derives
//! [`prefix_cv`], the chaining value after the first 64 material bytes, and
//! loads that instead. Both are equally secret.

use crate::blake3_core::{
    CHUNK_END, CHUNK_START, DERIVE_KEY_CONTEXT, DERIVE_KEY_MATERIAL, IV, PARENT, ROOT,
    SINGLE_BLOCK_ROOT, compress, decode_block, encode_words,
};
use crate::haraka::dsig_chain;
use crate::{CHAINS, Digest, ELEMENT_BYTES, Nonce, POSITIONS, SEED_DERIVATION_CONTEXT};

/// One BLAKE3 compression request, exactly as the lane receives it.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Request {
    /// Input chaining value or key words.
    pub cv: [u32; 8],
    /// Zero-padded block as little-endian words.
    pub block: [u32; 16],
    /// Chunk counter, or XOF output-block number for root outputs.
    pub counter: u64,
    /// Meaningful bytes in `block`.
    pub block_len: u32,
    /// BLAKE3 domain flags.
    pub flags: u32,
}

impl Request {
    /// Run the request through the reference compression function.
    ///
    /// Returns all 16 output words; callers keep the first 8 as a chaining
    /// value, or use all 16 as 64 bytes of root output.
    #[must_use]
    pub const fn compress(&self) -> [u32; 16] {
        compress(
            self.cv,
            self.block,
            self.counter,
            self.block_len,
            self.flags,
        )
    }
}

/// Zero-pad up to 64 bytes and convert to 16 little-endian words.
fn block_of(bytes: &[u8]) -> [u32; 16] {
    let mut padded = [0; 64];
    padded[..bytes.len()].copy_from_slice(bytes);
    decode_block(padded)
}

/// First 8 output words: the chaining value of a compression.
fn cv_of(words: [u32; 16]) -> [u32; 8] {
    core::array::from_fn(|i| words[i])
}

/// First 32 output bytes: a 32-byte hash (seed, `pk_hash`, Merkle node).
fn bytes32(words: [u32; 16]) -> [u8; 32] {
    let bytes = encode_words(words);
    core::array::from_fn(|i| bytes[i])
}

/// BLAKE3 derive-key context key for [`SEED_DERIVATION_CONTEXT`].
///
/// BLAKE3's key-derivation mode first hashes a context string into a key,
/// then hashes the key material under that key. This is the first half.
#[must_use]
pub fn context_key() -> [u32; 8] {
    let context = SEED_DERIVATION_CONTEXT.as_bytes();
    assert!(context.len() <= 64, "single-block context");
    cv_of(compress(
        IV,
        block_of(context),
        0,
        context.len() as u32,
        CHUNK_START | CHUNK_END | ROOT | DERIVE_KEY_CONTEXT,
    ))
}

/// Host-side: chaining value after hashing `master ‖ signer` as key material.
///
/// The key material is `master (32 B) ‖ signer identity (32 B) ‖ epoch ‖
/// batch ‖ index`. Its first 64 bytes are the same for every key of a run,
/// so the host compresses them once here; the FPGA continues from this
/// value with [`seed_request`].
#[must_use]
pub fn prefix_cv(master: &[u8; 32], signer: &[u8; 32]) -> [u32; 8] {
    let mut first = [0; 64];
    first[..32].copy_from_slice(master);
    first[32..].copy_from_slice(signer);
    cv_of(compress(
        context_key(),
        decode_block(first),
        0,
        64,
        CHUNK_START | DERIVE_KEY_MATERIAL,
    ))
}

/// The batch namespace a slice works in.
///
/// Together with a key index, these three values name exactly one one-time
/// key. A fresh, durably allocated epoch per run is what keeps keys from
/// being regenerated (and reused) after a restart.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Namespace {
    /// From [`prefix_cv`]; secret.
    pub prefix_cv: [u32; 8],
    /// Durably allocated epoch.
    pub epoch: u64,
    /// Batch within the epoch.
    pub batch_id: u64,
}

/// `Seed`: the second (final) material block, `epoch ‖ batch ‖ index`.
///
/// 8 + 8 + 4 = 20 bytes, little-endian. The output's first 32 bytes are the
/// key's one-time seed.
#[must_use]
pub fn seed_request(ns: &Namespace, index: u32) -> Request {
    let mut material = [0; 20];
    material[..8].copy_from_slice(&ns.epoch.to_le_bytes());
    material[8..16].copy_from_slice(&ns.batch_id.to_le_bytes());
    material[16..].copy_from_slice(&index.to_le_bytes());
    Request {
        cv: ns.prefix_cv,
        block: block_of(&material),
        counter: 0,
        block_len: 20,
        flags: CHUNK_END | ROOT | DERIVE_KEY_MATERIAL,
    }
}

/// Prefix of the public `pk_nonce` derivation.
///
/// A different 4-byte prefix per purpose ("domain separation") makes the two
/// nonces unrelated even though both come from the same seed.
pub const PK_NONCE_PREFIX: u32 = 0x5eed;
/// Prefix of the signer-private message nonce derivation.
pub const NONCE_PREFIX: u32 = 0xc0ca;

/// `PkNonce` / `Nonce`: hash `LE32(prefix) ‖ seed`, keep 16 bytes.
#[must_use]
pub fn nonce_request(seed: &[u8; 32], prefix: u32) -> Request {
    // 4-byte prefix then the 32-byte seed: 36 bytes.
    let mut bytes = [0; 36];
    bytes[..4].copy_from_slice(&prefix.to_le_bytes());
    bytes[4..].copy_from_slice(seed);
    Request {
        cv: IV,
        block: block_of(&bytes),
        counter: 0,
        block_len: 36,
        flags: SINGLE_BLOCK_ROOT,
    }
}

/// `Xof(t)`: output block `t` of `BLAKE3-XOF(seed)`.
///
/// BLAKE3's extendable output: the same root compression run with counter
/// `t = 0, 1, 2, …` gives 64 fresh bytes each time. 20 blocks give the
/// 1,224 bytes of chain secrets (68 × 18).
#[must_use]
pub fn xof_request(seed: &[u8; 32], block: u8) -> Request {
    Request {
        cv: IV,
        block: block_of(seed),
        counter: u64::from(block),
        block_len: 32,
        flags: SINGLE_BLOCK_ROOT,
    }
}

/// `Chunk0(j)` (`chunk = 0`) or `Chunk1(m)` (`chunk = 1`) of the commitment.
///
/// `cv` is IV for the first block of a chunk and the previous block's
/// chaining value otherwise; `word` is the packer's output for this block.
///
/// `bytes` is the block length (64, or 24 for the last block), `first` /
/// `last` set the `CHUNK_START` / `CHUNK_END` flags. No `ROOT` flag: the two
/// chunks are joined by [`parent_request`].
#[must_use]
pub fn commitment_request(
    cv: [u32; 8],
    word: &[u8; 64],
    bytes: u32,
    chunk: u64,
    first: bool,
    last: bool,
) -> Request {
    Request {
        cv,
        block: decode_block(*word),
        counter: chunk,
        block_len: bytes,
        flags: if first { CHUNK_START } else { 0 } | if last { CHUNK_END } else { 0 },
    }
}

/// `Parent`: combine the two chunk chaining values into `pk_hash`.
#[must_use]
pub fn parent_request(cv0: [u32; 8], cv1: [u32; 8]) -> Request {
    // Block = CV of chunk 0 (8 words) ‖ CV of chunk 1 (8 words).
    let mut block = [0; 16];
    block[..8].copy_from_slice(&cv0);
    block[8..].copy_from_slice(&cv1);
    Request {
        cv: IV,
        block,
        counter: 0,
        block_len: 64,
        flags: PARENT | ROOT,
    }
}

/// `Merkle`: one batch-tree parent, `BLAKE3(left ‖ right)`.
///
/// The same request the [subtree builder](crate::slice_merkle) and the
/// [cert unit](crate::cert_unit) issue for every inner tree node.
#[must_use]
pub fn merkle_request(left: &Digest, right: &Digest) -> Request {
    let mut bytes = [0; 64];
    bytes[..32].copy_from_slice(left);
    bytes[32..].copy_from_slice(right);
    Request {
        cv: IV,
        block: decode_block(bytes),
        counter: 0,
        block_len: 64,
        flags: SINGLE_BLOCK_ROOT,
    }
}

/// `Message`: salted digit hash for a 16-byte message.
///
/// `pk_hash (32 B) ‖ private nonce (16 B) ‖ message (16 B)` fills one block
/// exactly. Its 64 output bytes become the 68 digits
/// ([`digits_kernel`](crate::slice_signer::digits_kernel) in hardware).
#[must_use]
pub fn message_request(pk_hash: &Digest, nonce: &Nonce, message: &[u8; crate::MESSAGE_BYTES]) -> Request {
    let mut bytes = [0; 64];
    bytes[..32].copy_from_slice(pk_hash);
    bytes[32..48].copy_from_slice(nonce);
    bytes[48..].copy_from_slice(&message[..16]);
    Request {
        cv: IV,
        block: decode_block(bytes),
        counter: 0,
        block_len: 64,
        // Profile 2 continues in [`message_tail_request`].
        flags: if crate::MESSAGE_BYTES == 16 { SINGLE_BLOCK_ROOT } else { CHUNK_START },
    }
}

/// Profile 2's second digest block: message bytes 16..64 (48 bytes),
/// chained from the first block's chaining value `cv` (its output words
/// 0..8), `CHUNK_END | ROOT`. Its output is the 64-byte XOF.
#[must_use]
pub fn message_tail_request(cv: [u32; 8], message: &[u8; crate::MESSAGE_BYTES]) -> Request {
    let mut bytes = [0; 64];
    bytes[..crate::MESSAGE_BYTES - 16].copy_from_slice(&message[16..]);
    Request {
        cv,
        block: decode_block(bytes),
        counter: 0,
        block_len: (crate::MESSAGE_BYTES - 16) as u32,
        flags: CHUNK_END | ROOT,
    }
}

/// The message digest (64 XOF words) as the slice computes it: one block in
/// profile 1, two chained blocks in profile 2.
#[must_use]
pub fn message_digest(pk_hash: &Digest, nonce: &Nonce, message: &[u8; crate::MESSAGE_BYTES]) -> [u32; 16] {
    let first = message_request(pk_hash, nonce, message).compress();
    if crate::MESSAGE_BYTES == 16 {
        return first;
    }
    message_tail_request(first[..8].try_into().unwrap(), message).compress()
}

/// Everything a slice produces for one key, built only from the requests above.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ModelKey {
    /// One-time seed (secret).
    pub seed: [u8; 32],
    /// Public chain salt.
    pub pk_nonce: Nonce,
    /// Signer-private message nonce.
    pub nonce: Nonce,
    /// Cache rows: `nodes[position][chain]`.
    ///
    /// Exactly what the four [cache banks](crate::cache_bank) hold for this
    /// key: bank `p` stores `nodes[p]`.
    pub nodes: [[[u8; ELEMENT_BYTES]; CHAINS]; POSITIONS],
    /// Endpoint commitment, the Merkle leaf.
    pub pk_hash: Digest,
    /// Every request issued for this key, in [`Op`](crate::slice_schedule::Op) order.
    pub requests: Vec<Request>,
}

/// The 1,240-byte commitment stream split into the packer's 20 blocks.
///
/// Returns `(bytes, length)` per block: 19 blocks of 64 bytes and a final
/// block of 24. This is the same split the hardware
/// [packer](crate::packer) makes with a 16-byte prefix.
#[must_use]
pub fn commitment_blocks(
    pk_nonce: &Nonce,
    ends: &[[u8; ELEMENT_BYTES]; CHAINS],
) -> Vec<(Vec<u8>, u32)> {
    // pk_nonce (16 B) then the 68 chain ends (18 B each).
    let mut stream = pk_nonce.to_vec();
    for end in ends {
        stream.extend_from_slice(end);
    }
    stream
        .chunks(64)
        .map(|c| (c.to_vec(), c.len() as u32))
        .collect()
}

/// Build key `index` of the namespace purely from slice requests.
///
/// Every BLAKE3 call goes through `issue`, which records the request and
/// returns its output, so `requests` is the complete list in order.
#[must_use]
pub fn model_key(ns: &Namespace, index: u32) -> ModelKey {
    let mut requests = Vec::new();
    // Record a request, then run it.
    let mut issue = |request: Request| {
        requests.push(request);
        request.compress()
    };
    let seed = bytes32(issue(seed_request(ns, index)));
    // First 16 output bytes (a nonce).
    let first16 = |words: [u32; 16]| -> Nonce {
        let bytes = encode_words(words);
        core::array::from_fn(|i| bytes[i])
    };
    let pk_nonce = first16(issue(nonce_request(&seed, PK_NONCE_PREFIX)));
    let nonce = first16(issue(nonce_request(&seed, NONCE_PREFIX)));
    // 20 XOF blocks = 1,280 bytes; the first 68 × 18 are the chain secrets.
    let mut xof = Vec::new();
    for block in 0..20 {
        xof.extend_from_slice(&encode_words(issue(xof_request(&seed, block))));
    }
    // Walk every chain: position 0 is the secret, each next position is one
    // salted Haraka chain step of the previous one.
    let mut nodes = [[[0; ELEMENT_BYTES]; CHAINS]; POSITIONS];
    for chain in 0..CHAINS {
        nodes[0][chain].copy_from_slice(&xof[ELEMENT_BYTES * chain..ELEMENT_BYTES * (chain + 1)]);
        for depth in 0..POSITIONS - 1 {
            nodes[depth + 1][chain] = dsig_chain(&nodes[depth][chain], &pk_nonce, chain, depth);
        }
    }
    // Hash pk_nonce ‖ chain ends (position 3) as BLAKE3 chunks 0 and 1.
    let blocks = commitment_blocks(&pk_nonce, &nodes[POSITIONS - 1]);
    assert_eq!(blocks.len(), 20);
    // Running chaining value of each chunk, starting from IV.
    let mut chunk_cv = [IV, IV];
    for (n, (bytes, length)) in blocks.iter().enumerate() {
        // Blocks 0..16 are chunk 0 (16 blocks), 16..20 are chunk 1 (4 blocks).
        let (chunk, within, size) = if n < 16 { (0, n, 16) } else { (1, n - 16, 4) };
        let mut word = [0; 64];
        word[..bytes.len()].copy_from_slice(bytes);
        let request = commitment_request(
            chunk_cv[chunk],
            &word,
            *length,
            chunk as u64,
            within == 0,
            within == size - 1,
        );
        chunk_cv[chunk] = cv_of(issue(request));
    }
    // Join the two chunks: this is the key's public commitment.
    let pk_hash = bytes32(issue(parent_request(chunk_cv[0], chunk_cv[1])));
    ModelKey {
        seed,
        pk_nonce,
        nonce,
        nodes,
        pk_hash,
        requests,
    }
}

/// Batch root from 128 leaves using only [`merkle_request`].
///
/// Hashes pairs level by level until one node is left. In hardware the
/// lower levels are done by each slice's subtree builder and the top levels
/// by the cert unit; the result must be the same.
#[must_use]
pub fn model_root(leaves: &[Digest]) -> Digest {
    let mut level = leaves.to_vec();
    while level.len() > 1 {
        level = level
            .chunks(2)
            .map(|pair| bytes32(merkle_request(&pair[0], &pair[1]).compress()))
            .collect();
    }
    level[0]
}

/// Proof that the request-level model equals the high-level reference.
#[cfg(test)]
mod tests {
    use super::*;
    use crate::reference::{PreparedBatch, message_digits};
    use ed25519_dalek::SigningKey;

    /// Build all 128 keys of one batch from requests; compare a sample of
    /// keys field by field, the message digits, and the batch root with the
    /// reference.
    #[test]
    fn slice_requests_reproduce_the_reference_batch_exactly() {
        // Fixed test secrets; never used outside tests.
        let master = [0x42; 32];
        let signer = SigningKey::from_bytes(&[7; 32]);
        let identity = signer.verifying_key().to_bytes();
        let (epoch, batch_id) = (5, 9);
        let mut batch = PreparedBatch::new(master, epoch, batch_id, &signer);
        let ns = Namespace {
            prefix_cv: prefix_cv(&master, &identity),
            epoch,
            batch_id,
        };
        let mut leaves = Vec::new();
        for index in 0..128 {
            let model = model_key(&ns, index);
            assert_eq!(
                model.requests.len(),
                44,
                "seed, 2 nonces, 20 XOF, 21 commitment"
            );
            leaves.push(model.pk_hash);
            // Check a spread of keys in full (every 37th, plus the last).
            if index % 37 == 0 || index == 127 {
                let key = batch.take_key_for_device(index as usize).unwrap();
                assert_eq!(model.pk_hash, key.public().pk_hash, "pk_hash {index}");
                assert_eq!(model.pk_nonce, key.public().pk_nonce, "pk_nonce {index}");
                assert_eq!(model.nonce, key.signing_nonce_for_device());
                assert_eq!(&model.nodes, key.cache_for_device(), "cache {index}");
                // The message slot reproduces the reference digit hash.
                let message: [u8; crate::MESSAGE_BYTES] = core::array::from_fn(|i| index as u8 ^ (i as u8 * 3));
                let xof = encode_words(message_digest(&model.pk_hash, &model.nonce, &message));
                assert_eq!(
                    crate::reference::digits_from_xof(&xof),
                    message_digits(&model.pk_hash, &model.nonce, &message)
                );
            }
        }
        assert_eq!(model_root(&leaves), batch.certificate().commitment.root);
    }
}