laantungir/n_signer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 40 Wiki Activity

v0.1.0 - CYD firmware v0.0.2: algorithm-based API upgrade (all verbs, all algorithms), vendored Keccak/SHAKE + PSA ed25519/x25519 for IDF v5.4, Web Serial test page, CYD docs, Teensy 4.1 port plan (1TB SDXC OTP pad), brainstorming READMEs for BLE/IR/NFC/FPGA signer concepts

Browse Source
This commit is contained in:
Laan Tungir
2026-07-21 13:16:04 -04:00
parent ca18e1e42d
commit 64fbd5c874
23 changed files with 4271 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
firmware/README.md
View File

@@ -53,6 +53,26 @@ WebUSB path:
- Run `get_public_key`
- Confirm pubkey matches CDC result
## CYD (ESP32-2432S028) validation — Web Serial
The CYD has no native USB; its CH340 bridge exposes a serial port. The browser
transport is **Web Serial** (`navigator.serial`), Chromium-only. A full test
page covering every algorithm and verb lives at
[`examples/cyd_webserial_demo.html`](../examples/cyd_webserial_demo.html):
- Open [`examples/cyd_webserial_demo.html`](../examples/cyd_webserial_demo.html) in Chrome/Edge
- Click **Connect Web Serial**, select the CH340 port (`1a86:7523`)
- Exercise each card: `get_public_key` (all 6 algorithms), `sign`/`verify`,
`encapsulate`/`decapsulate`, `derive_shared_secret`, `derive`,
`nostr_get_public_key`, `nostr_sign_event`, `nostr_mine_event`,
`nostr_nip04`/`nostr_nip44` encrypt+decrypt, and `encrypt`/`decrypt` (otp)
- Each request shows the raw JSON-RPC request and response
The CYD firmware (v0.0.2+) speaks the same algorithm-based API as the host
([`README.md`](../README.md) §4). The OTP pad is derived from the mnemonic
seed (no USB pad on this board); the offset advances monotonically and is
reported in every `encrypt`/`decrypt` response.
## Linux WebUSB host setup (one-time)
Chrome and Edge need permission to open the device on Linux. Install a udev rule for the firmware VID:PID and reload rules:
@@ -123,33 +143,34 @@ firmware uses a **crypto backend abstraction** ([`resources/pqclean/common/crypt
with two implementations:
- [`resources/pqclean/common/crypto_backend_openssl.c`](../resources/pqclean/common/crypto_backend_openssl.c) — host build (OpenSSL EVP)
- [`resources/pqclean/common/crypto_backend_mbedtls.c`](../resources/pqclean/common/crypto_backend_mbedtls.c) — ESP32 firmware (mbedtls)
- [`resources/pqclean/common/crypto_backend_mbedtls.c`](../resources/pqclean/common/crypto_backend_mbedtls.c) — ESP32 firmware (mbedtls + vendored Keccak)
The mbedtls backend uses:
- `mbedtls_sha256_ret()` for SHA-256 (ESP32-S3 hardware accelerated)
- `mbedtls_sha512_ret()` for SHA-512 (ESP32-S3 hardware accelerated)
- `mbedtls_md` API for SHA3-256, SHA3-512, SHAKE-128, SHAKE-256
- `mbedtls_sha256()` for SHA-256 (ESP32 hardware accelerated where available)
- `mbedtls_sha512()` for SHA-512 (ESP32 hardware accelerated where available)
- A **self-contained Keccak-f[1600]** implementation (FIPS 202, public domain)
for SHA3-256, SHA3-512, SHAKE-128, and SHAKE-256. This is vendored directly
in `crypto_backend_mbedtls.c` because ESP-IDF v5.x mbedtls does not expose
SHAKE (and SHA3 is only available when `CONFIG_MBEDTLS_SHA3_C` is set) through
the `mbedtls_md` API. Carrying the Keccak core avoids any mbedtls config
dependency for the PQ algorithms.
### Enabling SHA3/SHAKE in menuconfig
### ed25519 / x25519 via PSA crypto
mbedtls does not enable SHA3/SHAKE by default. You must enable them in
menuconfig before building:
ESP-IDF v5.x mbedtls removed the low-level `mbedtls_ed25519_*` functions. The
firmware uses the **PSA Crypto API** for ed25519 sign/verify/key-derivation and
x25519 key derivation + ECDH. Enable PSA in `sdkconfig.defaults`:
```
Component config → mbedTLS → Hash functions → SHA-3
Component config → mbedTLS → Hash functions → SHAKE
CONFIG_MBEDTLS_PSA_CRYPTO_C=y
CONFIG_MBEDTLS_ECP_DP_CURVE25519_ENABLED=y
```
Or add to `sdkconfig.defaults`:
```
CONFIG_MBEDTLS_SHA3_C=y
CONFIG_MBEDTLS_SHAKE_C=y
```
### No SHA3/SHAKE menuconfig requirement
If mbedtls does not have SHAKE support, the firmware build will fail at link
time with unresolved `mbedtls_md_info_from_type(MBEDTLS_MD_SHAKE128)`. In that
case, either enable the config options above or patch mbedtls with a
Keccak/SHAKE contribution.
Because SHA3/SHAKE are provided by the vendored Keccak core (not mbedtls), you
do **not** need to enable `CONFIG_MBEDTLS_SHA3_C` or any SHAKE config. The PQ
algorithms build and run with the default mbedtls configuration.
### PQClean component