llms-full.txt

# eBoot — full documentation (llms-full.txt)

This file is a checked-in concatenation of eBoot's documentation,
in the order listed below, so agents and tools can read the whole
corpus as one document. It is generated by hand from the sources —
when a source doc changes, update this file in the same commit.

Sources, in order:

- `docs/architecture.md`
- `docs/secure_boot_chain.md`
- `docs/security.md`
- `docs/threat_model.md`
- `docs/update-flow.md`
- `docs/key_lifecycle.md`
- `docs/memory-map.md`
- `docs/installation_usage.md`
- `docs/quickstart.md`
- `docs/eflash.md`
- `docs/mcuboot_comparison.md`

# === docs/architecture.md ===

# eBootloader Architecture

## Staged Boot Architecture

```
ROM / Reset Vector
   ↓
eBootloader   (stage-0 / minimal core)
   ↓
E-Boot         (stage-1 boot manager)
   ↓
Application Firmware
   ↕
EoS Firmware Services
```

## Module Map

| Module        | Layer   | Role                                      |
|---------------|---------|-------------------------------------------|
| `stage0/`     | Stage-0 | Reset entry, minimal HW init, recovery check, jump to stage-1 |
| `stage1/`     | Stage-1 | Image scan, boot policy, boot log, jump to application |
| `core/`       | Shared  | Boot control, image verify, slot management, recovery state machine, firmware services |
| `hal/`        | HAL     | Board-agnostic flash/watchdog/UART/jump wrappers |
| `boards/`     | BSP     | Board-specific register-level implementations |
| `include/`    | API     | All public headers and type definitions |
| `tools/`      | Host    | Image packer, signing tool, UART recovery client |
| `tests/`      | Test    | Host-side unit tests with simulated flash |

## Flash Memory Map (STM32F407 Reference)

```
Address Range              Size    Region
─────────────────────────────────────────────────────
0x08000000 - 0x08003FFF    16K     Stage-0 (eBootloader)
0x08004000 - 0x0800FFFF    48K     Stage-1 (E-Boot)
0x08010000 - 0x0807FFFF    448K    Slot A (active firmware)
0x08080000 - 0x080EFFFF    448K    Slot B (candidate firmware)
0x080F0000 - 0x080F3FFF    16K     Recovery image
0x080F4000 - 0x080F5FFF    8K      Boot control (primary)
0x080F6000 - 0x080F7FFF    8K      Boot control (backup)
0x080F8000 - 0x080F9FFF    8K      Boot log
0x080FA000 - 0x080FFFFF    24K     Device config / reserved
```

## Boot Flow

```
Reset_Handler()
  ├── Copy .data, zero .bss
  ├── ebldr_hw_init_minimal()
  │   ├── board_get_ops() → register HAL
  │   └── board_early_init() → clocks, flash latency
  └── ebldr_stage0_main()
      ├── ebldr_watchdog_init()
      ├── eos_bootctl_load() → load boot state
      ├── ebldr_recovery_triggered()?
      │   └── YES → eos_recovery_enter() → UART command loop
      └── jump to stage-1 → eboot_main()
          ├── eos_bootctl_load()
          ├── eos_boot_log_init()
          ├── eboot_should_recover()?
          │   └── YES → eos_recovery_enter()
          ├── eboot_scan_images() → verify both slots
          ├── eboot_select_slot() → boot policy
          │   ├── Check max attempts → rollback
          │   ├── Check pending upgrade → test boot
          │   ├── Try active slot
          │   └── Fallback to alternate slot
          └── eboot_jump_to_app()
              ├── Increment boot attempts
              ├── Disable interrupts
              ├── Deinit peripherals
              └── Jump to application vector table
```

## Rollback Sequence

```
1. Application writes new image → Slot B
2. eos_fw_request_upgrade(SLOT_B, EOS_UPGRADE_TEST)
3. system_reboot()
4. E-Boot sees pending_slot = B, flags = TEST_BOOT
5. Verifies Slot B image → boots Slot B
6. boot_attempts++
7. New firmware runs self-test
8. eos_fw_confirm_running_image() → marks CONFIRMED
   OR
   Firmware crashes / fails self-test
   → Watchdog resets → boot_attempts++
   → After max_attempts reached → E-Boot rolls back to Slot A
```

## Recovery Protocol (UART)

| Command   | Code | Description                     |
|-----------|------|---------------------------------|
| PING      | 0x01 | Identity check — returns "EOS"  |
| INFO      | 0x02 | Flash layout, slot addresses and capabilities. Unauthenticated (ADR-021). Response: 22 bytes packed -- `ack`, `flash_size`, `slot_a_addr`, `slot_a_size`, `slot_b_addr`, `slot_b_size` (LE `uint32`), `caps` (bit 0 RNG, bit 1 OTP) |
| ERASE     | 0x03 | Erase target slot               |
| WRITE     | 0x04 | Write chunk to slot             |
| VERIFY    | 0x05 | Verify slot image integrity     |
| BOOT      | 0x06 | Set active slot and reboot      |
| LOG       | 0x07 | Dump boot log                   |
| RESET     | 0x08 | System reset                    |
| FACTORY   | 0x09 | Erase all + reset defaults      |

Packet format: `[cmd:1][slot:1][len:2][offset:4]`

# === docs/secure_boot_chain.md ===

# Secure Boot Chain — eBootloader

> **Last updated:** 2026-04-03
>
> **Scope:** Complete chain of trust from ROM through application firmware in the eBootloader system.

---

## 1. Chain of Trust Overview

The eBootloader implements a staged chain of trust where each boot stage verifies the next before transferring execution. Every link in the chain must pass verification — a single failure triggers recovery or halt.

```
┌─────────────────────────────────────────────────────────────────────┐
│                        SILICON ROM                                  │
│                  (immutable root of trust)                          │
│                                                                     │
│  • Loads from fixed flash address (0x08000000)                      │
│  • Platform-dependent: may verify stage-0 hash via eFuse/OTP       │
│  • Sets initial stack pointer and jumps to Reset_Handler            │
└────────────────────────┬────────────────────────────────────────────┘
                         │ TB-1: ROM → Stage-0
                         │ Verified by: ROM hash (SoC-dependent)
                         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     STAGE-0 (eBootloader)                           │
│                       16 KB flash region                            │
│                                                                     │
│  • Copy .data, zero .bss                                            │
│  • ebldr_hw_init_minimal() — clocks, flash latency                 │
│  • board_get_ops() — register HAL vtable                            │
│  • ebldr_watchdog_init()                                            │
│  • eos_bootctl_load() — load boot state from flash                 │
│  • Check recovery trigger (pin or flag)                             │
│  • ★ VERIFY stage-1 image (hash + signature)                       │
│  • Jump to stage-1 entry point                                      │
└────────────────────────┬────────────────────────────────────────────┘
                         │ TB-2: Stage-0 → Stage-1
                         │ Verified by: SHA-256 + Ed25519 signature
                         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     STAGE-1 (E-Boot)                                │
│                      48 KB flash region                             │
│                                                                     │
│  • eos_bootctl_load() — reload boot state                           │
│  • eos_boot_log_init() — initialize boot log                       │
│  • Check recovery trigger (pin, flag, max attempts)                 │
│  • eboot_scan_images() — parse and verify both slots                │
│  • ★ VERIFY application image (hash + signature + version)          │
│  • eboot_select_slot() — boot policy decision                      │
│  • Anti-rollback check (security counter)                           │
│  • eboot_jump_to_app() — transfer to application                   │
└────────────────────────┬────────────────────────────────────────────┘
                         │ TB-3: Stage-1 → Application
                         │ Verified by: SHA-256 + Ed25519 + anti-rollback
                         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                   APPLICATION FIRMWARE                               │
│                   448 KB × 2 slots (A/B)                            │
│                                                                     │
│  • Application entry point (vector table)                           │
│  • Self-test → eos_fw_confirm_running_image()                       │
│  • Runtime firmware services via eos_fwsvc API                      │
│  • OTA update: write to inactive slot + eos_fw_request_upgrade()    │
└─────────────────────────────────────────────────────────────────────┘
```

---

## 2. Verification Steps at Each Stage

### 2.1 ROM → Stage-0 (TB-1)

| Step | Operation | API / Mechanism |
|---|---|---|
| 1 | ROM reads stage-0 vector table from `0x08000000` | SoC boot ROM (vendor) |
| 2 | ROM verifies stage-0 hash against OTP/eFuse value | SoC-specific (e.g., STM32 Secure Boot, nRF Secure Boot) |
| 3 | ROM sets MSP from vector table entry 0 | Hardware |
| 4 | ROM jumps to Reset_Handler (vector table entry 1) | Hardware |

**What is verified:**
- Stage-0 binary integrity (hash match)
- Stage-0 authenticity (if ROM supports signature verification)

**What is NOT verified by ROM:**
- Stage-1 or application images (responsibility of stage-0 and stage-1)
- Boot control block integrity (loaded later by stage-0)

### 2.2 Stage-0 → Stage-1 (TB-2)

| Step | Operation | API |
|---|---|---|
| 1 | Initialize minimal hardware | `ebldr_hw_init_minimal()` |
| 2 | Register board HAL | `board_get_ops()` → `eos_hal_init()` |
| 3 | Start watchdog | `ebldr_watchdog_init()` |
| 4 | Load boot control block | `eos_bootctl_load()` |
| 5 | Check recovery trigger | `ebldr_recovery_triggered()` |
| 6 | Parse stage-1 image header at `0x08004000` | `eos_image_parse_header()` |
| 7 | Verify stage-1 CRC32 (Phase 1) or SHA-256 hash (Phase 2) | `eos_image_verify_integrity()` |
| 8 | Verify stage-1 Ed25519 signature (Phase 2) | `eos_image_verify_signature()` |
| 9 | Check stage-1 version against minimum (Phase 2) | `eos_image_check_version()` |
| 10 | Disable interrupts, deinit peripherals | `eos_hal_disable_interrupts()` |
| 11 | Set MSP and jump to stage-1 | `eos_hal_set_msp()` → `eos_hal_jump()` |

**Verification flow (Phase 2):**

```c
int stage0_verify_stage1(void) {
    eos_image_header_t hdr;
    int rc;

    rc = eos_image_parse_header(STAGE1_ADDR, &hdr);
    if (rc != EOS_OK) return rc;

    rc = eos_image_verify_integrity(&hdr, STAGE1_ADDR + hdr.hdr_size);
    if (rc != EOS_OK) return rc;

    rc = eos_image_verify_signature(&hdr);
    if (rc != EOS_OK) return rc;

    rc = eos_image_check_version(hdr.image_version, min_stage1_version);
    if (rc != EOS_OK) return rc;

    return EOS_OK;
}
```

### 2.3 Stage-1 → Application (TB-3)

| Step | Operation | API |
|---|---|---|
| 1 | Reload boot control block | `eos_bootctl_load()` |
| 2 | Initialize boot log | `eos_boot_log_init()` |
| 3 | Check recovery conditions | `eboot_should_recover()` |
| 4 | Scan both image slots (A and B) | `eboot_scan_images()` |
| 5 | Parse image header for candidate slot | `eos_image_parse_header()` |
| 6 | Verify image integrity (CRC32 / SHA-256) | `eos_image_verify_integrity()` |
| 7 | Verify image signature (Ed25519) | `eos_image_verify_signature()` |
| 8 | Check image version against security counter | `eos_image_check_version()` |
| 9 | Apply boot policy (test boot, rollback, fallback) | `eboot_select_slot()` |
| 10 | Increment boot attempts | `eos_bootctl_increment_attempts()` |
| 11 | Disable interrupts, deinit peripherals | `eos_hal_disable_interrupts()`, `eos_hal_deinit_peripherals()` |
| 12 | Jump to application vector table | `eboot_jump_to_app()` |

---

## 3. Failure Modes and Recovery Paths

### 3.1 Failure Mode Summary

