rhdl_dsig_scalable_core/ubft/

probe.rs

//! A uBFT stand-in for measuring [`super::UbftEngine`] on one card.
//!
//! # The problem
//!
//! The service's latency only means something when it is measured on the
//! card, at the card's clock, through the same RTL a uBFT replica would use.
//! But a replica needs peers, a network and a host stack; one card has none
//! of that. The probe plays the replica's part of the conversation:
//!
//! ```text
//!   probe ──sign request i──▶ UbftEngine ──frame i──▶ probe ──▶ HBM (frame i)
//!         ──verify request (header + frame i, message patched in)──▶
//!         ◀──verdict i── check: valid unless i was tampered, tag == i
//! ```
//!
//! Requests go one at a time with `gap` idle cycles between them, so every
//! request is isolated and the engine's own latency counters (see
//! [`super`]) time it. The frame goes to HBM so the host checks every
//! signature against the software reference and Ed25519.
//!
//! # Messages
//!
//! Request `i` signs the 16 bytes `i (LE64) ‖ !i (LE64)` with tag `i`. When
//! `tamper_every` is `t > 0`, every request with `i mod t == t − 1` is
//! verified with message byte 0 flipped, and must be rejected.
//!
//! In DSig profile 2 (`DSIG_MESSAGE_BYTES=64`) request `i` signs a 48-byte
//! context zero-extended to 64 bytes: `i ‖ !i`, then those 16 bytes XOR
//! `0xa5`, then XOR `0x3c` ([`probe_message_kernel`]). The sign request is
//! in layout v2 (tag 0..8, context 8..56) and the verify record is 27
//! beats: the frame's last beat carries the message's first 22 bytes, and
//! an appended beat the other 42 (as `crate::verify::record`).
//!
//! # Feeding the verify request at full rate
//!
//! The frame is kept in a 32-row block RAM while it arrives. During the
//! verify request the RAM is read one row ahead: the read address is always
//! the row that will be presented next cycle, so a taken beat is replaced by
//! the next one without a bubble.

use super::{Axis64, Axis512};
use crate::slice_signer::FrameBeat;
use rhdl::prelude::*;
use rhdl_fpga::core::{
    dff::DFF,
    ram::synchronous::{In as RamIn, SyncBRAM, Write as RamWrite},
};

/// Probe arguments.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct ProbeArgs {
    /// Requests to make.
    pub count: b32,
    /// Idle cycles between one verdict and the next sign request.
    pub gap: b32,
    /// Key slot the verify requests name.
    pub slot: b4,
    /// Tamper with every `tamper_every`-th verification (0: never).
    pub tamper_every: b32,
    /// Start (once the engine runs).
    pub go: bool,
}

/// Probe inputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct ProbeIn {
    /// Arguments.
    pub args: ProbeArgs,
    /// The engine's `s_axis_sign` `tready`.
    pub sign_ready: bool,
    /// The engine's `m_axis_frame`.
    pub frame: Axis512,
    /// The engine's `s_axis_verify` `tready`.
    pub verify_ready: bool,
    /// The engine's `m_axis_verdict`.
    pub verdict: Axis64,
    /// The HBM writer takes the presented beat.
    pub writer_ready: bool,
}

/// Probe outputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct ProbeOut {
    /// Sign request to the engine.
    pub sign: Axis512,
    /// Frame `tready` to the engine.
    pub frame_ready: bool,
    /// Verify request to the engine.
    pub verify: Axis512,
    /// Verdict `tready` to the engine.
    pub verdict_ready: bool,
    /// Frame beat to the HBM writer.
    pub beat: FrameBeat,
    /// Requests whose verdict came back.
    pub done: b32,
    /// Verdicts that matched the expectation (valid, or rejected when
    /// tampered) and carried the right tag.
    pub matched: b32,
    /// Verdicts that did not.
    pub mismatched: b32,
    /// The first mismatching verdict word (0 if none).
    pub first_bad: b64,
}

