[otbn] Add compression option

Use LZ4 to create a compressed OTBN binary (both imem and dmem). The OTBN build script
creates both the uncompressed and compressed binary relying on garbage
collection to filter out the unused binary.

Change the otbn.c and otbn.h in the cryptolib to use LZ4 from lib/base
in order to decompress the loaded imem and dmem from an application.

The cryptolib (lib/crypto) uses the compressed binaries, however, the applications from silicon_creator (using
silicon_creator/lib/drivers/otbn.c/h) still use the uncompressed version.

This option saves the cryptolib ~5400bytes while increasing ~400bytes to
load LZ4.c while providing backwards compatability for the boot.

Concerning the CRC: The CRC for the imem/dmem is calculated before
compression. For loading to OTBN, the OTBN is given the CRC of the
uncompressed payload before and checks itself the CRC of what it
receives. I.e., the CRC still provides end-2-end protection.

Signed-off-by: Siemen Dhooghe <sdhooghe@google.com>

Author: siemen11

sw/device/lib/crypto/drivers/BUILD

@@ -373,6 +373,7 @@ cc_library(
         "//sw/device/lib/base:bitfield",
         "//sw/device/lib/base:crc32",
         "//sw/device/lib/base:hardened",
+        "//sw/device/lib/base:lz4",
         "//sw/device/lib/base:random_order",
         "//sw/device/lib/crypto/impl:state",
         "//sw/device/lib/crypto/impl:status",

sw/device/lib/crypto/drivers/otbn.c

@@ -8,6 +8,7 @@
 #include "sw/device/lib/base/bitfield.h"
 #include "sw/device/lib/base/crc32.h"
 #include "sw/device/lib/base/hardened.h"
+#include "sw/device/lib/base/lz4.h"
 #include "sw/device/lib/base/macros.h"
 #include "sw/device/lib/base/random_order.h"
 #include "sw/device/lib/base/status.h"
@@ -291,30 +292,98 @@ status_t otbn_set_ctrl_software_errs_fatal(bool enable) {
 }
 
 /**
- * Checks if the OTBN application's IMEM and DMEM address parameters are valid.
+ * Checks if the OTBN application's compressed IMEM and DMEM address parameters
+ * are valid.
  *
  * This function checks the following properties:
- * - IMEM and DMEM ranges must not be "backwards" in memory, with the end
- * address coming before the start address.
- * - The IMEM range must be non-empty.
+ * - IMEM and DMEM compressed pointer ranges must not be "backwards" in memory.
+ * - The uncompressed IMEM range must be non-empty.
  *
  * @param app the OTBN application to check
  * @return `OTCRYPTO_OK` if checks pass, otherwise `OTCRYPTO_BAD_ARGS`.
  */
 static status_t check_app_address_ranges(const otbn_app_t *app) {
-  // IMEM must not be backwards or empty.
-  if (app->imem_end <= app->imem_start) {
+  // Compressed IMEM must not be backwards, and uncompressed size must not
+  // be empty.
+  if (app->imem_compressed_end <= app->imem_compressed_start ||
+      app->imem_uncompressed_words == 0) {
     // COVERAGE (SW ERR) This is an internal function, we only provide it valid
     // inputs.
     return OTCRYPTO_BAD_ARGS;
   }
-  HARDENED_CHECK_LT(app->imem_start, app->imem_end);
+  HARDENED_CHECK_LT((uintptr_t)app->imem_compressed_start,
+                    (uintptr_t)app->imem_compressed_end);
+  HARDENED_CHECK_GT(app->imem_uncompressed_words, 0);
 
-  // DMEM data section must not be backwards.
-  if (app->dmem_data_end < app->dmem_data_start) {
+  // Compressed DMEM must not be backwards.
+  if (app->dmem_compressed_end < app->dmem_compressed_start) {
     return OTCRYPTO_BAD_ARGS;
   }
-  HARDENED_CHECK_LE(app->dmem_data_start, app->dmem_data_end);
+  HARDENED_CHECK_LE((uintptr_t)app->dmem_compressed_start,
+                    (uintptr_t)app->dmem_compressed_end);
+
+  return OTCRYPTO_OK;
+}
+
+/**
+ * Decompresses an LZ4-compressed payload and writes it to an OTBN address.
+ *
+ * @param src Start of the compressed payload.
+ * @param src_end End of the compressed payload.
+ * @param mmio_addr Destination MMIO address in OTBN memory.
+ * @param expected_words Expected uncompressed size in 32-bit words.
+ * @return `OTCRYPTO_OK` if successful, otherwise `OTCRYPTO_FATAL_ERR`.
+ */
+static status_t decompress_load(const uint8_t *src, const uint8_t *src_end,
+                                uint32_t mmio_addr, size_t expected_words) {
+  // A 1024-byte stack buffer (256 32-bit words) for chunked
+  // decompression.
+  uint32_t local_chunk_buf[1024 / sizeof(uint32_t)];
+
+  uint32_t words_written = 0;
+
+  while (src < src_end) {
+    // Check the header size
+    if ((size_t)(src_end - src) < 4) {
+      return OTCRYPTO_FATAL_ERR;
+    }
+    // Parse the 4-byte chunk header as unsigned 32-bit integers
+    uint32_t comp_len = (uint32_t)(src[0] | (src[1] << 8));
+    uint32_t uncomp_len = (uint32_t)(src[2] | (src[3] << 8));
+    src += 4;
+
+    if (comp_len > (size_t)(src_end - src)) {
+      return OTCRYPTO_FATAL_ERR;
+    }
+
+    if (uncomp_len % sizeof(uint32_t) != 0) {
+      return OTCRYPTO_FATAL_ERR;
+    }
+
+    if (LZ4_decompress((const char *)src, (char *)local_chunk_buf,
+                       (int)comp_len,
+                       (int)sizeof(local_chunk_buf)) != (int)uncomp_len) {
+      return OTCRYPTO_FATAL_ERR;
+    }
+
+    // Write the decompressed data portion to OTBN memory.
+    uint32_t words = uncomp_len / (uint32_t)sizeof(uint32_t);
+    if (words > expected_words - words_written) {
+      return OTCRYPTO_FATAL_ERR;
+    }
+
+    for (uint32_t i = 0; launder32(i) < words; i++) {
+      abs_mmio_write32(mmio_addr + i * sizeof(uint32_t), local_chunk_buf[i]);
+    }
+
+    src += comp_len;
+    mmio_addr += uncomp_len;
+    words_written += words;
+  }
+
+  if (words_written != expected_words) {
+    return OTCRYPTO_FATAL_ERR;
+  }
 
   return OTCRYPTO_OK;
 }
@@ -329,15 +398,16 @@ status_t otbn_load_app(const otbn_app_t app) {
   hardened_bool_t skip_imem = kHardenedBoolFalse;
   // Check whether the state is present and use it if so
   if (status_ok(read_state_pointer(&state)) && state != NULL) {
-    if (launder32(state->imem_cache) == (uint32_t)(uintptr_t)app.imem_start) {
-      HARDENED_CHECK_EQ(state->imem_cache, (uint32_t)(uintptr_t)app.imem_start);
+    if (launder32(state->imem_cache) ==
+        (uint32_t)(uintptr_t)app.imem_compressed_start) {
+      HARDENED_CHECK_EQ(state->imem_cache,
+                        (uint32_t)(uintptr_t)app.imem_compressed_start);
       skip_imem = kHardenedBoolTrue;
     }
   }
 
-  const size_t imem_num_words = (size_t)(app.imem_end - app.imem_start);
-  const size_t data_num_words =
-      (size_t)(app.dmem_data_end - app.dmem_data_start);
+  const size_t imem_num_words = app.imem_uncompressed_words;
+  const size_t data_num_words = app.dmem_uncompressed_words;
 
   if (launder32(skip_imem) != kHardenedBoolTrue) {
     HARDENED_TRY(otbn_imem_sec_wipe());
@@ -358,13 +428,9 @@ status_t otbn_load_app(const otbn_app_t app) {
     HARDENED_TRY(
         check_offset_len(imem_offset, imem_num_words, kOtbnIMemSizeBytes));
     uint32_t imem_start_addr = kBase + OTBN_IMEM_REG_OFFSET + imem_offset;
-    uint32_t i = 0;
-    for (; launder32(i) < imem_num_words; i++) {
-      HARDENED_CHECK_LT(i, imem_num_words);
-      abs_mmio_write32(imem_start_addr + i * sizeof(uint32_t),
-                       app.imem_start[i]);
-    }
-    HARDENED_CHECK_EQ(i, imem_num_words);
+    HARDENED_TRY(decompress_load(app.imem_compressed_start,
+                                 app.imem_compressed_end, imem_start_addr,
+                                 imem_num_words));
   } else {
     HARDENED_CHECK_EQ(skip_imem, kHardenedBoolTrue);
   }
@@ -374,13 +440,9 @@ status_t otbn_load_app(const otbn_app_t app) {
   HARDENED_TRY(
       check_offset_len(data_offset, data_num_words, kOtbnDMemSizeBytes));
   uint32_t data_start_addr = kBase + OTBN_DMEM_REG_OFFSET + data_offset;
-  uint32_t i = 0;
-  for (; launder32(i) < data_num_words; i++) {
-    HARDENED_CHECK_LT(i, data_num_words);
-    abs_mmio_write32(data_start_addr + i * sizeof(uint32_t),
-                     app.dmem_data_start[i]);
-  }
-  HARDENED_CHECK_EQ(i, data_num_words);
+  HARDENED_TRY(decompress_load(app.dmem_compressed_start,
+                               app.dmem_compressed_end, data_start_addr,
+                               data_num_words));
 
   if (launder32(skip_imem) != kHardenedBoolTrue) {
     // Ensure that the checksum matches expectations.
@@ -394,7 +456,7 @@ status_t otbn_load_app(const otbn_app_t app) {
     HARDENED_CHECK_EQ(checksum, app.checksum);
 
     if (state != NULL) {
-      state->imem_cache = (uint32_t)(uintptr_t)app.imem_start;
+      state->imem_cache = (uint32_t)(uintptr_t)app.imem_compressed_start;
     }
   } else {
     HARDENED_CHECK_EQ(skip_imem, kHardenedBoolTrue);

sw/device/lib/crypto/drivers/otbn.h

@@ -67,36 +67,52 @@ typedef uint32_t otbn_addr_t;
  */
 typedef struct otbn_app {
   /**
-   * Start of OTBN instruction memory in the embedded program.
+   * Start of the compressed OTBN instruction memory in the embedded program.
    *
    * This pointer references Ibex's memory.
    */
-  const uint32_t *imem_start;
+  const uint8_t *imem_compressed_start;
   /**
-   * The first word after OTBN instruction memory in the embedded program.
+   * The first byte after the compressed OTBN instruction memory.
    *
    * This pointer references Ibex's memory.
    *
-   * This address satifies `imem_start < imem_end`.
+   * This address satisfies `imem_compressed_start <= imem_compressed_end`.
    */
-  const uint32_t *imem_end;
+  const uint8_t *imem_compressed_end;
   /**
-   * Start of initialized OTBN data in the embedded program.
+   * The expected size of the uncompressed instruction memory, in 32-bit words.
+   *
+   * This defines exactly how many words the host CPU will write to the OTBN
+   * IMEM registers after decompressing the payload.
+   */
+  const size_t imem_uncompressed_words;
+
+  /**
+   * Start of the compressed initialized OTBN data in the embedded program.
    *
    * This pointer references Ibex's memory.
    *
-   * Data in between `dmem_data_start` and `dmem_data_end` will be copied to
-   * OTBN at app load time.
+   * Data between `dmem_compressed_start` and `dmem_compressed_end` will be
+   * decompressed and copied to OTBN at app load time.
    */
-  const uint32_t *dmem_data_start;
+  const uint8_t *dmem_compressed_start;
   /**
-   * The first word after initialized OTBN data in the embedded program.
+   * The first byte after the compressed initialized OTBN data.
    *
    * This pointer references Ibex's memory.
    *
-   * Should satisfy `dmem_data_start <= dmem_data_end`.
+   * Should satisfy `dmem_compressed_start <= dmem_compressed_end`.
    */
-  const uint32_t *dmem_data_end;
+  const uint8_t *dmem_compressed_end;
+  /**
+   * The expected size of the uncompressed initialized data, in 32-bit words.
+   *
+   * This defines exactly how many words the host CPU will write to the OTBN
+   * DMEM registers after decompressing the payload.
+   */
+  const size_t dmem_uncompressed_words;
+
   /**
    * Start of initialized data section in OTBN's DMEM.
    *
@@ -166,22 +182,25 @@ typedef struct otbn_app {
 /**
  * Makes an embedded OTBN application image available for use.
  *
- * Make symbols available that indicate the start and the end of instruction
- * and data memory regions, as they are stored in the device memory.
+ * Makes symbols available that indicate the start and the end of the compressed
+ * instruction and data memory regions, their uncompressed sizes, and the
+ * expected checksum for integrity verification.
  *
  * Use this macro instead of manually declaring the symbols as symbol names
  * might change.
  *
  * @param app_name Name of the application to load, which is typically the
  *                 name of the main (assembly) source file.
  */
-#define OTBN_DECLARE_APP_SYMBOLS(app_name)              \
-  OTBN_DECLARE_SYMBOL_PTR(app_name, _imem_start);       \
-  OTBN_DECLARE_SYMBOL_PTR(app_name, _imem_end);         \
-  OTBN_DECLARE_SYMBOL_PTR(app_name, _dmem_data_start);  \
-  OTBN_DECLARE_SYMBOL_PTR(app_name, _dmem_data_end);    \
-  OTBN_DECLARE_SYMBOL_ADDR(app_name, _dmem_data_start); \
-  OTBN_DECLARE_SYMBOL_ADDR(app_name, _checksum)
+#define OTBN_DECLARE_APP_SYMBOLS(app_name)                                 \
+  extern const uint8_t OTBN_SYMBOL_PTR(app_name, imem_compressed_start)[]; \
+  extern const uint8_t OTBN_SYMBOL_PTR(app_name, imem_compressed_end)[];   \
+  extern const uint8_t OTBN_SYMBOL_PTR(app_name, dmem_compressed_start)[]; \
+  extern const uint8_t OTBN_SYMBOL_PTR(app_name, dmem_compressed_end)[];   \
+  OTBN_DECLARE_SYMBOL_ADDR(app_name, _dmem_data_start);                    \
+  OTBN_DECLARE_SYMBOL_ADDR(app_name, _checksum);                           \
+  OTBN_DECLARE_SYMBOL_ADDR(app_name, imem_uncompressed_bytes);             \
+  OTBN_DECLARE_SYMBOL_ADDR(app_name, dmem_uncompressed_bytes)
 
 /**
  * Initializes the OTBN application information structure.
@@ -190,17 +209,27 @@ typedef struct otbn_app {
  * through `OTBN_DECLARE_APP_SYMBOLS()`, use this macro to initialize an
  * `otbn_app_t` struct with those symbols.
  *
+ * This macro automatically handles the mapping of the compressed payload
+ * pointers and converts the uncompressed byte counts provided by the linker
+ * into the 32-bit word counts expected by the OTBN loader.
+ *
  * @param app_name Name of the application to load.
  * @see OTBN_DECLARE_APP_SYMBOLS()
  */
-#define OTBN_APP_T_INIT(app_name)                                           \
-  ((otbn_app_t){                                                            \
-      .imem_start = OTBN_SYMBOL_PTR(app_name, _imem_start),                 \
-      .imem_end = OTBN_SYMBOL_PTR(app_name, _imem_end),                     \
-      .dmem_data_start = OTBN_SYMBOL_PTR(app_name, _dmem_data_start),       \
-      .dmem_data_end = OTBN_SYMBOL_PTR(app_name, _dmem_data_end),           \
-      .dmem_data_start_addr = OTBN_ADDR_T_INIT(app_name, _dmem_data_start), \
-      .checksum = OTBN_ADDR_T_INIT(app_name, _checksum),                    \
+#define OTBN_APP_T_INIT(app_name)                                            \
+  ((otbn_app_t){                                                             \
+      .imem_compressed_start =                                               \
+          OTBN_SYMBOL_PTR(app_name, imem_compressed_start),                  \
+      .imem_compressed_end = OTBN_SYMBOL_PTR(app_name, imem_compressed_end), \
+      .imem_uncompressed_words =                                             \
+          OTBN_ADDR_T_INIT(app_name, imem_uncompressed_bytes) / 4,           \
+      .dmem_compressed_start =                                               \
+          OTBN_SYMBOL_PTR(app_name, dmem_compressed_start),                  \
+      .dmem_compressed_end = OTBN_SYMBOL_PTR(app_name, dmem_compressed_end), \
+      .dmem_uncompressed_words =                                             \
+          OTBN_ADDR_T_INIT(app_name, dmem_uncompressed_bytes) / 4,           \
+      .dmem_data_start_addr = OTBN_ADDR_T_INIT(app_name, _dmem_data_start),  \
+      .checksum = OTBN_ADDR_T_INIT(app_name, _checksum),                     \
   })
 
 /**

sw/device/lib/crypto/drivers/otbn_test.c

@@ -43,16 +43,31 @@ static status_t run_negative_test(void) {
   // Test memory boundary check (offset + length exceeds memory)
   CHECK(otbn_dmem_read(0xFFFFFFFF, 0, NULL).value == OTCRYPTO_BAD_ARGS.value);
 
-  // App range check (imem_end comes before imem_start)
-  static const uint32_t kDummyMem[] = {0};
-  otbn_app_t bad_range_app = {.imem_start = kDummyMem + 1,
-                              .imem_end = kDummyMem,  // Backwards!
-                              .dmem_data_start = kDummyMem,
-                              .dmem_data_end = kDummyMem,
+  // Dummy byte array for testing invalid pointers
+  static const uint8_t kDummyMem[] = {0};
+
+  // App range check (imem_compressed_end comes before imem_compressed_start)
+  otbn_app_t bad_range_app = {.imem_compressed_start = kDummyMem + 1,
+                              .imem_compressed_end = kDummyMem,  // Backwards!
+                              .imem_uncompressed_words = 1,
+                              .dmem_compressed_start = kDummyMem,
+                              .dmem_compressed_end = kDummyMem,
+                              .dmem_uncompressed_words = 0,
                               .dmem_data_start_addr = 0,
                               .checksum = 0};
   CHECK(otbn_load_app(bad_range_app).value == OTCRYPTO_BAD_ARGS.value);
 
+  // App range check (imem uncompressed size is 0 - not allowed)
+  otbn_app_t empty_imem_app = {.imem_compressed_start = kDummyMem,
+                               .imem_compressed_end = kDummyMem + 1,
+                               .imem_uncompressed_words = 0,  // Empty!
+                               .dmem_compressed_start = kDummyMem,
+                               .dmem_compressed_end = kDummyMem,
+                               .dmem_uncompressed_words = 0,
+                               .dmem_data_start_addr = 0,
+                               .checksum = 0};
+  CHECK(otbn_load_app(empty_imem_app).value == OTCRYPTO_BAD_ARGS.value);
+
   // Force OTBN out of the IDLE state by manually triggering a Secure Wipe.
   abs_mmio_write32(TOP_EARLGREY_OTBN_BASE_ADDR + OTBN_CMD_REG_OFFSET,
                    CMD_SEC_WIPE_DMEM);
@@ -64,13 +79,21 @@ static status_t run_negative_test(void) {
   CHECK(otbn_set_ctrl_software_errs_fatal(true).value == OTCRYPTO_OK.value);
   CHECK(otbn_set_ctrl_software_errs_fatal(false).value == OTCRYPTO_OK.value);
 
-  // 6. Test bad checksum
-  otbn_app_t bad_checksum_app = {.imem_start = kDummyMem,
-                                 .imem_end = kDummyMem + 1,
-                                 .dmem_data_start = kDummyMem,
-                                 .dmem_data_end = kDummyMem + 1,
-                                 .dmem_data_start_addr = 0,
-                                 .checksum = 0xDEADBEEF};
+  // Test bad checksum
+  // We provide a tiny valid compressed block (0x40 = 4 literals, followed by
+  // four 0x00 bytes) so decompression succeeds, ensuring we actually hit the
+  // checksum verification failure.
+  static const uint8_t kValidLz4[] = {0x40, 0x00, 0x00, 0x00, 0x00};
+
+  otbn_app_t bad_checksum_app = {
+      .imem_compressed_start = kValidLz4,
+      .imem_compressed_end = kValidLz4 + sizeof(kValidLz4),
+      .imem_uncompressed_words = 1,
+      .dmem_compressed_start = kDummyMem,
+      .dmem_compressed_end = kDummyMem,
+      .dmem_uncompressed_words = 0,
+      .dmem_data_start_addr = 0,
+      .checksum = 0xDEADBEEF};
   CHECK(otbn_load_app(bad_checksum_app).value == OTCRYPTO_FATAL_ERR.value);
 
   return OTCRYPTO_OK;