| Stage | Failure | Detection | Recovery |
|---|---|---|---|
| ROM → Stage-0 | Stage-0 hash mismatch | ROM verification | Device-specific (JTAG/SWD reflash, ROM recovery mode) |
| ROM → Stage-0 | Stage-0 corrupted | ROM verification or crash | JTAG/SWD reflash |
| Stage-0 → Stage-1 | Stage-1 header invalid | `eos_image_parse_header()` returns error | Enter UART recovery mode |
| Stage-0 → Stage-1 | Stage-1 integrity check fails | `eos_image_verify_integrity()` returns `EOS_ERR_CRC` | Enter UART recovery mode |
| Stage-0 → Stage-1 | Stage-1 payload unreadable | `eos_image_verify_integrity()` returns `EOS_ERR_FLASH` | Enter UART recovery mode |
| Stage-0 → Stage-1 | Stage-1 signature invalid | `eos_image_verify_signature()` returns `EOS_ERR_SIGNATURE` | Enter UART recovery mode |
| Stage-0 → Stage-1 | Stage-1 header edited after signing | `eos_image_verify_signature()` returns `EOS_ERR_SIGNATURE` (the signature covers the header prefix) | Enter UART recovery mode |
| Stage-0 → Stage-1 | Stage-1 version too old | `eos_image_check_version()` returns `EOS_ERR_VERSION` | Enter UART recovery mode |
| Stage-1 → App | Active slot image invalid | Integrity/signature check fails | Try alternate slot (B→A or A→B) |
| Stage-1 → App | Both slots invalid | Both fail verification | Enter UART recovery mode |
| Stage-1 → App | Boot attempts exceeded | `boot_attempts >= max_attempts` | Rollback to `confirmed_slot` |
| Stage-1 → App | Application crashes on test boot | Watchdog reset; `boot_attempts` incremented | After `max_attempts`: rollback |
| Stage-1 → App | Application fails self-test | App calls `eos_fw_request_recovery()` | Recovery mode on next boot |
| Any stage | Boot control block corrupt | `eos_bootctl_validate()` returns false | Use backup copy; if both corrupt, init defaults |

### 3.2 Recovery Decision Tree

```
Stage-0 verification of stage-1:
  ├── PASS → jump to stage-1
  └── FAIL
      ├── Recovery pin asserted? → YES → UART recovery
      └── NO → attempt recovery anyway (no valid stage-1)

Stage-1 verification of application:
  ├── Active slot PASS
  │   ├── Test boot?
  │   │   ├── YES → boot with attempt tracking
  │   │   └── NO → boot normally
  │   └── Boot
  ├── Active slot FAIL
  │   ├── Alternate slot PASS → boot alternate
  │   └── Alternate slot FAIL → UART recovery
  └── max_attempts exceeded → rollback to confirmed_slot
```

### 3.3 Unrecoverable Conditions

| Condition | Cause | Resolution |
|---|---|---|
| ROM verification fails (if enabled) | Corrupted stage-0 in flash | JTAG/SWD reflash required |
| All OTP key slots revoked | Incorrect key revocation sequence | Device is permanently bricked — hardware replacement |
| Flash hardware failure | Physical damage, wear-out | Hardware replacement |
| Debug interface locked + no valid firmware | Debug lock prevents reflash | Contact manufacturer for unlock (if supported) |

---

## 4. Anti-Rollback Mechanism

### 4.1 Monotonic Security Counter

Each firmware image carries a `security_counter` field in its header. The device maintains a monotonic counter in persistent storage that can only increase.

```
┌─────────────┐        ┌─────────────────┐
│ Image Header│        │ Device Storage   │
│             │        │                  │
│ security_   │───────>│ security_version │
│ counter: N  │ compare│ (monotonic): M   │
│             │        │                  │
└─────────────┘        └─────────────────┘

  If N >= M → ACCEPT (M is *not* raised yet — see below)
  If N <  M → REJECT (rollback attempt)
```

Acceptance and raising the floor are deliberately separate steps.

Raising `M` at verification time — the moment a new image is accepted — would
make every older image unbootable while the new one is still unproven. If it
then failed to run, the device would have no bootable fallback: an
unrecoverable brick caused by the security control itself.

`M` is therefore raised only once the booted image has been **confirmed**:

| Step | Function | Effect on `M` |
|---|---|---|
| Image verified during boot | `eos_rollback_verify()` then `eos_rollback_stage()` | unchanged; `N` remembered |
| Image runs and proves itself | `eos_bootctl_confirm()` → `eos_rollback_commit()` | raised to `N` |
| Image fails its trial boot | slot rolled back by boot policy | unchanged |

The device is protected throughout: between verification and confirmation the
previous image can still boot, but nothing below the *existing* floor can.

Because the counter is backed by one-time-programmable storage,
`eos_rollback_commit()` also:

- **never lowers `M`** — confirming an older-but-acceptable image burns nothing;
- **is idempotent** — re-confirming the same image consumes no further fuses;
- **refuses advances larger than `EOS_ROLLBACK_MAX_STEP` (16)** — a build
  mistake or hostile image requesting a huge jump would exhaust the fuse bank
  and permanently end the device's ability to accept future counter bumps;
- **reads the counter back** after incrementing, because a fuse burn can fail
  without reporting an error, and a counter that silently did not move would
  leave the device believing it is protected when it is not.

Boards whose `eos_board_ops_t` provides no `monotonic_read`/`monotonic_increment`
report `EOS_ERR_NOT_SUPPORTED`; verification is permissive on those boards, since
failing closed would make every device without OTP unbootable. Detect this at
provisioning time with `eos_rollback_get_device_counter()` rather than relying on
boot-time enforcement.

### 4.2 Counter Storage Options

| Method | Storage | Properties |
|---|---|---|
| OTP/eFuse bits | One-time programmable fuses | Irreversible; limited counter range (depends on fuse count) |
| Flash sector | Dedicated flash sector with anti-tearing | Reversible with physical access; unlimited range |
| Secure element | SE-managed counter | Irreversible; high counter range; tamper-resistant |

### 4.3 Version vs. Security Counter

| Field | Purpose | Comparison |
|---|---|---|
| `image_version` | Human-readable version (major.minor.patch) | Informational; logged in boot log |
| `security_counter` | Anti-rollback enforcement | Compared against device monotonic counter |

The `security_counter` is incremented independently of `image_version`. A minor patch may not increment the security counter, while a critical security fix always does.

---

## 5. Comparison with mcuboot's Approach

| Aspect | eBootloader | mcuboot |
|---|---|---|
| Boot stages | 3-stage (ROM → stage-0 → stage-1 → app) | 2-stage (ROM → mcuboot → app) |
| Upgrade strategy | Direct-write A/B slots | Swap-based (default), overwrite, or direct-XIP |
| Image verification | Hash-then-verify-signature (same as mcuboot) | Hash-then-verify-signature |
| Anti-rollback | Monotonic counter (OTP/flash/SE) | Security counter in image TLV |
| HAL abstraction | `eos_board_ops_t` vtable (function pointers) | `flash_area` API |
| Multi-arch | 24+ platform targets | Primarily ARM Cortex-M |
| Recovery | Dedicated UART recovery protocol | No built-in recovery; depends on external tools |
| Metadata format | Fixed-layout image header + optional TLV | TLV-based metadata after image |

See [mcuboot Comparison](mcuboot_comparison.md) for a detailed analysis.

---

## 6. Debug Interface State at Each Boot Stage

The debug interface (JTAG/SWD) state transitions through the boot chain to balance development needs with production security.

### 6.1 Debug State Matrix

| Boot Stage | Development Build | Production Build |
|---|---|---|
| ROM | Enabled (default) | Enabled (ROM cannot change) |
| Stage-0 entry | Enabled | Enabled (not yet configured) |
| Stage-0 after init | Enabled | **Locked** — debug lock applied via `board_early_init()` |
| Stage-1 | Enabled | Locked (inherited from stage-0) |
| Application | Enabled | Locked (inherited) |

### 6.2 Debug Lock Implementation

```c
void board_early_init(void) {
    /* ... clock and flash init ... */

#if defined(EOS_BUILD_PRODUCTION)
    /* Lock debug interface — platform-specific */
    #if defined(STM32F4)
        /* Set RDP Level 1 (or Level 2 for permanent lock) */
        HAL_FLASH_OB_Unlock();
        FLASH_OBProgramInitTypeDef ob = { .RDPLevel = OB_RDP_LEVEL_1 };
        HAL_FLASHEx_OBProgram(&ob);
        HAL_FLASH_OB_Lock();
    #elif defined(NRF52)
        NRF_APPROTECT->FORCEPROTECT = 1;
    #endif
#endif
}
```

### 6.3 Debug Lock Policy

| Policy | Description |
|---|---|
| **Development** | Debug always enabled. Well-known development signing key used. |
| **Staging** | Debug enabled via flag. Staging signing key used. |
| **Production** | Debug locked at stage-0. Production signing key. Unlock requires authenticated procedure (platform-dependent). |

---

## References

- [Architecture](architecture.md)
- [Key Lifecycle](key_lifecycle.md)
- [Threat Model](threat_model.md)
- [Security Model](security.md)
- [mcuboot Comparison](mcuboot_comparison.md)
- [Update Flow](update-flow.md)

# === docs/security.md ===

# eBootloader Security Model

## Phased Security Approach

eBootloader uses an incremental security model. The idea is to start
with a correct, simple system and layer complexity only when needed.

## Phase 1: Minimum Viable Protection

Available now in the initial codebase.

### CRC32 Integrity Checks
- Every firmware image has a CRC32 in its header hash field
- The boot manager verifies CRC32 before jumping to any image
- Boot control blocks carry CRC32 to detect corruption

### Version Comparison
- Image headers include a version field (major.minor.patch)
- The `eos_image_check_version()` API enables anti-rollback policies
- Firmware services expose version info to the application

### Redundant Metadata
- Boot control block is stored in two independent flash sectors
- If the primary copy is corrupt, the backup is used
- Both copies are written on every metadata update

### Anti-Tearing Writes
- Write sequence: compute CRC → erase primary → write primary → erase backup → write backup
- Power loss at any point leaves at least one valid copy

## Phase 2: Production-Grade Protection

Planned for future releases.

### SHA-256 Image Hash
- Replace CRC32 with a full SHA-256 hash in the header
- `sign_image.py --method sha256` already generates SHA-256 hashes
- Firmware verification reads the hash and recomputes over the payload

### Ed25519 / ECDSA Signature Verification
- The image header has a 64-byte signature field
- `sig_type` field indicates the signature algorithm
- Public key is embedded in the stage-1 boot code (cannot be modified)
- Signature verification happens in `eos_image_verify_signature()`

### Anti-Rollback Counters
- A monotonic counter stored in a dedicated flash region
- Each firmware release increments the counter
- Older firmware versions cannot be installed

## Phase 3: Advanced Security

### Payload Encryption
- Images can be encrypted (AES-256-CBC or AES-256-GCM)
- Decryption key stored in hardware secure storage (OTP / eFuse)
- `EOS_IMG_FLAG_ENCRYPTED` flag in the image header

### Recovery Authorization
- Recovery mode requires authentication (shared secret or challenge-response)
- Prevents unauthorized firmware replacement via physical access

### Secure Boot Chain
- Stage-0 verifies stage-1 before jumping
- Stage-1 verifies application before jumping
- Full chain of trust from ROM to application

## Design Rules

1. **Do not start with maximum complexity.** A correct CRC-based boot
   path is better than a broken signature implementation.

2. **Security features should be additive.** Phase 1 code should work
   unchanged when Phase 2 features are added.

3. **Never store secrets in flash alongside firmware.** Use hardware
   secure storage (OTP, eFuse, secure enclave) for keys.

4. **Recovery mode is a security boundary.** Physical access to UART
   should require authentication in production builds.

---

## Implementation Status

### Phase 2 Feature Status

| Feature | Module | API | Status | Acceptance Criteria |
|---|---|---|---|---|
| SHA-256 image hash | `core/crypto_boot.c` | `eos_crypto_hash()`, `eos_crypto_verify_image()` | ✅ Implemented (FIPS 180-4) | Hash matches NIST CAVP test vectors; image verification rejects single-bit payload corruption |
| Ed25519 signature verification | `core/ed25519_verify.c` | `eos_ed25519_verify()`, via `eos_crypto_verify_signature()` | ✅ Implemented (RFC 8032) | RFC 8032 §7.1 vectors 1–3 accepted; every single-bit flip of a valid signature (512 cases) rejected; wrong key, tampered message, all-zero key/signature and non-canonical S (S+L) rejected — all asserted in `tests/unit/test_ed25519.c`. Scalar multiplication is branch-free; **timing has not been measured**, and verification handles only public inputs. |
| Image signature check | `core/image_verify.c` | `eos_image_verify_signature()` | ✅ Implemented | Valid signatures accepted; invalid rejected with `EOS_ERR_SIGNATURE`; all return codes checked |
| Key hash in TLV | `include/eos_image.h` | TLV extension (planned) | 🔲 Not started | Key hash selects correct verification key slot; unknown key hash returns error |
| Anti-rollback counter | `include/eos_bootctl.h` | `eos_image_check_version()` | 🔶 API defined | Counter stored in OTP/flash; images with lower counter rejected; counter survives factory reset |
| Security counter in header | `include/eos_image.h` | Header `reserved` field allocation | 🔲 Not started | Counter field parsed from header; compared against device counter before boot |
| Dual key slots | `include/eos_signing_key.h` | Compiled-in key array | 🔲 Not started | Two key slots available; revoked slots skipped; rotation without bricking |

### Phase 3 Feature Status

