Skip to content

Commit 4f9d182

Browse files
committed
docs: update README to clarify Runtime VM features and remove unused references
1 parent ef7da31 commit 4f9d182

1 file changed

Lines changed: 14 additions & 22 deletions

File tree

README.md

Lines changed: 14 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ Serializer::build_units() -- convert segmentation results to CompilationUn
106106
+-> Serializer::dump/load() -- round-trip to TOML manifest + binary format
107107
```
108108
109-
### Runtime VM (doc 16/17/19 forward-secrecy)
109+
### Runtime VM
110110
111111
```
112112
VM Bytecode Blob
@@ -116,13 +116,13 @@ VmEngine::create() -- blob validation, key derivation, state init
116116
|
117117
v
118118
dispatch_unit() pipeline -- fixed-width N sub-instructions per dispatch unit
119-
| Phase A-C: fetch, decrypt (SipHash), decode (two-layer PRP)
120-
| Phase D: ORAM scan (branchless) + handler dispatch (55 opcodes)
121-
| Phase E: branchless FPE encode (Speck64/128 XEX mode)
122-
| Phase F-G: BLAKE3 fingerprint + key ratchet (entangled)
123-
| Phase H-I: 16-register re-encode, stack hygiene
124-
| Phase K: enc_state advance (8-byte full-instruction ratchet)
125-
| Phase L: branchless BB MAC verification + transition MUX
119+
| fetch, decrypt (SipHash), decode (two-layer PRP)
120+
| ORAM scan (branchless) + handler dispatch (55 opcodes)
121+
| branchless FPE encode (Speck64/128 XEX mode)
122+
| BLAKE3 fingerprint + key ratchet (entangled)
123+
| 16-register re-encode, stack hygiene
124+
| enc_state advance (8-byte full-instruction ratchet)
125+
| branchless BB MAC verification + transition MUX
126126
v
127127
VmExecResult -- decoded return value
128128
```
@@ -158,13 +158,13 @@ Protected Binary
158158
159159
## Security Model
160160
161-
The runtime VM implements the **doc 16 forward-secrecy extension** with **doc 17 rolling-state ratchet** and **doc 19 timing normalization**:
161+
The runtime VM implements **forward secrecy** with a **rolling-state ratchet** and **timing normalization**:
162162
163163
- **Per-instruction FPE encoding** -- registers are encrypted with Speck64/128 in XEX mode; the key ratchets every instruction via `BLAKE3_KEYED(key, opcode || register_fingerprint)`
164-
- **8-byte full-instruction ratchet** (doc 17) -- all 8 bytes of the decrypted instruction drive the enc_state SipHash chain; any decryption error cascades into all subsequent instructions
164+
- **8-byte full-instruction ratchet** -- all 8 bytes of the decrypted instruction drive the enc_state SipHash chain; any decryption error cascades into all subsequent instructions
165165
- **BB chain evolution** -- one-way BLAKE3 chain state updated on every basic block transition; compromising the current state reveals nothing about past states (preimage resistance >= 2^256)
166166
- **Eager re-encoding** -- all 16 registers re-encoded on every BB transition; dead registers sanitized to `Enc(K_new, 0)` to prevent path-merge fingerprint desync
167-
- **Branchless execution** (doc 19) -- Phase E (FPE encode), Phase L (BB transition), and ORAM scans use bitwise MUX to prevent timing side channels
167+
- **Branchless execution** -- FPE encode, BB transition, and ORAM scans use bitwise MUX to prevent timing side channels
168168
- **Stack hygiene** -- all intermediate key material (Speck round keys, XEX tweaks, plaintext temporaries) zeroed via `secure_zero()` after use
169169
- **ORAM strategies** -- `RollingKeyOram` (full IND-CPA security) and `DirectOram` (fast testing) via compile-time policy selection
170170
@@ -390,14 +390,6 @@ third_party/ Git submodules
390390
elfio-modern/ ELF parsing
391391
```
392392

393-
## Tools
394-
395-
| Tool | Usage | Purpose |
396-
|------|-------|---------|
397-
| `dump_regions` | `dump_regions <binary>` | Show segmentation groups and sites |
398-
| `dump_compile` | `dump_compile <binary> [key]` | Full pipeline dump: segmentation, grouping, units, bytecodes |
399-
| `verify_roundtrip` | `verify_roundtrip <binary>` | Verify serializer dump/load round-trip (exit 0 = pass) |
400-
401393
## CI
402394

403395
| Compiler | Status |
@@ -416,7 +408,7 @@ third_party/ Git submodules
416408
- [x] **Backend** -- work-stealing thread pool, pluggable `CompilerBackend` interface, SimpleBackend stub
417409
- [x] **Unified Diagnostics** -- `DiagnosticCollector` with thread-safe collection, `DiagnosticCode` enum, summary report
418410
- [x] **Linker** -- ELF/PE/Mach-O editors with CRTP dispatch, stub emitters (x86-64, ARM64, x86-32), PayloadBuilder, FallbackChain dependency strategies
419-
- [x] **Runtime VM** -- doc 16/17/19 forward-secrecy engine: Speck-FPE register encoding, BLAKE3 key ratchet, 55 opcodes, branchless dispatch unit, ORAM strategies, platform ASM trampolines (SysV x64, Win64, AAPCS64, cdecl/stdcall)
411+
- [x] **Runtime VM** -- forward-secrecy engine: Speck-FPE register encoding, BLAKE3 key ratchet, 55 opcodes, branchless dispatch unit, ORAM strategies, platform ASM trampolines (SysV x64, Win64, AAPCS64, cdecl/stdcall)
420412
- [x] **CI/CD** -- MSVC, GCC, Clang, Apple Clang on GitHub Actions
421413
- [x] **Modern CMake** -- presets, modular cmake/ includes, per-target sanitizers, CPM 0.42.1
422414

@@ -472,12 +464,12 @@ flowchart TB
472464
EDIT --> STUB --> PAY
473465
end
474466
475-
subgraph Runtime["Runtime VM (doc 16/17/19)"]
467+
subgraph Runtime["Runtime VM"]
476468
ENG["VmEngine&lt;Policy, Oram&gt;<br/><i>dispatch_unit pipeline</i>"]
477469
FPE["Speck-FPE Encoding<br/><i>per-instruction key ratchet<br/>XEX tweakable mode</i>"]
478470
HAND["55 Opcode Handlers<br/><i>data, arith, logic, compare,<br/>control, width, atomic</i>"]
479471
BRIDGE["Native Bridge<br/><i>platform ASM trampolines<br/>SysV/Win64/AAPCS64</i>"]
480-
CHAIN["Forward Secrecy<br/><i>BLAKE3 chain evolution<br/>branchless Phase L</i>"]
472+
CHAIN["Forward Secrecy<br/><i>BLAKE3 chain evolution<br/>branchless BB transition</i>"]
481473
ENG --> FPE --> HAND --> BRIDGE
482474
ENG --> CHAIN
483475
end

0 commit comments

Comments
 (0)