/// Phases of one request.
const IDLE: b3 = b3(0);
/// Present the sign request.
const SIGN: b3 = b3(1);
/// Receive the frame (and pass it to HBM).
const FRAME: b3 = b3(2);
/// Present the verify header.
const HEADER: b3 = b3(3);
/// Present the frame beats.
const BODY: b3 = b3(4);
/// Wait for the verdict.
const VERDICT: b3 = b3(5);
/// The frame's last beat number.
const LAST_BEAT: b5 = b5(25);
/// Byte of beat 25 where the record's message starts (1642 − 25·64).
const MESSAGE_AT: usize = 42;
/// Profile 2: send the record's 27th beat.
const TAIL: b3 = b3(6);
/// DSig profile 2 (64-byte messages; see the module notes).
const P2: bool = crate::MESSAGE_BYTES == 64;
/// Bytes of the signed message.
const MSG: usize = crate::MESSAGE_BYTES;
// Loop bounds that are zero in the other profile, so no index reaches past
// a 16-byte message in profile 1.
/// Profile 1's message bytes in beat 25 and in the sign request.
const P1_MSG: usize = if P2 { 0 } else { 16 };
/// Profile 2's 48-byte context in the sign request.
const P2_CTX: usize = if P2 { 48 } else { 0 };
/// Profile 2's message bytes in beat 25 (1642..1664).
const P2_HEAD: usize = if P2 { 22 } else { 0 };
/// Profile 2's message bytes in the appended beat (1664..1706).
const P2_TAIL: usize = if P2 { 42 } else { 0 };
/// Profile 2's context bytes 16..48 (two derived 16-byte runs).
const P2_RUN: usize = if P2 { 16 } else { 0 };
/// Byte of the sign request where the tag starts.
const SIGN_TAG_AT: usize = if P2 { 0 } else { 16 };
/// Beat 25's first byte after the message: zeros from here.
const ZERO_FROM: usize = MESSAGE_AT + P1_MSG + P2_HEAD;

/// Resettable probe state.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
#[doc(hidden)]
pub struct ProbeState {
    phase: b3,
    /// Current request number.
    i: b32,
    /// Beat number within the frame.
    beat: b5,
    /// Idle cycles left before the next request.
    wait: b32,
    /// The current request is tampered.
    tampered: bool,
    /// Requests since the last tampered one.
    since: b32,
    done: b32,
    matched: b32,
    mismatched: b32,
    first_bad: b64,
}

/// The probe.
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct UbftProbe {
    /// Phases, counters.
    state: DFF<ProbeState>,
    /// The current frame, one beat per row.
    frame: SyncBRAM<[b8; 64], 5>,
}

impl Default for UbftProbe {
    /// Idle.
    fn default() -> Self {
        Self {
            state: DFF::new(ProbeState::default()),
            frame: SyncBRAM::default(),
        }
    }
}

impl SynchronousIO for UbftProbe {
    type I = ProbeIn;
    type O = ProbeOut;
    type Kernel = ubft_probe_kernel;
}

/// The message of request `i`: `i ‖ !i`, little endian (16 bytes); in
/// profile 2 followed by those bytes XOR `0xa5` and XOR `0x3c`, then 16 zero
/// bytes (a 48-byte context zero-extended to 64).
#[allow(clippy::needless_range_loop)]
#[kernel]
pub fn probe_message_kernel(i: b32) -> [b8; MSG] {
    let x: b64 = i.resize();
    let y: b64 = !x;
    let mut m = [b8(0); MSG];
    for k in 0..8 {
        m[k] = (x >> ((8 * k) as u128)).resize();
        m[8 + k] = (y >> ((8 * k) as u128)).resize();
    }
    for k in 0..P2_RUN {
        m[16 + k] = m[k] ^ b8(0xa5);
        m[32 + k] = m[k] ^ b8(0x3c);
    }
    m
}

