[crypto] add platform hook for MAC frame AES-CCM* AEAD

suveshpratapa · suveshpratapa · commit 4319db5dd22d · 2026-06-02T12:05:43.000-04:00
Adds `OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE` and two new platform
APIs, `otPlatCryptoAesEncryptAndTag()` and `otPlatCryptoAesDecryptAndVerify()`,
allowing a hardware accelerator to perform MAC frame authenticated encryption
in place of the software `Crypto::AesCcm` engine.
diff --git a/include/openthread/instance.h b/include/openthread/instance.h
@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (602)
+#define OPENTHREAD_API_VERSION (603)
 
 /**
  * @addtogroup api-instance
diff --git a/include/openthread/platform/crypto.h b/include/openthread/platform/crypto.h
@@ -428,6 +428,61 @@ otError otPlatCryptoAesSetKey(otCryptoContext *aContext, const otCryptoKey *aKey
  */
 otError otPlatCryptoAesEncrypt(otCryptoContext *aContext, const uint8_t *aInput, uint8_t *aOutput);
 
+/**
+ * Decrypt and verify the given AES-CCM* payload.
+ *
+ * @param[in]      aContext        AES context initialised with `otPlatCryptoAesSetKey()`.
+ * @param[in]      aNonce          Nonce (13 bytes, IEEE 802.15.4 CCM* format).
+ * @param[in]      aHeader         Additional authenticated data (MAC header).
+ * @param[in]      aHeaderLength   Length of @p aHeader in bytes.
+ * @param[in,out]  aPayload        Ciphertext on input; replaced with plaintext in place on success.
+ * @param[in]      aPayloadLength  Length of @p aPayload in bytes.
+ * @param[in]      aTag            MIC buffer of length @p aTagLength bytes.
+ * @param[in]      aTagLength      MIC length in bytes (4, 8, or 16).
+ *
+ * @retval OT_ERROR_NONE          Successfully decrypted and verified @p aPayload.
+ * @retval OT_ERROR_SECURITY      MIC verification failed.
+ * @retval OT_ERROR_INVALID_ARGS  @p aContext, @p aNonce, @p aPayload, or @p aTag was NULL.
+ * @retval OT_ERROR_FAILED        Other failure.
+ *
+ * @note This API is only used by OT core when `OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE` is enabled.
+ */
+otError otPlatCryptoAesDecryptAndVerify(otCryptoContext *aContext,
+                                        const uint8_t   *aNonce,
+                                        const void      *aHeader,
+                                        uint16_t         aHeaderLength,
+                                        void            *aPayload,
+                                        uint16_t         aPayloadLength,
+                                        const void      *aTag,
+                                        uint8_t          aTagLength);
+
+/**
+ * Encrypt and tag the given AES-CCM* payload.
+ *
+ * @param[in]      aContext        AES context initialised with `otPlatCryptoAesSetKey()`.
+ * @param[in]      aNonce          Nonce (13 bytes, IEEE 802.15.4 CCM* format).
+ * @param[in]      aHeader         Additional authenticated data (MAC header).
+ * @param[in]      aHeaderLength   Length of @p aHeader in bytes.
+ * @param[in,out]  aPayload        Plaintext on input; replaced with ciphertext in place on success.
+ * @param[in]      aPayloadLength  Length of @p aPayload in bytes.
+ * @param[out]     aTag            Buffer to receive the MIC; must be at least @p aTagLength bytes.
+ * @param[in]      aTagLength      MIC length in bytes (4, 8, or 16).
+ *
+ * @retval OT_ERROR_NONE          Successfully encrypted @p aPayload and generated MIC in @p aTag.
+ * @retval OT_ERROR_INVALID_ARGS  @p aContext, @p aNonce, @p aPayload, or @p aTag was NULL.
+ * @retval OT_ERROR_FAILED        Other failure.
+ *
+ * @note This API is only used by OT core when `OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE` is enabled.
+ */
+otError otPlatCryptoAesEncryptAndTag(otCryptoContext *aContext,
+                                     const uint8_t   *aNonce,
+                                     const void      *aHeader,
+                                     uint16_t         aHeaderLength,
+                                     void            *aPayload,
+                                     uint16_t         aPayloadLength,
+                                     void            *aTag,
+                                     uint8_t          aTagLength);
+
 /**
  * Free the AES context.
  *
diff --git a/src/core/config/crypto.h b/src/core/config/crypto.h
@@ -68,6 +68,20 @@
 #define OPENTHREAD_CONFIG_CRYPTO_PLATFORM_ALLOCS_CONTEXT 0
 #endif
 
+/**
+ * @def OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE
+ *
+ * Define to 1 to enable the platform AES-CCM* hook for MAC frame security.
+ *
+ * When enabled, `ProcessTransmitAesCcm()` and `ProcessReceiveAesCcm()` call
+ * `otPlatCryptoAesEncryptAndTag()` and `otPlatCryptoAesDecryptAndVerify()` respectively,
+ * allowing a platform to offload MAC frame AEAD to a hardware accelerator.
+ * When disabled (default), the OpenThread core `Crypto::AesCcm` engine is used.
+ */
+#ifndef OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE
+#define OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE 0
+#endif
+
 #if OPENTHREAD_CONFIG_CRYPTO_LIB == OPENTHREAD_CONFIG_CRYPTO_LIB_PLATFORM
 
 /**
diff --git a/src/core/crypto/aes_ccm.cpp b/src/core/crypto/aes_ccm.cpp
@@ -297,5 +297,29 @@ void AesCcm::GenerateNonce(const Mac::ExtAddress &aAddress,
     aNonce[0] = aSecurityLevel;
 }
 
+#if OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE
+Error AesCcm::DecryptAndVerify(const uint8_t *aNonce,
+                               const void    *aHeader,
+                               uint16_t       aHeaderLength,
+                               void          *aPayload,
+                               uint16_t       aPayloadLength,
+                               const void    *aTag,
+                               uint8_t        aTagLength)
+{
+    return mEcb.DecryptAndVerify(aNonce, aHeader, aHeaderLength, aPayload, aPayloadLength, aTag, aTagLength);
+}
+
+Error AesCcm::EncryptAndTag(const uint8_t *aNonce,
+                            const void    *aHeader,
+                            uint16_t       aHeaderLength,
+                            void          *aPayload,
+                            uint16_t       aPayloadLength,
+                            void          *aTag,
+                            uint8_t        aTagLength)
+{
+    return mEcb.EncryptAndTag(aNonce, aHeader, aHeaderLength, aPayload, aPayloadLength, aTag, aTagLength);
+}
+#endif
+
 } // namespace Crypto
 } // namespace ot
diff --git a/src/core/crypto/aes_ccm.hpp b/src/core/crypto/aes_ccm.hpp
@@ -187,6 +187,53 @@ class AesCcm
                               uint8_t                aSecurityLevel,
                               uint8_t               *aNonce);
 
+#if OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE
+    /**
+     * Decrypts and verifies the given AES-CCM* payload via the platform hook.
+     *
+     * @param[in]      aNonce          Nonce (13 bytes, IEEE 802.15.4 CCM* format).
+     * @param[in]      aHeader         Additional authenticated data.
+     * @param[in]      aHeaderLength   Length of @p aHeader in bytes.
+     * @param[in,out]  aPayload        Ciphertext on input; replaced with plaintext in place on success.
+     * @param[in]      aPayloadLength  Length of @p aPayload in bytes.
+     * @param[in]      aTag            MIC buffer of length @p aTagLength bytes.
+     * @param[in]      aTagLength      MIC length in bytes (4, 8, or 16).
+     *
+     * @retval kErrorNone      Successfully decrypted and verified @p aPayload.
+     * @retval kErrorSecurity  MIC verification failed.
+     * @retval kErrorFailed    Platform operation failed.
+     */
+    Error DecryptAndVerify(const uint8_t *aNonce,
+                           const void    *aHeader,
+                           uint16_t       aHeaderLength,
+                           void          *aPayload,
+                           uint16_t       aPayloadLength,
+                           const void    *aTag,
+                           uint8_t        aTagLength);
+
+    /**
+     * Encrypts and tags the given AES-CCM* payload via the platform hook.
+     *
+     * @param[in]      aNonce          Nonce (13 bytes, IEEE 802.15.4 CCM* format).
+     * @param[in]      aHeader         Additional authenticated data.
+     * @param[in]      aHeaderLength   Length of @p aHeader in bytes.
+     * @param[in,out]  aPayload        Plaintext on input; replaced with ciphertext in place on success.
+     * @param[in]      aPayloadLength  Length of @p aPayload in bytes.
+     * @param[out]     aTag            Buffer to receive the MIC; must be at least @p aTagLength bytes.
+     * @param[in]      aTagLength      MIC length in bytes (4, 8, or 16).
+     *
+     * @retval kErrorNone    Successfully encrypted @p aPayload and generated MIC in @p aTag.
+     * @retval kErrorFailed  Platform operation failed.
+     */
+    Error EncryptAndTag(const uint8_t *aNonce,
+                        const void    *aHeader,
+                        uint16_t       aHeaderLength,
+                        void          *aPayload,
+                        uint16_t       aPayloadLength,
+                        void          *aTag,
+                        uint8_t        aTagLength);
+#endif
+
 private:
     AesEcb   mEcb;
     uint8_t  mBlock[AesEcb::kBlockSize];
