rhdl_dsig_scalable_core/

chain_lane.rs

//! The chain hash: Haraka-512, BLAKE3 or SHA-512, chosen at compile time.
//!
//! # Why there is a choice
//!
//! The chain hash decides most of the signer's area (see the table below),
//! so the crate can be built with any of three DSig-compatible chain hashes
//! and each build measured on its own. Haraka-512 is made of AES rounds,
//! which map well to FPGA tables. This module is the single switch: it names the
//! lane type ([`ChainLane`]), its latency ([`LANE_LATENCY`]), the software
//! reference ([`software_chain`]) and the profile name ([`PROFILE`]) for the
//! hash picked by the `DSIG_CHAIN` build variable (`build.rs`). Nothing else in the crate needs to know
//! which hash was chosen.
//!
//! A W-OTS+ chain step hashes one 64-byte *chain block*
//! ([`dsig_chain_block`](crate::haraka::dsig_chain_block): a salted 16-byte
//! nonce, the 18-byte node, zeros) and keeps 18 bytes. That is 204 of the ~251
//! hash calls in a signature, so the chain hash decides most of the area. The
//! three DSig-compatible choices:
//!
//! | Build variable | Profile | Chain step | Lane hardware | Latency |
//! |---|---|---|---|---|
//! | `DSIG_CHAIN=haraka` (default) | `DSIG_FPGA_W4_HARAKA_BLAKE3_V1` | `Haraka-512(block)` truncated, mid bytes | [`TableChainStepLane`](crate::chain_step::TableChainStepLane), 494 S-boxes | 20 |
//! | `DSIG_CHAIN=blake3` | `DSIG_FPGA_W4_BLAKE3CHAIN_BLAKE3_V1` | `BLAKE3(block)[..18]` (one compression) | [`Blake3ChainLane`] | 28 |
//! | `DSIG_CHAIN=sha512` | `DSIG_FPGA_W4_SHA512CHAIN_BLAKE3_V1` | `SHA-512(block)[..18]` (one padded block) | [`Sha512ChainLane`] | 82 |
//!
//! Everything else (seeds, XOF, commitment, Merkle, message digest) stays
//! BLAKE3 in every profile. Each profile is a different signature scheme:
//! signatures from one never verify under another, and [`PROFILE`] names the
//! one compiled in.
//!
//! Every lane has the same ports as the Haraka lane
//! ([`ChainStepInput`] → [`ChainStepOutput`]) and publishes its latency as
//! [`LANE_LATENCY`], which the chain engine and the factory's timetable use.
//!
//! # How the choice spreads through the slice
//!
//! ```text
//!   chain-* feature ─▶ ChainLane, LANE_LATENCY
//!        │                 │
//!        │                 ▼
//!        │     slice_chain: SLICE_CHAIN_LATENCY = 3 × LANE_LATENCY
//!        │                 │
//!        │                 ▼
//!        │     slice_factory: END_DELAY = SLICE_CHAIN_LATENCY + 2
//!        │                 ├─▶ SCHEDULE (where commitment ops can go)
//!        │                 ├─▶ PACK_HISTORY (older pk_nonces kept)
//!        └───────────────▶ └─▶ CTX_BITS (5 with DSIG_CHAIN=sha512, else 4)
//! ```
//!
//! With SHA-512 the chain ends of a key emerge about three key periods after
//! its chains start. By then newer keys are feeding the engine, which is why
//! the factory keeps older `pk_nonce`s and needs 32 key contexts instead of
//! 16 (see [`crate::slice_factory::PACK_HISTORY`] and
//! [`crate::slice_factory::CTX_BITS`]).

use crate::blake3_core::{CompressionInput, InlineCompressionPipeline};
use crate::cert_unit::FLAGS_SINGLE_BLOCK;
use crate::chain_step::{ChainStepInput, ChainStepOutput, STEP_OUTPUT_BYTES, chain_step_block_kernel};
use rhdl::prelude::*;
use rhdl_fpga::core::dff::DFF;
use rhdl_sha512_pipelined::{LATENCY as SHA_LATENCY, Sha512Pipeline, ShaIn};

