[otbn] Add compression option

Use LZ4 to add a compression option in otbn_binary (activated by setting
compress = True). If this is set, the imem and dmem of the otbn
application are compressed before they are stored.
By default, binaries are not compressed.

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 compression option is therefore mandatory in the cryptolib
(lib/crypto), however, the applications from silicon_creator (using
silicon_creator/lib/drivers/otbn.c/h) still use the uncompressed version
(and will not work with the compressed version).

This option saves the cryptolib ~7000bytes 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

rules/otbn.bzl

@@ -91,6 +91,20 @@ def _otbn_binary(ctx, additional_srcs = []):
 
     deps = [f for dep in ctx.attr.deps for f in dep.files.to_list()]
 
+    script_args = [
+        "--app-name={}".format(ctx.attr.name),
+        "--archive",
+        "--no-assembler",
+        "--out-dir={}".format(elf.dirname),
+    ]
+
+    # Add the compress flag if the BUILD file requested it
+    if getattr(ctx.attr, "compress", False):
+        script_args.append("--compress")
+
+    # Add the input files
+    script_args += [o.path for o in ([obj] + deps)]
+
     # Run the otbn_build.py script to link object files from the sources and
     # dependencies.
     ctx.actions.run(
@@ -106,12 +120,7 @@ def _otbn_binary(ctx, additional_srcs = []):
             "RV32_TOOL_LD": ctx.executable._riscv32_ld.path,
             "RV32_TOOL_OBJCOPY": ctx.executable._riscv32_objcopy.path,
         },
-        arguments = [
-            "--app-name={}".format(ctx.attr.name),
-            "--archive",
-            "--no-assembler",
-            "--out-dir={}".format(elf.dirname),
-        ] + [o.path for o in ([obj] + deps)],
+        arguments = script_args,
         executable = ctx.executable._wrapper,
     )
 
@@ -375,6 +384,7 @@ otbn_binary = rv_rule(
         "srcs": attr.label_list(allow_files = True),
         "deps": attr.label_list(providers = [DefaultInfo]),
         "args": attr.string_list(),
+        "compress": attr.bool(default = False),
         "_riscv32_ar": attr.label(
             default = Label("@lowrisc_rv32imcb_toolchain//:bin/riscv32-unknown-elf-ar"),
             allow_single_file = True,

sw/device/lib/crypto/drivers/BUILD

@@ -387,6 +387,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: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"
@@ -283,79 +284,114 @@ 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;
 }
 
 status_t otbn_load_app(const otbn_app_t app) {
   HARDENED_TRY(check_app_address_ranges(&app));
 
+  // Ensure that the total uncompressed IMEM section fits in IMEM.
+  // IMEM always starts at offset 0.
+  HARDENED_TRY(
+      check_offset_len(0, app.imem_uncompressed_words, kOtbnIMemSizeBytes));
+
+  // Ensure that the total uncompressed data section fits in DMEM.
+  HARDENED_TRY(check_offset_len(app.dmem_data_start_addr,
+                                app.dmem_uncompressed_words,
+                                kOtbnDMemSizeBytes));
+
   // Ensure OTBN is idle.
   HARDENED_TRY(otbn_assert_idle());
 
-  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);
-
   HARDENED_TRY(otbn_imem_sec_wipe());
   HARDENED_TRY(otbn_dmem_sec_wipe());
 
   // Reset the LOAD_CHECKSUM register.
   abs_mmio_write32(kBase + OTBN_LOAD_CHECKSUM_REG_OFFSET, 0);
 
-  // Ensure that the IMEM section fits in IMEM and the data section fits in
-  // DMEM.
-  HARDENED_TRY(check_offset_len(app.dmem_data_start_addr, data_num_words,
-                                kOtbnDMemSizeBytes));
-
-  // Write to IMEM. Always starts at zero on the OTBN side.
-  otbn_addr_t imem_offset = 0;
-  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]);
+  // A 256-byte stack buffer for chunked decompression.
+  uint32_t local_chunk_buf[256 / sizeof(uint32_t)];
+
+  // IMEM decompression and loading
+  const uint8_t *src = app.imem_compressed_start;
+  uint32_t mmio_addr = kBase + OTBN_IMEM_REG_OFFSET;
+
+  while (src < app.imem_compressed_end) {
+    // 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 (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 to IMEM. Always starts at zero on the OTBN side.
+    uint32_t words = uncomp_len / (uint32_t)sizeof(uint32_t);
+    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;
   }
-  HARDENED_CHECK_EQ(i, imem_num_words);
 
-  // Write the data portion to DMEM.
-  otbn_addr_t data_offset = app.dmem_data_start_addr;
-  HARDENED_TRY(
-      check_offset_len(data_offset, data_num_words, kOtbnDMemSizeBytes));
-  uint32_t data_start_addr = kBase + OTBN_DMEM_REG_OFFSET + data_offset;
-  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]);
+  // DMEM decompression and loading
+  src = app.dmem_compressed_start;
+  mmio_addr = kBase + OTBN_DMEM_REG_OFFSET + app.dmem_data_start_addr;
+
+  while (src < app.dmem_compressed_end) {
+    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 (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 data portion to DMEM.
+    uint32_t words = uncomp_len / (uint32_t)sizeof(uint32_t);
+    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;
   }
-  HARDENED_CHECK_EQ(i, data_num_words);
 
   // Ensure that the checksum matches expectations.
   uint32_t checksum = abs_mmio_read32(kBase + OTBN_LOAD_CHECKSUM_REG_OFFSET);

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),                     \
   })
 
 /**