Lesson 37. Secure commands over MQTT, CAN, and RS-485: HMAC, anti-replay, and idempotency

MQTT/CAN/RS-485 transport
→ decoding
→ format and length validation
→ message authentication
→ replay protection
→ operation authorization
→ local constraints validation
→ owner-task queue
→ execution
→ result persistence
→ acknowledgment

reconnect EC25
change APN
change MQTT broker
start OTA
change the input filter
restart the device
enable/disable a load

the broker is compromised;
the publisher account is stolen;
an old message is redelivered;
a retained command arrives after reboot;
QoS repeats an operation;
the server sends a command to the wrong device.

Authenticity:
  a trusted sender created the command.
Integrity:
  the fields have not changed.
Freshness:
  this is not replayed old traffic.
Authorization:
  the sender is permitted to perform the operation.
Idempotency:
  redelivery does not create another side effect.
Auditability:
  it is possible to understand what arrived and why it was accepted/rejected.

typedef enum {
    CMD_NONE = 0,
    CMD_MODEM_RESET,
    CMD_MQTT_RECONNECT,
    CMD_SET_LOG_LEVEL,
    CMD_SET_IR_DUTY,
    CMD_CONFIG_STAGE,
    CMD_CONFIG_COMMIT,
    CMD_OTA_START,
    CMD_SYSTEM_REBOOT,
} command_type_t;
typedef struct {
    uint8_t protocol_version;
    uint32_t issuer_id;
    uint32_t key_id;
    uint32_t target_device_id;
    uint64_t command_id;
    uint64_t sequence;
    uint64_t issued_utc_s;
    uint64_t expires_utc_s;
    uint64_t session_id;
    uint64_t nonce;
    command_type_t type;
    const uint8_t *payload;
    uint16_t payload_length;
    const uint8_t *auth_tag;
    uint16_t auth_tag_length;
} secure_command_view_t;

protocol_version
issuer_id big-endian
key_id big-endian
target_device_id big-endian
command_id big-endian
sequence big-endian
issued_at big-endian
expires_at big-endian
session_id big-endian
nonce big-endian
command_type big-endian
payload_length big-endian
payload bytes

tag = HMAC-SHA256(key, canonical_command)

static bool constant_time_equal(const uint8_t *a,
                                const uint8_t *b,
                                size_t length)
{
    uint8_t difference = 0;
    for (size_t i = 0; i < length; i++) {
        difference |= (uint8_t)(a[i] ^ b[i]);
    }
    return difference == 0;
}

MQTT server commands:
  server key signature or per-device HMAC
local RS-485:
  per-link HMAC
CAN with a small payload:
  gateway-authenticated session or CAN FD

typedef struct {
    uint64_t highest_accepted_sequence;
    uint64_t replay_bitmap;
} replay_window_t;

SET_OUTPUT ON
SET_LOG_LEVEL WARN
SET_IR_DUTY 30%

TOGGLE_OUTPUT
INCREMENT_COUNTER
PULSE_OUTPUT

typedef enum {
    CMD_RESULT_NONE = 0,
    CMD_RESULT_IN_PROGRESS,
    CMD_RESULT_SUCCESS,
    CMD_RESULT_REJECTED,
    CMD_RESULT_FAILED,
} command_result_code_t;
typedef struct {
    uint64_t command_id;
    command_result_code_t result;
    int32_t error_code;
    uint32_t result_generation;
    uint64_t completed_mono_us;
} command_result_entry_t;

IR duty must not exceed the safe maximum;
OTA only on primary power;
factory reset only with a physical button;
GPIO polarity changes only in service mode;
watchdog cannot be fully disabled remotely.

1. Treating QoS 2 as a guarantee of one physical action.
2. Using a retained REBOOT command.
3. Signing a C structure.
4. Checking timestamp but not sequence.
5. Updating replay counter before MAC verification.
6. One HMAC key for the entire fleet.
7. Comparing MAC with a variable length.
8. Using memcmp() for a security tag.
9. Executing the command in an MQTT callback.
10. Executing first and saving command_id afterwards.
11. Treating Modbus/CAN CRC as authentication.
12. Allowing all protections to be disabled remotely.

# Secure command policy
1. Transport security does not replace message authentication.
2. Every command has target_device_id, command_id and sequence.
3. Commands are authenticated before replay state is changed.
4. Imperative MQTT commands are never retained.
5. Duplicate command_id never repeats a side effect.
6. Authorization is checked separately from authentication.
7. Local safety checks may reject an authenticated command.
8. Critical command results are persisted before ACK.
9. Keys are unique per device or verification uses a server public key.
10. Security failures use rate-limited diagnostics.

typedef enum {
    SEC_CMD_OK = 0,
    SEC_CMD_BAD_FORMAT,
    SEC_CMD_WRONG_TARGET,
    SEC_CMD_UNKNOWN_KEY,
    SEC_CMD_BAD_AUTH,
    SEC_CMD_REPLAY,
    SEC_CMD_EXPIRED,
    SEC_CMD_UNAUTHORIZED,
    SEC_CMD_INVALID_PARAMS,
    SEC_CMD_DUPLICATE,
} secure_command_status_t;
typedef struct {
    uint32_t device_id;
    uint64_t current_session_id;
    uint64_t current_utc_s;
    bool utc_valid;
    replay_window_t replay;
} secure_command_context_t;

valid command;
a payload bit changed;
repeated sequence;
repeated command_id;
old session_id;
expired;
unknown key_id;
unauthorized;
zero MAC length;
payload length exceeds the buffer.

untrusted transport payload
→ bounded decoder
→ canonical representation
→ HMAC/signature verification
→ target/session check
→ anti-replay
→ authorization
→ local safety validation
→ idempotency lookup
→ owner-task execution
→ persistent result
→ authenticated response