Skip to content

Add RTL8735B HUK wrapped-key examples for ECC, AES and mutual TLS and fix stale docs - #655

Merged
night1rider merged 1 commit into
wolfSSL:masterfrom
dgarske:rtl8735b_wrap_doc
Nov 17, 2026
Merged

night1rider merged 1 commit into
wolfSSL:masterfrom
dgarske:rtl8735b_wrap_doc

Conversation

@dgarske

@dgarske dgarske commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

Description

Adds wrap, store and reload examples for HUK-wrapped keys to the rtl8735b example: an ECC signing key in both wrap formats the wolfSSL RealTek port accepts, an AES key loaded into a hardware key-storage slot, and a mutual TLS client whose private key exists only as a HUK-wrapped blob. It also corrects two places where the example disagreed with the port.

What it adds

  • huk_key_blob - the format, seed, wrapped scalar and public key an application stores, plus the IV and tag for GCM

  • huk_blob_create() - generates a P-256 key and wraps its scalar under the HUK with a fresh seed, using AES-GCM (recommended) or AES-ECB (the STM32 DHUK blob layout, for wrap code shared between the two parts)

  • huk_blob_load() - sets up a signing key from a stored blob through ecc_key->devCtx; an ECB blob leaves the IV and tag fields NULL/0

  • huk_ecdsa_reload_test() - for each format, signs from the blob and verifies with the stored public key; a damaged GCM blob fails with AES_GCM_AUTH_E, and a damaged ECB blob signs but its signature does not verify

  • huk_slot_key_test() - wraps an AES key under the HUK (RFC 3394 or ECB), loads it into a key-storage slot with wc_KeyStore_ImportWrapped(), and runs AES-GCM and AES-ECB from the slot through wc_AesInit_Id(); the output matches software AES with the same key, a damaged RFC 3394 blob fails with BAD_KEYWRAP_IV_E, and delete and re-import of a slot work

  • tls/ huk_mtls_test() - mutual TLS 1.2 where the client's P-256 key is stored only as a HUK-wrapped blob, in either wrap format: the client loads its certificate and public key, an ECC sign callback signs CertificateVerify from the blob through wc_Rtl8735b_EccKey, and a tampered blob fails the handshake (a GCM blob at the client's unwrap, an ECB blob when the server rejects the signature); the existing server-auth handshake now shares the same session helper

Signing with an ECB blob and the slot-key test both need wolfSSL PR #12056; against an older wolfSSL the slot-key test is not built.

Corrections

The README and the comment above huk_ecdsa_test() described the scalar wrap as ECB. The code and the port's wc_Rtl8735b_EccKey use AES-GCM with an IV and tag, and both now say so.

plain_gcm_badiv_test() required a non-12-byte IV to fail on the plaintext-key AES device. The port deliberately declines that request so software GCM serves it with the same literal key, so the encrypt succeeds and the test printed [FAIL]. It is now plain_gcm_long_iv_test(), which requires the encrypt to succeed and its output to match software GCM with the same key. The HUK device still hard-fails a non-12-byte IV because its key bytes are a derivation seed, and huk_gcm_badiv_test() is unchanged.

Testing

Built with the RealTek FreeRTOS SDK against wolfSSL PR #12056 and run on an RTL8735B EVB with all checks passing, both ECC blob formats and both AES slot-key formats included, AES-128 and AES-256. The TLS example was run on the same board with the server-auth handshake and the mutual-auth handshakes for both client-key formats passing. Against current wolfSSL master the GCM checks pass and the ECB sign is rejected, as expected. A blob wrapped by one flashed image also loaded and signed correctly in a later image after a power-on reset, using a temporary test build of the example. Moving a blob to a second device was not tested, because only one board was available.

@dgarske dgarske self-assigned this Nov 5, 2026
Copilot AI balanced review requested due to automatic review settings November 5, 2026 19:31

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The damaged-blob guarantee overstates integrity protection because qx and qy are neither authenticated nor read during loading; the documentation and test description need to distinguish authenticated scalar-wrap protection from public-key integrity.

1 open issue
What changed in this PR

Adds a HUK-wrapped P-256 key reload example to the RTL8735B demo and aligns existing tests and documentation with the RealTek port’s behavior.

Changes:

  • Adds a stored-key blob format and helpers to wrap, reload, and sign, with signature verification and tag-tampering checks.
  • Replaces plaintext AES-GCM long-IV rejection expectations with a software-fallback comparison.
  • Corrects scalar-wrapping descriptions from ECB to AES-GCM and updates sample output.
File Description
rtl8735b/​README.md Documents wrapped-key storage, corrects the wrapping mode, and updates expected output.
rtl8735b/​main.c Adds blob creation and reload tests, corrects the long-IV test, and updates comments.

Review effort: Balanced

Comment thread rtl8735b/README.md Resolved
@dgarske dgarske changed the title Add RTL8735B HUK wrapped-key reload example and fix stale test and docs Add RTL8735B HUK wrapped-key reload example for GCM and ECB blobs and fix stale test and docs Nov 6, 2026

@wolfSSL-Fenrir-bot wolfSSL-Fenrir-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fenrir Automated Review — PR #655

Scan targets checked: wolfssl-examples-src, wolfssl-examples-bugs
Not reviewed (no scan target covers them): rtl8735b/README.md
Coverage: 1 of 1 in-scope changed file(s) opened by the reviewer

Fenrir result: Approved ✅

No new issues found in the changed files.

Advisory only — this automated result does not count as a GitHub approval.

Review tier: Max

@dgarske
dgarske force-pushed the rtl8735b_wrap_doc branch 2 times, most recently from ec394b0 to 87a857b Compare November 9, 2026 22:58
@dgarske dgarske changed the title Add RTL8735B HUK wrapped-key reload example for GCM and ECB blobs and fix stale test and docs Add RTL8735B HUK wrapped-key examples for ECC and AES keys and fix stale test and docs Nov 9, 2026
@dgarske
dgarske requested a review from night1rider November 11, 2026 21:10
@dgarske dgarske assigned wolfSSL-Bot and night1rider and unassigned dgarske Nov 11, 2026
@dgarske
dgarske requested a balanced review from Copilot November 13, 2026 16:22

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block approval of the HUK wrapped-key storage and reload changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@night1rider night1rider left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some items found:

Comment thread rtl8735b/main.c Resolved
Comment thread rtl8735b/main.c Resolved
Comment thread rtl8735b/main.c Resolved
Comment thread rtl8735b/main.c Resolved
@dgarske dgarske self-assigned this Nov 13, 2026
@dgarske
dgarske requested a review from night1rider November 13, 2026 23:40
@dgarske dgarske changed the title Add RTL8735B HUK wrapped-key examples for ECC and AES keys and fix stale test and docs Add RTL8735B HUK wrapped-key examples for ECC, AES and mutual TLS and fix stale docs Nov 13, 2026
@dgarske dgarske removed their assignment Nov 13, 2026
@night1rider
night1rider merged commit 9a96435 into wolfSSL:master Nov 17, 2026
218 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants