Configurable validation suffix for AT commands, responses, and events (CRC, HMAC)

[mAliGem]

Is your feature request related to a problem?

Depending on the application, the host may need to detect corrupted, truncated, duplicated, or forged AT messages.

UART parity and hardware flow control do not provide end-to-end validation of an entire AT command or response. Applications can add validation inside individual custom parameters, but there is no consistent mechanism that covers all standard commands, responses, and asynchronous events.

A protocol-level suffix would provide a uniform validation mechanism without changing the semantics of every AT command separately. Example use cases include:

• CRC-16 or CRC-32 for detecting accidental corruption;
• a truncated HMAC for authenticating the host and ESP-AT messages;
• product-specific validation algorithms implemented by a custom ESP-AT component; and
• consistent validation of asynchronous URCs as well as solicited responses.

Describe the solution you'd like.

1. Optional validation mode

Validation should be disabled by default so existing hosts and firmware remain compatible.

When enabled, every complete inbound AT command must include a suffix of the configured length. ESP-AT must validate the message before executing the command. Invalid messages must be rejected and must not cause command side effects.

Every complete outbound protocol message should include a suffix computed over the message content before the suffix is added. This should include, as applicable:

• command responses such as OK and ERROR;
• response data such as +GMR:...;
• URCs and asynchronous events;
• prompts such as >;
• data-transfer completion or cancellation messages; and
• other messages written to the AT command port.

2. Configurable suffix length

The application should be able to configure the suffix length in bytes, for example:

esp_at_message_validation_config_t config = {
    .suffix_len = 4,
    .encoding = ESP_AT_VALIDATION_ENCODING_HEX,
};

The configured byte count should refer to the decoded validation value, not the number of printable hexadecimal characters. For example, a four-byte suffix represented as hexadecimal would occupy eight characters on the AT command port.

The implementation should define a reasonable maximum suffix size and reject unsupported sizes.

3. CRC/HMAC generation callback

Please expose a callback after one complete inbound AT command has been received and framed, but before it is parsed or executed.

The generation callback should receive only the complete message bytes without the received or transmitted validation suffix:

typedef bool (*esp_at_generate_validation_cb_t)(
    const uint8_t *message,
    size_t message_len,
    uint8_t *calculated_suffix,
    size_t suffix_len,
    void *context);

The callback computes a CRC or HMAC using only message and message_len, then writes exactly suffix_len bytes to calculated_suffix. The calculation callback must not receive or include the validation suffix that arrived on the wire. This prevents a custom calculation function from accidentally calculating the CRC/HMAC over the received value itself.

For an HMAC implementation, the callback and its private context can own the key. ESP-AT should not need to know or expose the key.

The same generation callback can be used in both directions:

• for an inbound command, generate the expected CRC/HMAC before comparing it with the received suffix; and
• for an outbound response or event, generate the suffix that ESP-AT appends to the message.

If different keys or algorithms are required for each direction, the configuration could provide separate generate_rx and generate_tx callbacks or direction-specific contexts.

4. CRC/HMAC comparison callback

Please expose a separate callback for comparing the calculated value with the suffix received from the host:

typedef bool (*esp_at_compare_validation_cb_t)(
    const uint8_t *calculated_suffix,
    const uint8_t *received_suffix,
    size_t suffix_len,
    void *context);

Keeping comparison separate from generation allows applications to provide constant-time HMAC comparison, special CRC byte-order handling, secure-element verification, or another product-specific comparison policy.

The suggested inbound flow is:

1. ESP-AT frames the complete command and separates the received suffix.
2. ESP-AT calls generate_rx with the command bytes only.
3. The generation callback returns the calculated CRC/HMAC.
4. ESP-AT passes the calculated and received values to compare_rx.
5. ESP-AT executes the command only when compare_rx returns true.

5. Outbound suffix generation

For an outbound message, ESP-AT should call the generation callback with the complete response or event before adding a suffix. It should then encode and append the generated value using the configured wire format.

The generation callback should be invoked for both normal command responses and unsolicited events. A comparison callback is not needed for outbound messages because no suffix has been received.

Framing and wire-format requirements

The suffix format must be unambiguous and must not break the existing AT command parser. The documentation should define:

• whether CR-LF is included in the validated bytes;
• whether command echo is validated;
• the delimiter between the message and suffix, if any;
• whether the suffix is binary, hexadecimal, Base64, or configurable;
• whether prefixes such as 0x are included;
• how multi-line responses are framed and validated;
• whether each response line has its own suffix or the entire response has one suffix;
• how prompts such as > are framed;
• how raw or passthrough data is handled; and
• the byte ordering used by any built-in CRC implementation.

One possible text-safe wire format is:

AT+GMR*7A91B203\r\n
+GMR:<version>*D1646DAA\r\n
OK*D736D92D\r\n

In this example, * separates the message from an eight-character hexadecimal representation of a four-byte suffix. The callback input would contain AT+GMR, +GMR:<version>, or OK, without *, the suffix, or CR-LF unless inclusion of CR-LF is explicitly configured.

The exact delimiter is not important, but it should be escaped or otherwise handled when it occurs in command parameters or event data.

Describe alternatives you've considered.

Only for important AT commands, creating custom equivalents which have CRC/HMAC parameters

Additional context.

No response

[ustccw]

@mAliGem Thanks for the detailed feature request and for bringing up this interesting perspective!

If I understand correctly, your primary goal is to establish a reliable and tamper-proof data delivery mechanism between the Host MCU and the ESP-AT device. Here are a few thoughts from our end:

• Data Security & Tamper Resistance: To prevent malicious tampering on the UART interface, we have an interface security example available: examples/at_interface_security. It uses AES-CTR encryption to ensure data confidentiality and integrity.
• Reliable Delivery: For detecting transmission errors, standard UART parity along with hardware flow control is typically sufficient and has been broadly proven in mass production across numerous customer applications. Could you elaborate on how adding a protocol-level CRC fundamentally differs from native UART parity checks in your use case, or what specific pain point it addresses that UART parity cannot solve?

That said, if you still prefer to implement custom CRC/HMAC validation for your specific product requirements, you can achieve this by overriding the at_port_read_data and at_port_write_data functions in main/interface/at_interface_api.c. This allows you to inspect, validate, or append suffixes before the AT core processes or transmits the stream.

[mAliGem]

Thanks for the speedy response!

Data Security & Tamper Resistance

From what I understand, AES-CTR (and pretty much all stream cipher implementations) definitely do ensure data confidentiality, however, they cannot, by themselves, ensure data integrity. This would require something like AES-GCM (which contains an HMAC portion to each block). From my understanding, this is a limitation to all stream ciphers. AES-GCM is a block cipher and so there is an expected number of bytes one must read in order to properly decrypt data and ensure it's validity (via a suffixed HMAC).

Reliable Delivery

I will test UART Parity and see if this improves my reliability. Note that, in 99% of cases, we have no issue with EMI. Only when running our internal testing and stress testing does this occur occasionally.

Thanks for the support!