F439_CPP_TX-RX_LoRa_Project

Loading...
Searching...
No Matches
Protocol Verification and QA Harness

## Overview

The RadioLink protocol-verification harness exercises the hardened Wire v3 RX path with hostile and boundary-condition inputs.

The intent of this harness is to verify that RX continues operating safely when presented with malformed, malicious, replayed, or boundary-value frames.

## Verification Model

The verification model intentionally separates roles:

- TX runs a deterministic QA frame generator from qaTests/qaApp/qa_app.c
- RX runs the normal radio receive/IRQ path and calls the production RadioLink_ParseWireV3Frame() parser

This approach validates the real RX rejection path rather than a test-only RX parser. Expected QA rejections are logged and must not invoke Error_Handler().

## Enabling the QA Harness

Protocol verification is enabled by defining:

    #define RADIOLINK_QA_TEST

When enabled, Core/Src/main.c routes DIO1 EXTI events to QaApp_OnDio1Exti() and runs QaApp_Loop() instead of RadioApp_Loop(). The harness selects TX or RX behavior using sx1262Role.

## Execution Expectations

During QA execution, TX sends one case per second, or after TX completion or timeout, and cycles through the same stable order. TX logs the test name, sessionSeqId, msgCounter, frame length, and expected RX result before queuing each frame and after TX completion or timeout.

RX must:

- reject invalid or hostile frames without halting
- avoid mutating replay state on rejected frames
- continue processing subsequent traffic
- accept valid frames, including maximum legal payload cases

## Expected TX Log Pattern

TX emits lines similar to:

    QA TX: start test=truncated-frame sess=1 ctr=1 expected=rejected: below minimum Wire v3 frame length
    QA TX: queued test=truncated-frame len=10 sess=1 ctr=1 expected=rejected: below minimum Wire v3 frame length
    QA TX: done test=truncated-frame sess=1 ctr=1 expected=rejected: below minimum Wire v3 frame length

## Expected RX Log Pattern

RX emits a raw header prefix followed by parser outcome lines similar to:

    QA RXHDR: 03 01 ... len=42
    QA RX: rejected frame sess=1 ctr=3 RSSI=-45 SNR=9
    QA RX: accepted [QA replay frame] sess=1 ctr=4 RSSI=-45 SNR=9

## Verified Test Coverage

The TX sequencer actively transmits the following cases in order:

1. Truncated Frame Rejection

   A frame shorter than the minimum Wire v3 frame length is injected.

   Expected RX behavior:

   - frame rejected
   - no system halt
   - receiver continues running

2. Frame Length Mismatch

   A frame where the declared payload length does not match the received frame size is injected.

   Expected RX behavior:

   - frame rejected
   - no replay-state corruption
   - receiver continues running

3. CMAC Authentication Failure

   A validly structured frame with an intentionally corrupted authentication tag is injected.

   Expected RX behavior:

   - frame rejected
   - no plaintext accepted
   - receiver continues running

4. Replay Rejection

   The sequencer sends a valid replay seed frame and then sends an exact duplicate with the same nodeId, sessionSeqId, and msgCounter values.

   Expected RX behavior:

   - first frame accepted
   - duplicate rejected
   - replay state remains correct

5. Maximum Payload Boundary Acceptance

   A frame containing RADIOLINK_WIRE_V3_MAX_PLAINTEXT_LEN plaintext bytes is transmitted.

   Expected RX behavior:

   - frame accepted
   - payload decrypted successfully

6. Oversized Payload Rejection

   A frame declaring a plaintext length larger than RADIOLINK_WIRE_V3_MAX_PLAINTEXT_LEN is injected.

   Expected RX behavior:

   - frame rejected
   - receiver continues running

7. Invalid NodeId Rejection

   A frame whose nodeId byte is overwritten after frame construction is injected. The QA builder sets nodeId to 0xFF. Because the nodeId is covered by the CMAC, modifying it after the tag is computed invalidates the authentication tag.

   Expected RX behavior:

   - frame rejected at CMAC verification (tampered header)
   - replay state not indexed by the injected nodeId
   - receiver continues running

## RX Rejection Behavior Requirement

Rejected protocol frames must be discarded without invoking Error_Handler().

The verified RX contract is:

- discard the rejected frame
- preserve receiver liveness
- preserve replay-state integrity
- continue processing future frames

## Future Logging Hooks

This verification work also establishes the categories that should eventually map to unique structured logging identifiers for remote syslog forwarding, for example:

- RX_REJECT_TRUNCATED
- RX_REJECT_LENGTH_MISMATCH
- RX_REJECT_PAYLOAD_TOO_LARGE
- RX_REJECT_CMAC_FAIL
- RX_REJECT_REPLAY
- RX_REJECT_TAMPERED_HEADER