diff --git a/src/core/crypto/aes_ecb.cpp b/src/core/crypto/aes_ecb.cpp
@@ -47,6 +47,32 @@ void AesEcb::Encrypt(const uint8_t aInput[kBlockSize], uint8_t aOutput[kBlockSiz
     SuccessOrAssert(otPlatCryptoAesEncrypt(&mContext, aInput, aOutput));
 }
 
+#if OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE
+Error AesEcb::DecryptAndVerify(const uint8_t *aNonce,
+                               const void    *aHeader,
+                               uint16_t       aHeaderLength,
+                               void          *aPayload,
+                               uint16_t       aPayloadLength,
+                               const void    *aTag,
+                               uint8_t        aTagLength)
+{
+    return otPlatCryptoAesDecryptAndVerify(&mContext, aNonce, aHeader, aHeaderLength, aPayload, aPayloadLength, aTag,
+                                           aTagLength);
+}
+
+Error AesEcb::EncryptAndTag(const uint8_t *aNonce,
+                            const void    *aHeader,
+                            uint16_t       aHeaderLength,
+                            void          *aPayload,
+                            uint16_t       aPayloadLength,
+                            void          *aTag,
+                            uint8_t        aTagLength)
+{
+    return otPlatCryptoAesEncryptAndTag(&mContext, aNonce, aHeader, aHeaderLength, aPayload, aPayloadLength, aTag,
+                                        aTagLength);
+}
+#endif
+
 AesEcb::~AesEcb(void) { SuccessOrAssert(otPlatCryptoAesFree(&mContext)); }
 
 } // namespace Crypto
