ruvix_boot/
lib.rs

1//! # RVF Boot Loading for RuVix Cognition Kernel
2//!
3//! This crate provides the RVF (RuVector Format) boot loading infrastructure
4//! for the RuVix Cognition Kernel as specified in ADR-087.
5//!
6//! ## Boot Sequence (ADR-087 Section 9.1)
7//!
8//! The kernel boot follows a five-stage process:
9//!
10//! | Stage | Name | Description |
11//! |-------|------|-------------|
12//! | **0** | Hardware Init | Platform-specific initialization (mocked in Phase A) |
13//! | **1** | RVF Verify | Parse manifest + ML-DSA-65 signature verification |
14//! | **2** | Object Create | Create root task, regions, queues, witness log |
15//! | **3** | Component Mount | Mount components + distribute capabilities |
16//! | **4** | First Attestation | Boot attestation to witness log |
17//!
18//! ## Security (SEC-001)
19//!
20//! This crate implements critical security fixes:
21//!
22//! - **Signature failure**: PANIC IMMEDIATELY, no fallback boot path
23//! - **Root task capability drop**: After Stage 3, root task drops to minimum set
24//! - **Witness log integrity**: Append-only, cryptographically linked
25//!
26//! ## Features
27//!
28//! - `std`: Enable standard library support (default)
29//! - `alloc`: Enable alloc crate support
30//! - `metrics`: Enable boot metrics collection
31//! - `verbose`: Enable verbose boot logging
32//! - `baremetal`: Phase B bare metal (no std, no libc)
33//!
34//! ## Example
35//!
36//! ```rust,ignore
37//! use ruvix_boot::{BootLoader, BootConfig};
38//!
39//! let config = BootConfig::default();
40//! let mut loader = BootLoader::new(config);
41//!
42//! // Load and verify the RVF boot image
43//! let manifest_bytes = include_bytes!("boot.rvf.manifest");
44//! let signature = include_bytes!("boot.rvf.sig");
45//!
46//! // This will PANIC if signature verification fails (SEC-001)
47//! loader.boot(manifest_bytes, signature)?;
48//! ```
49
50#![cfg_attr(not(feature = "std"), no_std)]
51#![forbid(unsafe_code)]
52#![deny(missing_docs)]
53#![deny(clippy::all)]
54#![warn(clippy::pedantic)]
55
56#[cfg(feature = "alloc")]
57extern crate alloc;
58
59#[cfg(feature = "std")]
60extern crate std;
61
62mod attestation;
63mod boot_loader;
64mod capability_distribution;
65mod manifest;
66mod mount;
67mod signature;
68mod stages;
69mod witness_log;
70
71pub use attestation::{BootAttestation, AttestationEntry};
72pub use boot_loader::{BootConfig, BootLoader, BootResult, BootStage};
73pub use capability_distribution::{
74    CapabilityDistribution, MinimumCapabilitySet, RootCapabilityDrop,
75};
76pub use manifest::{
77    ComponentDecl, ComponentGraph, MemorySchema, ProofPolicy, QueueWiring,
78    RollbackHook, RvfManifest, WitnessLogPolicy,
79};
80pub use mount::{MountConfig, MountResult, RvfMount};
81pub use signature::{SignatureVerifier, VerifyResult};
82pub use stages::{Stage0Hardware, Stage1Verify, Stage2Create, Stage3Mount, Stage4Attest};
83pub use witness_log::{WitnessLog, WitnessLogConfig, WitnessLogEntry};
84
85// Re-export commonly used types from dependencies
86pub use ruvix_cap::{BootCapabilitySet, InitialCapability};
87pub use ruvix_types::{
88    KernelError, ProofAttestation, ProofTier, RegionHandle, RegionPolicy,
89    RvfMountHandle, RvfVerifyStatus, TaskHandle, TaskPriority,
90};
91
92/// Result type for boot operations.
93pub type Result<T> = core::result::Result<T, KernelError>;
94
95/// Boot stage constants.
96pub mod stage {
97    /// Stage 0: Hardware initialization (mocked in Phase A).
98    pub const HARDWARE_INIT: u8 = 0;
99
100    /// Stage 1: RVF manifest parse + ML-DSA-65 signature verification.
101    pub const RVF_VERIFY: u8 = 1;
102
103    /// Stage 2: Kernel object creation (root task, regions, queues, witness log).
104    pub const OBJECT_CREATE: u8 = 2;
105
106    /// Stage 3: Component mount + capability distribution.
107    pub const COMPONENT_MOUNT: u8 = 3;
108
109    /// Stage 4: First attestation (boot attestation to witness log).
110    pub const FIRST_ATTESTATION: u8 = 4;
111}
112
113/// ML-DSA-65 signature size in bytes (NIST FIPS 204).
114pub const ML_DSA_65_SIGNATURE_SIZE: usize = 3309;
115
116/// ML-DSA-65 public key size in bytes.
117pub const ML_DSA_65_PUBLIC_KEY_SIZE: usize = 1952;
118
119/// Maximum manifest size in bytes.
120pub const MAX_MANIFEST_SIZE: usize = 1024 * 1024; // 1 MiB
121
122/// Maximum number of components in an RVF package.
123pub const MAX_COMPONENTS: usize = 256;
124
125/// Maximum queue wiring connections per manifest.
126pub const MAX_QUEUE_WIRINGS: usize = 1024;
127
128/// Maximum region declarations per manifest.
129pub const MAX_REGION_DECLS: usize = 256;
130
131#[cfg(test)]
132mod tests {
133    use super::*;
134
135    #[test]
136    fn test_stage_constants() {
137        assert_eq!(stage::HARDWARE_INIT, 0);
138        assert_eq!(stage::RVF_VERIFY, 1);
139        assert_eq!(stage::OBJECT_CREATE, 2);
140        assert_eq!(stage::COMPONENT_MOUNT, 3);
141        assert_eq!(stage::FIRST_ATTESTATION, 4);
142    }
143
144    #[test]
145    fn test_signature_constants() {
146        // ML-DSA-65 (NIST FIPS 204) signature size
147        assert_eq!(ML_DSA_65_SIGNATURE_SIZE, 3309);
148        assert_eq!(ML_DSA_65_PUBLIC_KEY_SIZE, 1952);
149    }
150}
ruvix_boot/lib.rs

ruvix_boot/
lib.rs
