rhdl_dsig_scalable_core/

ed25519.rs

#![doc = include_str!("../docs/certificate-bridge.md")]
//!
//! ## Where this bridge sits, and why it is so thin
//!
//! Every batch of 128 one-time keys needs one Ed25519 signature over its
//! 64-byte envelope (see [`crate::certificate`]). The Ed25519 math is large
//! and was already built and tested by a separate project, so DSig reuses
//! that core unchanged (vendored as `rhdl_ed25519_scalable_core`) instead of
//! writing its own. This file is only the plug between the two.
//!
//! ```text
//!   crate::cert_unit (bookkeeping: tags, ≤ 32 in flight, in-order delivery)
//!        │ CertificateSignerInput: key control + epoch, batch_id, root, tag
//!        ▼
//!   ┌──────────── CertificateSigner (this file, no state of its own) ───────┐
//!   │ certificate_request(): batch_commitment_words() → SignRequest          │
//!   │        │ CachedSignIn                                                 │
//!   │        ▼                                                              │
//!   │ Ed25519SignCoreSmall  (SHA-512, key expansion, scalar multiply)       │
//!   └────────┬──────────────────────────────────────────────────────────────┘
//!            │ CachedSignOut: ready, valid pulse, signature, tag, occupancy,
//!            ▼                internal_error (forwarded unchanged)
//!   crate::cert_unit
//! ```
//!
//! Why no registers or queues here? Every extra stage would be a new place
//! where a request could be lost, duplicated or reordered, and a new piece of
//! state that a reset could leave half-finished. Keeping the bridge stateless
//! means all policy (credits, fault latching, tag records, draining) lives in
//! one place, [`crate::cert_unit`], where it can be reviewed as a whole.
//!
//! Figures: the core cost 25,383 CLB LUTs in context on the routed `slices-2`
//! link (the planner's [`ED25519_LUT`](crate::config::ED25519_LUT)) and
//! 25,911 LUTs and 248 DSPs inside the certificate unit of build v13 (routed,
//! measured). It finishes one signature per ~895 cycles with at least 32
//! requests in flight (Ed25519 project, simulation), far more than the one
//! certificate per 128 signatures, about 94,000 per second at 12M signatures
//! per second, that the engine needs.
#![forbid(unsafe_code)]

use crate::certificate::batch_commitment_words;
use rhdl::prelude::*;
use rhdl_ed25519_scalable_core::{CachedSignIn, Ed25519SignCoreSmall, SignRequest, Words512};

/// Unmodified cached-signer output, including unbackpressured completion and fault.
pub use rhdl_ed25519_scalable_core::CachedSignOut;
/// Actual Ed25519 seed/public-key word type used at the bridge boundary.
pub use rhdl_ed25519_scalable_core::ScalarWords;

/// Key-control signals and one complete DSig certificate request.
///
/// This is the bundle of wires the certificate unit drives every clock. The
/// key-control fields (`load_key_valid`, `key_seed`, `clear_key`) manage the
/// one Ed25519 signing key the core caches; the request fields (`valid`,
/// `epoch`, `batch_id`, `root`, `tag`) describe one envelope to sign.
///
/// A request transfers only on `valid && output.ready`. The caller binds its
/// full namespace/root and trusted signer identity to a unique outstanding
/// [`Self::tag`], and reserves completion capacity before asserting `valid`.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct CertificateSignerInput {
    /// Accept a secret seed only while `output.load_key_ready` is asserted.
    ///
    /// One-bit strobe: high for the clock on which `key_seed` is offered.
    pub load_key_valid: bool,
    /// Secret 32-byte Ed25519 seed in four little-endian 64-bit words.
    ///
    /// Write-only: the core never outputs it, only the derived public key.
    pub key_seed: ScalarWords,
    /// Clear the cached key only after every accepted request has retired.
    ///
    /// Keep `valid` and `load_key_valid` low during clear. This is not a cancel
    /// handshake and does not erase every intermediate pipeline or memory bit.
    pub clear_key: bool,
    /// Marks the namespace/root/tag as a pending signing request.
    ///
    /// Hold the request fields stable while `valid` is high and
    /// `output.ready` is low.
    pub valid: bool,
    /// Durably allocated epoch, included in the signed DSig envelope.
    pub epoch: b64,
    /// Batch identity within the epoch, included in the signed envelope.
    pub batch_id: b64,
    /// Completed 128-key Merkle root, in its original 32-byte order.
    pub root: [b8; 32],
    /// Opaque 16-bit routing tag; it is outside the signed message.
    ///
    /// Never truncate an epoch/batch identity into this field as a substitute
    /// for a full outstanding-request record. Reject unknown or reused tags.
    pub tag: b16,
}

impl Default for CertificateSignerInput {
    /// All strobes low and all data zero: an idle input that requests nothing.
    fn default() -> Self {
        Self {
            load_key_valid: false,
            key_seed: ScalarWords { words: [b64(0); 4] },
            clear_key: false,
            valid: false,
            epoch: b64(0),
            batch_id: b64(0),
            root: [b8(0); 32],
            tag: b16(0),
        }
    }
}