| Feature | Module | API | Status | Acceptance Criteria |
|---|---|---|---|---|
| AES-256-GCM payload encryption | `core/crypto_boot.c` | Planned | 🔲 Not started | Encrypted images decrypted before verification; GCM tag validated; plaintext never stored in flash |
| Recovery authentication | `core/recovery.c` | Planned | 🔲 Not started | Unauthenticated UART commands rejected; challenge-response completes in < 5 seconds; brute-force rate limited |
| Debug lock at boot | `boards/*/board_init.c` | Platform-specific | 🔲 Not started | JTAG/SWD locked in production builds; debug lock applied before any secret processing; verified by probe test |
| MPU isolation between stages | `core/mpu_boot.c` | `eos_mpu_boot.h` | 🔲 Not started | Stage-1 cannot write stage-0 region; application cannot write bootloader regions; MPU fault handler logs violation |
| Flash write protection | HAL | Platform-specific | 🔲 Not started | Bootloader flash sectors marked read-only after stage-0 init; write attempts generate fault |
| Recovery audit logging | `core/recovery.c` | Planned | 🔲 Not started | All recovery commands logged with timestamp; log survives reset; log readable via LOG command |

### Status Legend

| Symbol | Meaning |
|---|---|
| ✅ | Implemented and tested |
| 🔶 | API defined, partial or stub implementation |
| 🔲 | Not started |

---

## Cross-References

| Document | Description |
|---|---|
| [Threat Model](threat_model.md) | STRIDE-based threat analysis with risk ratings for each trust boundary |
| [Key Lifecycle](key_lifecycle.md) | Ed25519 key generation, dual-slot support, rotation, revocation, and emergency response |
| [Secure Boot Chain](secure_boot_chain.md) | Complete chain of trust from ROM → stage-0 → stage-1 → application with verification steps |
| [mcuboot Comparison](mcuboot_comparison.md) | Design decisions relative to mcuboot — adopted patterns, intentional divergences |
| [Security Review Checklist](security_review_checklist.md) | PR review checklist for security-critical code changes |
| [Architecture](architecture.md) | Staged boot architecture, module map, flash memory map, boot flow |
| [Update Flow](update-flow.md) | OTA update sequence, rollback triggers, anti-tearing protection |
| [Risk Register](compliance/risk_register.md) | Project-wide risk register with likelihood, impact, and mitigation status |

# === docs/threat_model.md ===

# Threat Model — eBootloader

> **Methodology:** STRIDE (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege)
>
> **Last updated:** 2026-04-03
>
> **Scope:** eBootloader staged boot system (stage-0, stage-1, recovery, flash storage, firmware update pipeline)

---

## 1. Assumptions

### 1.1 Physical Access Model

| Assumption | Description |
|---|---|
| **Field deployment** | Devices are deployed in physically accessible locations (edge gateways, industrial controllers, IoT endpoints). An attacker may gain physical access to the device enclosure. |
| **Debug ports** | JTAG/SWD debug headers may be populated on development boards but should be disabled or locked in production builds. |
| **UART access** | The recovery UART is accessible with enclosure removal. Production builds must authenticate recovery sessions. |
| **Chip decapping** | Invasive silicon attacks (decapping, FIB probing) are out of scope for the base threat model. Devices requiring this level of protection should use a discrete secure element. |

### 1.2 Deployment Context

| Parameter | Value |
|---|---|
| Target platforms | Cortex-M0/M3/M4/M7/M33, Cortex-A53/A72, Cortex-R5F, RISC-V RV32/RV64 |
| Connectivity | Devices may be network-connected (OTA updates via application firmware) |
| Lifetime | 5–15 year field deployment |
| Update frequency | Quarterly security patches, ad-hoc critical fixes |
| Regulatory context | ISO/IEC 20243 (supply chain), ISO/IEC/IEEE 15288:2023 (secure lifecycle) |

---

## 2. Trust Boundaries

```
┌──────────────────────────────────────────────────┐
│                   Silicon ROM                     │
│           (immutable, vendor-provided)            │
├─ ─ ─ ─ ─ ─ TB-1: ROM → Stage-0 ─ ─ ─ ─ ─ ─ ─ ─┤
│              Stage-0 (eBootloader)                │
│      16 KB — minimal HW init, recovery check      │
├─ ─ ─ ─ ─ ─ TB-2: Stage-0 → Stage-1 ─ ─ ─ ─ ─ ─┤
│              Stage-1 (E-Boot)                     │
│    48 KB — image scan, boot policy, boot log      │
├─ ─ ─ ─ ─ ─ TB-3: Stage-1 → Application ─ ─ ─ ─ ┤
│              Application Firmware                 │
│         448 KB × 2 slots (A/B)                    │
└──────────────────────────────────────────────────┘

External boundaries:
  TB-4: UART Recovery Interface (physical)
  TB-5: Flash Storage (internal/external NOR/NAND)
  TB-6: Debug Interface (JTAG/SWD)
  TB-7: Firmware Update Pipeline (OTA → application → slot write)
```

### Boundary Descriptions

| Boundary | From | To | Data Crossing | Protection |
|---|---|---|---|---|
| TB-1 | Silicon ROM | Stage-0 | Execution handoff, vector table | ROM validates stage-0 hash (SoC-dependent) |
| TB-2 | Stage-0 | Stage-1 | Execution handoff, HAL vtable | Stage-0 verifies stage-1 image header + hash/signature |
| TB-3 | Stage-1 | Application | Execution handoff, boot state | Stage-1 verifies application image header + hash/signature |
| TB-4 | External host | Stage-0/Stage-1 | UART packets (PING, ERASE, WRITE, BOOT, etc.) | Packet format validation; authentication planned (Phase 3) |
| TB-5 | Flash IC | CPU | Image payloads, boot control block, boot log | CRC32 (Phase 1), SHA-256 + signatures (Phase 2), encryption (Phase 3) |
| TB-6 | Debug probe | CPU | Memory read/write, halt, step | Debug lock bits (platform-dependent) |
| TB-7 | Cloud/server | Application → Flash | Firmware image bytes | Application-layer TLS; bootloader verifies image before activation |

---

## 3. Attack Surfaces

### 3.1 UART Recovery Protocol

- **Interface:** `eos_hal_uart_send()` / `eos_hal_uart_recv()` via `eos_board_ops_t` function pointers
- **Packet format:** `[cmd:1][slot:1][len:2][offset:4]` — 8-byte header
- **Commands exposed:** PING, INFO, ERASE, WRITE, VERIFY, BOOT, LOG, RESET, FACTORY
- **Attack vector:** Malformed packets, unauthorized firmware replacement, command injection

### 3.2 Flash Contents

- **Regions:** Slot A (448 KB), Slot B (448 KB), Recovery (16 KB), Boot control primary (8 KB), Boot control backup (8 KB), Boot log (8 KB), Device config (24 KB)
- **Attack vector:** Direct flash modification (physical), corrupted OTA writes, bit-flip attacks

### 3.3 JTAG/SWD Debug Interface

- **Attack vector:** Memory extraction, firmware dumping, runtime state manipulation, bypassing boot verification
- **Notes:** Debug lock mechanism is platform-dependent (e.g., STM32 RDP level, nRF APPROTECT)

### 3.4 Firmware Update Pipeline

- **Flow:** Cloud → Application (TLS download) → `eos_hal_flash_write()` to inactive slot → `eos_fw_request_upgrade()` → reboot → Stage-1 verification
- **Attack vector:** Man-in-the-middle on OTA channel, supply chain compromise, malicious update server

### 3.5 Boot Control Block

- **Structure:** `eos_bootctl_t` — 96 bytes with CRC32 protection
- **Fields at risk:** `active_slot`, `pending_slot`, `boot_attempts`, `max_attempts`, `flags`
- **Attack vector:** Corrupt control block to force boot to attacker-controlled slot, reset boot attempts to prevent rollback, set factory reset flag

---

## 4. Threat Matrix

### TB-1: ROM → Stage-0

| ID | STRIDE | Threat | Likelihood | Impact | Risk | Mitigation | Status |
|---|---|---|---|---|---|---|---|
| T-101 | Tampering | Attacker modifies stage-0 binary in flash | Low | Critical | High | ROM hash verification (SoC-dependent); debug lock | Planned |
| T-102 | Elevation of Privilege | Stage-0 contains vulnerability allowing arbitrary code execution | Low | Critical | High | Minimal code surface (16 KB); no dynamic memory; stack bounds | Mitigated |
| T-103 | Information Disclosure | Stage-0 leaks key material or secrets via UART during early init | Low | High | Medium | No secrets processed in stage-0; UART output limited to recovery mode | Mitigated |

### TB-2: Stage-0 → Stage-1

| ID | STRIDE | Threat | Likelihood | Impact | Risk | Mitigation | Status |
|---|---|---|---|---|---|---|---|
| T-201 | Tampering | Attacker replaces stage-1 binary with malicious code | Medium | Critical | High | SHA-256 hash verification of stage-1 image (Phase 2); Ed25519 signature verification (Phase 2) | Planned |
| T-202 | Spoofing | Attacker presents old stage-1 version to exploit known vulnerability | Medium | High | High | Anti-rollback security counter enforced against the device monotonic counter (`eos_rollback_verify()`), raised on slot confirmation (`eos_rollback_commit()`); `eos_image_check_version()` | Mitigated (boards with a monotonic counter) |
| T-203 | Denial of Service | Corrupt stage-1 image prevents boot | Low | High | Medium | Recovery mode fallback; redundant boot control block | Mitigated |
| T-204 | Elevation of Privilege | Stage-1 runs with same privilege as stage-0 (no isolation) | Medium | High | Medium | MPU configuration at stage boundary (Phase 3); `eos_mpu_boot.h` | Planned |

### TB-3: Stage-1 → Application

| ID | STRIDE | Threat | Likelihood | Impact | Risk | Mitigation | Status |
|---|---|---|---|---|---|---|---|
| T-301 | Tampering | Attacker modifies application firmware in flash | Medium | Critical | High | CRC32 integrity check (Phase 1); SHA-256 + Ed25519 signature over the full header prefix (Phase 2) | Partial |
| T-303 | Tampering | Attacker edits image header metadata (entry point, load address, integrity flags) while keeping a valid signature | Medium | Critical | High | Signature covers `EOS_IMG_SIGNED_LEN` bytes of the header, not `hash[]` alone (image header v2) | Mitigated |
| T-302 | Spoofing | Rollback to older firmware version with known vulnerabilities | Medium | High | High | Version comparison via `eos_image_check_version()`; monotonic counter (Phase 2) | Planned |
| T-303 | Information Disclosure | Unencrypted firmware reveals intellectual property | Medium | Medium | Medium | AES-256-GCM payload encryption (Phase 3); `EOS_IMG_FLAG_ENCRYPTED` | Planned |
| T-304 | Denial of Service | Both slots contain invalid images, device is bricked | Low | Critical | Medium | Recovery image in dedicated partition (16 KB); UART recovery protocol | Mitigated |
| T-305 | Repudiation | No audit trail of which firmware version was booted | Low | Medium | Low | Boot log records slot, version, verification result, reset reason | Mitigated |
| T-306 | Elevation of Privilege | Application gains ability to overwrite bootloader regions | Low | Critical | Medium | Flash write protection for bootloader regions (platform MPU/flash lock) | Planned |

### TB-4: UART Recovery Interface

| ID | STRIDE | Threat | Likelihood | Impact | Risk | Mitigation | Status |
|---|---|---|---|---|---|---|---|
| T-401 | Spoofing | Unauthorized party connects to UART and replaces firmware | Medium | Critical | High | Recovery authentication — challenge-response or shared secret (Phase 3) | Planned |
| T-402 | Tampering | Malformed UART packets corrupt flash or boot state | Medium | High | High | Packet validation; length bounds checking; CRC on write data | Partial |
| T-403 | Denial of Service | Flood UART with garbage to prevent legitimate recovery | Low | Medium | Low | Command timeout; watchdog feed during recovery; rate limiting | Partial |
| T-404 | Information Disclosure | INFO discloses flash geometry and, since #139, a capability byte (`caps`: has RNG, has OTP); LOG discloses boot history | Low | Medium | Low | LOG restricted to authenticated sessions (Phase 3). INFO is deliberately unauthenticated per ADR-021: everything it discloses an attacker learns by trying, and the integrator needs it before AUTH to diagnose a board with no entropy source | Partial (INFO decided; LOG planned) |
| T-405 | Repudiation | Recovery operations not logged | Medium | Medium | Medium | Boot log records recovery entry, commands executed, exit reason | Planned |
| T-406 | Elevation of Privilege | FACTORY command erases all data without authorization | Medium | Critical | High | Require authentication before FACTORY; confirmation sequence | Planned |

### TB-5: Flash Storage

