01 — MQTT Envelope¶
Every message published by the HDT-AF system is wrapped in an MqttEnvelope<T>.
The envelope guarantees authenticity, integrity, anti-replay protection, and traceability for every message.
Java record structure¶
public record MqttEnvelope<T>(
String messageId, // unique UUID v4 per message
String schemaVersion, // always "1.0.0"
String experimentId, // experiment identifier
String contractVersion, // contract version (e.g.: "1.0.0")
long roundId, // round number (0 if not applicable)
String senderId, // sender identity
Instant timestamp, // moment the message was created
String nonce, // random anti-replay UUID v4
String payloadHash, // "sha256:{64 hex}" of the serialized payload
String signature, // "x509:{id}:{base64}" or sender's HMAC-SHA256 signature
T payload // typed payload
)
Location: modules/federated-common/src/main/java/br/ufma/lsdi/common/mqtt/MqttEnvelope.java
Wire format and schema note¶
MqttPayloadCodec uses default Jackson ObjectMapper on the Java record MqttEnvelope<T>, so JSON payloads transported over the MQTT broker use camelCase property names (messageId, schemaVersion, experimentId, contractVersion, roundId, senderId, timestamp, nonce, payloadHash, signature, payload). Note that the older schemas/mqtt/envelope.schema.json file specifies snake_case field names (message_id, schema_version, ...), so validate wire captures using camelCase against the Java record definition above.
Record Field (wire camelCase) |
Legacy Schema Field | Type | Constraint |
|---|---|---|---|
messageId |
message_id |
string |
UUID format |
schemaVersion |
schema_version |
string |
"1.0.0" |
experimentId |
experiment_id |
string |
— |
senderId |
sender_id |
string |
— |
timestamp |
timestamp |
string |
ISO-8601 date-time |
nonce |
nonce |
string |
random UUID v4 |
payloadHash |
payload_hash |
string |
^sha256:[a-f0-9]{64}$ |
signature |
signature |
string |
HMAC or x509:... |
payload |
payload |
object |
typed payload |
Optional fields: contractVersion (contract_version), roundId (round_id).
How the signature is generated¶
The MqttEnvelope.signed() method computes the canonical string before signing:
canonical = messageId + "|" + experimentId + "|" + contractVersion + "|" + roundId
+ "|" + senderId + "|" + timestamp + "|" + nonce + "|" + payloadHash
The signature is generated by SignatureService.sign(senderId, canonical). Two implementations exist:
| Implementation | Scheme | When to use |
|---|---|---|
HmacSignatureService |
HMAC-SHA256, shared secret per identity | Sessions where orchestrator, aggregator and client(s) run in the same JVM process (research/experiments/* in-process sessions, simulators, tests) — no real trust boundary to protect, since every identity's secret already lives in the same process memory. |
X509SignatureService |
Asymmetric (RSA/EC), certificate issued by a local CA, verified via certificate.verify(trustAnchor) |
Participants that run in a separate process or device from the orchestrator, talking only over the shared MQTT broker — external Docker clients and the Android app. Nobody but the identity itself ever holds its private key, unlike HMAC where verifier and signer must share the same secret. See X509SignatureService's javadoc (modules/federated-common/.../crypto/X509SignatureService.java) for the full rationale, and scripts/generate-signing-identities.sh to provision certificates from the same CA already used for MQTT mTLS (scripts/generate-mqtt-tls.sh). X509SignatureServiceLoader.load(...) loads a ready-to-use instance from PKCS12/PEM material on disk, mirroring MqttTlsConfig's loading style. |
Verification is done via envelope.verify(signatureService), which reconstructs the same canonical string and calls SignatureService.verify(senderId, canonical, signature) — identical call shape regardless of which implementation is wired in, since MqttEnvelope only depends on the SignatureService interface.
Migrated to X509SignatureService (opt-in, see CompositeSignatureService below): the exp-ergonomic-risk-001 daemons — DockerErgonomicClientDaemonApp, DockerAggregatorDaemonApp and the orchestrator-side signer in ErgonomicRiskFederatedSession (its RoundCoordinator/FedAvgAggregationService wiring specifically — the in-process simulated clients stay on plain HmacSignatureService, no real trust boundary there). DockerParticipantLaunchService provisions the container-side material via DockerMqttEnvironment.appendSigningEnvironment. Migration is opt-in: when SIGNING_CA_CERT/SIGNING_DIR/SIGNING_KEYSTORE_PASSWORD aren't configured, every one of these keeps behaving exactly as before (plain HMAC) — nothing breaks for a deployment that hasn't provisioned certificates yet. When they are configured, the migrated identities (orchestrator-001, aggregator-001, each client id) stop being registered in the HMAC fallback at all — the old hardcoded secret genuinely stops working, not just becomes redundant.
Not yet migrated (tracked in backlog.md): the exp-synthetic-smoke-001 daemons (DockerSmokeClientDaemonApp, DockerSmokeAggregatorDaemonApp, SmokeFederatedPipeline) share one SmokeExperimentContract.buildSignatures(clientIds) helper that hands back a single fully-populated HmacSignatureService to every caller regardless of which identity that specific process actually owns — unlike the ergonomic daemons (which already had one buildSignatures per file), migrating this one safely means threading through which identity is "self" for X.509 vs. "peer" for verification, which the shared helper's current signature doesn't distinguish. The Android client (FederatedMqttService/ClientConfig.java, still defaulting orchestrator_secret to the literal "orchestrator-secret") needs the same composite wiring plus a device-side provisioning story for its own keystore + the orchestrator's certificate. Both are mechanical repeats of the exp-ergonomic-risk-001 pattern once their own shape is worked out — see the backlog entry for this delivery.
CompositeSignatureService (modules/federated-common/.../crypto/) is what makes partial, per-identity migration possible: it routes sign/verify to a primary backend (X509SignatureService) and falls back to a secondary one (HmacSignatureService, for identities that never migrate — e.g. simulated dataset-replay provenance) without either caller or the SignatureService interface needing to know which backend actually owns which identity.
JSON example (wire camelCase produced by MqttPayloadCodec)¶
{
"messageId": "a3f9e1b2-4c8d-47a0-b5f1-2e9d3c6a0f12",
"schemaVersion": "1.0.0",
"experimentId": "exp-har-smartphones-001",
"contractVersion": "1.0.0",
"roundId": 3,
"senderId": "client-org-001",
"timestamp": "2026-05-27T14:22:00Z",
"nonce": "7b1e4a92-0c5d-4f8b-a123-9e2f6d3c0a45",
"payloadHash": "sha256:3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"signature": "x509:client-org-001:base64-signature-value",
"payload": {}
}
Creating an envelope in code¶
MqttEnvelope<ClientUpdateMessage> envelope = MqttEnvelope.signed(
contract.experimentId(),
contract.contractVersion(),
roundConfig.roundId(),
clientId,
message.evidenceString(), // serialized text of the payload used for hashing
message, // typed payload
signatureService
);
mqttGateway.publish(MqttTopics.clientUpdate(experimentId, roundId, clientId), envelope);
Invariants¶
payloadHashmust be the SHA-256 of the payload's text before final serialization — not of the envelope's JSON.nonceis a UUID v4 generated at creation time; never reuse it between messages.- The receiver must call both
envelope.verify(signatures)andenvelope.verifyPayloadIntegrity()before processing the payload (verify()alone proves only that the hash was signed, not that it matches the transported payload). - A signature verification failure must silently discard the message (log + metric), never propagate the payload.