From bd344f20d63f07d642a764c8ec07ff27e698113d Mon Sep 17 00:00:00 2001 From: srpatcha Date: Tue, 1 Sep 2026 13:41:37 -0700 Subject: [PATCH 1/3] docs: eSec is Implemented in eos, and one part is not MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README said "Status: Planned. There is no implementation yet." The crypto services are Implemented under §28 — 15 source files and seven test suites passing in eos, at services/crypto/. But flatly upgrading the status would overstate it. Package signature verification is Experimental at best: services/pkg/eos_pkg.c verifies against eos_pkg_public_key[32] = {0}, and the low-order-key rejection that makes an all-zero anchor fail closed rather than open only just landed (eos#99). A verifier with no real key authenticates nothing, and a README claiming a working security framework should say so. Tracked as eos#98. Also replaces the old rationale with v2.0 §10 and §21.1, adds the component manifest as the way to depend on this, and records why splitting early is costly — two Ed25519 implementations across eos and eBoot carried the same bypass. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fd064fe..5531d38 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,36 @@ Security framework for the EmbeddedOS platform — reusable security services above the boot chain. -**Status: Planned.** There is no implementation in this repository yet. The -code that will become eSec lives in [`eos`](https://github.com/embeddedos-org/eos) -today, at `services/security/ and services/crypto/`. +**Status: Implemented, with one part Experimental — in +[`eos`](https://github.com/embeddedos-org/eos), at `services/crypto/`.** Not here. -This repository exists so the component has a home, an issue tracker, and a +Under §28, *Implemented* means "feature exists and is usable", evidenced by code +and functional tests. The crypto services meet that: 15 source files and seven +test suites — `test_crypto`, `_aes`, `_ecc`, `_rsa`, `_sha512`, +`_ed25519_loworder`, `_failclosed` — all passing. + +One part is **Experimental** rather than Implemented, and should not be read as +finished: package signature verification. `services/pkg/eos_pkg.c` verifies +against `eos_pkg_public_key[32] = {0}`, an all-zero trust anchor, and the +low-order-key rejection that makes such a key fail closed rather than open was +only just added (embeddedos-org/eos#99). Tracked as embeddedos-org/eos#98. A +verifier with no real key authenticates nothing, and this README should not +imply otherwise. + +Depend on eSec through a **component manifest**, not through this repository — +see embeddedos-org/embeddedos-stack#20. The v2.0 master design is direct: + +> §10: **Repositories should not be the dependency API.** + +> §21.1: A subsystem earns a separate repository when it has a stable interface, +> independent release lifecycle, clear maintainers and multiple consumers. + +None of those four holds for eSec today, and the cost of splitting anyway is +already visible: there are two independent Ed25519 implementations in the +platform, in eos and eBoot, and the same low-order-key bypass was present in +both. Duplication across repositories is how one fix stops being one fix. + +This repository exists so the component has an issue tracker and a place to record decisions before any code moves. It is deliberately not a mirror: duplicating the sources here would give the platform two copies to keep in step, and §24 of the architecture document is explicit that internal From 5f27056475f1180598a54891548d4b185126ac69 Mon Sep 17 00:00:00 2001 From: Srikanth Patchava Date: Mon, 5 Oct 2026 23:48:17 -0700 Subject: [PATCH 2/3] docs: name the Experimental part in the status line, and update its facts The status line said eSec is Implemented at services/crypto/ with "one part Experimental" without naming it, so a reader could take one of the seven crypto suites for the unfinished part. Name package signature verification (services/pkg/eos_pkg.c) in the status line itself. Also correct the paragraph behind it: it described eos_pkg verifying against an all-zero key. embeddedos-org/eos#120 removed that key; eos_pkg now verifies only against a platform-supplied trust anchor (eos_pkg_set_trust_anchor() or EOS_PKG_TRUST_ANCHOR_HEX) and refuses otherwise unless EOS_ALLOW_UNSIGNED_PKG is set. It stays Experimental: eos ships no key and the v2 signature envelope landed on 2026-10-04. Still tracked as embeddedos-org/eos#98. --- README.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e295f3d..e567f05 100644 --- a/README.md +++ b/README.md @@ -2,21 +2,26 @@ Security framework for the EmbeddedOS platform — reusable security services above the boot chain. -**Status: Implemented, with one part Experimental — in -[`eos`](https://github.com/embeddedos-org/eos), at `services/crypto/`.** Not here. +**Status: Implemented in [`eos`](https://github.com/embeddedos-org/eos), at +`services/crypto/`, except package signature verification +(`services/pkg/eos_pkg.c`), which is Experimental.** Not here. Under §28, *Implemented* means "feature exists and is usable", evidenced by code and functional tests. The crypto services meet that: 15 source files and seven test suites — `test_crypto`, `_aes`, `_ecc`, `_rsa`, `_sha512`, `_ed25519_loworder`, `_failclosed` — all passing. -One part is **Experimental** rather than Implemented, and should not be read as -finished: package signature verification. `services/pkg/eos_pkg.c` verifies -against `eos_pkg_public_key[32] = {0}`, an all-zero trust anchor, and the -low-order-key rejection that makes such a key fail closed rather than open was -only just added (embeddedos-org/eos#99). Tracked as embeddedos-org/eos#98. A -verifier with no real key authenticates nothing, and this README should not -imply otherwise. +The Experimental part is **package signature verification** in +`services/pkg/eos_pkg.c`. It is not one of the crypto suites above, and it should +not be read as finished. It no longer verifies against an all-zero key +(embeddedos-org/eos#120 removed it, and embeddedos-org/eos#99 made such a key +fail closed). It now verifies only against a trust anchor the platform supplies, +through `eos_pkg_set_trust_anchor()` or the build-time `EOS_PKG_TRUST_ANCHOR_HEX`. +With neither, it refuses to verify. Only test and bring-up builds that set +`EOS_ALLOW_UNSIGNED_PKG` skip verification. eos ships no key of its own, and the +v2 signature envelope (covering header, binary and resources) landed only on +2026-10-04, so this stays Experimental until a platform supplies a real anchor and +the envelope has been exercised end to end. Tracked as embeddedos-org/eos#98. Depend on eSec through a **component manifest**, not through this repository — see embeddedos-org/embeddedos-stack#20. The v2.0 master design is direct: From 64b98e17e3e3b007f50b9194f89920bf49c0b12a Mon Sep 17 00:00:00 2001 From: Srikanth Patchava Date: Tue, 6 Oct 2026 16:17:28 -0700 Subject: [PATCH 3/3] docs: recount eos services/crypto/src (16 files at eos dc13c59) Signed-off-by: Srikanth Patchava --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e567f05..a86c50a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Security framework for the EmbeddedOS platform — reusable security services ab (`services/pkg/eos_pkg.c`), which is Experimental.** Not here. Under §28, *Implemented* means "feature exists and is usable", evidenced by code -and functional tests. The crypto services meet that: 15 source files and seven +and functional tests. The crypto services meet that: 16 source files (10 `.c`, 6 internal headers) and seven test suites — `test_crypto`, `_aes`, `_ecc`, `_rsa`, `_sha512`, `_ed25519_loworder`, `_failclosed` — all passing.