rhdl_ed25519_core/

lib.rs

//! # Dalek-compatible Ed25519 hardware in RHDL
//!
//! This crate is the hardware facade for the workspace. Its modules re-export
//! the real SHA-512, field, scalar, point, message-feeder, and wire-type crates
//! used by the synthesizable design. It contains no Dalek implementation code:
//! the `rhdl_ed25519_model` crate uses the pinned Dalek snapshot only as a
//! differential-test oracle.
//!
//! The workspace has two hardware tracks:
//!
//! - The **compatibility core** implements public-key derivation, cold and
//!   cached-key signing, strict verification, multipart byte streams, and key
//!   clearing. `rhdl_ed25519_top::Ed25519Core` assembles the modules exported
//!   here into the end-to-end synchronous design.
//! - The **fixed-64 fast path** is an optimization track for saturated cold
//!   signing of 64-byte messages on an AMD Alveo U280. Its `fast_field`,
//!   `fast_fixed_base`, `fast_sha512`, `fast_point_codec`, `fast_scalar`, and
//!   `fast_sign` crates contain the specialized SystemVerilog datapath, RHDL
//!   wrapper types, cycle models, and RTL tests. It is not yet a replacement for
//!   the compatibility core.
//!
//! ## End-to-end signing
//!
//! For an RFC 8032 seed `sk` and message `M`, the hardware executes:
//!
//! ```text
//! SHA512(sk) -----------------> clamp -> a -------> [a]B -> encode -> A
//!     |
//!     +-----------------------> prefix
//!
//! SHA512(prefix || M) --------> reduce mod l -> r -> [r]B -> encode -> R
//! SHA512(R || A || M) --------> reduce mod l -> k
//! S = r + k*a mod l
//! signature = R || S
//! ```
//!
//! The host never supplies a prehash, expanded key, reduced nonce, challenge,
//! or intermediate point. SHA-512 padding, clamping, reduction, scalar
//! multiplication, point compression, and signature assembly all execute in
//! hardware.
//!
//! ## Strict verification
//!
//! Verification rejects malformed inputs before evaluating the group equation:
//!
//! ```text
//! canonical(S)?
//! decode(A) -> reject malformed or small-order A
//! decode(R) -> reject malformed or small-order R
//! SHA512(R || A || M) -> reduce mod l -> k
//! compare R with encode([S]B - [k]A)
//! ```
//!
//! Dedicated result codes distinguish framing errors, a missing cached key,
//! malformed points, non-canonical `S`, small-order points, and equation
//! failure. See [`types`] for the wire-level contract.
//!
//! ## Arithmetic hierarchy
//!
//! The compatibility backend follows Dalek's serial 32-bit organization:
//!
//! - [`field`] represents values modulo `p = 2^255 - 19` with ten alternating
//!   26/25-bit limbs stored in 32-bit lanes.
//! - [`scalar`] represents values modulo the Ed25519 group order `l` and
//!   implements wide reduction, 256-bit reduction, canonicality, and
//!   `r + k*a mod l`.
//! - [`point`] uses extended Edwards coordinates `(X:Y:Z:T)`, Projective Niels
//!   points, balanced radix-16 recoding, and fixed-pattern candidate scans.
//! - [`sha512`] implements padding, a 16-word circular schedule, and all 80
//!   compression rounds in synchronous logic.
//! - [`hash_feeder`] inserts hash prefixes and retains the first 4 KiB of a
//!   message for the second signing pass.
//!
//! ## Memory and traffic
//!
//! Arithmetic engines use registers and local BRAM/ROM only. They do not use
//! HBM or DDR as scratch storage. For a signing message of `N` bytes, the 4 KiB
//! cache gives the logical external message traffic
//!
//! ```text
//! N + max(N - 4096, 0)
//! ```
//!
//! before AXI-line padding. Verification reads `N` message bytes once. The
//! top-level result separately reports logical stream bytes and external read
//! bytes; host/AXI/HBM traffic must also count command records, result records,
//! line padding, and data-mover behavior.
//!
//! ## Secret-dependent work
//!
//! Scalar loops have fixed trip counts. Point-table lookup reads every candidate
//! bank at the same public address and selects only after the reads. A secret
//! digit must not select a BRAM address, enabled bank, iteration count, or stall
//! pattern. Zero digits execute the same point-operation schedule as nonzero
//! digits. These properties require emitted-RTL address and enable tests in
//! addition to functional Rust tests.
//!
//! ## Source map
//!
//! The modules below are the stable way to navigate arithmetic and protocol
//! APIs. Their items are re-exported from the owning implementation crates.
//! Higher-level control is intentionally split into separate crates:
//!
//! | Crate | Responsibility |
//! |---|---|
//! | `rhdl_ed25519_top` | child wiring, arbitration, and top-level synchronous design |
//! | `rhdl_ed25519_controller_types` | top-level I/O, states, and status |
//! | `rhdl_ed25519_transition` | pure high-level next-state kernel |
//! | `rhdl_ed25519_commands` | child-engine command generation |
//! | `rhdl_ed25519_registers` | retained cache/work/point register updates |
//! | `rhdl_ed25519_result` | result and error classification |
//! | `rhdl_ed25519_api` | Dalek signing traits over a driver/simulator transport |
//! | `rhdl_ed25519_model` | pinned-Dalek reference behavior and vectors |
//! | `rhdl_ed25519_sim` | cycle simulation, traces, RTL export, and checksums |
//! | [`architecture`] | current backend map, pipeline, cycle breakdown, and contributor guide |
//!
//! ## Evidence and performance status
//!
//! The compatibility core has end-to-end RHDL simulation evidence, including
//! exact RFC 8032 signing and strict verification. The recorded 64-byte signing
//! run takes 90,928 core cycles. A U280 out-of-context synthesis constrained to
//! 300 MHz records 237,294 LUTs, 94,129 registers, 800 DSPs, and 6 block-RAM
//! tiles, but has negative WNS and therefore must not be described as a closed
//! 300 MHz implementation.
//!
//! The latest 64-signature Verilator test observed 33,051 cycles across 31
//! post-warmup completion intervals, or 1,066.161 cycles/completion. Every
//! signature matched pinned Dalek. At an assumed 250 MHz that finite window
//! projects to 234,486 signatures/s, but no integrated 250 MHz timing result is
//! current. The latest archived integrated U280 OOC report targets 300 MHz,
//! uses 360,288 LUTs, 154,783 registers, 90 RAMB36 tiles, and 720 DSPs, and has
//! WNS of -1.078 ns. It therefore neither closes 300 MHz nor meets the earlier
//! 260,000-LUT budget. Final acceptance still requires post-route timing and a
//! long sustained U280 run with every signature checked by pinned Dalek.
//!
//! ## Contributor workflow
//!
//! 1. Start in the owning module below, not in generated Verilog.
//! 2. Add an independent arithmetic or Dalek differential test first.
//! 3. Compile the affected RHDL kernel and simulate emitted RTL when lowering or
//!    a SystemVerilog black box is involved.
//! 4. Inspect secret-dependent address, enable, and valid traces.
//! 5. Run the end-to-end simulator before changing a compatibility claim.
//! 6. Regenerate Vivado evidence before changing an area or timing claim.
//!
//! On memory-constrained hosts, use one Cargo job and iterate on narrow crates:
//!
//! ```text
//! cargo test -p rhdl_ed25519_model --release -j 1
//! cargo test -p rhdl_ed25519_core --release -j 1
//! RHDL_SKIP_IVERILOG_CHECK=1 cargo test --workspace --release -j 1
//! cargo doc --workspace --no-deps -j 1
//! ```

