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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn
This commit is contained in:
Robert Allan James
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
7cbf92ac8f
commit
10b96870c5
+8
-1
@@ -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.
|
||||
|
||||
@@ -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 <stdint.h>
|
||||
|
||||
#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 */
|
||||
Reference in New Issue
Block a user