[crypto/aes] Cleanup on failures

siemen11 · siemen11 · commit a4f7dbe7f4ca · 2026-05-23T17:15:57.000+02:00
Use the cleanup attribute in order to attach a guard to cleanup the hardware.
These functions are called when the variables go out of scope.
Hence, we clear the hardware on both the succesful execution (as it was before) and on bad status
output (which is new).

Apply this new setting to the AES, CMAC, and GCM where we split the driver to no longer
clean the HW when calling aes_end. Instead, we always call it from impl
(and users using the drivers still can manually call the clean in
drivers).

Signed-off-by: Siemen Dhooghe &lt;sdhooghe@google.com&gt;
diff --git a/sw/device/lib/crypto/drivers/aes.c b/sw/device/lib/crypto/drivers/aes.c
@@ -343,6 +343,10 @@ status_t aes_end(aes_block_t *iv) {
     HARDENED_CHECK_EQ(i, ARRAYSIZE(iv->data));
   }
 
+  return spin_until(AES_STATUS_IDLE_BIT);
+}
+
+status_t aes_clear(void) {
   uint32_t trigger_reg = 0;
   trigger_reg = bitfield_bit32_write(
       trigger_reg, AES_TRIGGER_KEY_IV_DATA_IN_CLEAR_BIT, true);
diff --git a/sw/device/lib/crypto/drivers/aes.h b/sw/device/lib/crypto/drivers/aes.h
@@ -173,6 +173,14 @@ status_t aes_update(aes_block_t *dest, const aes_block_t *src);
 OT_WARN_UNUSED_RESULT
 status_t aes_end(aes_block_t *iv);
 
+/**
+ * Clears the AES hardware data registers and triggers.
+ *
+ * @return The result of the operation.
+ */
+OT_WARN_UNUSED_RESULT
+status_t aes_clear(void);
+
 /**
  * Compute the checksum of an AES key.
  *
diff --git a/sw/device/lib/crypto/impl/aes.c b/sw/device/lib/crypto/impl/aes.c
@@ -279,6 +279,14 @@ otcrypto_status_t otcrypto_aes_padded_plaintext_length(
   return OTCRYPTO_OK;
 }
 
+/**
+ * Hardware cleanup guard.
+ */
+static void hw_wipe_guard(uint32_t *dummy) {
+  (void)aes_clear();
+  (void)keymgr_sideload_clear_aes();
+}
+
 /**
  * Performs the AES operation.
  *
@@ -297,6 +305,9 @@ static otcrypto_status_t otcrypto_aes_impl(
     otcrypto_aes_mode_t aes_mode, otcrypto_aes_operation_t aes_operation,
     const otcrypto_const_byte_buf_t *cipher_input,
     otcrypto_aes_padding_t aes_padding, otcrypto_byte_buf_t *cipher_output) {
+  // Guarantees hw_wipe_guard() is called on exit.
+  uint32_t hw_cleanup_guard __attribute__((cleanup(hw_wipe_guard))) = 1;
+
   // Calculate the number of blocks for the input, including the padding for
   // encryption.
   size_t input_nblocks;
@@ -450,8 +461,7 @@ static otcrypto_status_t otcrypto_aes_impl(
     HARDENED_TRY(hardened_memcpy(iv->data, aes_iv.data, kAesBlockNumWords));
   }
 
-  // In case the key was sideloaded, clear it.
-  return otcrypto_eval_exit(keymgr_sideload_clear_aes());
+  return otcrypto_eval_exit(OTCRYPTO_OK);
 }
 
 otcrypto_status_t otcrypto_aes_padding_strip(
diff --git a/sw/device/lib/crypto/impl/aes_gcm.c b/sw/device/lib/crypto/impl/aes_gcm.c
@@ -42,6 +42,20 @@ enum {
   kAesGcmContextNumWords = sizeof(aes_gcm_context_t) / sizeof(uint32_t),
 };
 
+/**
+ * AES cleanup guard.
+ */
+static void aes_wipe_guard(uint32_t *dummy) { (void)aes_clear(); }
+
+/**
+ * Sideload cleanup guard.
+ */
+static void sideload_wipe_guard(hardened_bool_t *is_sideloaded) {
+  if (*is_sideloaded == kHardenedBoolTrue) {
+    (void)keymgr_sideload_clear_aes();
+  }
+}
+
 /**
  * Save an AES-GCM context.
  *
@@ -252,30 +266,6 @@ static status_t load_key_if_sideloaded(const aes_key_t key) {
   return keymgr_generate_key_aes(diversification);
 }
 
-/**
- * Clear the sideload slot if the AES key was sideloaded.
- *
- * It is important to clear the sideload slot before returning to the caller so
- * that other applications can't access the key in between operations.
- *
- * If the key is not a sideloaded key, this function does nothing.
- *
- * @param key Key that was possibly loaded.
- * @return OK or errror.
- */
-static status_t clear_key_if_sideloaded(const aes_key_t key) {
-  if (launder32(key.sideload) == kHardenedBoolFalse) {
-    HARDENED_CHECK_EQ(key.sideload, launder32(kHardenedBoolFalse));
-    return OTCRYPTO_OK;
-  } else if (launder32(key.sideload) != kHardenedBoolTrue) {
-    // COVERAGE (SW ERR) This is an internal function, the aes key's sideload is
-    // set internal by good parameters.
-    return OTCRYPTO_BAD_ARGS;
-  }
-  HARDENED_CHECK_EQ(key.sideload, launder32(kHardenedBoolTrue));
-  return keymgr_sideload_clear_aes();
-}
-
 otcrypto_status_t otcrypto_aes_gcm_encrypt(
     otcrypto_blinded_key_t *key, const otcrypto_const_byte_buf_t *plaintext,
     const otcrypto_const_word32_buf_t *iv, const otcrypto_const_byte_buf_t *aad,
@@ -300,6 +290,11 @@ otcrypto_status_t otcrypto_aes_gcm_encrypt(
   }
 #endif
 
+  // LIFO Cleanup: aes_clear() executes before sideload_clear().
+  hardened_bool_t is_sideloaded __attribute__((cleanup(sideload_wipe_guard))) =
+      kHardenedBoolFalse;
+  uint32_t hw_cleanup_guard __attribute__((cleanup(aes_wipe_guard))) = 1;
+
   // Ensure the plaintext and ciphertext lengths match.
   if (launder32(ciphertext->len) != plaintext->len) {
     return OTCRYPTO_BAD_ARGS;
@@ -315,6 +310,9 @@ otcrypto_status_t otcrypto_aes_gcm_encrypt(
   // Construct the AES key.
   aes_key_t aes_key;
   HARDENED_TRY(aes_gcm_key_construct(key, &aes_key));
+  if (launder32(aes_key.sideload) == kHardenedBoolTrue) {
+    is_sideloaded = kHardenedBoolTrue;
+  }
   HARDENED_TRY(load_key_if_sideloaded(aes_key));
 
   // Call the core encryption operation.
@@ -323,8 +321,6 @@ otcrypto_status_t otcrypto_aes_gcm_encrypt(
                                auth_tag->len, key->config.security_level,
                                auth_tag->data, ciphertext->data));
 
-  HARDENED_TRY(clear_key_if_sideloaded(aes_key));
-
   // Verify the input buffers
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(plaintext));
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(iv));
@@ -359,9 +355,16 @@ otcrypto_status_t otcrypto_aes_gcm_decrypt(
   }
 #endif
 
+  hardened_bool_t is_sideloaded __attribute__((cleanup(sideload_wipe_guard))) =
+      kHardenedBoolFalse;
+  uint32_t hw_cleanup_guard __attribute__((cleanup(aes_wipe_guard))) = 1;
+
   // Construct the AES key.
   aes_key_t aes_key;
   HARDENED_TRY(aes_gcm_key_construct(key, &aes_key));
+  if (launder32(aes_key.sideload) == kHardenedBoolTrue) {
+    is_sideloaded = kHardenedBoolTrue;
+  }
   HARDENED_TRY(load_key_if_sideloaded(aes_key));
 
   // Ensure the plaintext and ciphertext lengths match.
@@ -379,8 +382,6 @@ otcrypto_status_t otcrypto_aes_gcm_decrypt(
                                auth_tag->len, auth_tag->data, plaintext->data,
                                key->config.security_level, success));
 