// Exactly one chain hash is compiled in: `build.rs` reads `DSIG_CHAIN`
// (haraka, blake3 or sha512; default haraka), rejects anything else, and sets
// `cfg(dsig_chain = "…")` to that one name.

/// The compiled-in DSig profile.
///
/// A profile name identifies the whole signature scheme (w = 4, the chain
/// hash, BLAKE3 for everything else). Signatures made under one profile
/// never verify under another.
/// Haraka is the default and the experimental profile this project
/// preserves.
#[cfg(dsig_chain = "haraka")]
pub const PROFILE: &str = "DSIG_FPGA_W4_HARAKA_BLAKE3_V1";
/// The compiled-in DSig profile.
#[cfg(dsig_chain = "blake3")]
pub const PROFILE: &str = "DSIG_FPGA_W4_BLAKE3CHAIN_BLAKE3_V1";
/// The compiled-in DSig profile.
#[cfg(dsig_chain = "sha512")]
pub const PROFILE: &str = "DSIG_FPGA_W4_SHA512CHAIN_BLAKE3_V1";

/// The lane type the chain engine instantiates three times per slice.
///
/// `MASK` is an area knob for the Haraka T-table lane (which AES rounds use
/// table ROMs); the BLAKE3 and SHA-512 lanes accept it and ignore it, so the
/// rest of the crate has one signature for all three.
#[cfg(dsig_chain = "haraka")]
pub type ChainLane<const MASK: usize> = crate::chain_step::TableChainStepLane<MASK>;
/// The lane type the chain engine instantiates three times per slice.
#[cfg(dsig_chain = "blake3")]
pub type ChainLane<const MASK: usize> = Blake3ChainLane<MASK>;
/// The lane type the chain engine instantiates three times per slice.
#[cfg(dsig_chain = "sha512")]
pub type ChainLane<const MASK: usize> = Sha512ChainLane<MASK>;

/// Cycles from a lane's input to its output.
///
/// Haraka: 20 (two pipeline stages per AES round, 10 rounds).
#[cfg(dsig_chain = "haraka")]
pub const LANE_LATENCY: usize = crate::chain_step::CHAIN_STEP_LATENCY;
/// Cycles from a lane's input to its output.
///
/// BLAKE3: 28, the compression pipeline's depth.
#[cfg(dsig_chain = "blake3")]
pub const LANE_LATENCY: usize = crate::blake3_core::PIPELINE_STAGES;
/// Cycles from a lane's input to its output.
///
/// SHA-512: 82, the depth of the pipelined core from the
/// `rhdl_sha512_pipelined` crate.
#[cfg(dsig_chain = "sha512")]
pub const LANE_LATENCY: usize = SHA_LATENCY;

/// Software chain step for the compiled-in profile (the reference).
///
/// Input: the 64-byte chain block. Output: the next 18-byte chain node.
/// Tests compare every hardware lane against this function bit for bit.
#[must_use]
pub fn software_chain(block: &[u8; 64]) -> [u8; STEP_OUTPUT_BYTES] {
    // Haraka: the 18 middle bytes of Haraka-512 (see `haraka`).
    #[cfg(dsig_chain = "haraka")]
    {
        crate::haraka::mid_haraka512(block)
    }
    // BLAKE3: the first 18 bytes of the standard hash.
    #[cfg(dsig_chain = "blake3")]
    {
        blake3::hash(block).as_bytes()[..STEP_OUTPUT_BYTES].try_into().unwrap()
    }
    // SHA-512: the first 18 bytes of the digest.
    #[cfg(dsig_chain = "sha512")]
    {
        use sha2::Digest;
        sha2::Sha512::digest(block)[..STEP_OUTPUT_BYTES].try_into().unwrap()
    }
}

// ---------------------------------------------------------------- BLAKE3 lane

/// Little-endian words of a 64-byte block.
///
/// A thin wrapper around
/// [`words_from_bytes_kernel`](crate::slice_factory::words_from_bytes_kernel),
/// because BLAKE3 reads its message block as little-endian 32-bit words.
#[kernel]
pub fn le_words_kernel(block: [b8; 64]) -> [b32; 16] {
    crate::slice_factory::words_from_bytes_kernel(block)
}