| ID | STRIDE | Threat | Likelihood | Impact | Risk | Mitigation | Status |
|---|---|---|---|---|---|---|---|
| T-501 | Tampering | Direct flash modification via physical access or glitch attack | Low | Critical | Medium | SHA-256 + signature verification at boot; flash write protection | Planned |
| T-502 | Tampering | Power loss during boot control block write corrupts metadata | Medium | High | High | Anti-tearing dual-write (primary + backup); CRC32 validation on load | Mitigated |
| T-503 | Information Disclosure | Flash contents readable via chip-off or debug interface | Low | High | Medium | Payload encryption with AES-256-GCM (Phase 3); debug lock | Planned |
| T-504 | Denial of Service | Flash wear-out from excessive erase/write cycles | Low | High | Low | Wear-leveling for boot control region; write coalescing | Monitored |

### TB-6: Debug Interface (JTAG/SWD)

| ID | STRIDE | Threat | Likelihood | Impact | Risk | Mitigation | Status |
|---|---|---|---|---|---|---|---|
| T-601 | Information Disclosure | Firmware and secrets extracted via debug probe | Medium | Critical | High | Platform debug lock (STM32 RDP Level 2, nRF APPROTECT); disabled in production | Planned |
| T-602 | Tampering | Runtime memory modified to bypass signature checks | Medium | Critical | High | Debug lock; glitch detection (platform-dependent) | Planned |
| T-603 | Elevation of Privilege | Debug interface used to execute arbitrary code | Medium | Critical | High | Debug lock in production; conditional compilation removes debug hooks | Planned |

### TB-7: Firmware Update Pipeline

| ID | STRIDE | Threat | Likelihood | Impact | Risk | Mitigation | Status |
|---|---|---|---|---|---|---|---|
| T-701 | Tampering | Man-in-the-middle modifies firmware image during OTA download | Medium | Critical | High | Application-layer TLS; Stage-1 verifies image signature before boot | Partial |
| T-702 | Spoofing | Attacker impersonates update server | Medium | High | High | Certificate pinning in application; image signed with Ed25519 key | Planned |
| T-703 | Repudiation | No record of who authorized a firmware update | Low | Medium | Low | Boot log records update source, version, timestamp | Planned |
| T-704 | Denial of Service | Repeated invalid update attempts exhaust flash erase cycles | Low | Medium | Low | Rate limiting on update requests; validate header before erase | Monitored |

**External evidence — CVE-2026-86326 (Moxa, Oct 2026).** Moxa MGate
MB3000/EIP3000/5000 gateways do not verify firmware authenticity
(CVSSv4 8.6, MPSA-269540) — and **no firmware fix shipped at disclosure**;
customers were given a compensating-controls playbook only. This is the
exact flaw class the #162 Ed25519 envelope answers, and the "no fix
shipped" detail is why eBoot's verify-before-boot must be fail-closed
(boot refuses unsigned firmware) rather than advisory: when the vendor
never patches, the device's only protection is the one baked into the
boot chain.

**External evidence — CVE-2026-84411 (MikroTik RouterOS, Oct 2026).**
Unauthenticated RCE via integer underflow in the RouterOS HTTP login
(CVSS 9.8, CISA advisory) — a single crafted request, all RouterOS <7.24.
Patched in 7.24, but field adoption is ~zero as of Oct 5: the patch exists
and the fleet is still vulnerable. The "patch-available-but-not-deployed"
class — the device's own boot chain cannot rely on the vendor's update
cadence reaching it in time.

**External evidence — CVE-2026-105484 (TOTOLINK X6000R, Oct 2026).**
Unauthenticated RCE (CVSS 10.0) with **no patched firmware confirmed at
disclosure** — a second "no firmware fix at disclosure" case alongside the
Moxa row above. When neither a patch nor a timeline exists, fail-closed
verify-before-boot is the only control the device actually has.

---

## 5. Risk Summary

| Risk Level | Count | Examples |
|---|---|---|
| **Critical** | 0 | — |
| **High** | 12 | T-201, T-301, T-401, T-601, T-602, T-603, T-701 |
| **Medium** | 10 | T-204, T-303, T-304, T-306, T-402, T-405, T-501, T-503 |
| **Low** | 6 | T-103, T-305, T-403, T-404, T-504, T-704 |

> **Note:** No risks are rated Critical overall because the phased mitigation strategy addresses the highest-impact threats. Residual risk is High for threats dependent on Phase 2/3 implementation.

---

## 6. Mitigation Roadmap

### Phase 1 — Implemented

| Control | Threats Addressed |
|---|---|
| CRC32 integrity check on images | T-301 (partial) |
| Dual boot control block with CRC | T-502 |
| Version comparison API | T-302 (partial) |
| Boot log with reset reason | T-305 |
| Recovery mode with packet validation | T-402 (partial) |
| Redundant metadata (primary + backup) | T-203, T-304 |

### Phase 2 — Planned

| Control | Threats Addressed | Target |
|---|---|---|
| SHA-256 image hash | T-201, T-301, T-501 | v0.2.0 |
| Ed25519 signature verification | T-201, T-301, T-701 | v0.2.0 |
| Anti-rollback monotonic counter | T-202, T-302 | v0.2.0 |
| Key hash in image TLV | T-701, T-702 | v0.2.0 |
| Security counter in image header | T-202, T-302 | v0.2.0 |

### Phase 3 — Planned

| Control | Threats Addressed | Target |
|---|---|---|
| AES-256-GCM payload encryption | T-303, T-503 | v0.3.0 |
| Recovery authentication (challenge-response) | T-401, T-404, T-405, T-406 | v0.3.0 |
| Debug lock enforcement at boot | T-601, T-602, T-603 | v0.3.0 |
| MPU isolation between stages | T-204, T-306 | v0.3.0 |
| Flash write protection for bootloader | T-101, T-306 | v0.3.0 |

### Watch items — external dependencies

| Item | Detail | eBoot impact | Status |
|---|---|---|---|
| ESP-IDF v6.1 disables ECDSA Secure Boot V2 on ESP32-H2/C5/P4 | Disabled "due to a security vulnerability found in the ECDSA based Secure Boot flow"; details promised in chip errata. 192-bit curve removed. | If eBoot's ESP32 trust path assumes the ECDSA-SBv2 flow, it inherits the vulnerability. Verify the assumption and plan the migration to the v6.1-supported flow. | Monitored |
| ESP-IDF v6.1: ESP32-P4 default silicon rev v3.0 | Images must target the revision they ship for. | eBoot ESP32-P4 bring-up docs must name the rev. | Monitored |
| ESP-IDF v6.1 fixes LP-SPI MISO bug (v6.0-6.0.3) |  | Relevant to SPI flash attach on affected parts. | Monitored |

---

## 7. Risk Assessment Method

Consistent with [risk_register.md](compliance/risk_register.md):

- **Likelihood:** Low / Medium / High
- **Impact:** Low / Medium / High / Critical
- **Overall Risk:** Derived from likelihood × impact matrix:

| | Low Impact | Medium Impact | High Impact | Critical Impact |
|---|---|---|---|---|
| **High Likelihood** | Medium | High | High | Critical |
| **Medium Likelihood** | Low | Medium | High | High |
| **Low Likelihood** | Low | Low | Medium | Medium |

- **Status:** Open / Monitored / Partial / Planned / Mitigated / Closed

---

## 8. Review Schedule

| Activity | Frequency | Owner |
|---|---|---|
| Threat model review | Every major release | Security lead |
| Risk rating update | Quarterly | Project lead |
| New attack surface assessment | On architecture change | Development team |
| Penetration test (UART, flash) | Annually | External assessor |

---

## References

- [Security Model](security.md)
- [Risk Register](compliance/risk_register.md)
- [Architecture](architecture.md)
- [Key Lifecycle](key_lifecycle.md)
- [Secure Boot Chain](secure_boot_chain.md)

# === docs/update-flow.md ===

# eBootloader Update Flow

## Overview

eBootloader supports three firmware update strategies. This document
describes the recommended OTA workflow (firmware-owned download,
bootloader-owned activation).

## OTA Update Sequence

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Cloud /    │     │ Application │     │  E-Boot     │
│   Server     │     │  Firmware   │     │  (Stage-1)  │
└──────┬───────┘     └──────┬──────┘     └──────┬──────┘
       │                    │                    │
       │  1. New version    │                    │
       │    available       │                    │
       │ ──────────────────>│                    │
       │                    │                    │
       │  2. Download       │                    │
       │    image chunks    │                    │
       │ ──────────────────>│                    │
       │                    │                    │
       │                    │ 3. Write to        │
       │                    │    inactive slot   │
       │                    │ (Slot B)           │
       │                    │                    │
       │                    │ 4. Request         │
       │                    │    test boot       │
       │                    │ eos_fw_request_    │
       │                    │ upgrade(B, TEST)   │
       │                    │                    │
       │                    │ 5. Reboot          │
       │                    │ ──────────────────>│
       │                    │                    │
       │                    │                    │ 6. Verify Slot B
       │                    │                    │    image
       │                    │                    │
       │                    │                    │ 7. Boot Slot B
       │                    │                    │    (test mode)
       │                    │                    │
       │                    │ 8. Self-test       │
       │                    │<───────────────────│
       │                    │                    │
       │                    │ 9. eos_fw_confirm_ │
       │                    │    running_image() │
       │                    │                    │
       │                    │    ── OR ──        │
       │                    │                    │
       │                    │ 9b. Crash /        │
       │                    │     watchdog       │
       │                    │     → rollback     │
       │                    │                    │
```

## Application Code Example

### Requesting an Update

```c
int do_ota_update(const uint8_t *image_data, size_t image_len)
{
    eos_slot_t target = EOS_SLOT_B;
    uint32_t addr = eos_hal_slot_addr(target);

    /* Erase target slot */
    eos_hal_flash_erase(addr, eos_hal_slot_size(target));

    /* Write image (header + payload) */
    eos_hal_flash_write(addr, image_data, image_len);

    /* Request test boot */
    int rc = eos_fw_request_upgrade(target, EOS_UPGRADE_TEST);
    if (rc != EOS_OK) return rc;

    /* Reboot to apply */
    eos_hal_system_reset();
    return EOS_OK; /* unreachable */
}
```

### Confirming After Self-Test

```c
int app_startup(void)
{
    if (eos_fw_is_test_boot()) {
        if (self_test_passed()) {
            eos_fw_confirm_running_image();
        } else {
            /* Don't confirm — let watchdog trigger rollback */
            eos_fw_request_recovery();
            eos_hal_system_reset();
        }
    }
    return 0;
}
```

## Rollback Triggers

| Trigger                          | Result                         |
|----------------------------------|--------------------------------|
| Unconfirmed test boot + reboot   | boot_attempts incremented      |
| boot_attempts ≥ max_attempts     | Automatic rollback to Slot A   |
| Watchdog reset during test boot  | boot_attempts incremented      |
| No valid image in active slot    | Fallback to alternate slot     |
| No valid image in either slot    | Enter recovery mode            |

## Anti-Tearing Protection

The boot control block is written to **two separate flash sectors**
(primary and backup). The write sequence is:

1. Compute CRC32 of new boot control data
2. Erase primary sector
3. Write primary sector
4. Erase backup sector
5. Write backup sector

On load, if the primary copy fails CRC validation, the backup is used.
This protects against power loss during metadata updates.

# === docs/key_lifecycle.md ===

# Key Lifecycle Management — eBootloader

> **Last updated:** 2026-04-03
>
> **Applies to:** Ed25519 signing keys used for firmware image verification in the eBootloader secure boot chain.

---

## 1. Overview

eBootloader uses **Ed25519** (RFC 8032) digital signatures to verify firmware image authenticity and integrity. This document defines the full lifecycle of the signing keypair — from generation through rotation, revocation, and emergency response.

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Generate    │────>│   Deploy     │────>│   Verify     │
│  Keypair     │     │   Public Key │     │   at Boot    │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │                     │
       │              ┌─────┴─────┐               │
       │              │ Key Slot 0│               │
       │              │ Key Slot 1│               │
       │              └───────────┘               │
       │                                          │
       ▼                                          ▼
┌──────────────┐                          ┌──────────────┐
│   Rotate     │                          │   Revoke     │
│   (new key)  │                          │   (counter)  │
└──────────────┘                          └──────────────┘
```

---

## 2. Ed25519 Keypair Generation

### 2.1 Algorithm Specification

| Parameter | Value |
|---|---|
| Algorithm | Ed25519 (EdDSA over Curve25519) |
| Private key size | 32 bytes |
| Public key size | 32 bytes |
| Signature size | 64 bytes |
| Hash function | SHA-512 (internal to Ed25519) |
| Reference | RFC 8032, Section 5.1 |

### 2.2 Generation Procedure