diff --git a/src/core/crypto/aes_ecb.hpp b/src/core/crypto/aes_ecb.hpp
@@ -39,6 +39,7 @@
 #include <openthread/platform/crypto.h>
 
 #include "common/code_utils.hpp"
+#include "common/error.hpp"
 #include "crypto/context_size.hpp"
 #include "crypto/storage.hpp"
 
@@ -84,6 +85,57 @@ class AesEcb
      */
     void Encrypt(const uint8_t aInput[kBlockSize], uint8_t aOutput[kBlockSize]);
 
+#if OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE
+    /**
+     * Decrypts and verifies the given AES-CCM* payload.
+     *
+     * Calls `otPlatCryptoAesDecryptAndVerify()` using the AES context set by `SetKey()`.
+     *
+     * @param[in]      aNonce          Nonce (13 bytes, IEEE 802.15.4 CCM* format).
+     * @param[in]      aHeader         Additional authenticated data.
+     * @param[in]      aHeaderLength   Length of @p aHeader in bytes.
+     * @param[in,out]  aPayload        Ciphertext on input; replaced with plaintext in place on success.
+     * @param[in]      aPayloadLength  Length of @p aPayload in bytes.
+     * @param[in]      aTag            MIC buffer of length @p aTagLength bytes.
+     * @param[in]      aTagLength      MIC length in bytes (4, 8, or 16).
+     *
+     * @retval kErrorNone      Successfully decrypted and verified @p aPayload.
+     * @retval kErrorSecurity  MIC verification failed.
+     * @retval kErrorFailed    Platform operation failed.
+     */
+    Error DecryptAndVerify(const uint8_t *aNonce,
+                           const void    *aHeader,
+                           uint16_t       aHeaderLength,
+                           void          *aPayload,
+                           uint16_t       aPayloadLength,
+                           const void    *aTag,
+                           uint8_t        aTagLength);
+
+    /**
+     * Encrypts and tags the given AES-CCM* payload.
+     *
+     * Calls `otPlatCryptoAesEncryptAndTag()` using the AES context set by `SetKey()`.
+     *
+     * @param[in]      aNonce          Nonce (13 bytes, IEEE 802.15.4 CCM* format).
+     * @param[in]      aHeader         Additional authenticated data.
+     * @param[in]      aHeaderLength   Length of @p aHeader in bytes.
+     * @param[in,out]  aPayload        Plaintext on input; replaced with ciphertext in place on success.
+     * @param[in]      aPayloadLength  Length of @p aPayload in bytes.
+     * @param[out]     aTag            Buffer to receive the MIC; must be at least @p aTagLength bytes.
+     * @param[in]      aTagLength      MIC length in bytes (4, 8, or 16).
+     *
+     * @retval kErrorNone    Successfully encrypted @p aPayload and generated MIC in @p aTag.
+     * @retval kErrorFailed  Platform operation failed.
+     */
+    Error EncryptAndTag(const uint8_t *aNonce,
+                        const void    *aHeader,
+                        uint16_t       aHeaderLength,
+                        void          *aPayload,
+                        uint16_t       aPayloadLength,
+                        void          *aTag,
+                        uint8_t        aTagLength);
+#endif
+
 private:
     ContextWith<kAesContextSize> mContext;
 };
