Implement authenticated recovery log retrieval (#31)

Co-authored-by: Srikanth Patchava <srikanth.patchava@outlook.com>

Author: prerna1001

core/recovery.c

@@ -44,6 +44,8 @@
 #define RCVR_MAX_AUTH_FAILS  5
 #define RCVR_BACKOFF_BASE_MS 1000
 
+#define RCVR_LOG_MAX_ENTRIES 8
+
 /* Recovery protocol packet header */
 #ifdef _MSC_VER
 #pragma pack(push, 1)
@@ -80,6 +82,8 @@ extern int  eos_slot_erase(eos_slot_t slot);
 
 /* Forward declarations from boot_log */
 extern void eos_boot_log_append(uint32_t event, uint32_t slot, uint32_t detail);
+extern int eos_boot_log_read(uint32_t index, eos_boot_log_entry_t *out);
+extern uint32_t eos_boot_log_get_head(void);
 
 static int recovery_send_ack(void)
 {
@@ -96,19 +100,20 @@ static int recovery_send_nack(void)
 /**
  * @brief Check if a command requires authentication.
  */
-static bool cmd_requires_auth(uint8_t cmd)
-{
-    switch (cmd) {
-    case RCVR_CMD_ERASE:
-    case RCVR_CMD_WRITE:
-    case RCVR_CMD_VERIFY:
-    case RCVR_CMD_BOOT:
-    case RCVR_CMD_FACTORY:
-        return true;
-    default:
-        return false;
-    }
-}
+static bool cmd_requires_auth(uint8_t cmd)
+{
+    switch (cmd) {
+    case RCVR_CMD_ERASE:
+    case RCVR_CMD_WRITE:
+    case RCVR_CMD_VERIFY:
+    case RCVR_CMD_BOOT:
+    case RCVR_CMD_FACTORY:
+    case RCVR_CMD_LOG:
+        return true;
+    default:
+        return false;
+    }
+}
 
 /**
  * @brief Handle authentication challenge-response.
@@ -169,18 +174,18 @@ static int recovery_handle_auth(void)
         eos_sha256_init(&ctx);
         eos_sha256_update(&ctx, challenge, RCVR_CHALLENGE_SIZE);
 
-        /* Read shared secret from OTP */
-        uint8_t shared_secret[32];
-        rc = eos_hal_otp_read(0x180, shared_secret, sizeof(shared_secret));
-        if (rc != EOS_OK) {
-            /* Fail authentication if OTP secret is unreadable */
-            auth_fail_count++;
-            auth_state = RCVR_AUTH_NONE;
-            eos_boot_log_append(0x21, EOS_SLOT_NONE, auth_fail_count); /* AUTH_FAIL */
-            return recovery_send_nack();
-        }
-
-        eos_sha256_update(&ctx, shared_secret, sizeof(shared_secret));
+        /* Read shared secret from OTP */
+        uint8_t shared_secret[32];
+        rc = eos_hal_otp_read(0x180, shared_secret, sizeof(shared_secret));
+        if (rc != EOS_OK) {
+            /* Fail authentication if OTP secret is unreadable */
+            auth_fail_count++;
+            auth_state = RCVR_AUTH_NONE;
+            eos_boot_log_append(0x21, EOS_SLOT_NONE, auth_fail_count); /* AUTH_FAIL */
+            return recovery_send_nack();
+        }
+
+        eos_sha256_update(&ctx, shared_secret, sizeof(shared_secret));
         eos_sha256_final(&ctx, expected);
 
         /* Securely zero the secret */
@@ -303,16 +308,16 @@ static int recovery_handle_verify(eos_slot_t slot)
     if (rc != EOS_OK)
         return recovery_send_nack();
 
-    /* eos_image_verify_integrity() adds hdr_size internally — pass base addr only */
-    rc = eos_image_verify_integrity(&hdr, addr);
-    if (rc != EOS_OK)
-        return recovery_send_nack();
-
-    rc = eos_image_verify_signature(&hdr);
-    if (rc != EOS_OK)
-        return recovery_send_nack();
-
-    return recovery_send_ack();
+    /* eos_image_verify_integrity() adds hdr_size internally — pass base addr only */
+    rc = eos_image_verify_integrity(&hdr, addr);
+    if (rc != EOS_OK)
+        return recovery_send_nack();
+
+    rc = eos_image_verify_signature(&hdr);
+    if (rc != EOS_OK)
+        return recovery_send_nack();
+
+    return recovery_send_ack();
 }
 
 static int recovery_handle_boot(eos_slot_t slot, eos_bootctl_t *bctl)
@@ -335,19 +340,98 @@ static int recovery_handle_boot(eos_slot_t slot, eos_bootctl_t *bctl)
     return EOS_OK;
 }
 
