HOVEL // module 01.02
Module 01.02 Payload provider / Integrated

picblobs User Guide

Link or install the module package from modules/picblobs. Its manifest is modules/picblobs/hovel-module.yaml and declares a payload_provider over JSON-RPC stdio.

Prepare a Source Checkout

task picblobs:setup
task picblobs:provider-stage
task picblobs:stage

The provider launcher is staged at modules/picblobs/bin/picblobs-provider. Payload bytes are staged under modules/picblobs/python/picblobs/blobs/ with manifest.json as the runtime catalogue.

Operate from Hovel

Use Hovel's module package commands to link the prepared directory. The provider lists staged blobs, resolves payload queries, and returns base64 encoded artifacts with SHA-256 metadata. Hovel treats these as native typed payloads: kind: pic, os, arch, and tags such as pic, flat, linux, or windows are part of the provider response.

Payload Formats

Query format: pic or format: flat-pic for the raw finalized blob. Linux payloads whose architecture is supported by picblobs' ELF wrapper also advertise format: elf; Hovel returns a minimal executable ELF containing the PIC bytes. The legacy bin request remains accepted as a compatibility alias for pic. 

payload.kind = pic
payload.os = linux
payload.arch = aarch64
payload.format = elf

Mbed OS 5.15.9 NaCl Proof of Concept

The Mbed application runs the real hosted Cortex-M4 nacl_server and nacl_client PIC blobs from RAM on two NUCLEO-F429ZI boards. Mbed supplies Ethernet, TCP sockets, retargeted serial output, hardware random bytes, and the memory-policy transition needed to execute the copied blob. This is a focused proof of concept, not a general Mbed deployment framework.

Secure Channel

  1. The client connects to the configured server IPv4 address and port.
  2. Each peer generates a fresh ephemeral X25519 keypair.
  3. Each ephemeral public key is encrypted and authenticated with the shared 32-byte deployment authentication key.
  4. The peers derive the same fresh 32-byte per-session key from X25519 and wipe their ephemeral secret keys.
  5. The client sends its message with NaCl crypto_secretbox; the server authenticates and decrypts it before printing it.
  6. The server sends the distinct ACK hovel-nacl-server-ack-v1 with the same per-session key; the client authenticates, decrypts, and verifies it before reporting success.

crypto_secretbox provides symmetric XSalsa20 encryption and Poly1305 authentication in both directions. Every handshake and application frame receives a random 24-byte nonce from the platform TRNG. The end-to-end wire capture requires the four generated nonces to be nonzero and unique. A frame is nonce[24] || ciphertext_length_u32_le || ciphertext; the ciphertext includes the 16-byte authenticator. Failed authentication, an unexpected ACK, a malformed length, or incomplete I/O closes the channel and exits unsuccessfully. Tests independently modify client and server application ciphertext and require both directions to fail closed.

Materialize Key and Endpoint Configuration

Create one random 32-byte key for an authorized lab deployment. Use the same materialization command to produce the matched server and client headers: 

task picblobs:mbed-blobs -- \
  --server-ip=192.0.2.10 \
  --auth-key-file=/secure/path/mbed-poc.key \
  --port=9999

The key file may contain exactly 32 raw bytes or 64 hexadecimal characters. Wrong-sized, malformed, and all-zero keys are rejected. --auth-key-hex exists for disposable lab use, but leaks the key through command and process arguments. The materializer validates the IPv4 address and port, replaces only the expected trailing .config template, writes both headers atomically with mode 0600, and reports size and SHA-256 without printing the key.

The generated files are modules/picblobs/mbed/blobs/nacl_server_blob.h and nacl_client_blob.h. The server image contains the port and authentication key. The client image contains the same port and key plus the server IPv4 address. These ignored generated headers and the resulting firmware necessarily contain the deployment key: keep them out of commits and artifacts, protect provisioning, and use a distinct random key for each assessment or lab deployment. Anyone who extracts that key can impersonate either peer for that deployment.

Build and Run the Pair

task picblobs:mbed-compile

This builds separate server and client firmware for the pinned NUCLEO-F429ZI/GCC_ARM target. See Building for role-only commands, pins, outputs, and local Mbed checkout validation. Flash the corresponding image to each board using the lab's normal board workflow, connect both boards to the same authorized Ethernet network, and start the server before the client.

Successful serial output includes:

[server] decrypted: Hello from NaCl PIC blob!
[server] secure channel OK

[client] decrypted ACK: hovel-nacl-server-ack-v1
[client] secure channel OK

A silent connected peer cannot block forever: accepted and connected sockets use a 5000 ms operation timeout. For the exact CI evidence and the checks that still require physical boards, continue to Testing.