#![allow(clippy::needless_range_loop)]

#[doc = include_str!("../../../docs/ARCHITECTURE.md")]
pub mod architecture {}

pub mod field {
    //! Field arithmetic modulo `2^255 - 19`.
    //!
    //! The compatibility backend uses [`FieldElement2625`] and exposes serial
    //! and four-lane engines. Encoding, inversion, square-root chains, and
    //! parallel multiplication are implemented by the owning
    //! `rhdl_ed25519_field` crate.

    pub use rhdl_ed25519_field::*;
}

pub mod hash_feeder {
    //! Streaming SHA-512 input assembly and the 4 KiB message replay cache.
    //!
    //! [`HashFeederEngine`] combines an internal [`crate::sha512::Sha512Engine`]
    //! with prefix selection, 64-bit message-word framing, logical/external byte
    //! counters, and signing-pass replay requests.

    pub use rhdl_ed25519_hash_feeder::*;
}

pub mod point {
    //! Edwards-point arithmetic, scalar multiplication, and point encoding.
    //!
    //! This module re-exports the point controller, balanced-radix-16 scalar
    //! multiplier, strict compression/decompression controller, and the
    //! constant-time 32-byte equality kernel used by verification.

    pub use rhdl_ed25519_bytes_equal::*;
    pub use rhdl_ed25519_point::*;
    pub use rhdl_ed25519_point_codec::*;
    pub use rhdl_ed25519_scalar_mul::*;
}

pub mod scalar {
    //! Scalar arithmetic modulo the Ed25519 group order.
    //!
    //! [`ScalarEngine`] accepts wide and 256-bit reductions, modular multiply-add,
    //! and canonicality commands through one fixed-latency state machine.

    pub use rhdl_ed25519_scalar::*;
}

pub mod sha512 {
    //! End-to-end hardware SHA-512.
    //!
    //! [`Sha512Engine`] accepts an optional internal prefix and a byte stream,
    //! constructs FIPS 180-4 padding in hardware, and emits the eight-word
    //! digest. No host prehash is part of the public path.

    pub use rhdl_ed25519_sha512::*;
}

pub mod types {
    //! Public command, message-stream, pass-request, result, flag, and error
    //! encodings shared by the core, simulator, and FPGA shell.

    pub use rhdl_ed25519_types::*;
}

pub use types::*;