-static int recovery_handle_factory_reset(eos_bootctl_t *bctl)
+static int recovery_handle_factory_reset(eos_bootctl_t *bctl)
+{
+    int rc1 = eos_slot_erase(EOS_SLOT_A);
+    int rc2 = eos_slot_erase(EOS_SLOT_B);
+    eos_bootctl_init_defaults(bctl);
+    int rc3 = eos_bootctl_save(bctl);
+    
+    if (rc1 != EOS_OK || rc2 != EOS_OK || rc3 != EOS_OK) {
+        return recovery_send_nack();
+    }
+    
+    eos_boot_log_append(EOS_LOG_FACTORY_RESET, EOS_SLOT_NONE, 0);
+    return recovery_send_ack();
+}
+
+static int recovery_collect_boot_log_entries(
+    eos_boot_log_entry_t *entries_out,
+    uint16_t *entry_count_out
+)
 {
-    int rc1 = eos_slot_erase(EOS_SLOT_A);
-    int rc2 = eos_slot_erase(EOS_SLOT_B);
-    eos_bootctl_init_defaults(bctl);
-    int rc3 = eos_bootctl_save(bctl);
-    
-    if (rc1 != EOS_OK || rc2 != EOS_OK || rc3 != EOS_OK) {
+    eos_boot_log_entry_t raw_entries[EOS_BOOT_LOG_MAX];
+    uint32_t valid_entry_count = 0;
+    uint32_t log_head;
+    uint16_t written_count = 0;
+
+    if (!entries_out || !entry_count_out)
+        return EOS_ERR_INVALID;
+
+    for (uint32_t i = 0; i < EOS_BOOT_LOG_MAX; i++) {
+        int rc = eos_boot_log_read(i, &raw_entries[i]);
+        if (rc != EOS_OK)
+            return rc;
+
+        if (raw_entries[i].event != 0)
+            valid_entry_count++;
+    }
+
+    log_head = eos_boot_log_get_head() % EOS_BOOT_LOG_MAX;
+
+    for (uint32_t i = 0; i < valid_entry_count; i++) {
+        uint32_t entry_index = (valid_entry_count == EOS_BOOT_LOG_MAX) ?
+                               ((log_head + i) % EOS_BOOT_LOG_MAX) : i;
+
+        if (raw_entries[entry_index].event == 0)
+            continue;
+
+        entries_out[written_count++] = raw_entries[entry_index];
+    }
+
+    *entry_count_out = written_count;
+    return EOS_OK;
+}
+
+static int recovery_handle_boot_log(uint32_t start_index, uint16_t requested_count)
+{
+    eos_boot_log_entry_t boot_log_entries[EOS_BOOT_LOG_MAX];
+    uint16_t total_entries = 0;
+    uint16_t response_entry_count;
+    int rc;
+
+    if (requested_count == 0)
+        requested_count = RCVR_LOG_MAX_ENTRIES;
+    if (requested_count > RCVR_LOG_MAX_ENTRIES)
+        requested_count = RCVR_LOG_MAX_ENTRIES;
+
+    rc = recovery_collect_boot_log_entries(boot_log_entries, &total_entries);
+    if (rc != EOS_OK)
         return recovery_send_nack();
+    
+    if (start_index >= total_entries) {
+        uint8_t empty_response_header[3] = { RCVR_ACK, 0, 0 };
+        return eos_hal_uart_send(empty_response_header, sizeof(empty_response_header));
     }
+
+    response_entry_count = (uint16_t)(total_entries - start_index);
+    if (response_entry_count > requested_count)
+        response_entry_count = requested_count;
+    
+    uint8_t response_header[3] = {
+        RCVR_ACK,
+        (uint8_t)(response_entry_count & 0xFF),
+        (uint8_t)((response_entry_count >> 8) & 0xFF)
+    };
+
+    rc = eos_hal_uart_send(response_header, sizeof(response_header));
+    if (rc != EOS_OK)
+        return rc;
 
-    eos_boot_log_append(EOS_LOG_FACTORY_RESET, EOS_SLOT_NONE, 0);
-    return recovery_send_ack();
+    return eos_hal_uart_send(
+        &boot_log_entries[start_index],
+        response_entry_count * sizeof(boot_log_entries[0])
+    );
 }
 
 int eos_recovery_enter(eos_bootctl_t *bctl)
@@ -415,6 +499,10 @@ int eos_recovery_enter(eos_bootctl_t *bctl)
             recovery_handle_factory_reset(bctl);
             break;
 
+        case RCVR_CMD_LOG:
+            recovery_handle_boot_log(pkt.offset, pkt.len);
+            break;
+
         default:
             recovery_send_nack();
             break;

docs/installation_usage.md

@@ -155,14 +155,20 @@ void main(void) {
 ### Step 5: Pack and sign firmware image
 
 ```bash
+# Install Python tool dependencies
+python3 -m pip install -r requirements.txt
+
 # Pack firmware with eboot image header
 python tools/imgpack.py firmware.bin --output firmware.packed.bin
 
 # Sign the image
 python tools/sign_image.py firmware.packed.bin --key signing_key.pem
 
-# Flash to board
-python tools/uart_recovery.py --port /dev/ttyUSB0 firmware.packed.bin
+# Set the recovery shared secret used by the UART tool
+export EBOOT_RECOVERY_SECRET_HEX=<64-hex-char-secret>
+
+# Upload the image to slot B over UART recovery
+python tools/uart_recovery.py --port /dev/ttyUSB0 upload --slot B --image firmware.packed.bin
 ```
 
 ### Step 6: Confirm boot (in your app)

requirements.txt

@@ -1 +1,3 @@
 pyyaml>=6.0
+pytest>=9.0
+pyserial>=3.5

run_all_tests.py

@@ -12,10 +12,23 @@
 
 def run_tests():
     print("=== Running all production-ready tests via pytest ===")
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "pytest", 
+            "tests/unit", 
+            "tests/functional", 
+            "tests/performance", 
+            "tests/simulation", 
+            "-v"
+        ], 
+        capture_output=False
+    )
+    sys.exit(result.returncode)
     command = [sys.executable, "-m", "pytest", *TEST_PATHS, "-v"]
     result = subprocess.run(command, capture_output=False)
     return result.returncode