**Prerequisites:**
- Air-gapped workstation running a hardened OS (no network interfaces active)
- Hardware random number generator (TRNG) or `/dev/random` with sufficient entropy
- OpenSSL ≥ 1.1.1 or `ed25519-keygen` from the eBootloader tools

**Steps:**

```bash
# 1. Generate Ed25519 private key (PEM format)
openssl genpkey -algorithm Ed25519 -out eboot_signing_key.pem

# 2. Extract public key
openssl pkey -in eboot_signing_key.pem -pubout -out eboot_signing_pub.pem

# 3. Export raw 32-byte public key for embedding
openssl pkey -in eboot_signing_key.pem -pubout -outform DER | \
    tail -c 32 > eboot_signing_pub.raw

# 4. Generate SHA-256 hash of public key (for TLV embedding)
sha256sum eboot_signing_pub.raw > eboot_signing_pub.sha256

# 5. Verify the keypair
echo "test" | openssl pkeyutl -sign -inkey eboot_signing_key.pem | \
    openssl pkeyutl -verify -pubin -inkey eboot_signing_pub.pem
```

**Alternative — using eBootloader tooling:**

```bash
# Generate the keypair and the value the bootloader build takes as its
# trust anchor. Writes keys/private.pem, keys/public.pem and
# keys/public_key.hex (64 hex characters). There is no header to embed:
# the anchor is compiled in at configure time from the flag below.
python3 tools/sign_image.py --genkey --output keys/
cmake -B build -DEBLDR_BOARD=<board> -DCMAKE_BUILD_TYPE=Release \
      -DEBLDR_PRODUCTION_KEY=$(cat keys/public_key.hex)
```

### 2.3 Key Storage After Generation

| Storage Location | Content | Access Control |
|---|---|---|
| HSM or air-gapped vault | Private key (`eboot_signing_key.pem`) | Two-person access; encrypted at rest |
| CI/CD signing server | Private key (encrypted) | Build system service account only |
| Source repository | **Never** — private keys must never be committed | N/A |

---

## 3. Public Key Embedding

### 3.1 Compiled-In Key (Default)

The public key is compiled into the bootloader. `eos_keystore_init()`
(`core/keystore.c`) uses it only when the board has no OTP at all — when
`eos_hal_otp_read()` returns `EOS_ERR_NOT_SUPPORTED` because the board port
provides no `otp_read` hook. Today that is every board under `boards/`, so
on every shipped board the compiled-in key *is* the trust anchor.

**Which key gets compiled in is a configure-time decision:**

```bash
# A real key: the raw 32-byte Ed25519 public key as 64 hex characters,
# e.g. the `.pub.raw` file from §2.2 step 3, hex-encoded.
cmake -B build -DEBLDR_BOARD=stm32f4 -DCMAKE_BUILD_TYPE=Release \
      -DEBLDR_PRODUCTION_KEY=3d4017c3e843895a92b70aa74d1b7ebc9c982ccf2ec4968cc0cd55f12af4660c
```

`cmake/ProductionKey.cmake` checks the value (exactly 64 hex characters, and
not the development key), generates `build/generated/production_key.c`
defining `ebldr_production_key[]` (declared in `include/eos_production_key.h`),
compiles it into `eboot_core`, and defines `EBLDR_PRODUCTION_KEY` so
`core/keystore.c` uses that symbol in place of its development key.

**Without `EBLDR_PRODUCTION_KEY` the compiled-in key is the development key**
(§7.4), and the build says so with a `#warning` on every compile of
`core/keystore.c`. A **Release build of a real board refuses to configure**
in that state:

```
CMake Error at CMakeLists.txt:56 (message):
  EBLDR_PRODUCTION_KEY is not set: a Release build of board 'stm32f4' would
  compile in the RFC 8032 test key as its trust anchor, and anyone can sign
  for that key. Pass -DEBLDR_PRODUCTION_KEY=<64 hex characters> (the raw
  Ed25519 public key), or, for a bring-up or CI build that will never reach a
  device, -DEBLDR_ALLOW_DEV_KEY=ON.
```

`-DEBLDR_ALLOW_DEV_KEY=ON` is the one way past the gate. It exists for
bring-up on a bench and for CI cross-compiles that only check the tree
builds; it is never passed by `.github/workflows/release.yml`, and
`tests/unit/test_release_workflow_production_key.py` fails if it ever is.
`tests/unit/test_production_key_gate.py` runs real configures against the
tree and pins each of the behaviours above.

**Verification** uses whatever the keystore selected: `eos_image_verify_signature()`
takes the active key from `eos_keystore_get_active_key()` and checks the
Ed25519 signature over the signed header prefix (`EOS_IMG_SIGNED_LEN`).

### 3.2 OTP/eFuse Key Storage

For devices with one-time-programmable memory:

| Field | OTP Address | Size | Description |
|---|---|---|---|
| `pubkey_slot_0` | OTP base + 0x00 | 32 bytes | Primary public key |
| `pubkey_slot_1` | OTP base + 0x20 | 32 bytes | Backup public key |
| `key_revoke_mask` | OTP base + 0x40 | 4 bytes | Bit mask — bit N=1 revokes slot N |
| `security_version` | OTP base + 0x44 | 4 bytes | Monotonic counter for anti-rollback |

**Advantages over compiled-in:**
- Public key cannot be modified by flash reprogramming
- Key revocation is permanent (OTP bits are one-way)
- Survives complete flash erase

### 3.3 Secure Element Key Storage

For high-security deployments using an external secure element (e.g., ATECC608B, OPTIGA Trust M):

| Operation | API |
|---|---|
| Store public key | `se_write_slot(slot_id, pubkey, 32)` |
| Verify signature | `se_verify_ed25519(slot_id, hash, sig)` |
| Read key hash | `se_read_slot_hash(slot_id, hash_out)` |

The secure element performs the signature verification internally — the public key is protected from modification by the SE's tamper-resistant hardware.

---

## 4. Dual-Key Slot Support

eBootloader supports **two key slots** (primary and backup) to enable seamless key rotation without bricking deployed devices.

### 4.1 Key Slot Architecture

```
┌─────────────────────────────────┐
│        Image Header             │
│   sig_type = ED25519            │
│   signature[64]                 │
│   (signed with either key)      │
└──────────────┬──────────────────┘
               │
        ┌──────┴──────┐
        ▼             ▼
  ┌──────────┐  ┌──────────┐
  │ Slot 0   │  │ Slot 1   │
  │ Primary  │  │ Backup   │
  │ pubkey   │  │ pubkey   │
  └──────────┘  └──────────┘
```

### 4.2 Verification Algorithm

The bootloader tries each non-revoked key slot in order:

1. Check `key_revoke_mask` — skip any revoked slots
2. Attempt signature verification with slot 0 public key
3. If slot 0 fails, attempt with slot 1 public key
4. If all slots fail → `EOS_ERR_SIGNATURE`

### 4.3 Slot Assignment Convention

| Slot | Purpose | Typical Usage |
|---|---|---|
| Slot 0 | Primary production key | Signs all production firmware releases |
| Slot 1 | Backup / rotation target | Receives new key during rotation; becomes new primary |

---

## 5. Key Rotation Procedure

Key rotation replaces the active signing key without disrupting deployed devices. The dual-slot architecture ensures that devices can verify firmware signed with either the old or new key during the transition window.

### 5.1 Rotation Timeline

```
Phase 1: Prepare          Phase 2: Transition       Phase 3: Revoke
(1 release cycle)         (2 release cycles)        (after full fleet update)

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│ Generate new    │      │ Sign firmware   │      │ Revoke old key  │
│ keypair         │      │ with NEW key    │      │ (set revoke bit)│
│                 │      │                 │      │                 │
│ Install new     │      │ Old key still   │      │ Increment       │
│ pubkey in       │      │ accepted for    │      │ security version│
│ slot 1          │      │ verification    │      │                 │
│                 │      │                 │      │ Sign firmware   │
│ Continue signing│      │ Fleet updates   │      │ with new key    │
│ with OLD key    │      │ propagate       │      │ only            │
└─────────────────┘      └─────────────────┘      └─────────────────┘
```

### 5.2 Step-by-Step Procedure

**Phase 1 — Prepare (release N):**

1. Generate new Ed25519 keypair on air-gapped workstation (see §2.2)
2. Update `eos_signing_pubkey_1` in `include/eos_signing_key.h` with new public key
3. Build and sign stage-1 bootloader with existing (old) key
4. Deploy bootloader update — devices now have both public keys
5. Continue signing application firmware with old key (slot 0)

**Phase 2 — Transition (releases N+1, N+2):**

6. Begin signing new application firmware with the **new** key (slot 1)
7. Devices that received the bootloader update verify with slot 1
8. Devices still on old bootloader verify with slot 0 (old firmware still deployed)
9. Monitor fleet update telemetry — track percentage of devices on new bootloader

**Phase 3 — Revoke (release N+3, after fleet convergence):**

10. Verify ≥99% of fleet has updated bootloader with both key slots
11. Set `key_revoke_mask` bit 0 to revoke old key (slot 0)
12. Move new key to slot 0; generate next rotation key in slot 1 (optional)
13. Increment `security_version` monotonic counter
14. Securely destroy old private key material

### 5.3 Rotation Checklist

- [ ] New keypair generated on air-gapped workstation
- [ ] New public key tested in CI with `sign_image.py --verify`
- [ ] Bootloader binary with new public key deployed and confirmed on test fleet
- [ ] Fleet telemetry confirms ≥99% adoption of new bootloader
- [ ] Old key revocation applied (OTP bit or compiled-in flag)
- [ ] Old private key material securely destroyed
- [ ] Key inventory updated in HSM management system
- [ ] Security counter incremented

---

## 6. Key Revocation via Monotonic Counter

### 6.1 Security Version Counter

The security version is a monotonic counter that can only increment. It is stored in:

| Storage | Mechanism | Reversibility |
|---|---|---|
| OTP/eFuse | One-time programmable bits | Irreversible |
| Dedicated flash sector | Counter with anti-tearing write | Reversible (with flash access) |
| Secure element | SE-managed counter | Irreversible |

### 6.2 Revocation Flow

```
Image header: security_counter = 5
Device OTP:   security_version = 5   → ACCEPT (5 ≥ 5)

Image header: security_counter = 4
Device OTP:   security_version = 5   → REJECT (4 < 5, rollback attempt)

Image header: security_counter = 6
Device OTP:   security_version = 5   → ACCEPT (6 ≥ 5)
                                        Update OTP to 6
```

### 6.3 Counter Management Rules

1. **Never decrement.** The counter is monotonic — any attempt to write a lower value is silently ignored.
2. **Increment on key rotation.** Every key rotation bumps the security version by 1.
3. **Increment on critical CVE.** A security-critical fix may bump the counter to prevent rollback to vulnerable versions.
4. **Coordinate with fleet.** Before incrementing, ensure the new firmware is available for all devices.

---

## 7. Production vs. Development Key Separation

### 7.1 Key Environments

| Environment | Key Purpose | Storage | Signing Authority |
|---|---|---|---|
| **Development** | Local builds, unit tests, CI | Plaintext PEM in developer workspace | Any developer |
| **Staging** | Pre-production validation | Encrypted PEM on staging build server | Release engineer |
| **Production** | Release firmware | HSM-protected; two-person authorization | Release manager + security officer |

### 7.2 Enforcement Mechanism

There is one switch, and it is structural rather than advisory:

- `core/keystore.c` compiles the development key under `#ifndef
  EBLDR_PRODUCTION_KEY` and the generated `ebldr_production_key[]` under
  `#else`. The two never coexist in one object.
- `CMakeLists.txt` defines `EBLDR_PRODUCTION_KEY` only when a key was given,
  and refuses a Release build of a real board that gives none (§3.1).
- `.github/workflows/release.yml` passes the `EBLDR_PRODUCTION_KEY_HEX`
  repository secret on every board configure; with the secret unset the value
  is empty and the configure fails closed. After every firmware build it scans
  each `.elf`, `.bin`, `.a` and `.o` under `build/` for the development key's
  32 bytes and fails the job on a hit.

Staging keys are not modelled: a staging build is a production-shaped build
configured with a staging public key.

### 7.3 Development Key Policy

