An IDE/MCUEXPRESSO/RW612 directory with a known-good user_settings.h and the
steps to build the port against the SDK rather than Zephyr, plus the port
README's pointer to it. The README itself grew alongside the offloads it
documents.
The port was reachable only through the Zephyr module, on the assumption that
NXP's els_pkc is a Zephyr artifact. It is not: els_pkc is NXP's CLNS middleware,
shipped as an MCUXpresso SDK component that additionally carries a Zephyr module,
so a project using the SDK directly should be able to build the port too.
Add --with-els-pkc=DIR alongside --with-mcux-sdk=DIR for the SoC device headers
its platform layer includes, and --with-els-pkc-platform=SOC defaulting to rw61x.
The component include directories are globbed rather than enumerated: the list
runs to roughly fifty entries and moves with each vendor release.
The port states its prerequisites as #error in els_pkc_port.h, so promote
WOLF_CRYPTO_CB_COPY and WOLF_CRYPTO_CB_FREE here the way --enable-rtl8735b does.
A wrong or missing path is diagnosed at configure time, naming the option, rather
than several hundred lines into the build with a missing mcuxClEls.h.
The vendor library stays link-only, so the archive carries unresolved mcuxCl*
references by design, as the SE050 port does.
Serves WC_ALGO_TYPE_SEED as well as WC_ALGO_TYPE_RNG, so wolfCrypt's own
Hash-DRBG is seeded from the hardware rather than only the direct generate path
being accelerated.
The engine takes at least four bytes and only whole words. With the driver's
parameter checks compiled out, a sub-word length would program the DMA past the
end of the caller's buffer, and odd sizes are ordinary (wc_RNG_GenerateByte), so
the tail comes from a word-sized scratch.
The input must arrive already padded to a whole block per SP 800-38B, 0x80 then
zeros, while inputLength stays the true pre-padding count, because that count is
what selects subkey K1 or K2.
Only the last block needs holding back, since only it takes the other subkey, so
everything before it goes in a single command. Every ELS command costs a fixed
~8us for AES, measured by sweeping buffer size on frdm_rw612, so a command per
16-byte block is what throughput is actually made of: AES-128-CMAC over 1KB runs
at 7.2 MiB/s this way against 775 KiB/s one block at a time.
pMac is [in, out] and carries the intermediate state, so it lives in the caller's
Cmac rather than in a pool.
The whole Init/UpdateAad/UpdateData/Finalize sequence runs under one lock, which
it can because the callback hands over the entire message at once.
Every stage consumes whole blocks: the final partial data block is zero-padded
with msgendw carrying its real byte count, and the AAD length reaches the
hardware only through Finalize. An exact block multiple needs no padding and so
comes out correct either way, which means a test exercising only 16, 32 and 64
bytes passes against a port that is wrong for every other length.
J0 is IV || 0x00000001, the single-block form Aead_Init takes; other IV lengths
need the GHASH-based derivation through Aead_PartialInit and are declined.
Finalize outputs the expected tag on decrypt rather than checking it, so the
comparison is done here in constant time, and a mismatch clears the plaintext so
a caller that ignores the return value is not handed unauthenticated data.
Adds the AES cipher modes, and with them the slot reference that lets a
wolfCrypt key name a key living inside the ELS key store.
A callback sees only key->id[], its length and the devId, so the reference is
self-describing and travels as the key's id blob: sixteen bytes of magic,
version, key class, slot, flags and eight bytes binding it to a public point.
wolfPSA stores the same bytes for a vendor-location key. Fields are never
redefined; the version bumps and the format appends. Each key class maps onto
exactly one ELS permission bit and one entry point, and every entry point reads
the slot's properties back and checks that permission before issuing a command,
because a permission violation resets the part instead of returning an error.
AES-192 and any trailing partial block decline to software: ELS knows only 128-
and 256-bit keys and only whole blocks.
CBC chaining is maintained here. The documentation says ELS "will always read
and write" pIV, but it only reads it, so aes->reg still held the original IV
after a one-block encrypt: correct for a single call and wrong from the second
onward. The next IV is the last ciphertext block either way, saved before an
in-place decrypt overwrites it. cphsie/cphsoe are set only for CTR; for CBC they
are documented as ignored, but setting them made ELS treat pIV as an internal
state blob and produce output that was self-consistent yet disagreed with
software.
The ECC classes include a key generation seed, the ukgsrc permission, for a
P-256 key that arrives as its scalar and becomes a key pair only once the engine
generates from it. WC_ELSPKC_KEY_MAX names the last class, so the bounds checks
on building and parsing a reference stay as they are when a class is added.
ELS serves SHA-2 in all four widths. SHA-384 and SHA-512 share the engine's
512-bit state and 1024-bit block, so they differ from SHA-256 only in the mode
selector, a 128-bit padding length field, and SHA-384 taking the leading 48
bytes of the final state.
HMAC benefits without an arm of its own: HmacKeyInitHash passes the Hmac's devId
to the inner hash, so HMAC-SHA384, HMAC-SHA512, HKDF and the SHA-384 TLS PRF all
compress on the engine.
The ELS HMAC command stays unused. It is one shot, with no equivalent of the
hash command's state load, while the wolfCrypt callback is incremental, so
serving it would mean buffering whole messages on parts routinely built without
an allocator.
Routes wolfCrypt through the on-chip EdgeLock subsystem (ELS) on RW612 via the
crypto callback interface, with SHA-256 as the first offloaded primitive.
Anything the hardware does not implement declines to software, so enabling the
port never removes functionality.
Three properties of the hardware shape the design.
ELS is one peripheral with global busy state: every operation is an _Async call
followed by a wait, and nothing may start between the two, so one lock is held
across each pair.
ELS answers a rejected request by signalling the tamper controller, which
resets the SoC, rather than by returning an error. Validation therefore happens
in software before the call: getting it wrong reboots the device.
mcuxClEls_WaitForOperation() busy-spins with no timeout, and would do so
holding that lock. Completion is taken from the ELS interrupt instead, wired
with IRQ_CONNECT because the IRQ has no devicetree node, with polling as the
fallback for ISR context and for anything before the IRQ is armed. A late
interrupt degrades to the synchronous wait rather than cancelling: measured,
MCUXCLELS_RESET_CANCEL on an in-flight operation reboots the SoC.
For SHA-256 the engine round-trips its intermediate state (hashoe writes it,
hashld reloads it), so the state lives in the caller's wc_Sha256 and the lock
covers one call. Holding it from update to final deadlocks TLS 1.3, which keeps
several transcript hashes alive at once. ELS never pads, so the port carries the
residual block and appends the padding itself.
Registration happens inside wolfCrypt_Init(), which is also what zeroes the
callback device table. Zephyr gains CONFIG_WOLFSSL_SYS_INIT to run that at boot
from POST_KERNEL rather than leaving it to whichever library call happens to be
first, which starts to matter once initialization brings up a peripheral. It
defaults on when the port is enabled and stays available on its own, since
nothing about it is specific to this hardware. The hook calls wolfSSL_Init() so
the TLS layer is initialized too, and wolfCrypt_Init() in a WOLFCRYPT_ONLY
build, where wolfSSL_Init() is not compiled.
The port's Kconfig symbol is restricted to SOC_SERIES_RW6XX, the only series for
which els_pkc exports src/platforms/<soc>, where mcux_els.h lives.
FIPS builds at v5.2 or older force WOLFSSL_NO_SHAKE128/256 on in
settings.h, which blocks ML-DSA and ML-KEM's internal SHAKE hashing
under --enable-fips=v5. Adds a CFLAGS opt-in, V523_NONFIPS_SHAKE,
that restores SHAKE128/256 for exactly the cert4718 (5.2.1) build.
- configure.ac, src/include.am, wolfssl/wolfcrypt/include.am: build
and install the paired shake.c/shake.h from the internal fips repo
overlay only when the opt-in and FIPS version match, validating
both files exist first
- hash.c, asn.c, wc_mldsa.c/.h, benchmark.c, test.c, test_sha3.c:
include shake.h ahead of their first sha3.h/asn.h include, since
asn.h can reach sha3.h unguarded via ed448.h/wc_lms.h/wc_xmss.h
first
- wc_mlkem.h: the one exception - its override must come after its
sha3.h include, since sha3.h processes first there with SHAKE off,
and shake.h's own fallback typedef and prototypes are what actually
declare wc_Shake
- every override site uses the same
defined(WOLFSSL_SHA3) && defined(V523_NONFIPS_SHAKE) guard
- registers V523_NONFIPS_SHAKE in .wolfssl_known_macro_extras, which
check-source-text otherwise flags as unrecognized
openssl.test starts its servers, then waits in check_server_ready until
each one accepts connections. The RSA-PSS server starts after that loop,
so the first wolfSSL client connects once s_server has survived 0.1
seconds. On a busy node s_server has not bound the port by then and the
client fails with "Connection refused".
Run check_server_ready for the RSA-PSS server too.
