IGL‑RV‑emb: Secure Runtime for MCU Modules ARM Cortex‑M / RISC‑V

IGL‑RV‑emb: Secure Runtime for MCU Modules (ARM Cortex‑M / RISC‑V)

It consists of:

• Host‑packer (PC): Validates WASM‑subset, lowers it into compact bytecode BC2, builds policies, and assembles the IGL‑PKG container (optionally signs and adds HW‑lock).

• no_std runtime (MCU): Verifies IGL‑PKG and executes BC2 in a VM, strictly enforcing policies.

Key principle: No uncontrolled side effects — external interactions are available only through permitted hostcalls.

Quick Overview

IGL‑RV‑emb is a bundle of tools and runtime for safe execution of "embedded modules" on microcontrollers:

Host‑packer (PC) no_std runtime (MCU) Security Pipeline Policy Enforcement Gas/Fuel Metering HW‑lock Support

Key principle: No uncontrolled side effects. All external interactions available only through hostcalls and explicitly granted permissions.

️ Effect Control (Hostcalls + Policy)

Hostcalls

VM has no direct peripheral access. Interactions go through hostcalls:

MMIO read/write (if permitted)
IRQ enable/disable and other platform operations (if permitted)
Timers/delays/diagnostics (if permitted)

MMIO Sandbox

MMIO access is defined by allowlist ranges and permissions (deny-by-default). Runtime/host implementation validates address and access type, blocking out-of-bounds operations.

Execution Limiting (Gas/Fuel)

Container includes GasV1 section defining maximum VM steps:

max_steps = 0 ⇒ immediate trap on step limit
Infinite loops are bounded by steps
Runner executes VM with: vm.run(module.gas.max_steps as usize)

Gas is the primary mechanism for execution time predictability and hang protection.

Module Trust: Integrity, Signature, Strict Mode

Integrity (CRC)

CRC32 allows quick rejection of corrupted packages (flash/transport) — first line of defense against "bad" data.

Signature (P‑256 ECDSA)

Signature verified on MCU (no_std). In strict mode, missing or invalid signatures cause launch rejection. Signature protects policy/flags to prevent permission/limit modifications without breaking signature.

Strict Mode (via Package Flags)

Mandatory rules are defined by package data, not "firmware logic":

Enables dev packages vs production packages
Ensures uniform policy application across platforms/runners

HW‑lock (Device Binding)

Supports module binding to specific device at container level:

Package stores HW‑lock descriptor (mode, chip_family_id, salt, expected)
Verification occurs before VM execution via security pipeline
For STM32F103: uses UID (96‑bit) as "raw little‑endian bytes" + salt + SHA‑256
Provisioning mode in runner allows reading UID for generating HW‑locked packages

Frequently Asked Questions

1 How is IGL‑RV‑emb different from "WASM on microcontrollers"?

IGL‑RV‑emb does not execute "raw" WASM on MCU. WASM-subset is validated and lowered on host to compact BC2 bytecode, which then runs on MCU in no_std VM. This simplifies runtime, reduces attack surface, and improves predictability.

2 How secure is this?

Security model includes: CRC integrity, P‑256 signature, strict flags, gas/fuel limits, MMIO deny-by-default, hostcall allowlists, and (optional) HW‑lock. In strict mode, module won't launch if requirements aren't met.

3 What exactly does the signature protect?

Signature protects package contents including policy parameters and strict mode flags. This prevents permission/limit substitution and "weakening" of security mode without breaking signature.

4 Can modules be updated without reflashing entire firmware?

Yes. Recommended model: store PKG separately (e.g., in dedicated flash area) and load/verify it at startup or on update event.

5 What happens on verification error or limit violation?

Package won't launch, or VM traps on violation (step limit, forbidden hostcall, memory bounds, etc.). In production: fail‑stop with minimal diagnostic indication recommended.

6 How is execution time controlled?

Via GasV1 (fuel): module receives VM step limit, preventing infinite loops and defining predictable computation quota.

7 How is peripheral access limited?

Through hostcall allowlists and MMIO sandbox deny‑by‑default (allowed ranges and operation types).

8 How does HW‑lock work and why is it needed?

HW‑lock binds package to specific device (e.g., by STM32F103 UID). Reduces risk of module copying/transfer and helps implement license management/deployment per device.

9 What's the RAM/Flash footprint?

Depends on VM configuration, hostcall set, and enabled security options. Exact numbers fixed during pilot on target board (RAM: VM memory + stack/locals; Flash: runtime + HAL + crypto).

10 Is this suitable for RTOS (e.g., Zephyr)?

Yes. Typical path: run VM in separate thread/task, use gas as CPU quota, implement hostcalls atop RTOS drivers (timers, queues, GPIO/UART). Simplifies modular lifecycle (load/start/stop/update).

📋 Request Integration Pilot

MCU / Architecture *

RTOS / Platform *

Security Level *

Contact for Follow-up *

RAM/Flash Constraints

Required Peripherals / Hostcalls

Integration Pilot: What We Deliver

A runner integration template (verify → load → run) for your platform (bare‑metal/Zephyr/FreeRTOS)
Hostcalls/HAL mapping for the peripherals you need (deny‑by‑default, allowlist-based)
A strict security profile tuned to your constraints (gas limits, memory limits, required sections)
A demo module pipeline (WASM‑subset → BC2 → PKG) and reference tests
Footprint report (Flash/RAM) and performance notes on your target

Recommended Firmware Scheme (Runner)

(Optional) Provisioning mode for UID/diagnostics
verify_and_load_module_v1(pkg, mem_len, ctx) — unified loading contract
Create HostApi/HAL with allowlist policies
Run VM with gas: vm.run(module.gas.max_steps as usize)

On verification error: fail‑stop with diagnostic output (UART/LED) — the module must not execute.

What We Need From You

Target board/MCU + memory constraints (Flash/RAM)
RTOS choice and driver stack (Zephyr drivers, vendor HAL, etc.)
Which effects must be allowed (hostcalls) and which must be forbidden (must-not list)
How modules will be delivered/updated (flash partition / OTA / file system)

Notes

Detailed binary formats and opcode tables are provided during the pilot under NDA (if needed).
RISC‑V support is planned; current demo focus is STM32F103 (Blue Pill).

Demo Kit v0.1 (Hardware Trial)

Try IGL‑RV‑emb on real hardware without exposing production keys and without integrating it into your firmware from scratch. The demo kit is designed to show the full secure module pipeline: signed package → strict verification → sandboxed execution.

What’s included

Demo runner firmware (STM32F103 “Blue Pill” reference)
Host tools: igl-pkg-build-demo CLI for building signed, HW‑locked packages
Example module: blink/uart logic compiled into a WASM‑subset and lowered into BC2

How the demo runner behaves

Provisioning mode via PA0 (active‑low): prints device UID to UART2
Loads IGL‑PKG from a fixed flash partition
Runs the unified security pipeline:
- PKG structure + CRC
- Signature verification (demo key)
- HW‑lock verification (UID‑based)
- VM execution (BC2) with policy enforcement
On any verification failure: diagnostic UART output + fail‑stop (module does not execute)

Flash layout (reference demo)

Runner firmware: main flash region
IGL‑PKG partition: fixed address (example: 0x0800C000), updated independently

This lets you update the module without rebuilding the firmware: you only rewrite the PKG partition.

Quick start (Blue Pill reference)

Flash the demo runner firmware onto the board.
Provisioning UID: connect PA0 to GND, reset the board, read UID from UART2 (24 hex chars = 12 bytes LE).
Save UID as: keys/devices/<device>/device_uid.hex
Build a signed, HW‑locked package:
igl-pkg-build-demo --profile strict --uid-file keys/devices/<device>/device_uid.hex --out out/<device>.pkg --meta device=<device>
Write the package into the flash partition (ST‑Link example):
st-flash write out/<device>.pkg 0x0800C000
Reset the board (without PA0 pulled low). The module will be verified and executed.

Important note about the demo key

The demo runner accepts packages signed with a demo key only.
This is a separate demo ecosystem: even if a package leaks, it is not a production artifact and will not run on a production runner.
HW‑lock is used to bind demo modules to a specific device UID.

Request a Demo Kit for Your Hardware

Want the same demo experience on your MCU/board? Submit a request — we can prepare a runner + host tools profile tailored to your target.

Demo Kit Request

MCU / Architecture *

Board / Part number *

Preferred PKG storage *

Device identity source (for HW‑lock)

Required peripherals / hostcalls

Contact *

🤝 Collaborate on IGL‑RV‑emb

IGL‑RV‑emb is a secure embedded module runtime (BC2 VM + signed PKG + policy enforcement). We’re looking for collaborators to help with real hardware integrations, security hardening, and RTOS adoption.

1MCU / HAL Integration

Help implement and validate HostApi/HAL backends on real targets:

STM32Cortex‑MRISC‑V (later)

Implement safe hostcalls (GPIO/UART/timers/IRQ) with deny-by-default behavior
Review MMIO sandbox assumptions and suggest edge cases
Provide “minimal hardware demos” (blink/uart/protocol handlers) as modules