-  HARDENED_TRY(clear_key_if_sideloaded(aes_key));
-
   // Verify the input buffers
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(plaintext));
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(iv));
@@ -401,19 +402,25 @@ otcrypto_status_t otcrypto_aes_gcm_encrypt_init(
   }
 #endif
 
+  hardened_bool_t is_sideloaded __attribute__((cleanup(sideload_wipe_guard))) =
+      kHardenedBoolFalse;
+  uint32_t hw_cleanup_guard __attribute__((cleanup(aes_wipe_guard))) = 1;
+
   // Construct the AES key.
   aes_key_t aes_key;
   HARDENED_TRY(aes_gcm_key_construct(key, &aes_key));
+  if (launder32(aes_key.sideload) == kHardenedBoolTrue) {
+    is_sideloaded = kHardenedBoolTrue;
+  }
   HARDENED_TRY(load_key_if_sideloaded(aes_key));
 
   // Call the internal init operation.
   aes_gcm_context_t internal_ctx;
   internal_ctx.security_level = key->config.security_level;
   HARDENED_TRY(aes_gcm_encrypt_init(aes_key, iv->len, iv->data, &internal_ctx));
 
-  // Save the context and clear the key if needed.
+  // Save the context.
   HARDENED_TRY(gcm_context_save(&internal_ctx, ctx));