/// Pack the actual DSig fixed-64 message into the actual Ed25519 request type.
///
/// Calls [`batch_commitment_words`] directly. No host prehash, duplicated
/// domain/profile constants, endian conversion, or intermediate register is
/// inserted. The returned tag is routing metadata, not a signed field.
///
/// Inputs: 64-bit `epoch` and `batch_id`, the 32-byte `root` and the 16-bit
/// `tag`. Output: the core's `SignRequest` (eight 64-bit message words plus
/// the tag). Timing: combinational, zero cycles.
#[kernel]
pub fn certificate_request(epoch: b64, batch_id: b64, root: [b8; 32], tag: b16) -> SignRequest {
    SignRequest {
        message: Words512 {
            words: batch_commitment_words(epoch, batch_id, root),
        },
        tag,
    }
}

/// Direct RHDL composition of one DSig packer and exactly one cached signer.
///
/// The sole stateful child is the Ed25519 project's scalable RHDL core,
/// `Ed25519SignCoreSmall` = `Ed25519SignCore<1, 1, 1, 0>` (vendored in
/// `vendor/ed25519-scalable-core`; one
/// fixed-base machine, one SHA-512 ring, one scalar ring, 128 contexts). It
/// accepts up to 32 requests in flight and may finish them out of order. This
/// wrapper adds no FIFO, register, controller, admission policy, credit state,
/// fault latch, or output backpressure. Its output is [`CachedSignOut`] itself.
///
/// The caller must reserve every completion slot in advance, latch any
/// `internal_error` before processing a coincident `valid` pulse, bind the
/// returned tag to the full namespace/root/signer identity, and drain before
/// clearing. Quarantine outstanding requests across reset; neither reset nor
/// clear proves cancellation or grants permission to reuse a DSig allocation.
/// No bank may be marked certified solely because this wrapper emitted bytes.
#[derive(Clone, Debug, Default, Synchronous, SynchronousDQ)]
pub struct CertificateSigner {
    /// The vendored Ed25519 signing core; the only stateful part.
    signer: Ed25519SignCoreSmall,
}

impl SynchronousIO for CertificateSigner {
    /// Input: key control plus one certificate request.
    type I = CertificateSignerInput;
    /// Output: the core's own output, unchanged.
    type O = CachedSignOut;
    /// The wiring kernel that runs every clock.
    type Kernel = certificate_signer_kernel;
}

/// Stateless wiring for [`CertificateSigner`]; clock/reset reaches its child
/// through RHDL's synchronous hierarchy, and every child output is forwarded.
///
/// In RHDL a component's kernel is called every clock with the inputs `input`
/// and the children's current outputs `q`, and returns this component's
/// outputs plus the children's next inputs `d`. Here `d` is the input
/// mapped field by field (the request packed by [`certificate_request`]) and
/// the output is `q.signer` as is. Timing: combinational; all latency is the
/// core's.
#[kernel]
pub fn certificate_signer_kernel(
    _clock_reset: ClockReset,
    input: CertificateSignerInput,
    q: CertificateSignerQ,
) -> (CachedSignOut, CertificateSignerD) {
    // Next inputs for the core: key control passes through, the request is packed.
    let d = CertificateSignerD {
        signer: CachedSignIn {
            load_key_valid: input.load_key_valid,
            key_seed: input.key_seed,
            clear_key: input.clear_key,
            valid: input.valid,
            request: certificate_request(input.epoch, input.batch_id, input.root, input.tag),
        },
    };
    // Forward the core's output untouched, faults and all.
    (q.signer, d)
}

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

    /// The kernel forwards every control bit and every child output, even an
    /// illegal mix, without masking anything.
    #[test]
    fn wiring_preserves_coincident_completion_fault_and_control_signals() {
        let input = CertificateSignerInput {
            load_key_valid: true,
            key_seed: ScalarWords {
                words: [b64(0x81); 4],
            },
            clear_key: true,
            valid: true,
            epoch: b64(0x8000_0000_0000_0001),
            batch_id: b64(0xfedc_ba98_7654_3210),
            root: [b8(0x42); 32],
            tag: b16(0xf135),
        };
        let child = CachedSignOut {
            load_key_ready: false,
            key_loaded: true,
            public_key: ScalarWords {
                words: [b64(0xab); 4],
            },
            ready: true,
            valid: true,
            signature: Words512 {
                words: [b64(0xcd); 8],
            },
            tag: b16(0xf135),
            occupancy: b8(3),
            internal_error: true,
        };
        // Deliberately illegal control coincidence is forwarded, not silently
        // made safe. This is a combinational wiring test, not a core transaction.
        let (output, d) = certificate_signer_kernel(
            clock_reset(clock(false), reset(false)),
            input,
            CertificateSignerQ { signer: child },
        );
        assert_eq!(output, child);
        assert!(d.signer.load_key_valid && d.signer.clear_key && d.signer.valid);
        assert_eq!(d.signer.key_seed, input.key_seed);
        assert_eq!(
            d.signer.request,
            certificate_request(input.epoch, input.batch_id, input.root, input.tag)
        );
    }
}