/// The probe's logic.
#[allow(clippy::needless_range_loop, clippy::too_many_lines)]
#[kernel]
pub fn ubft_probe_kernel(_clock_reset: ClockReset, input: ProbeIn, q: UbftProbeQ) -> (ProbeOut, UbftProbeD) {
    let mut s = q.state;
    let args = input.args;
    let message = probe_message_kernel(q.state.i);
    let mut sign = Axis512 {
        valid: false,
        data: [b8(0); 64],
        last: true,
    };
    let mut verify = Axis512 {
        valid: false,
        data: [b8(0); 64],
        last: false,
    };
    let mut frame_ready = false;
    let mut beat = FrameBeat {
        valid: false,
        data: input.frame.data,
        last: input.frame.last,
    };
    let mut write = RamWrite::<[b8; 64], 5> {
        addr: q.state.beat,
        value: input.frame.data,
        enable: false,
    };
    // The row presented next cycle (see the module notes).
    let mut read_addr = q.state.beat;

    if q.state.phase == IDLE {
        if args.go && q.state.i < args.count {
            if q.state.wait == b32(0) {
                s.phase = SIGN;
                // `since` counts requests since the last tampered one:
                // request i is tampered when i mod t == t - 1.
                let next = q.state.since + b32(1);
                let tamper = args.tamper_every != b32(0) && next == args.tamper_every;
                s.tampered = tamper;
                s.since = if tamper { b32(0) } else { next };
            } else {
                s.wait = q.state.wait - b32(1);
            }
        }
    } else if q.state.phase == SIGN {
        // Profile 1: message 0..16, tag 16..24. Profile 2 (layout v2): tag
        // 0..8, the 48-byte context 8..56.
        for k in 0..P1_MSG {
            sign.data[k] = message[k];
        }
        for k in 0..P2_CTX {
            sign.data[8 + k] = message[k];
        }
        for k in 0..4 {
            sign.data[SIGN_TAG_AT + k] = (q.state.i >> ((8 * k) as u128)).resize();
        }
        sign.valid = true;
        if input.sign_ready {
            s.phase = FRAME;
            s.beat = b5(0);
        }
    } else if q.state.phase == FRAME {
        frame_ready = input.writer_ready;
        beat.valid = input.frame.valid && input.writer_ready;
        if input.frame.valid && input.writer_ready {
            write.enable = true;
            if q.state.beat == LAST_BEAT {
                s.phase = HEADER;
                s.beat = b5(0);
                read_addr = b5(0);
            } else {
                s.beat = q.state.beat + b5(1);
            }
        }
    } else if q.state.phase == HEADER {
        verify.valid = true;
        verify.data[0] = args.slot.resize();
        for k in 0..4 {
            verify.data[4 + k] = (q.state.i >> ((8 * k) as u128)).resize();
        }
        read_addr = b5(0);
        if input.verify_ready {
            s.phase = BODY;
        }
    } else if q.state.phase == BODY {
        verify.valid = true;
        verify.data = q.frame;
        let is_last = q.state.beat == LAST_BEAT;
        if is_last {
            // The record has the message where the frame has the tag
            // (profile 2: its first 22 bytes; the rest follow in TAIL).
            for k in 0..P1_MSG {
                verify.data[MESSAGE_AT + k] = message[k];
            }
            for k in 0..P2_HEAD {
                verify.data[MESSAGE_AT + k] = message[k];
            }
            for k in ZERO_FROM..64 {
                verify.data[k] = b8(0);
            }
            if q.state.tampered {
                verify.data[MESSAGE_AT] = message[0] ^ b8(1);
            }
        }
        verify.last = is_last && !P2;
        if input.verify_ready {
            if is_last {
                s.phase = if P2 { TAIL } else { VERDICT };
            } else {
                s.beat = q.state.beat + b5(1);
                read_addr = q.state.beat + b5(1);
            }
        }
    } else if q.state.phase == TAIL {
        // Profile 2's 27th record beat: message bytes 22..64, then zeros.
        verify.valid = true;
        for k in 0..P2_TAIL {
            verify.data[k] = message[P2_HEAD + k];
        }
        verify.last = true;
        if input.verify_ready {
            s.phase = VERDICT;
        }
    } else {
        // VERDICT
        if input.verdict.valid {
            let word = input.verdict.data;
            let valid = (word & b64(0xff)) == b64(0x80);
            let tag_ok = (word >> 32) == q.state.i.resize::<64>();
            let ok = tag_ok && (valid != q.state.tampered);
            if ok {
                s.matched = q.state.matched + b32(1);
            } else {
                s.mismatched = q.state.mismatched + b32(1);
                if q.state.mismatched == b32(0) {
                    s.first_bad = word;
                }
            }
            s.done = q.state.done + b32(1);
            s.i = q.state.i + b32(1);
            s.wait = args.gap;
            s.phase = IDLE;
        }
    }

    let d = UbftProbeD {
        state: s,
        frame: RamIn::<[b8; 64], 5> { read_addr, write },
    };
    (
        ProbeOut {
            sign,
            frame_ready,
            verify,
            verdict_ready: q.state.phase == VERDICT,
            beat,
            done: q.state.done,
            matched: q.state.matched,
            mismatched: q.state.mismatched,
            first_bad: q.state.first_bad,
        },
        d,
    )
}