-  HARDENED_TRY(clear_key_if_sideloaded(internal_ctx.key));
 
   // Verify the input buffer
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(iv));
@@ -431,19 +438,25 @@ otcrypto_status_t otcrypto_aes_gcm_decrypt_init(
   }
 #endif
 
+  hardened_bool_t is_sideloaded __attribute__((cleanup(sideload_wipe_guard))) =
+      kHardenedBoolFalse;
+  uint32_t hw_cleanup_guard __attribute__((cleanup(aes_wipe_guard))) = 1;
+
   // Construct the AES key.
   aes_key_t aes_key;
   HARDENED_TRY(aes_gcm_key_construct(key, &aes_key));
+  if (launder32(aes_key.sideload) == kHardenedBoolTrue) {
+    is_sideloaded = kHardenedBoolTrue;
+  }
   HARDENED_TRY(load_key_if_sideloaded(aes_key));
 
   // Call the internal init operation.
   aes_gcm_context_t internal_ctx;
   internal_ctx.security_level = key->config.security_level;
   HARDENED_TRY(aes_gcm_decrypt_init(aes_key, iv->len, iv->data, &internal_ctx));
 
-  // Save the context and clear the key if needed.
+  // Save the context.
   HARDENED_TRY(gcm_context_save(&internal_ctx, ctx));
-  HARDENED_TRY(clear_key_if_sideloaded(internal_ctx.key));
 
   // Verify the input buffer
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(iv));
@@ -465,17 +478,23 @@ otcrypto_status_t otcrypto_aes_gcm_update_aad(
     return OTCRYPTO_OK;
   }
 
+  hardened_bool_t is_sideloaded __attribute__((cleanup(sideload_wipe_guard))) =
+      kHardenedBoolFalse;
+  uint32_t hw_cleanup_guard __attribute__((cleanup(aes_wipe_guard))) = 1;
+
   // Restore the AES-GCM context object and load the key if needed.
   aes_gcm_context_t internal_ctx;
   HARDENED_TRY(gcm_context_restore(ctx, &internal_ctx));
+  if (launder32(internal_ctx.key.sideload) == kHardenedBoolTrue) {
+    is_sideloaded = kHardenedBoolTrue;
+  }
   HARDENED_TRY(load_key_if_sideloaded(internal_ctx.key));
 
   // Call the internal update operation.
   HARDENED_TRY(aes_gcm_update_aad(&internal_ctx, aad->len, aad->data));
 
-  // Save the context and clear the key if needed.
+  // Save the context.
   HARDENED_TRY(gcm_context_save(&internal_ctx, ctx));
-  HARDENED_TRY(clear_key_if_sideloaded(internal_ctx.key));
 
   // Verify the input buffer
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(aad));
@@ -500,9 +519,16 @@ otcrypto_status_t otcrypto_aes_gcm_update_encrypted_data(
     return OTCRYPTO_OK;
   }
 
+  hardened_bool_t is_sideloaded __attribute__((cleanup(sideload_wipe_guard))) =
+      kHardenedBoolFalse;
+  uint32_t hw_cleanup_guard __attribute__((cleanup(aes_wipe_guard))) = 1;
+
   // Restore the AES-GCM context object and load the key if needed.
   aes_gcm_context_t internal_ctx;
   HARDENED_TRY(gcm_context_restore(ctx, &internal_ctx));