/// A chain step as one BLAKE3 compression: the standard single-block hash of
/// the 64-byte chain block (`CHUNK_START | CHUNK_END | ROOT`, counter 0),
/// truncated to 18 bytes. One step per clock, [`PIPELINE_STAGES`](crate::blake3_core::PIPELINE_STAGES) cycles.
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct Blake3ChainLane<const MASK: usize> {
    /// The same 28-stage BLAKE3 compression pipeline the factory uses. Its
    /// 32-bit tag already fits the chain tag, so no extra delay line is needed.
    core: InlineCompressionPipeline,
}

/// A BLAKE3 lane with an empty pipeline.
impl<const MASK: usize> Default for Blake3ChainLane<MASK> {
    /// Builds the pipeline.
    fn default() -> Self {
        Self {
            core: InlineCompressionPipeline,
        }
    }
}

/// Gives the BLAKE3 lane the same ports as the Haraka lane.
impl<const MASK: usize> SynchronousIO for Blake3ChainLane<MASK> {
    /// Salted nonce, node, tag, valid.
    type I = ChainStepInput;
    /// Next node, tag, valid, ready.
    type O = ChainStepOutput;
    /// The wiring, [`blake3_chain_lane_kernel`].
    type Kernel = blake3_chain_lane_kernel<MASK>;
}

/// Build the block, compress, keep the first 18 output bytes.
///
/// The input enters the pipeline this cycle; the matching output appears
/// [`PIPELINE_STAGES`](crate::blake3_core::PIPELINE_STAGES) (28) cycles later. `ready` is always true: there are
/// no tables to load.
#[allow(clippy::needless_range_loop)]
#[kernel]
pub fn blake3_chain_lane_kernel<const MASK: usize>(
    _cr: ClockReset,
    input: ChainStepInput,
    q: Blake3ChainLaneQ<MASK>,
) -> (ChainStepOutput, Blake3ChainLaneD<MASK>) {
    // The 64-byte chain block: salted nonce, node, zeros.
    let block = chain_step_block_kernel(input.salted_nonce, input.secret);
    // One-block root hash from the IV, counter 0, full 64-byte block.
    let d = Blake3ChainLaneD::<MASK> {
        core: CompressionInput {
            cv: crate::slice_factory::IV_BITS,
            block: le_words_kernel(block),
            counter_low: b32(0),
            counter_high: b32(0),
            block_len: b32(64),
            flags: FLAGS_SINGLE_BLOCK,
            tag: input.tag,
            valid: input.valid,
        },
    };
    // Output side: the pipeline's result for the input of 28 cycles ago.
    let bytes = crate::slice_factory::bytes_from_words_kernel(q.core.words);
    // The next node is the first 18 bytes of the hash.
    let mut node = [b8(0); STEP_OUTPUT_BYTES];
    for b in 0..STEP_OUTPUT_BYTES {
        node[b] = bytes[b];
    }
    (
        ChainStepOutput {
            node,
            tag: q.core.tag,
            valid: q.core.valid,
            ready: true,
        },
        d,
    )
}

// ---------------------------------------------------------------- SHA-512 lane

/// The single padded SHA-512 block of a 64-byte message, big-endian words:
/// the message, `0x80`, zeros, and the 128-bit length 512.
///
/// SHA-512 works on 128-byte blocks. A 64-byte message plus its padding
/// fits in exactly one block, so one pass of the core is one chain step.
/// Combinational.
#[kernel]
pub fn sha512_block_kernel(message: [b8; 64]) -> [b64; 16] {
    let mut words = [b64(0); 16];
    // Words 0..8: the message, eight bytes per word, first byte highest.
    for w in 0..8 {
        words[w] = (message[8 * w].resize::<64>() << 56)
            | (message[8 * w + 1].resize::<64>() << 48)
            | (message[8 * w + 2].resize::<64>() << 40)
            | (message[8 * w + 3].resize::<64>() << 32)
            | (message[8 * w + 4].resize::<64>() << 24)
            | (message[8 * w + 5].resize::<64>() << 16)
            | (message[8 * w + 6].resize::<64>() << 8)
            | message[8 * w + 7].resize::<64>();
    }
    // Padding: a single 1 bit right after the message, zeros, then the
    // message length in bits (64 × 8 = 512) in the last word.
    words[8] = b64(0x8000_0000_0000_0000);
    words[15] = b64(512);
    words
}