diff --git a/src/core/crypto/crypto_platform_mbedtls.cpp b/src/core/crypto/crypto_platform_mbedtls.cpp
@@ -152,6 +152,50 @@ OT_TOOL_WEAK otError otPlatCryptoAesFree(otCryptoContext *aContext)
     return error;
 }
 
+#if OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE
+// OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE is for hardware AEAD accelerators.
+// Platforms enabling it must supply these symbols; there is no software fallback.
+OT_TOOL_WEAK otError otPlatCryptoAesDecryptAndVerify(otCryptoContext *aContext,
+                                                     const uint8_t   *aNonce,
+                                                     const void      *aHeader,
+                                                     uint16_t         aHeaderLength,
+                                                     void            *aPayload,
+                                                     uint16_t         aPayloadLength,
+                                                     const void      *aTag,
+                                                     uint8_t          aTagLength)
+{
+    OT_UNUSED_VARIABLE(aContext);
+    OT_UNUSED_VARIABLE(aNonce);
+    OT_UNUSED_VARIABLE(aHeader);
+    OT_UNUSED_VARIABLE(aHeaderLength);
+    OT_UNUSED_VARIABLE(aPayload);
+    OT_UNUSED_VARIABLE(aPayloadLength);
+    OT_UNUSED_VARIABLE(aTag);
+    OT_UNUSED_VARIABLE(aTagLength);
+    return kErrorFailed;
+}
+
+OT_TOOL_WEAK otError otPlatCryptoAesEncryptAndTag(otCryptoContext *aContext,
+                                                  const uint8_t   *aNonce,
+                                                  const void      *aHeader,
+                                                  uint16_t         aHeaderLength,
+                                                  void            *aPayload,
+                                                  uint16_t         aPayloadLength,
+                                                  void            *aTag,
+                                                  uint8_t          aTagLength)
+{
+    OT_UNUSED_VARIABLE(aContext);
+    OT_UNUSED_VARIABLE(aNonce);
+    OT_UNUSED_VARIABLE(aHeader);
+    OT_UNUSED_VARIABLE(aHeaderLength);
+    OT_UNUSED_VARIABLE(aPayload);
+    OT_UNUSED_VARIABLE(aPayloadLength);
+    OT_UNUSED_VARIABLE(aTag);
+    OT_UNUSED_VARIABLE(aTagLength);
+    return kErrorFailed;
+}
+#endif // OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ENABLE
+
 #if OPENTHREAD_FTD || OPENTHREAD_MTD
 
 // HMAC implementations
diff --git a/src/core/crypto/crypto_platform_psa.cpp b/src/core/crypto/crypto_platform_psa.cpp
diff --git a/src/core/mac/mac_frame.cpp b/src/core/mac/mac_frame.cpp
diff --git a/tests/unit/test_aes.cpp b/tests/unit/test_aes.cpp
diff --git a/tests/unit/test_platform.cpp b/tests/unit/test_platform.cpp

Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@ extern "C" {`
`52`	`52`	`*`
`53`	`53`	`* @note This number versions both OpenThread platform and user APIs.`
`54`	`54`	`*/`
`55`		`-#define OPENTHREAD_API_VERSION (602)`
	`55`	`+#define OPENTHREAD_API_VERSION (603)`
`56`	`56`
`57`	`57`	`/**`
`58`	`58`	`* @addtogroup api-instance`