+  if (launder32(internal_ctx.key.sideload) == kHardenedBoolTrue) {
+    is_sideloaded = kHardenedBoolTrue;
+  }
   HARDENED_TRY(load_key_if_sideloaded(internal_ctx.key));
   // Remask the key if it is not sideloaded.
   HARDENED_TRY(gcm_remask_key(&internal_ctx));
@@ -526,9 +552,8 @@ otcrypto_status_t otcrypto_aes_gcm_update_encrypted_data(
                                              input->data, output_bytes_written,
                                              output->data));
 
-  // Save the context and clear the key if needed.
+  // Save the context.
   HARDENED_TRY(gcm_context_save(&internal_ctx, ctx));
-  HARDENED_TRY(clear_key_if_sideloaded(internal_ctx.key));
 
   // Verify the input buffers
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(input));
@@ -559,9 +584,16 @@ otcrypto_status_t otcrypto_aes_gcm_encrypt_final(
   // Randomize the tag before the operation.
   HARDENED_TRY(hardened_memshred(auth_tag->data, auth_tag->len));
 
+  hardened_bool_t is_sideloaded __attribute__((cleanup(sideload_wipe_guard))) =
+      kHardenedBoolFalse;
+  uint32_t hw_cleanup_guard __attribute__((cleanup(aes_wipe_guard))) = 1;
+
   // Restore the AES-GCM context object and load the key if needed.
   aes_gcm_context_t internal_ctx;
   HARDENED_TRY(gcm_context_restore(ctx, &internal_ctx));
+  if (launder32(internal_ctx.key.sideload) == kHardenedBoolTrue) {
+    is_sideloaded = kHardenedBoolTrue;
+  }
   HARDENED_TRY(load_key_if_sideloaded(internal_ctx.key));
   // Remask the key if it is not sideloaded.
   HARDENED_TRY(gcm_remask_key(&internal_ctx));
@@ -578,9 +610,8 @@ otcrypto_status_t otcrypto_aes_gcm_encrypt_final(
                                      auth_tag->data, ciphertext_bytes_written,
                                      ciphertext->data));
 
-  // Clear the context and the key if needed.
+  // Clear the context.
   HARDENED_TRY(hardened_memshred(ctx->data, ARRAYSIZE(ctx->data)));
-  HARDENED_TRY(clear_key_if_sideloaded(internal_ctx.key));
 
   // Verify the input buffers
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(ciphertext));
@@ -609,9 +640,16 @@ otcrypto_status_t otcrypto_aes_gcm_decrypt_final(
   // Check the tag length.
   HARDENED_TRY(aes_gcm_check_tag_length(auth_tag->len, tag_len));
 
+  hardened_bool_t is_sideloaded __attribute__((cleanup(sideload_wipe_guard))) =
+      kHardenedBoolFalse;
+  uint32_t hw_cleanup_guard __attribute__((cleanup(aes_wipe_guard))) = 1;
+
   // Restore the AES-GCM context object and load the key if needed.
   aes_gcm_context_t internal_ctx;
   HARDENED_TRY(gcm_context_restore(ctx, &internal_ctx));
+  if (launder32(internal_ctx.key.sideload) == kHardenedBoolTrue) {
+    is_sideloaded = kHardenedBoolTrue;
+  }
   HARDENED_TRY(load_key_if_sideloaded(internal_ctx.key));
   // Remask the key if it is not sideloaded.
   HARDENED_TRY(gcm_remask_key(&internal_ctx));
@@ -628,9 +666,8 @@ otcrypto_status_t otcrypto_aes_gcm_decrypt_final(
                                      auth_tag->data, plaintext_bytes_written,
                                      plaintext->data, success));
 
-  // Clear the context and the key if needed.
+  // Clear the context.
   HARDENED_TRY(hardened_memshred(ctx->data, ARRAYSIZE(ctx->data)));
-  HARDENED_TRY(clear_key_if_sideloaded(internal_ctx.key));
 
   // Verify the input buffers
   HARDENED_CHECK_EQ(kHardenedBoolTrue, OTCRYPTO_CHECK_BUF(auth_tag));
diff --git a/sw/device/lib/crypto/impl/cmac.c b/sw/device/lib/crypto/impl/cmac.c