| Rule | Rationale |
|---|---|
| Development private key is **committed** to the repository | Enables any developer to build and test signed images locally |
| Development key does not reach a production artifact **built through the gate** | Any build of a real board that is not `CMAKE_BUILD_TYPE=Debug` -- `Release`, `MinSizeRel`, `RelWithDebInfo`, any spelling, or no build type at all -- refuses to configure without `EBLDR_PRODUCTION_KEY` unless `EBLDR_ALLOW_DEV_KEY=ON` is passed explicitly; the key it accepts is checked to be a point in the prime-order subgroup (`tools/check_production_key.py`); and the release workflow validates the secret before any board is configured and scans every artifact for the development key's bytes (§3.1, §7.2). What the gate cannot see: a Debug build flashed to a device, a build that passes `EBLDR_ALLOW_DEV_KEY=ON`, or a fork that removes the gate. Those are policy, not mechanism. |
| Production key **never** appears in source control | Only the public key is embedded; private key stays in HSM |
| The stored `EBLDR_PRODUCTION_KEY_HEX` is checked against the generated `.pub` **before** it is stored | The configure-time and release-time checks refuse a key that is off the curve, of low order, or outside the prime-order subgroup -- but about **one in sixteen** single-hex-digit typos of a key lands on a *different valid key* inside the subgroup, which no check on the key alone can distinguish from the real one. That rate is derivable, not measured: a mutated encoding decodes to a curve point with probability about 1/2 and lands in the prime-order subgroup with probability 1/8. Measured counts for specific keys vary around it -- 52/960 for the development key, 64/960 for the RFC 8032 TEST 2 key, 75/960 for TEST 3. A device built on it refuses every image, with a green build. The only control for that case is comparing the secret to the `.pub` the key generator wrote, by eye or by `cmp`, before it enters the secret store. |
| CI pipeline uses **staging** key for integration tests | Tests signature verification without exposing production key |

### 7.4 Well-Known Development Key

The development key is the RFC 8032 section 7.1 TEST 1 key pair. Its secret
scalar is printed in the RFC, so images signed with it are not authenticated
by anyone in particular:

```
Public key (compiled in by core/keystore.c without EBLDR_PRODUCTION_KEY):
  d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a
Secret (RFC 8032 §7.1 TEST 1):
  9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60

⚠️  THIS KEY IS PUBLIC. Images signed with this key are NOT authenticated.
```

`tools/gen_fw_update_test_sigs.py` signs the unit-test fixtures with it, and
`tests/unit/test_keystore.c` checks that the compiled-in bytes are exactly
this key (an earlier revision of the array was off the curve, so nothing
could verify against it at all). `cmake/ProductionKey.cmake` refuses it as a
value for `EBLDR_PRODUCTION_KEY`.

---

## 8. Emergency Key Compromise Response

### 8.1 Compromise Classification

| Severity | Scenario | Response Time |
|---|---|---|
| **P0 — Confirmed compromise** | Private key material exposed publicly or to unauthorized party | Immediate (< 4 hours) |
| **P1 — Suspected compromise** | Unauthorized access to signing infrastructure detected | < 24 hours |
| **P2 — Precautionary** | Personnel change, infrastructure migration, policy violation | < 7 days |

### 8.2 P0 Response Procedure

```
┌─ HOUR 0 ──────────────────────────────────────────────┐
│ 1. Notify security team: security@embeddedos.org      │
│ 2. Revoke compromised key in CI/CD pipeline           │
│ 3. Halt all firmware signing with compromised key     │
└───────────────────────────────────────────────────────┘
         │
┌─ HOURS 1-4 ───────────────────────────────────────────┐
│ 4. Generate emergency replacement keypair (§2.2)      │
│ 5. Build emergency bootloader with new public key     │
│ 6. Sign emergency bootloader with backup key (slot 1) │
│ 7. Push emergency OTA to all connected devices        │
└───────────────────────────────────────────────────────┘
         │
┌─ HOURS 4-24 ──────────────────────────────────────────┐
│ 8. Increment security version counter                 │
│ 9. Revoke compromised key slot (OTP/eFuse)            │
│ 10. Monitor fleet for devices still on old key        │
│ 11. Publish security advisory                         │
└───────────────────────────────────────────────────────┘
         │
┌─ DAYS 1-7 ────────────────────────────────────────────┐
│ 12. Root cause analysis                               │
│ 13. Update key management procedures                  │
│ 14. Rotate all related credentials                    │
│ 15. Post-incident review                              │
└───────────────────────────────────────────────────────┘
```

### 8.3 Key Compromise Indicators

- Firmware images signed with the production key that were not produced by the authorized build pipeline
- Unauthorized access logs on the HSM or signing server
- Public disclosure of key material (paste sites, repositories, social media)
- Anomalous device behavior consistent with unauthorized firmware

### 8.4 Limitations

- **Compiled-in keys:** Devices with compiled-in public keys require a bootloader update to rotate keys. If both key slots are compromised and the device cannot receive OTA updates, physical UART recovery is required.
- **OTP/eFuse keys:** Once all OTP key slots are revoked, the device cannot verify any firmware. This is a permanent brick condition — plan key slots carefully.
- **Offline devices:** Devices not connected to the network cannot receive emergency key rotation. They remain vulnerable until physically recovered.

---

## References

- [Secure Boot Chain](secure_boot_chain.md)
- [Threat Model](threat_model.md)
- [Security Model](security.md)
- [Architecture](architecture.md)
- RFC 8032 — Edwards-Curve Digital Signature Algorithm (EdDSA)

# === docs/memory-map.md ===

# eBootloader Memory Map

## Default Layout (STM32F407, 1MB Flash)

```
┌──────────────────────────────────────────────────────────┐
│ 0x08000000  Stage-0 (eBootloader)              16 KB   │
├──────────────────────────────────────────────────────────┤
│ 0x08004000  Stage-1 (E-Boot)                    48 KB   │
├──────────────────────────────────────────────────────────┤
│ 0x08010000  Slot A (Active Firmware)            448 KB   │
├──────────────────────────────────────────────────────────┤
│ 0x08080000  Slot B (Candidate Firmware)         448 KB   │
├──────────────────────────────────────────────────────────┤
│ 0x080F0000  Recovery Image (Golden)              16 KB   │
├──────────────────────────────────────────────────────────┤
│ 0x080F4000  Boot Control (Primary)                8 KB   │
├──────────────────────────────────────────────────────────┤
│ 0x080F6000  Boot Control (Backup)                 8 KB   │
├──────────────────────────────────────────────────────────┤
│ 0x080F8000  Boot Log                              8 KB   │
├──────────────────────────────────────────────────────────┤
│ 0x080FA000  Device Config / Reserved             24 KB   │
└──────────────────────────────────────────────────────────┘
```

## Design Rules

1. **Stage-0 is never updated in the field** — it must remain immutable
   after manufacturing to guarantee recovery is always possible.

2. **Boot control is dual-copied** — primary at 0x080F4000, backup at
   0x080F6000. Both carry CRC32 protection. On load, if primary is
   corrupt the backup is used.

3. **Slot A and Slot B are identical in size** — this simplifies the
   swap/upgrade logic and allows either slot to be active.

4. **Recovery image is optional but recommended** — on flash-constrained
   devices, Slot B can double as recovery storage.

5. **Boot log is a circular buffer** — the `log_head` field in the boot
   control block tracks the write position.

## Adapting to Other MCUs

To port to a different MCU, create a new `boards/<mcu>/` directory and:

1. Define the memory map addresses in a board header
2. Implement `eos_board_ops_t` with appropriate flash/watchdog/UART drivers
3. Create linker scripts for stage-0 and stage-1
4. Provide `board_early_init()` and `board_get_ops()`

Example for nRF52840 (1MB Flash, 256KB RAM):

```
Stage-0:     0x00000000 - 0x00003FFF  (16K)
Stage-1:     0x00004000 - 0x0000FFFF  (48K)
Slot A:      0x00010000 - 0x0007FFFF  (448K)
Slot B:      0x00080000 - 0x000EFFFF  (448K)
Boot Ctrl:   0x000F0000 - 0x000F1FFF  (8K)
Boot Backup: 0x000F2000 - 0x000F3FFF  (8K)
Boot Log:    0x000F4000 - 0x000F5FFF  (8K)
Reserved:    0x000F6000 - 0x000FFFFF  (40K)
```

# === docs/installation_usage.md ===

# eboot Installation & Usage Guide

## Installation

eboot is a C project built with CMake. No package manager needed — just clone, configure, and build.

### Prerequisites

| Tool | Required? | Purpose |
|---|---|---|
| CMake 3.15+ | ✅ Required | Build system generator |
| GCC / Clang / MSVC | ✅ Required | C compiler (any) |
| ARM GCC | For ARM boards | `arm-none-eabi-gcc` |
| RISC-V GCC | For RISC-V boards | `riscv64-unknown-elf-gcc` |
| Python 3.9+ | For host tools | image packing, signing |

### 🐧 Linux

```bash
# Install build tools
sudo apt install cmake gcc g++ make python3

# Clone and build
git clone https://github.com/embeddedos-org/eboot.git
cd eboot
cmake -B build -DEBLDR_BUILD_TESTS=ON
cmake --build build

# Run tests
ctest --test-dir build --output-on-failure

# Install cross-compilers for target boards
sudo apt install gcc-arm-none-eabi   # ARM Cortex-M/R
sudo apt install gcc-aarch64-linux-gnu  # ARM64 Linux
```

### 🪟 Windows

```powershell
# Option A: Visual Studio
# Install "Desktop development with C++" workload from Visual Studio Installer
# Install CMake from https://cmake.org/download/

git clone https://github.com/embeddedos-org/eboot.git
cd eboot
cmake -B build -DEBLDR_BUILD_TESTS=ON
cmake --build build --config Release

# Option B: MinGW / MSYS2
pacman -S cmake gcc make
cmake -B build -G "MinGW Makefiles" -DEBLDR_BUILD_TESTS=ON
cmake --build build
```

### 🍎 macOS

```bash
brew install cmake
xcode-select --install  # Clang compiler

git clone https://github.com/embeddedos-org/eboot.git
cd eboot
cmake -B build -DEBLDR_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build
```

### Via ebuild (recommended)

```bash
# If you have ebuild installed, it builds eboot automatically
cd eboot
ebuild build
```

---

## Usage — How to Use eboot in Your Project

### Step 1: Choose your board

```bash
# See available boards
ls boards/
# stm32f4  stm32h7  nrf52  samd51  rpi4  imx8m  am64x
# riscv64_virt  sifive_u  esp32  x86_64_efi

# Build for STM32F4 (requires arm-none-eabi-gcc)
cmake -B build -DEBLDR_BOARD=stm32f4 \
  -DCMAKE_TOOLCHAIN_FILE=toolchains/arm-none-eabi.cmake
cmake --build build
```

### Step 2: Configure boot policy