/// A chain step as one SHA-512 block on the shared pipelined core
/// ([`rhdl_sha512_pipelined`]), truncated to 18 bytes. One step per clock,
/// [`SHA_LATENCY`] cycles. The 32-bit chain tag rides a parallel delay line
/// because the core's tag is 16 bits.
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct Sha512ChainLane<const MASK: usize> {
    /// The pipelined SHA-512 core from `rhdl_sha512_pipelined`.
    core: Sha512Pipeline,
    /// Delay line for the 32-bit chain tag, [`SHA_LATENCY`] stages, so the tag
    /// leaves together with its digest.
    tag: [DFF<b32>; SHA_LATENCY],
}

/// A SHA-512 lane with an empty pipeline and zeroed tag line.
impl<const MASK: usize> Default for Sha512ChainLane<MASK> {
    /// Builds the core and the tag delay line.
    fn default() -> Self {
        Self {
            core: Sha512Pipeline::default(),
            tag: core::array::from_fn(|_| DFF::new(b32(0))),
        }
    }
}

/// Gives the SHA-512 lane the same ports as the Haraka lane.
impl<const MASK: usize> SynchronousIO for Sha512ChainLane<MASK> {
    /// Salted nonce, node, tag, valid.
    type I = ChainStepInput;
    /// Next node, tag, valid, ready.
    type O = ChainStepOutput;
    /// The wiring, [`sha512_chain_lane_kernel`].
    type Kernel = sha512_chain_lane_kernel<MASK>;
}

/// Build and pad the block, hash, keep the first 18 digest bytes.
///
/// The input enters the core this cycle; its digest and tag appear
/// [`SHA_LATENCY`] (82) cycles later. `ready` is always true.
#[allow(clippy::needless_range_loop)]
#[kernel]
pub fn sha512_chain_lane_kernel<const MASK: usize>(
    _cr: ClockReset,
    input: ChainStepInput,
    q: Sha512ChainLaneQ<MASK>,
) -> (ChainStepOutput, Sha512ChainLaneD<MASK>) {
    // The 64-byte chain block: salted nonce, node, zeros.
    let block = chain_step_block_kernel(input.salted_nonce, input.secret);
    // Shift the tag delay line by one stage.
    let mut tag = q.tag;
    tag[0] = input.tag;
    for k in 1..SHA_LATENCY {
        tag[k] = q.tag[k - 1];
    }
    let d = Sha512ChainLaneD::<MASK> {
        // Start from the standard SHA-512 IV; one block, no chaining. The
        // core's own 16-bit tag is unused (the delay line carries ours).
        core: ShaIn {
            valid: input.valid,
            tag: b16(0),
            block: sha512_block_kernel(block),
            use_iv: true,
            chain: [b64(0); 8],
        },
        tag,
    };
    // The finished hash state (eight 64-bit words) for the input 82 cycles ago.
    let state = q.core.done.state;
    let mut node = [b8(0); STEP_OUTPUT_BYTES];
    // Digest bytes are big-endian within each word: bytes 0..16 from words
    // 0 and 1, bytes 16 and 17 from the top of word 2.
    for w in 0..2 {
        for k in 0..8 {
            node[8 * w + k] = (state[w] >> (56 - 8 * k as u128)).resize();
        }
    }
    node[16] = (state[2] >> 56).resize();
    node[17] = (state[2] >> 48).resize();
    (
        ChainStepOutput {
            node,
            tag: q.tag[SHA_LATENCY - 1],
            valid: q.core.done.valid,
            ready: true,
        },
        d,
    )
}