diff --git a/FABRIC-3.md b/FABRIC-3.md index 4933d67..78ec99a 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -3362,6 +3362,19 @@ redesign of the call path. loudly (boot-time message, safe fallback to this-boot-only cert) if no backend is present, and the pre-existing Zuse mint/cert behavior is unchanged on all three arches. The per-arch backends themselves are parked, explicitly, for v2.5.0. +- **v2.0.0 slice — BUILT and VERIFIED 2026-08-29.** `include/starkernel/rng.h` + + `src/starkernel/rng/rng.c` provide the single `rng_get_bytes()` entry point; `rng_init()` + probes the backend set (v2.0.0: virtio-rng only) and, on no backend, prints a loud + boot-time warning and `rng_get_bytes()` returns `RNG_ERR_NO_BACKEND` — it never silently + degrades to a deterministic seed. The backend-selection switch in `rng.c` is the exact seam + the v2.5.0 real per-arch drivers (amd64 RDRAND, riscv64 Zkr, aarch64 peripheral RNG) plug + into without touching the call path. Kernel consumers no longer touch `virtio_rng_*` + directly: `capsule_mint.c` (identity seed + `drive_uuid`) and `kernel_main.c` phase 8 + (`rng_init()`) route through the unified layer; `virtio_rng.c` stays as the sole backend. + Built clean on all three arches (`make -f Makefile.starkernel ARCH={amd64,aarch64,riscv64}`). + QEMU amd64 boot: POST `1012/0/0` + `ok>`, `rng: backend = virtio-rng` + `entropy: ready` + printed by the unified layer, and Zuse attach/identity confirmed from the thumbdrive — + Zuse mint/cert behavior unchanged. - **Exit criterion (v2.5.0 completion, for reference):** on each real board `rng_get_bytes()` returns genuinely non-deterministic bytes (two boots differ) and the Zuse mint path seeded from it produces a valid distinct cert per boot when bleached. diff --git a/Makefile.starkernel b/Makefile.starkernel index d1e0be2..e16f0f1 100644 --- a/Makefile.starkernel +++ b/Makefile.starkernel @@ -431,6 +431,7 @@ LOADER_SRCS_BASE := \ $(wildcard $(KERNEL_SRC)/capsule/*.c) \ $(wildcard $(KERNEL_SRC)/pci/*.c) \ $(wildcard $(KERNEL_SRC)/virtio/*.c) \ + $(wildcard $(KERNEL_SRC)/rng/*.c) \ $(wildcard $(KERNEL_SRC)/usb/*.c) \ $(KERNEL_SRC)/repl.c \ $(KERNEL_SRC)/doe_log.c \ @@ -483,6 +484,7 @@ KERNEL_SRCS_BASE := \ $(wildcard $(KERNEL_SRC)/capsule/*.c) \ $(wildcard $(KERNEL_SRC)/pci/*.c) \ $(wildcard $(KERNEL_SRC)/virtio/*.c) \ + $(wildcard $(KERNEL_SRC)/rng/*.c) \ $(wildcard $(KERNEL_SRC)/usb/*.c) \ $(wildcard $(KERNEL_SRC)/arch/$(ARCH)/*.c) \ $(KERNEL_SRC)/repl.c \ diff --git a/capsules/BLOCK_MAP.md b/capsules/BLOCK_MAP.md index c7b2736..fb9945c 100644 --- a/capsules/BLOCK_MAP.md +++ b/capsules/BLOCK_MAP.md @@ -1,5 +1,5 @@ # Capsule Block Manifest — Auto-generated - + diff --git a/disk/artemis.img b/disk/artemis.img index 8af565f..6c0c8eb 100644 Binary files a/disk/artemis.img and b/disk/artemis.img differ diff --git a/include/starkernel/rng.h b/include/starkernel/rng.h new file mode 100644 index 0000000..1293644 --- /dev/null +++ b/include/starkernel/rng.h @@ -0,0 +1,65 @@ +/* + * rng.h — Unified entropy entry point for StarKernel + * + * The single place any kernel consumer (keygen, identity mint, drive_uuid, + * certificate serials, ...) asks for entropy. All entropy flows through + * rng_get_bytes() and never touches a backend directly. + * + * The set of active backends is determined at rng_init() time by probing, + * in order, until one (or more) come up: + * - v2.0.0 (QEMU): virtio-rng is the sole backend — there is no virtio-rng + * on real hardware, but QEMU exposes it uniformly on all three arches + * (amd64/aarch64/riscv64), and the paravirtualized device sidesteps the + * per-ISA gap where no single CPU RNG covers all three models (amd64 has + * RDRAND, riscv64 has Zkr, but QEMU's aarch64 CPU models expose neither — + * see virtio_rng.h / vm_uuid.h for the identical finding). + * - v2.5.0 (real hardware): real per-arch backends are inserted here without + * touching the call path — amd64 RDRAND, riscv64 Zkr (RNDR), aarch64 + * peripheral RNG — each handled by a case in rng_init() and rng_get_bytes() + * (grid §G.4). On QEMU all three arches stay on virtio-rng; nothing changes. + * + * Probe-and-refuse-loudly contract (§G.2): if no backend comes up at + * rng_init(), the kernel prints a loud boot-time message. A later + * rng_get_bytes() call with no backend returns -1 (RNG_ERR_NO_BACKEND) rather + * than ever silently degrading to a deterministic throwaway — the exact failure + * Phases A/G call out as unacceptable. Callers (e.g. capsule_mint_identity) + * must surface that refusal as an explicit no-entropy error, never proceed with + * a deterministic seed. + * + * Important ordering: rng_init() must run before any rng_get_bytes()/mint call + * (it already does in kernel_main phase 8, ahead of Zuse boot attach, which is + * the only mint path in v2.0.0). rng_get_bytes() with rng_init() never + * successful returns RNG_ERR_NO_BACKEND, never blocks. + */ + +#ifndef STARKERNEL_RNG_H +#define STARKERNEL_RNG_H + +#include +#include + +/* Return codes (negative = failure). */ +#define RNG_ERR_NO_BACKEND (-1) /* rng_init() found no working entropy source */ + +/* + * rng_init — probe and bring up the entropy backends. Returns 0 if at least + * one backend is active (rng_get_bytes() will succeed), nonzero otherwise. + * Prints a loud boot-time message when no backend comes up. Call once, early. + */ +int rng_init(void); + +/* + * rng_ready — 1 if at least one backend is active, 0 otherwise. + */ +int rng_ready(void); + +/* + * rng_get_bytes — fill buf with n bytes of real entropy, blocking until all + * n bytes are obtained. + * + * Returns 0 on success (buf fully filled). + * Returns RNG_ERR_NO_BACKEND (-1) if no backend is active. + */ +int rng_get_bytes(uint8_t *buf, size_t n); + +#endif /* STARKERNEL_RNG_H */ diff --git a/src/starkernel/capsule/capsule_mint.c b/src/starkernel/capsule/capsule_mint.c index 83bf841..3f35c3c 100644 --- a/src/starkernel/capsule/capsule_mint.c +++ b/src/starkernel/capsule/capsule_mint.c @@ -16,7 +16,7 @@ #include "starkernel/user_identity_seed.h" #include "starkernel/x509_ed25519.h" #include "starkernel/ed25519.h" -#include "starkernel/virtio_rng.h" +#include "starkernel/rng.h" #include "block_subsystem.h" /* compute_crc64() */ #include "blkio.h" #include @@ -101,11 +101,11 @@ MintResult capsule_mint_identity(struct blkio_dev *dev, VM *issuer_vm, /* issuer_vm==NULL is genesis mode (§F.21) -- no existing Zuse to * require a cert from. */ if (issuer_vm && !issuer_vm->zuse_cert_installed) return MINT_ERR_NO_ZUSE_CERT; - if (!virtio_rng_ready()) return MINT_ERR_NO_ENTROPY; + if (!rng_ready()) return MINT_ERR_NO_ENTROPY; /* Fresh identity keypair. */ uint8_t seed[32], pubkey[32]; - if (virtio_rng_get_bytes(seed, sizeof(seed)) != 0) return MINT_ERR_NO_ENTROPY; + if (rng_get_bytes(seed, sizeof(seed)) != 0) return MINT_ERR_NO_ENTROPY; ed25519_keygen(seed, pubkey); if (out_pubkey) memcpy(out_pubkey, pubkey, 32); if (out_seed) memcpy(out_seed, seed, 32); @@ -114,7 +114,7 @@ MintResult capsule_mint_identity(struct blkio_dev *dev, VM *issuer_vm, * the identity seed (§F.8 decision 3: "which physical drive," not * "whose identity"). */ uint8_t drive_uuid[16]; - if (virtio_rng_get_bytes(drive_uuid, sizeof(drive_uuid)) != 0) + if (rng_get_bytes(drive_uuid, sizeof(drive_uuid)) != 0) return MINT_ERR_NO_ENTROPY; uint32_t cert_devblock = 0; diff --git a/src/starkernel/kernel_main.c b/src/starkernel/kernel_main.c index 05517d2..e4a384c 100644 --- a/src/starkernel/kernel_main.c +++ b/src/starkernel/kernel_main.c @@ -65,7 +65,7 @@ EFI_RUNTIME_SERVICES *g_sk_runtime_services = NULL; #include "starkernel/repl.h" #include "starkernel/pci.h" #include "starkernel/virtio_blk.h" -#include "starkernel/virtio_rng.h" +#include "starkernel/rng.h" #include "starkernel/virtio_input.h" #include "starkernel/xhci_driver.h" #include "block_subsystem.h" @@ -590,20 +590,20 @@ static void kernel_main_deep(BootInfo *boot_info) { } } - /* Phase 8: virtio-rng entropy source. Real per-arch RNG doesn't cover - * all three architectures (amd64 RDRAND, riscv64 Zkr, but aarch64 has - * neither in QEMU's CPU models -- see vm_uuid.h's identical finding), - * so signing/keygen entropy comes from this paravirtualized device - * instead. Unconditional call site, same graceful-noop precedent as - * virtio_blk_find_artemis() above -- boot proceeds either way, the - * device is only required once something actually calls - * virtio_rng_get_bytes(). */ + /* Phase 8: entropy. Real per-arch RNG doesn't cover all three + * architectures (amd64 RDRAND, riscv64 Zkr, but aarch64 has neither in + * QEMU's CPU models -- see vm_uuid.h's identical finding), so signing/ + * keygen entropy comes from the unified rng_get_bytes() layer, whose + * v2.0.0 backend is the paravirtualized virtio-rng device. Unconditional + * call site, same graceful-noop precedent as virtio_blk_find_artemis() + * above -- boot proceeds either way, the device is only required once + * something actually calls rng_get_bytes(). */ { - int rrc = virtio_rng_init(); + int rrc = rng_init(); if (rrc == 0) { - console_println("virtio-rng: ready"); + console_println("entropy: ready"); } else { - console_println("virtio-rng: not available (continuing without)"); + console_println("entropy: not available (continuing without)"); } } diff --git a/src/starkernel/rng/rng.c b/src/starkernel/rng/rng.c new file mode 100644 index 0000000..685429c --- /dev/null +++ b/src/starkernel/rng/rng.c @@ -0,0 +1,60 @@ +/* + StarKernel — Unified entropy layer (rng_get_bytes) + + Single entropy entry point for the kernel; see include/starkernel/rng.h for + the contract and the probe-and-refuse-loudly discipline this implements. + + v2.0.0: virtio-rng is the sole active backend (QEMU-only, uniform across all + three arches). The backend-selection switch in rng_get_bytes() is the exact + seam where the v2.5.0 real per-arch drivers (amd64 RDRAND, riscv64 Zkr, + aarch64 peripheral RNG) plug in without touching the call path. +*/ + +#ifndef __STARKERNEL__ +#error "rng.c is kernel-only" +#endif + +#include "starkernel/rng.h" +#include "starkernel/virtio_rng.h" +#include "starkernel/console.h" + +/* Number of entropy backends known to this build. Each maps to one case in + * rng_init() and rng_get_bytes(). v2.0.0 has exactly one: virtio-rng. */ +enum { + RNG_BACKEND_NONE = 0, + RNG_BACKEND_VIRTIO, /* virtio-rng (QEMU, all three arches) */ +}; + +static int g_rng_backend = RNG_BACKEND_NONE; + +int rng_init(void) { + /* Probe backends in priority order; first success wins. virtio-rng is + * the sole backend at v2.0.0; v2.5.0 adds real per-arch drivers here. */ + if (virtio_rng_init() == 0) { + g_rng_backend = RNG_BACKEND_VIRTIO; + console_println("rng: backend = virtio-rng"); + return 0; + } + + /* Refuse loudly: never fall through to a deterministic seed. */ + g_rng_backend = RNG_BACKEND_NONE; + console_println( + "rng: WARNING — no entropy backend available; rng_get_bytes() " + "will refuse (no deterministic seed fallback)"); + return -1; +} + +int rng_ready(void) { + return g_rng_backend != RNG_BACKEND_NONE; +} + +int rng_get_bytes(uint8_t *buf, size_t n) { + switch (g_rng_backend) { + case RNG_BACKEND_VIRTIO: + return virtio_rng_get_bytes(buf, n); + default: + /* v2.5.0 real per-arch cases land here. No backend: refuse loudly, + * never return a deterministic throwaway. */ + return RNG_ERR_NO_BACKEND; + } +}