Ir para o conteúdo

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

  • payloadHash must be the SHA-256 of the payload's text before final serialization — not of the envelope's JSON.
  • nonce is a UUID v4 generated at creation time; never reuse it between messages.
  • The receiver must call both envelope.verify(signatures) and envelope.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.