feat(key_mgr): Add Key Manager HAL for ESP32-C5 and ESP32-P4 (IDFGH-17725) - #113
Draft
hrushikesh430 wants to merge 6 commits into
Draft
feat(key_mgr): Add Key Manager HAL for ESP32-C5 and ESP32-P4 (IDFGH-17725)#113hrushikesh430 wants to merge 6 commits into
hrushikesh430 wants to merge 6 commits into
Conversation
Add a Key Manager (KM) hardware abstraction layer that the esp-flasher-stub keymanager plugin uses to deploy and recover keys through the KM and HUK Generator peripherals. What's included: - target/key_mgr.h: the plugin<->HAL contract. Declares HUK generator control, KM bring-up, state-machine stepping, key-memory I/O, and result checks (HUK/key valid, eFuse KM_INIT_KEY presence). API names mirror ESP-IDF's esp_key_mgr.c so the code can be reviewed side by side; the IDF locks, logging and RTOS plumbing are dropped (the stub is single-threaded). - ESP32-C5 driver + SoC register headers: clock/reset bring-up, key-memory MMIO helpers, 5-bit eFuse key-purpose decoding, HUK status/configure, and external ECC bring-up for ECDH0/ECDH1. - ESP32-P4 driver + SoC register headers: the same HAL mapped onto P4's HP_SYS_CLKRST clock/reset layout and 4-bit eFuse key-purpose fields. HUK_INFO is 660 bytes to match IDF's HUK_INFO_LEN. There is no chip-side crypto: the host (espsecure) does all AES/ECDH preprocessing and the stub only drives the peripheral.
Collaborator
|
Hello @hrushikesh430, I know this is not ready and even now it is quite good, just a heads up for you, please try to follow the contribution guide. |
github-actions
Bot
changed the title
There was a problem hiding this comment.
Pull request overview
Adds a Key Manager (KM) + HUK Generator target HAL for ESP32-C5 and ESP32-P4 within esp-stub-lib, providing the chip-side peripheral driving needed by an external flasher-stub “keymanager” plugin.
Changes:
- Introduces a new internal target HAL contract header (
target/key_mgr.h) for KM/HUK operations. - Adds ESP32-C5 and ESP32-P4 KM/HUK implementations plus minimal SoC register definitions for each.
- Wires the new sources into the ESP32-C5 and ESP32-P4 target builds via CMake.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| src/target/base/include/target/key_mgr.h | New internal plugin↔HAL interface for KM/HUK operations and constants/enums. |
| src/target/esp32c5/src/key_mgr.c | ESP32-C5 KM/HUK driver (bring-up, state machine ops, MMIO helpers, efuse purpose scan). |
| src/target/esp32c5/include/soc/keymng_reg.h | ESP32-C5 Key Manager register definitions (plus PCR/ECC-related bring-up regs). |
| src/target/esp32c5/include/soc/huk_reg.h | ESP32-C5 HUK Generator register definitions (including LP_AON/PUF SRAM controls). |
| src/target/esp32c5/CMakeLists.txt | Adds src/key_mgr.c to the ESP32-C5 target library. |
| src/target/esp32p4/src/key_mgr.c | ESP32-P4 KM/HUK driver using HP_SYS_CLKRST clock/reset sequencing and efuse purpose scan. |
| src/target/esp32p4/include/soc/keymng_reg.h | ESP32-P4 Key Manager register definitions (hw_ver3). |
| src/target/esp32p4/include/soc/huk_reg.h | ESP32-P4 HUK Generator register definitions (hw_ver3). |
| src/target/esp32p4/include/soc/hp_sys_clkrst_reg.h | Minimal HP_SYS_CLKRST register subset needed for KM/ECC/ECDSA clock/reset. |
| src/target/esp32p4/CMakeLists.txt | Adds src/key_mgr.c to the ESP32-P4 target library. |
Author
Yes, sure. Thanks. |
- New common/src/key_mgr.c with weak defaults for every stub_target_* declared in target/key_mgr.h. - SOC_KEY_MANAGER_SUPPORTED in c5+p4 soc_caps.h. - BIT(n) instead of 1U<<n; EFUSE register access via SOC header macros (new efuse_reg.h for C5; P4 uses its existing definitions). - stub_target_huk_configure returns STUB_LIB_OK / STUB_LIB_FAIL / STUB_LIB_ERR_INVALID_ARG (caller's err != 0 check stays compatible). - STUB_LOGE before every error return; NULL-buffer check at the top of every public MMIO I/O helper.
- Restrict ESP32-P4 Key Manager to v3.0+ (ROM ECO >= 5, 660-byte HUK); add stub_target_km_is_supported() reading the wafer major version from eFuse and reject earlier P4 silicon that used the 384-byte HUK. - Clamp Key Manager mem I/O lengths to the peripheral window size in the read/write wrappers (defensive bounds). - Use BIT(STUB_KM_KEY_TYPE_FLASH_XTS_AES) instead of a magic bit index. - Reconcile HUK 660/384 docstrings and clarify the 384-byte path is the MMIO window; tidy internal HAL wording and mem I/O preconditions.
hrushikesh430
added a commit
to hrushikesh430/esp-flasher-stub
that referenced
this pull request
Jun 10, 2026
…rt check The keymanager plugin calls stub_target_km_is_supported(), which lands in esp-stub-lib PR #113; the previously committed submodule pointer predates it and the plugin no longer compiled. Pin the submodule to the PR #113 head (espressif/esp-stub-lib#113) — to be re-bumped to the merged commit once that PR lands.
AdityaHPatwardhan
left a comment
AdityaHPatwardhan
left a comment
There was a problem hiding this comment.
Two questions from reviewing the C5/P4 Key Manager HAL.
|
|
||
| void stub_target_km_wait_for_state(stub_km_state_t state) | ||
| { | ||
| while (stub_target_km_get_state() != state) { |
There was a problem hiding this comment.
Should this wait have a timeout? With no watchdog in the stub, if KM never reaches the expected state the host just sees a hang with no error (same applies to the P4 wait_for_state).
| * configure_huk asserts KEYMNG_HUK_VLD instead, but on this C5 v1.2 | ||
| * board the KM doesn't latch HUK from a standalone huk_configure — | ||
| * it only sets KEYMNG_HUK_VLD as a side-effect of a subsequent | ||
| * key-deploy. Cross-boot RECOVER on a cold chip currently fails |
There was a problem hiding this comment.
Can we surface this known cross-boot RECOVER failure (gen=2/risk=7 on a cold C5) in the PR description before un-drafting? It's easy to miss buried in the comment here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a Key Manager (KM) hardware abstraction layer (HAL) for ESP32-C5 and ESP32-P4. This HAL is what the
esp-flasher-stubkeymanager plugin calls to deploy and recover keys through the chip's Key Manager and HUK Generator peripherals.Why
esptool is gaining Key Manager support (host side + a flasher-stub plugin). The plugin needs a thin, chip-specific driver to actually drive the KM peripheral. This PR provides that driver for C5 and P4. There is no crypto on the chip — the host (
espsecure) does all AES/ECDH preprocessing, and the stub only drives the peripheral state machine.What's in this PR
target/key_mgr.h— the plugin↔HAL contract. Declares HUK generator control, KM bring-up, state-machine stepping, key-memory I/O, and result checks (HUK/key valid, eFuseKM_INIT_KEYpresence). API names mirror ESP-IDF'sesp_key_mgr.cso it can be reviewed side by side; IDF's locks/logging/RTOS plumbing are dropped (the stub is single-threaded).esp32c5/src/key_mgr.c+ SoC register headers) — clock/reset bring-up, key-memory MMIO helpers, 5-bit eFuse key-purpose decoding, HUK status/configure, external ECC bring-up for ECDH0/ECDH1.esp32p4/src/key_mgr.c+ SoC register headers) — the same HAL mapped onto P4'sHP_SYS_CLKRSTclock/reset layout and 4-bit eFuse key-purpose fields.HUK_INFOis 660 bytes to match IDF'sHUK_INFO_LEN.Testing
KM_TESTING_REPORT.md
Notes
esp-flasher-stubadds the keymanager plugin and bumps its submodule to this commit.