Create a `boot.yaml` (or use ebuild's EoS AI to generate one):

```yaml
boot:
  board: stm32f4
  arch: arm
  flash_base: "0x08000000"
  flash_size: 1048576    # 1MB
  layout:
    stage0:
      offset: "0x0"
      size: 16384          # 16KB
    stage1:
      offset: "0x4000"
      size: 65536          # 64KB
    bootctl_primary:
      offset: "0x14000"
      size: 4096
    bootctl_backup:
      offset: "0x15000"
      size: 4096
    slot_a:
      offset: "0x16000"
      size: 479232
    slot_b:
      offset: "0x8B000"
      size: 479232
  policy:
    max_boot_attempts: 3
    watchdog_timeout_ms: 5000
    require_signature: true
```

### Step 3: Generate C headers from config

```bash
# Generate flash layout header + linker script
python scripts/generate_config.py boot.yaml generated/

# Output:
#   generated/eboot_generated_layout.h   — #define constants
#   generated/eboot_generated_memory.ld  — MEMORY regions
```

### Step 4: Build your firmware application

```c
// Your app (runs after eboot hands off)
#include <stdint.h>

void main(void) {
    // eboot already initialized hardware, verified image, jumped here
    // Your application starts running
    while (1) {
        // application logic
    }
}
```

### Step 5: Pack and sign firmware image

```bash
# Install Python tool dependencies
python3 -m pip install -r requirements.txt

# Pack firmware with eboot image header. The input limits (size, load and
# entry addresses) are listed in quickstart.md and in tools/imgpack.py.
python tools/imgpack.py --input firmware.bin --output firmware.packed.bin \
    --version 1.0.0 --load-addr 0x08010000 --entry-addr 0x08010100

# Sign the image
python tools/sign_image.py firmware.packed.bin --key signing_key.pem

# Set the recovery shared secret used by the UART tool
export EBOOT_RECOVERY_SECRET_HEX=<64-hex-char-secret>

# Upload the image to slot B over UART recovery
python tools/uart_recovery.py --port /dev/ttyUSB0 upload --slot B --image firmware.packed.bin
```

### Step 6: Confirm boot (in your app)

```c
#include "eos_bootctl.h"

void app_init(void) {
    eos_bootctl_t bctl;
    eos_bootctl_load(&bctl);

    // Tell eboot this boot succeeded — don't rollback
    eos_bootctl_confirm(&bctl);
}
```

---

## Boot Flow

```
Power On
  │
  ▼
Stage-0 (≤16KB, immutable)
  ├── Minimal HW init (clocks, watchdog)
  ├── Check recovery pin
  └── Jump to Stage-1
        │
        ▼
Stage-1 (≤64KB)
  ├── Load boot control block
  ├── Select boot slot (A or B)
  ├── Verify image (SHA-256 + signature)
  ├── Check boot attempt counter
  ├── If max attempts exceeded → rollback to other slot
  └── Jump to application
        │
        ▼
Application (your firmware / RTOS / Linux)
  └── Call eos_bootctl_confirm() to mark boot successful
```

---

## API Quick Reference

| Header | Purpose | Key Functions |
|---|---|---|
| `eos_bootctl.h` | Boot control block | `load`, `save`, `confirm`, `set_pending`, `request_recovery` |
| `eos_image.h` | Image verification | `verify_header`, `verify_hash`, `verify_signature` |
| `eos_fwsvc.h` | Firmware services | `get_version`, `get_slot`, `mark_valid` |
| `eos_fw_update.h` | OTA update | `begin`, `write`, `finalize`, `progress` |
| `eos_rtos_boot.h` | RTOS boot | `detect`, `boot`, MPU config |
| `eos_multicore.h` | Multicore | `start_smp`, `start_amp`, `boot_all` |
| `eos_board_config.h` | HW config | Pin/memory/clock/IRQ macros |
| `eos_boot_menu.h` | Boot menu | UART-based interactive menu |
| `eos_device_table.h` | Device table | UEFI-style resource table |
| `eos_runtime_svc.h` | Runtime services | Get/set variables, reset, time |

# === docs/quickstart.md ===

# eboot Quickstart

Build and flash the eboot bootloader for your board in 3 commands.

---

## What is eboot?

eboot is a multi-stage bootloader that provides:
- **Staged boot:** Stage-0 (minimal init) → Stage-1 (full bootloader)
- **Secure boot:** RSA/ECC signature verification
- **A/B slot management:** Dual firmware slots for safe OTA updates
- **Recovery:** Rollback to known-good firmware on failure

## Prerequisites

```bash
# ARM toolchain (for ARM targets)
sudo apt install gcc-arm-none-eabi cmake
```

---

## Build in 3 Commands

```bash
cd EoS/eboot

# Configure for your board
cmake -B build -DEBLDR_BOARD=nrf52

# Build
cmake --build build

# Flash (nRF52 example)
nrfjprog --program build/eboot.hex --chiperase --verify
nrfjprog --reset
```

## Supported Boards

| Board | Architecture | Flash Tool |
|-------|-------------|-----------|
| `nrf52` | ARM Cortex-M4F | nrfjprog / J-Link |
| `stm32h7` | ARM Cortex-M7 | OpenOCD / ST-Link |
| `stm32f4` | ARM Cortex-M4F | OpenOCD / ST-Link |
| `rpi4` | ARM64 Cortex-A72 | SD card |
| `x86` | x86_64 | BIOS/UEFI |
| `sparc` | SPARC LEON3 | GRMON |

---

## Flash Layout

eboot organizes flash into regions. For a 512 KB flash (e.g., nRF52):

```
Address     Size    Region
---------   -----   ------------------
0x00000     16 KB   Stage-0 (first-stage loader)
0x04000     64 KB   Stage-1 (full bootloader)
0x14000     8 KB    Boot Control (2 x 4 KB blocks)
0x16000     212 KB  Slot A (primary firmware)
0x4B000     212 KB  Slot B (OTA update slot)
```

For larger flash devices, slot sizes scale proportionally.

## Generating Flash Layout Headers

```bash
cd EoS/ebuild
ebuild generate-boot ../eboot/configs/nrf52_boot.yaml --output-dir _generated
```

This produces:
- `eboot_flash_layout.h` — C header with flash region addresses and sizes
- `eboot_linker.ld` — Linker script for placing firmware in Slot A

## Signing Firmware Images

```bash
cd EoS/eboot/tools

# Generate an Ed25519 keypair (first time only).
# Writes keys/private.pem, keys/public.pem and keys/public_key.hex -- the
# 64-hex-character value the bootloader build takes as its trust anchor.
python3 sign_image.py --genkey --output keys/

# Build the bootloader with THAT key as its trust anchor. Without
# EBLDR_PRODUCTION_KEY a board build keeps the RFC 8032 test key, whose
# private half is public -- and a release-shaped build refuses to configure
# rather than let that happen silently. Full lifecycle: docs/key_lifecycle.md.
cmake -B build -DEBLDR_BOARD=<board> -DCMAKE_BUILD_TYPE=Release \
      -DEBLDR_PRODUCTION_KEY=$(cat keys/public_key.hex)

# Pack a raw firmware binary into an .eimg container. imgpack refuses what
# the bootloader refuses (core/image_verify.c): an input that is empty or
# over 16 MiB (16777216 bytes), checked before it is read; addresses or
# flags that do not fit 32 bits; and, when --load-addr is non-zero, a load
# address + size past 0xFFFFFFFF or an --entry-addr outside
# [load-addr, load-addr + size). --load-addr 0 means "unset" and skips the
# entry check, as the bootloader does.
python3 imgpack.py --input firmware.bin --output firmware.eimg \
    --load-addr 0x08010000 --entry-addr 0x08010100 --version 1.0.0

# Sign it. This also sets the SHA-256 flag and marks the header as v2.
python3 sign_image.py --image firmware.eimg --method ed25519 \
    --key keys/private.pem

# Verify before flashing: recomputes the payload hash and checks the
# signature over the header prefix.
python3 sign_image.py --image firmware.eimg --verify --key keys/public.pem
```

The signature covers the first 92 bytes of the header — every field the
bootloader acts on, including `load_addr`, `entry_addr`, `image_size` and
`flags` — not just the payload hash. Editing any of them invalidates it.
Images signed under the v1 format (signature over `hash[]` alone) must be
re-signed.

## Boot Flow

```
Power On
   |
   v
Stage-0 (16 KB)
   |-- Minimal hardware init (clock, memory)
   |-- Verify Stage-1 integrity
   |-- Jump to Stage-1
   v
Stage-1 (64 KB)
   |-- Full hardware init
   |-- Read boot control block
   |-- Verify firmware signature (RSA/ECC)
   |-- Select active slot (A or B)
   |-- Jump to application
   v
Application (Slot A or B)
   |-- eos_hal_init()
   |-- Your firmware runs here
```

## Next Steps

- [Integration Guide](../../docs/integration-guide.md) — how eboot works with eos and ebuild
- [Security Documentation](security.md) — key management, chain of trust
- [Memory Map](memory-map.md) — detailed flash and RAM layout
- [Update Flow](update-flow.md) — OTA update sequence diagram

# === docs/eflash.md ===

# eFlash — eBootloader Unified Flash Tool

**eFlash** wraps board-vendor flashing tools behind a single CLI. Instead of remembering vendor-specific commands for each board, use `eflash` and it auto-dispatches to the correct tool.

## Quick Start

```bash
# List all supported boards
python tools/eflash.py list

# Flash an STM32F4 board
python tools/eflash.py flash --board stm32f4 --image build/eboot_firmware.bin --verify --reset

# Flash nRF52
python tools/eflash.py flash --board nrf52 --image build/eboot_firmware.bin

# Flash ESP32 (UART-based)
python tools/eflash.py flash --board esp32 --image build/eboot_firmware.bin --port /dev/ttyUSB0

# Flash Raspberry Pi 4 (SD card)
python tools/eflash.py flash --board rpi4 --image build/eboot_firmware.bin --mount /media/user/boot

# Dry-run (show command without executing)
python tools/eflash.py flash --board stm32f4 --image build/eboot_firmware.bin --dry-run
```

## CMake Integration

When building with CMake, use the `flash` target:

```bash
cmake -B build -DEBLDR_BOARD=stm32f4 -DCMAKE_TOOLCHAIN_FILE=toolchains/arm-none-eabi.cmake
cmake --build build
cmake --build build --target flash          # Flash firmware
cmake --build build --target flash_stage0   # Flash stage-0 only
cmake --build build --target flash_info     # Show flash tool info
```

## Commands

### `list` — List Boards

```bash
python tools/eflash.py list
```

Shows all 25 supported boards with their architecture, flash tool, and interface type.

### `info` — Board Details

```bash
python tools/eflash.py info --board <name>
```

Shows the flash tool, commands, setup instructions, and installation hints for a specific board.

### `check` — Verify Tool Installation

```bash
python tools/eflash.py check --board <name>
```

Checks if the required vendor flash tool is installed and reports its version.

### `flash` — Flash Image

```bash
python tools/eflash.py flash --board <name> --image <path> [options]
```

| Flag | Description |
|------|-------------|
| `--board`, `-b` | Target board (auto-detects from `build/CMakeCache.txt` if omitted) |
| `--image`, `-i` | Firmware image file (`.bin` or `.eimg`) |
| `--address`, `-a` | Override flash address (hex) |
| `--port`, `-p` | Serial port (for UART boards like ESP32) |
| `--device`, `-d` | Target device path (for disk boards like x86) |
| `--mount`, `-m` | SD card mount point (for RPi4) |
| `--verify` | Verify image after flashing |
| `--reset` | Reset device after flashing |
| `--dry-run` | Print the flash command without executing |

### `erase` — Erase Flash

```bash
python tools/eflash.py erase --board <name> [--yes]
```

Erases the flash on the target board. Requires confirmation unless `--yes` is passed.

### `doctor` — System Audit

```bash
python tools/eflash.py doctor
```

Scans all 25 boards and reports which vendor tools are installed and which are missing, with install hints.

## Supported Boards

| Board | Architecture | Flash Tool | Interface |
|-------|-------------|-----------|-----------|
| stm32f4 | ARM Cortex-M4F | OpenOCD | ST-Link |
| stm32h7 | ARM Cortex-M7 | OpenOCD | ST-Link |
| stm32mp1 | ARM Cortex-A7 | STM32CubeProgrammer | ST-Link |
| nrf52 | ARM Cortex-M4F | nrfjprog | J-Link |
| samd51 | ARM Cortex-M4F | OpenOCD | CMSIS-DAP |
| cortex_r5 | ARM Cortex-R5 | OpenOCD | J-Link |
| rpi4 | ARM64 Cortex-A72 | SD card copy | SD card |
| imx8m | ARM64 Cortex-A53 | UUU (mfgtools) | USB |
| am64x | ARM64 Cortex-A53 | TI UniFlash | JTAG |
| qemu_arm64 | ARM64 | QEMU | Virtual |
| sifive_u | RISC-V 64 | OpenOCD | J-Link |
| riscv64_virt | RISC-V 64 | QEMU | Virtual |
| esp32 | Xtensa LX6 | esptool.py | UART |
| x86 | x86 | dd | Disk |
| x86_64_efi | x86_64 | dd | EFI |
| sparc | SPARC LEON3 | GRMON | JTAG |
| m68k | M68K | OpenOCD | BDM |
| mips | MIPS | OpenOCD | JTAG |
| powerpc | PowerPC | OpenOCD | JTAG |
| sh4 | SH-4 | OpenOCD | JTAG |
| v850 | V850 | OpenOCD | JTAG |
| frv | FR-V | GDB | JTAG |
| h8300 | H8/300 | GDB | JTAG |
| mn103 | MN103 | GDB | JTAG |
| strongarm | StrongARM | OpenOCD | JTAG |
| xscale | XScale | OpenOCD | JTAG |

## Adding a New Board

1. Add a board entry to `configs/flash_tools.yaml`:

```yaml
my_board:
  arch: arm-cortex-m33
  tool: pyocd
  tool_check: "pyocd --version"
  interface: cmsis-dap
  flash_address: "0x00000000"
  flash_command: >-
    pyocd flash -t my_mcu {image}
  erase_command: >-
    pyocd erase -t my_mcu --chip
  reset_command: >-
    pyocd reset -t my_mcu
  install_hint: "pip install pyocd"
  notes: "Connect CMSIS-DAP debug probe."
```

2. Test with `python tools/eflash.py info --board my_board`
3. Flash with `python tools/eflash.py flash --board my_board --image firmware.bin --dry-run`

## Custom Handlers

Boards that don't use a simple CLI flash command (like RPi4's SD card copy or QEMU's emulator launch) use custom Python handlers defined in `eflash.py`. Add the `custom_handler` key in `flash_tools.yaml` to route to a handler function.

## Troubleshooting

| Problem | Solution |
|---------|----------|
| "tool is not installed" | Run `eflash.py check --board <name>` for install instructions |
| "image file not found" | Build first: `cmake --build build` |
| Flash fails on STM32 | Ensure ST-Link is connected and drivers installed |
| ESP32 won't enter bootloader | Hold BOOT button while pressing RESET, then flash |
| RPi4 won't boot | Check `config.txt` has `kernel=eboot_firmware.bin` |
| QEMU exits immediately | Ensure image is a valid ELF or raw binary for the target arch |

## Requirements

- Python 3.10+
- `pyyaml` (`pip install pyyaml`)
- Board-specific vendor tool (run `eflash.py doctor` to check)

# === docs/mcuboot_comparison.md ===

# mcuboot Comparison — eBootloader

> **Last updated:** 2026-04-03
>
> **Purpose:** Document the design decisions in eBootloader relative to mcuboot — what was adopted, what was intentionally not adopted, and why.

---

## 1. Overview

[mcuboot](https://www.mcuboot.com/) is the de facto open-source secure bootloader for microcontrollers, originally developed for Apache Mynewt and Zephyr. eBootloader draws inspiration from mcuboot's proven security patterns while making architectural decisions tailored to multi-architecture support, operational recovery, and staged boot.

---

## 2. Patterns Adopted from mcuboot

### 2.1 TLV Metadata

**mcuboot pattern:** Image metadata (hash, signature, key ID, dependencies) is stored as Type-Length-Value (TLV) entries appended after the image payload.

**eBootloader adoption:** The image header (`eos_image_header_t`) uses a fixed-layout header with reserved fields for future TLV extension. The `sign_image.py` tool supports TLV generation for key hash and dependency information.

| TLV Type | mcuboot | eBootloader |
|---|---|---|
| SHA-256 hash | `IMAGE_TLV_SHA256` (0x10) | `hash[32]` field in fixed header |
| Key hash | `IMAGE_TLV_KEYHASH` (0x01) | Planned — TLV extension after header |
| Ed25519 signature | `IMAGE_TLV_ED25519` (0x24) | `signature[64]` field in fixed header |
| Security counter | `IMAGE_TLV_SEC_CNT` (0x50) | `image_version` field + dedicated counter |

**Rationale:** A fixed-layout header with known offsets simplifies stage-0 parsing (minimal code) and enables constant-time field access. TLV is used for optional/extensible metadata only.

### 2.2 Hash-Then-Verify-Signature

**mcuboot pattern:** First compute the hash of the image payload, then verify the signature over the hash. This separates integrity from authenticity.

**eBootloader adoption:** Identical approach:

```
Step 1: eos_image_verify_integrity()
  → Compute SHA-256 over payload
  → Compare against header hash field
  → FAIL → reject image (integrity violation)

Step 2: eos_image_verify_signature()
  → Verify Ed25519 signature over header hash
  → FAIL → reject image (authenticity violation)
```

**Rationale:** This is a well-established pattern that enables:
- Early rejection of corrupted images without expensive signature verification
- Separate integrity and authenticity error reporting
- Compatibility with CRC-only mode (Phase 1) where signature verification is absent

### 2.3 Key Hash in TLV

**mcuboot pattern:** Instead of embedding the full public key in the image, mcuboot stores a SHA-256 hash of the public key in the TLV. The bootloader holds the actual public key and compares hashes to select which key to use for verification.

**eBootloader adoption:** Planned for Phase 2. The image will carry a key hash identifying which key slot was used for signing. The bootloader compares this hash against its embedded public key hashes to select the correct verification key.

**Benefit:** Enables efficient multi-key support — the bootloader can determine which of its key slots to use without attempting verification with each key.

### 2.4 Security Counter

**mcuboot pattern:** A monotonic security counter is stored in the image TLV (`IMAGE_TLV_SEC_CNT`). The bootloader compares it against a device-side counter and rejects images with a lower counter.

**eBootloader adoption:** Monotonic counter stored in OTP/eFuse or dedicated flash sector. See [Key Lifecycle — §6](key_lifecycle.md#6-key-revocation-via-monotonic-counter).

---

## 3. Patterns Intentionally Not Adopted

### 3.1 Swap-Based Upgrade

**mcuboot approach:** By default, mcuboot uses a swap-based upgrade strategy. When a new image is placed in the secondary slot, mcuboot swaps the primary and secondary slot contents sector-by-sector. This allows automatic revert if the new image fails to boot.

**eBootloader decision: Not adopted.**

**Reasons:**

| Factor | Swap-Based (mcuboot) | Direct-Write A/B (eBootloader) |
|---|---|---|
| Flash wear | 3× write amplification (read A, read B, write A, write B, write scratch) | 1× write (write to inactive slot) |
| Boot time | Slow first boot after upgrade (swap takes seconds) | Instant — no data movement at boot |
| Scratch area | Requires dedicated scratch partition | Not needed |
| Code complexity | Complex swap state machine with resume-on-interrupt | Simple: select slot, verify, jump |
| Anti-tearing | Swap status tracked in dedicated area | Only boot control block needs anti-tearing |
| Flash size | Requires scratch area (~1 sector minimum) | No overhead |
| Recovery | Automatic revert via swap-back | Rollback by switching `active_slot` pointer |

**eBootloader approach:** Direct-write with A/B slot selection. The inactive slot is written by the application. On reboot, stage-1 verifies the candidate image and either boots it (test mode) or falls back to the confirmed slot. No data is moved between slots at boot time.

### 3.2 Overwrite-Only Upgrade

**mcuboot approach:** An alternative mode where the secondary slot image is copied to the primary slot, destroying the previous primary image.

**eBootloader decision: Not adopted.**

**Reason:** Overwrite-only eliminates rollback capability. eBootloader always maintains two slot copies for resilience.

### 3.3 Direct-XIP (Execute in Place)

**mcuboot approach:** Both slots contain fully position-independent images. mcuboot selects the slot to execute from without copying.

**eBootloader decision: Partially adopted.** eBootloader's A/B slots use fixed load addresses, but images are linked for their specific slot address. The boot manager selects which slot to jump to — similar to direct-XIP but with fixed addressing rather than position-independent code.

---

## 4. Architectural Differences

### 4.1 HAL Abstraction

| Aspect | mcuboot | eBootloader |
|---|---|---|
| Flash interface | `flash_area` API (`flash_area_open`, `flash_area_read`, etc.) | `eos_board_ops_t` vtable with function pointers |
| Registration | Compile-time via `flash_map` configuration | Runtime via `eos_hal_init(&board_ops)` |
| Multi-board | Board selection via Kconfig/CMake | Board selection via `board_get_ops()` at runtime |
| Watchdog | Not managed by mcuboot | `eos_board_ops_t.watchdog_init/feed` |
| UART | Not part of mcuboot HAL | `eos_board_ops_t.uart_init/send/recv` for recovery |
| Reset control | Not part of mcuboot HAL | `eos_board_ops_t.system_reset`, `get_reset_reason` |
| Jump/handoff | Direct function call to app entry | `eos_board_ops_t.jump` with MSP setup via `eos_hal_set_msp()` |

**Rationale:** The vtable approach allows a single eBootloader binary to support multiple boards via runtime board detection (useful for SoC families with board variants). It also integrates recovery, watchdog, and UART into the same HAL — mcuboot delegates these to the underlying RTOS.

### 4.2 Multi-Architecture Support

| Architecture | mcuboot | eBootloader |
|---|---|---|
| ARM Cortex-M (M0, M3, M4, M7, M33) | ✅ Primary target | ✅ Supported |
| ARM Cortex-A (A53, A72) | ❌ | ✅ Supported |
| ARM Cortex-R (R5F) | ❌ | ✅ Supported |
| RISC-V (RV32, RV64) | ✅ (limited) | ✅ Supported |
| x86 / x86_64 | ❌ | ✅ Supported |
| Xtensa | ❌ | ✅ Supported |
| PowerPC | ❌ | ✅ Platform enum defined |
| SPARC, M68K, SH4, MIPS, etc. | ❌ | ✅ Platform enum defined |

eBootloader's `eos_platform_t` enum in `eos_hal.h` defines 24 platform targets. The `eos_hal_set_msp()` inline function already includes architecture-specific assembly for ARM Cortex-M, Cortex-A/R, AArch64, and RISC-V.

### 4.3 Boot Stages

| Aspect | mcuboot | eBootloader |
|---|---|---|
| Stage count | 2 (ROM → mcuboot → app) | 3 (ROM → stage-0 → stage-1 → app) |
| First-stage size | ~32–64 KB typical | 16 KB (stage-0) + 48 KB (stage-1) |
| Stage-0 purpose | N/A | Minimal init, recovery check, stage-1 verification |
| Recovery | External tooling | Built-in UART recovery with 9-command protocol |

**Rationale:** The two-stage split (stage-0 + stage-1) keeps the root-of-trust code surface minimal (16 KB). Stage-0 can be locked in flash and rarely updated, while stage-1 can be updated more frequently with new boot policies. mcuboot is a single monolithic bootloader.

### 4.4 Recovery Mechanism

| Aspect | mcuboot | eBootloader |
|---|---|---|
| Built-in recovery | ❌ No | ✅ UART command protocol (9 commands) |
| Recovery trigger | N/A | Hardware pin (`recovery_pin_asserted`) or boot control flag |
| Remote recovery | Depends on app/RTOS | UART: PING, INFO, ERASE, WRITE, VERIFY, BOOT, LOG, RESET, FACTORY |
| Brick recovery | External programmer (JTAG/SWD) | UART recovery before JTAG is needed |

---

## 5. Security Features Comparison

| Security Feature | mcuboot | eBootloader | Notes |
|---|---|---|---|
| **Image integrity** | SHA-256 in TLV | SHA-256 in header (Phase 2), CRC32 (Phase 1) | Same algorithm, different metadata format |
| **Signature algorithms** | RSA-2048/3072, ECDSA-P256, Ed25519 | Ed25519 (primary), ECDSA (planned) | eBootloader focuses on Ed25519 for size/speed |
| **Key storage** | Compiled-in public key hash | Compiled-in, OTP/eFuse, or secure element | eBootloader supports more storage options |
| **Multi-key support** | Up to N keys via key hash TLV | Dual-slot (primary + backup) | Sufficient for rotation; simpler implementation |
| **Anti-rollback** | Security counter in TLV | Monotonic counter (OTP/flash/SE) | Same concept, different storage |
| **Payload encryption** | AES-256-CTR, AES-256-CBC, ECIES-P256+AES | AES-256-GCM (Phase 3) | eBootloader uses authenticated encryption |
| **Swap protection** | Swap status tracking | Not applicable (no swap) | eBootloader avoids swap complexity |
| **Debug lock** | Not managed | Stage-0 applies debug lock in production | Integrated into boot chain |
| **Recovery auth** | Not applicable | Challenge-response (Phase 3) | eBootloader authenticates recovery sessions |
| **Boot logging** | Minimal | Dedicated boot log region (8 KB) | Full audit trail of boot decisions |
| **Hardware dependencies** | Requires RTOS flash driver | Bare-metal HAL vtable | eBootloader has no RTOS dependency |

---

## 6. When to Choose Which

| Scenario | Recommended | Reason |
|---|---|---|
| Zephyr/Mynewt project on Cortex-M | mcuboot | Native integration, community support |
| Multi-arch project (ARM + RISC-V + x86) | eBootloader | Broader platform support |
| Bare-metal with no RTOS | eBootloader | No RTOS dependency; self-contained HAL |
| Need built-in UART recovery | eBootloader | 9-command recovery protocol included |
| Need swap-based upgrade with scratch | mcuboot | Mature swap implementation |
| Need minimal flash overhead | eBootloader | No scratch partition; A/B direct-write |
| Need boot audit logging | eBootloader | Dedicated boot log region |
| Existing mcuboot deployment | mcuboot | Migration cost outweighs benefits |

---

## References

- [mcuboot Documentation](https://docs.mcuboot.com/)
- [Secure Boot Chain](secure_boot_chain.md)
- [Architecture](architecture.md)
- [Security Model](security.md)
- [Key Lifecycle](key_lifecycle.md)

---

## Upstream CVE watch (2026-10-07)

eBoot audits itself against upstream bootloader components (Mbed TLS,
U-Boot, TF-A, GRUB2), but "we checked the latest" goes stale the day after
release. Standing subscription for the audit-comparison loop:

- **Subscribe**: the monthly dev.to "Open-Source Device CVEs: What to Patch
  by Vertical" series as the bootloader-class upstream baseline. Monthly
  cadence, per-vertical tables; it is the human-readable layer over the
  raw CVE feeds for exactly the component set eBoot tracks.

- **September-2026 datapoint**: U-Boot 2026.07 did not clear the month —
  network-boot fixes landed in **2026.10-rc3..rc5**. Any eBoot audit
  comparison that baselines against 2026.07 is stale on the network-boot
  surface; the comparison must re-baseline against **2026.10 on release**.

- **Tie to ZDS day-1 work**: mine the MCUboot measured-boot patterns from
  the Zephyr Developer Summit day-1 CRA-readiness and secure-boot sessions
  against the UART-recovery-auth findings in the current audit cycle —
  measured boot is the mechanism that turns "we verified the image" into
  "we can prove what booted."