-
-
+  
 if __name__ == "__main__":
     raise SystemExit(run_tests())

tests/unit/test_uart_recovery.py

@@ -0,0 +1,102 @@
+import hashlib
+import importlib.util
+import struct
+import sys
+import types
+import uuid
+from pathlib import Path
+
+
+UART_RECOVERY_PATH = Path(__file__).resolve().parents[2] / "tools" / "uart_recovery.py"
+
+
+class FakeSerial:
+    def __init__(self, incoming=b""):
+        self.incoming = bytearray(incoming)
+        self.writes = []
+        self.closed = False
+
+    def read(self, size):
+        chunk = bytes(self.incoming[:size])
+        del self.incoming[:size]
+        return chunk
+
+    def write(self, data):
+        self.writes.append(bytes(data))
+        return len(data)
+
+    def close(self):
+        self.closed = True
+
+
+def load_uart_recovery_module(monkeypatch, fake_serial):
+    serial_module = types.ModuleType("serial")
+    serial_module.Serial = lambda *args, **kwargs: fake_serial
+    monkeypatch.setitem(sys.modules, "serial", serial_module)
+
+    module_name = f"uart_recovery_test_{uuid.uuid4().hex}"
+    spec = importlib.util.spec_from_file_location(module_name, UART_RECOVERY_PATH)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    monkeypatch.setattr(module.time, "sleep", lambda _: None)
+    return module
+
+
+def test_auth_success_sends_expected_digest(monkeypatch):
+    secret = bytes(range(32))
+    challenge = bytes(range(32, 64))
+    fake_serial = FakeSerial(bytes([0xAA]) + challenge + bytes([0xAA]))
+    uart_recovery = load_uart_recovery_module(monkeypatch, fake_serial)
+
+    client = uart_recovery.RecoveryClient("dummy-port")
+
+    assert client.authenticate(secret.hex()) is True
+    assert fake_serial.writes[0] == struct.pack(
+        "<BBHI", uart_recovery.CMD_AUTH, 0, 0, 0
+    )
+    assert fake_serial.writes[1] == hashlib.sha256(challenge + secret).digest()
+
+
+def test_auth_rejects_invalid_secret_length(monkeypatch, capsys):
+    fake_serial = FakeSerial()
+    uart_recovery = load_uart_recovery_module(monkeypatch, fake_serial)
+
+    client = uart_recovery.RecoveryClient("dummy-port")
+
+    assert client.authenticate("00") is False
+    assert fake_serial.writes == []
+    assert "exactly 32 bytes" in capsys.readouterr().out
+
+
+def test_log_decodes_readable_entries(monkeypatch, capsys):
+    payload = b"".join(
+        [
+            struct.pack("<IIII", 100, 0x01, 0, 0),
+            struct.pack("<IIII", 200, 0x21, 0xFF, 3),
+        ]
+    )
+    header = bytes([0xAA]) + struct.pack("<H", 2)
+    fake_serial = FakeSerial(header + payload)
+    uart_recovery = load_uart_recovery_module(monkeypatch, fake_serial)
+
+    client = uart_recovery.RecoveryClient("dummy-port")
+
+    assert client.read_boot_log(0, 2) is True
+    output = capsys.readouterr().out
+    assert "BOOT_START" in output
+    assert "AUTH_FAIL" in output
+    assert "slot=A" in output
+    assert "slot=NONE" in output
+
+
+def test_log_rejects_incomplete_payload(monkeypatch, capsys):
+    payload = struct.pack("<IIII", 100, 0x01, 0, 0)
+    header = bytes([0xAA]) + struct.pack("<H", 2)
+    fake_serial = FakeSerial(header + payload)
+    uart_recovery = load_uart_recovery_module(monkeypatch, fake_serial)
+
+    client = uart_recovery.RecoveryClient("dummy-port")
+
+    assert client.read_boot_log(0, 2) is False
+    assert "Incomplete log response" in capsys.readouterr().out