HOVEL // module 01.05
Module 01.05 Payload provider / Integrated

picblobs Reference

Module Paths

Path Purpose
modules/picblobs/hovel-module.yamlHovel module package manifest.
modules/picblobs/provider/Hovel payload-provider JSON-RPC shim.
modules/picblobs/src/payload/C payload blob sources.
modules/picblobs/tools/registry.pySource of truth for platforms, blobs, generated files, and staging.
modules/picblobs/python/picblobs/Python API and release artifact loader.
modules/picblobs/nacl_protocol.pyCanonical NaCl wire framing and deployment-config constants.
modules/picblobs/mbed/Mbed application, platform adapter, materializer, pinned target builder, and tests.
modules/picblobs/src/payload/nacl_server.cAuthenticated X25519 handshake, message decryption, and encrypted ACK.
modules/picblobs/src/payload/nacl_client.cAuthenticated X25519 handshake, encrypted message, and ACK verification.
modules/picblobs/tests/nacl_e2e_test.pyWire capture, nonce, plaintext, tamper, and timeout assertions.
modules/picblobs/toolchains/repositories.bzlPinned Cortex-M, Mbed OS, GCC ARM, Bootlin, and QEMU repositories.
modules/picblobs/spec/Original requirements, models, traceability, and verification records.
modules/picblobs/docs/Preserved original standalone HTML documentation.

Mbed NaCl Protocol

Field Value
Authentication key32 deployment-provisioned bytes; seals both ephemeral X25519 public keys.
Session keyFresh 32-byte symmetric key derived from the peers' ephemeral X25519 keypairs.
Data protectionTweetNaCl crypto_secretbox: XSalsa20-Poly1305.
NonceFresh random 24 bytes per handshake or application frame.
Framenonce[24] || ciphertext_length[4 LE] || ciphertext.
Authentication overhead16 bytes included in each transmitted ciphertext.
Maximum plaintext4096 bytes.
Client payloadHello from NaCl PIC blob!
Server ACKhovel-nacl-server-ack-v1

The server config is 34 bytes: port_u16_le || auth_key[32]. The client config is 38 bytes: port_u16_le || server_ipv4[4] || auth_key[32]. Unconfigured blobs end in exact templates containing port 9999, loopback for the client, and a zero key. Materialization replaces the complete template and configured blobs reject an all-zero key at runtime. Read the materialization workflow before generating deployment images.

Mbed Runtime Adapter

  • Target: Mbed OS 5.15.9, NUCLEO-F429ZI, GCC_ARM, Ethernet with DHCP, and a required DEVICE_TRNG.
  • Descriptors: a 16-entry table reserves 0-2 for console I/O and maps later descriptors to listening or connected TCPSocket objects.
  • Timeout: accepted server sockets and connected client sockets receive a 5000 ms send/receive operation timeout.
  • Cleanup: close clears the table entry, closes and deletes the socket, and platform shutdown closes every remaining tracked socket and releases the TRNG.
  • Randomness: the adapter fills requests from Mbed's target TRNG in bounded chunks and terminates the blob on incomplete or failed random output.

MPU and Cache Behavior

On the board, the runner allocates SRAM, copies the blob, cleans every D-cache line touched by the allocation when a D-cache exists, invalidates the I-cache when present, and issues data and instruction barriers. It then calls Mbed's mbed_mpu_manager_lock_ram_execution() before entering the blob. Both the blob's non-returning exit_group path and the defensive returned-entry cleanup call mbed_mpu_manager_unlock_ram_execution(), restoring the normal RAM execute-never policy before the board halts or control returns.

The Linux/QEMU test path instead copies into an executable mmap allocation. It exercises the same vtable and blob but deliberately excludes the board-only MPU and cache calls; a physical smoke test remains the runtime evidence for those paths. See What CI Proves.

Mbed Task Index

Task Purpose
task picblobs:mbed-blobs -- ...Materialize matched configured server/client C headers.
task picblobs:mbed-compileCompile both pinned real-target firmware roles.
task picblobs:mbed-compile -- --role=serverCompile only the server role; use client for the peer.
task picblobs:testRun the integrated module suite, including Mbed and NaCl checks.
task picblobs:ciRun the module build and test gate.