2Security / Verification

Help harden the PKG verification pipeline and security profiles:

SignatureHW‑lockThreat Modeling

Threat model review (tampering, policy bypass, hostcall abuse, downgrade paths)
Strict-mode defaults (required sections/flags, safe limits)
Fuzzing targets: container parser, section table, decoder/VM

3RTOS Integration

Help turn IGL‑RV‑emb into a drop‑in component for RTOS-based firmware:

ZephyrFreeRTOSMCUboot/OTA

Runner integration: load PKG from flash partition, update/rollback hooks
Hostcall mapping to RTOS services (timers, queues, drivers)
Scheduling model: gas-per-timeslice, cooperative execution, safety boundaries

4Packer / WASM‑subset

Help improve lowering correctness and policy derivation from imports:

WASM subsetLoweringPolicy derive

Derive hostcall allowlist from WASM imports automatically
Golden tests: wasm → bc2 → VM trace
Improve error messages (actionable failures for integrators)

What You’ll Get

Credit in CONTRIBUTORS / release notes
Direct influence over strict-mode defaults, hostcall policies, and RTOS runner design
Real-world demos (signed modules, HW‑locked packages, sandboxed peripheral access)

What We Need From You

Your target constraints: MCU/arch, Flash/RAM, MMU/MPU availability, RTOS (if any)
A minimal repro (WASM or module behavior description) + expected outcome
Your “must-not” list: effects that must never be allowed (MMIO ranges, IRQ rules, timing)

Contribution Templates

Issue / Bug Report Template

Title:
[PKG/Signature/HW-lock/VM/Packer/HAL] <short summary>

Input:
- WASM file (or a minimal WAT)
- Target profile: (dev/strict/custom)
- Expected hostcalls/MMIO ranges (if relevant)

Expected:
What should happen?

Actual:
What happens now? Include exact error text / trap.

Logs:
- verify result (PkgError / SigError / VerifyPipelineError)
- optional: VM trace / hostcall log

Environment:
MCU/arch: (Cortex‑M3 / Cortex‑M4 / RV32IM / etc.)
RTOS: (bare metal / Zephyr / FreeRTOS)
Board: (Blue Pill / Nucleo / custom)
Commit/hash/version:

“Hardware Integration” Contribution Template

Target board: (e.g., STM32F103 Blue Pill)
Peripheral: (GPIO/UART/SPI/I2C/Timer/IRQ)
Desired hostcall API: (function name + params/returns)
Sandbox rules: (MMIO ranges / deny-by-default expectations)
Constraints: (no heap, ISR restrictions, timing)
Test plan: (how to verify on hardware)
Notes: (datasheet/register refs optional)

Collaboration Policy

We prioritize improvements backed by tests and reproducible artifacts
Security claims should include a minimal repro or a clear rule proposal
We keep the public demo safe: no production keys, strict defaults, and HW‑lock for downloadable packages

Architecture (Components)

Host Side

1) Packer / Lowering (WASM‑subset → BC2 → PKG)

The packer takes a WASM subset, validates it against a whitelist, lowers it into compact stack bytecode BC2, and builds the IGL‑PKG container together with a policy.

Limits: locals / stack / linear memory
Effects control: hostcalls allowlist
Sandbox: MMIO allowlist ranges (deny‑by‑default)
Execution budget: GasV1 (max VM steps)
Optional binding: HW‑lock parameters (device identity)

2) Integrity & Authenticity

CRC32 for fast corruption detection (flash/transport)
P‑256 ECDSA signature for authenticity

Important: the signature protects not only the code, but also critical policy/flags, preventing “policy weakening” without breaking verification.

MCU Side (no_std)

1) Container Verify + Load

The runtime verifies:

Package header, section table, and bounds/overlap rules
CRC integrity
Policy/MMIO/Gas/HW‑lock sections (if present)
Runtime hard limits (stack/locals/memory constraints of this build)
Strict mode via package flags (required sections and checks)

2) Security Pipeline (Unified Contract)

Firmware should use a single entry point to avoid wrong verification order:

verify_and_load_module_v1(pkg, mem_len, ctx)

Pipeline behavior:

Verify structure + CRC + policy + strict requirements
Verify signature (only if required by flags)
Verify HW‑lock (only if required by flags)
Return ModuleRef for VM execution

3) VM Runtime

no_std VM with static buffers (no heap by design)
Traps on invalid opcodes, bounds violations, and denied operations
Step metering enforced by GasV1
External effects only via HostApi/HAL and allowlisted hostcalls

Recommended failure policy: on verification error, do not execute the module (fail‑stop), optionally with UART/LED diagnostics.