From 10b96870c513ad229c5e4fded425d3885bcfeaf4 Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Wed, 26 Aug 2026 06:55:59 -0400 Subject: [PATCH] Add homeblocks_sig.h: drive signature header struct (Phase 8 kickoff) Implements the design from the previous commit as-is: homeblocks_sig_t (4096 bytes, magic+version+drive_uuid+timestamp+cert/blockmap offset reservations+real hdr_crc), HOMEBLOCKS_SIG_PACK/_GET_MAGIC/_GET_VERSION macros mirroring CAPSULE_MAGIC_PACK's bit layout, and a C99 compile-time size assertion matching stadium.h's own discipline. Verified standalone (sizeof == 4096, clean under -std=c99 -Wall -Wextra -Werror) -- nothing consumes this header yet, so no functional kernel change and no 3-arch acceptance boot needed for this step. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn --- FABRIC-3.md | 9 +- include/starkernel/homeblocks_sig.h | 125 ++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+), 1 deletion(-) create mode 100644 include/starkernel/homeblocks_sig.h diff --git a/FABRIC-3.md b/FABRIC-3.md index c590114..1b72894 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -203,7 +203,14 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR generated yet (Milestone 6), so this reserves the *shape* of where a cert will attach without committing to a cert format that doesn't exist. Same reasoning for `blockmap_offset`/`blockmap_devblocks` against Milestone 3's still-open block-map design. - Not yet written to a header file — presented for confirmation before implementation. + **Implemented (2026-08-26):** `include/starkernel/homeblocks_sig.h` — `homeblocks_sig_t` + + `HOMEBLOCKS_SIG_PACK`/`_GET_MAGIC`/`_GET_VERSION` macros, a C99 compile-time size assertion + (same discipline `stadium.h`'s own header-size checks use), and the identical field layout + shown above. Verified standalone: `sizeof(homeblocks_sig_t) == 4096`, compiles clean under + `-std=c99 -Wall -Wextra -Werror`. Not yet consumed by any code — nothing in the block + subsystem or xHCI driver reads or writes it yet, so no functional kernel change and no + 3-arch acceptance boot needed for this step; that starts with the signature-check + implementation, the next punch-list item below. - [ ] Implement the signature check, called before any write path touches a newly-inserted drive. diff --git a/include/starkernel/homeblocks_sig.h b/include/starkernel/homeblocks_sig.h new file mode 100644 index 0000000..8f2f474 --- /dev/null +++ b/include/starkernel/homeblocks_sig.h @@ -0,0 +1,125 @@ +/* + StarForth — Steady-State Virtual Machine Runtime + + Copyright (c) 2023–2025 Robert A. James + All rights reserved. + + This file is part of the StarForth project. + + Licensed under the StarForth License, Version 1.0 (the "License"); + you may not use this file except in compliance with the License. + + You may obtain a copy of the License at: + https://github.com/star.4th@proton.me/StarForth/LICENSE.txt + + This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND, + express or implied, including but not limited to the warranties of + merchantability, fitness for a particular purpose, and noninfringement. + + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * homeblocks_sig.h - Home-blocks drive signature format (FABRIC-3.md, + * Milestone 4, Phase 8 kickoff) + * + * Identifies and authenticates a physical thumb drive as a legitimate + * LithosAnanke home-blocks drive, before any write path touches it. + * Lives at the first 4KiB devblock of the drive's GPT metadata partition + * (the ~1GB partition decided 2026-08-22) -- this header's own format does + * not depend on the GPT parser that locates that partition; it is simply + * what gets written starting at that partition's first devblock, once + * something can find it. + * + * Mirrors two existing precedents exactly, not invented fresh: + * - CAPSULE_MAGIC_PACK's bit-packed magic (starkernel/capsule.h) + * - blk_volume_meta_t's magic+version+fields+pad-to-4096 structural + * convention (block_subsystem.h) + * + * Deliberately narrow in scope: this header identifies/authenticates the + * DRIVE only. It does not invent the on-drive block-map format (Milestone + * 3, still undesigned) or the credential/cert format (Milestone 6, blocked + * on a real CA that does not exist yet) -- it only reserves offset/size + * pointers to where those will attach, so this format does not need to be + * revisited when those get designed. + */ + +#ifndef STARKERNEL_HOMEBLOCKS_SIG_H +#define STARKERNEL_HOMEBLOCKS_SIG_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/*=========================================================================== + * Magic Field Packing -- same bit layout convention as CAPSULE_MAGIC_PACK + * + * bits 0..31 : 'LAHB' (0x4248414C little-endian) -- LithosAnanke Home Blocks + * bits 32..39 : version (0 for v0) + * bits 40..63 : reserved (zero) + *===========================================================================*/ + +#define HOMEBLOCKS_SIG_MAGIC 0x4248414CULL /* 'LAHB', same little-endian ASCII + * packing as CAPSULE_DESC_MAGIC's 'CAPS' */ +#define HOMEBLOCKS_SIG_VERSION_0 0 + +#define HOMEBLOCKS_SIG_PACK(ver) \ + (HOMEBLOCKS_SIG_MAGIC | ((uint64_t)(ver) << 32)) + +#define HOMEBLOCKS_SIG_GET_MAGIC(m) ((uint32_t)((m) & 0xFFFFFFFFULL)) +#define HOMEBLOCKS_SIG_GET_VERSION(m) ((uint8_t)(((m) >> 32) & 0xFF)) + +/*=========================================================================== + * homeblocks_sig_t - drive signature header (exactly one 4KiB devblock) + *===========================================================================*/ + +typedef struct { + uint64_t magic; /* HOMEBLOCKS_SIG_PACK(...) */ + uint8_t drive_uuid[16]; /* Unique per-mint instance id -- Phase 8 mints multiple + * distinct drives, needs something to tell them apart. */ + uint64_t minted_time_ns; /* Monotonic timestamp at mint time. */ + uint64_t metadata_devblocks; /* Size of this GPT metadata partition, in 4KiB devblocks -- + * sanity/bounds check against the GPT entry once a parser + * exists. */ + + uint32_t cert_offset; /* Devblock offset within this partition where the CA-signed + * cert blob starts; 0 = not yet minted. Format not decided -- + * Milestone 6's real CA does not exist yet. */ + uint32_t cert_devblocks; /* Size reserved for the cert blob, in devblocks. */ + + uint32_t blockmap_offset; /* Devblock offset where the block-map starts; 0 = not yet + * minted. Format not decided -- Milestone 3, still open. */ + uint32_t blockmap_devblocks; /* Size reserved for the block-map, in devblocks. */ + + uint64_t hdr_crc; /* REAL from day one, not a placeholder like + * blk_volume_meta_t's "unused yet" hdr_crc -- this header's + * whole job is gating a warn-and-refuse security check + * against blank/foreign/unrecognized media, so the crc has + * to actually work. Computed over every field above this + * one; callers must fill every other field before computing + * or verifying it. */ + + /* Padding to keep the header exactly one 4KiB devblock. */ + uint8_t _pad[4096 - ( + 8 + /* magic */ + 16 + /* drive_uuid */ + 8 + /* minted_time_ns */ + 8 + /* metadata_devblocks */ + 4 + 4 + /* cert_offset, cert_devblocks */ + 4 + 4 + /* blockmap_offset, blockmap_devblocks */ + 8 /* hdr_crc */ + )]; +} homeblocks_sig_t; + +/* C99-portable compile-time size assertion (no _Static_assert -- that's C11), + * same discipline stadium.h's own header-size checks already use. */ +typedef char homeblocks_sig_size_check[(sizeof(homeblocks_sig_t) == 4096) ? 1 : -1]; + +#ifdef __cplusplus +} +#endif + +#endif /* STARKERNEL_HOMEBLOCKS_SIG_H */