[crypto] add platform AES-CCM* one-shot hook

When OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE is set,
AesCcm::Engine::ProcessOneShot() calls the new weak platform hook:

  otPlatCryptoAesCcmProcessOneShot()

The hook operates in-place on a contiguous [payload|tag] buffer,
mapping to a one-shot PSA AEAD call or a packet-oriented hardware engine.

Default weak implementations:
- PSA path: psa_aead_encrypt / psa_aead_decrypt (one-shot).
- mbedTLS path: mbedtls_ccm_encrypt_and_tag / mbedtls_ccm_auth_decrypt,
  both support in-place (input == output).

Author: suveshpratapa

etc/cmake/options.cmake

@@ -307,6 +307,7 @@ endif()
 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 set(OT_CRYPTO_LIB_VALUES "MBEDTLS" "PSA" "PLATFORM")
 ot_multi_option(OT_CRYPTO_LIB OT_CRYPTO_LIB_VALUES OPENTHREAD_CONFIG_CRYPTO_LIB OPENTHREAD_CONFIG_CRYPTO_LIB_ "set Crypto backend library")
+ot_option(OT_CRYPTO_CCM_ONE_SHOT OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE "platform one-shot AES-CCM* hook")
 
 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 set(OT_THREAD_VERSION_VALUES "1.1" "1.2" "1.3" "1.3.1" "1.4")

include/openthread/instance.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (608)
+#define OPENTHREAD_API_VERSION (609)
 
 /**
  * @addtogroup api-instance

include/openthread/platform/crypto.h

@@ -749,6 +749,51 @@ otError otPlatCryptoPbkdf2GenerateKey(const uint8_t *aPassword,
                                       uint16_t       aKeyLen,
                                       uint8_t       *aKey);
 
+/**
+ * @struct otPlatCryptoAesCcmConfig
+ *
+ * Holds the parameters for a one-shot AES-CCM* operation passed to `otPlatCryptoAesCcmProcessOneShot`.
+ */
+typedef struct otPlatCryptoAesCcmConfig
+{
+    otCryptoKey    mKey;             ///< The encryption key.
+    const uint8_t *mNonce;           ///< Pointer to the nonce buffer (IEEE 802.15.4 CCM* format, 13 bytes).
+    uint8_t        mNonceLength;     ///< Length of @p mNonce in bytes.
+    uint8_t        mTagLength;       ///< Authentication tag length in bytes (even)
+    uint32_t       mHeaderLength;    ///< Length of the additional authenticated data (header) in bytes.
+    uint32_t       mPlainTextLength; ///< Payload length in bytes (excluding tag).
+} otPlatCryptoAesCcmConfig;
+
+/**
+ * Performs in-place AES-CCM* authenticated encryption or decryption in a single call.
+ *
+ * For encryption (@p aEncrypt == true):
+ *   - Plaintext at @p aData is replaced with ciphertext in-place.
+ *   - The authentication tag is written to @p aData + @p aConfig->mPlainTextLength.
+ *
+ * For decryption (@p aEncrypt == false):
+ *   - Ciphertext at @p aData is replaced with plaintext in-place.
+ *   - The tag to verify must be at @p aData + @p aConfig->mPlainTextLength.
+ *
+ * Requires `OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE`.
+ *
+ * Default weak mbedTLS and PSA implementations are provided.
+ *
+ * @param[in]      aEncrypt  True to encrypt and generate tag; false to decrypt and verify tag.
+ * @param[in]      aConfig   CCM* parameters (key, nonce, lengths).
+ * @param[in]      aHeader   Additional authenticated data (not encrypted). May be NULL if header length is 0.
+ * @param[in,out]  aData     Payload buffer (plaintext on encrypt entry, ciphertext on decrypt entry).
+ *                           The buffer must hold @p aConfig->mPlainTextLength + @p aConfig->mTagLength bytes.
+ *
+ * @retval OT_ERROR_NONE      Success.
+ * @retval OT_ERROR_SECURITY  Tag mismatch (decrypt only).
+ * @retval OT_ERROR_FAILED    Operation failed.
+ */
+otError otPlatCryptoAesCcmProcessOneShot(bool                            aEncrypt,
+                                         const otPlatCryptoAesCcmConfig *aConfig,
+                                         const uint8_t                  *aHeader,
+                                         uint8_t                        *aData);
+
 /**
  * @}
  */

script/check-simulation-build-cmake

@@ -196,6 +196,10 @@ build_all_features()
 
     reset_source
     "$(dirname "$0")"/cmake-build simulation -DOT_BLE_TCAT=ON
+
+    # Build with platform CCM one-shot enabled
+    reset_source
+    "$(dirname "$0")"/cmake-build simulation -DOT_CRYPTO_CCM_ONE_SHOT=ON
 }
 
 build_nest_common()

src/core/config/crypto.h

@@ -68,6 +68,19 @@
 #define OPENTHREAD_CONFIG_CRYPTO_PLATFORM_ALLOCS_CONTEXT 0
 #endif
 
+/**
+ * @def OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE
+ *
+ * Define to 1 to enable platform one-shot AES-CCM* acceleration.
+ *
+ * When enabled, `AesCcm::Engine::ProcessOneShot()` calls
+ * `otPlatCryptoAesCcmProcessOneShot()` instead of the built-in
+ * software CCM engine.
+ */
+#ifndef OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE
+#define OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE 0
+#endif
+
 #if OPENTHREAD_CONFIG_CRYPTO_LIB == OPENTHREAD_CONFIG_CRYPTO_LIB_PLATFORM
 
 /**

src/core/crypto/aes_ccm.cpp

@@ -212,13 +212,11 @@ Error AesCcm::Engine::ProcessOneShot(Operation      aOperation,
                                      const uint8_t *aHeader,
                                      uint8_t       *aData)
 {
-    // This method performs one-shot (single-part) AES-CCM processing.
-    // Currently, it is implemented by calling the multi-part
-    // streaming APIs sequentially. In the future, this can be
-    // optimized to directly call platform-specific one-shot hardware
-    // acceleration APIs if supported by the platform.
+    Error error = kErrorNone;
 
-    Error   error = kErrorNone;
+#if OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE
+    error = otPlatCryptoAesCcmProcessOneShot(aOperation == kEncrypt, &aConfig, aHeader, aData);
+#else
     uint8_t tag[kMaxTagLength];
 
     Start(aConfig);
@@ -236,6 +234,7 @@ Error AesCcm::Engine::ProcessOneShot(Operation      aOperation,
         error = (memcmp(aData + aConfig.mPlainTextLength, tag, aConfig.mTagLength) == 0) ? kErrorNone : kErrorSecurity;
         break;
     }
+#endif
 
     return error;
 }
@@ -249,7 +248,7 @@ void AesCcm::Engine::Start(const Config &aConfig)
 
     OT_ASSERT(aConfig.IsValid());
 
-    mEcb.SetKey(aConfig.mKey);
+    mEcb.SetKey(aConfig.GetKey());
 
     mNonceLength     = aConfig.mNonceLength;
     mTagLength       = aConfig.mTagLength;

src/core/crypto/aes_ccm.hpp

@@ -119,7 +119,7 @@ class AesCcm
      * @param[in]  aKey        A pointer to the key.
      * @param[in]  aKeyLength  Length of the key in bytes.
      */
-    void SetKey(const uint8_t *aKey, uint16_t aKeyLength) { mConfig.mKey.Set(aKey, aKeyLength); }
+    void SetKey(const uint8_t *aKey, uint16_t aKeyLength) { mConfig.GetKey().Set(aKey, aKeyLength); }
 
     /**
      * Sets the key.
@@ -128,7 +128,7 @@ class AesCcm
      *
      * @param[in]  aMacKey        Key Material for AES operation.
      */
-    void SetKey(const Mac::KeyMaterial &aMacKey) { aMacKey.ConvertToCryptoKey(mConfig.mKey); }
+    void SetKey(const Mac::KeyMaterial &aMacKey) { aMacKey.ConvertToCryptoKey(mConfig.GetKey()); }
 
     /**
      * Sets the Nonce.
@@ -245,16 +245,11 @@ class AesCcm
                         void       *aTag);
 
 private:
-    struct Config : public Clearable<Config>
+    struct Config : public otPlatCryptoAesCcmConfig, public Clearable<Config>
     {
-        bool IsValid(void) const;
-
-        Key            mKey;
-        uint8_t        mNonceLength;
-        uint8_t        mTagLength;
-        uint32_t       mHeaderLength;
-        uint32_t       mPlainTextLength;
-        const uint8_t *mNonce;
+        bool       IsValid(void) const;
+        Key       &GetKey(void) { return AsCoreType(&mKey); }
+        const Key &GetKey(void) const { return AsCoreType(&mKey); }
     };
 
     class Engine

src/core/crypto/crypto_platform_mbedtls.cpp

@@ -37,6 +37,7 @@
 #include <string.h>
 
 #include <mbedtls/aes.h>
+#include <mbedtls/ccm.h>
 #include <mbedtls/cmac.h>
 #include <mbedtls/ctr_drbg.h>
 #include <mbedtls/ecdsa.h>
@@ -152,6 +153,59 @@ OT_TOOL_WEAK otError otPlatCryptoAesFree(otCryptoContext *aContext)
     return error;
 }
 
+#if OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE
+
+OT_TOOL_WEAK otError otPlatCryptoAesCcmProcessOneShot(bool                            aEncrypt,
+                                                      const otPlatCryptoAesCcmConfig *aConfig,
+                                                      const uint8_t                  *aHeader,
+                                                      uint8_t                        *aData)
+{
+    Error               error = kErrorNone;
+    mbedtls_ccm_context ctx;
+    int                 ret;
+
+    mbedtls_ccm_init(&ctx);
+
+    VerifyOrExit(aConfig != nullptr && aConfig->mNonce != nullptr && aData != nullptr, error = kErrorInvalidArgs);
+
+    {
+        const LiteralKey key(*static_cast<const Key *>(&aConfig->mKey));
+
+        ret = mbedtls_ccm_setkey(&ctx, MBEDTLS_CIPHER_ID_AES, key.GetBytes(), key.GetLength() * kBitsPerByte);
+        VerifyOrExit(ret == 0, error = kErrorFailed);
+
+        if (aEncrypt)
+        {
+            ret = mbedtls_ccm_encrypt_and_tag(&ctx, aConfig->mPlainTextLength, aConfig->mNonce, aConfig->mNonceLength,
+                                              aHeader, aConfig->mHeaderLength, aData, aData,
+                                              aData + aConfig->mPlainTextLength, aConfig->mTagLength);
+            VerifyOrExit(ret == 0, error = kErrorFailed);
+        }
+        else
+        {
+            // MBEDTLS_ERR_CCM_AUTH_FAILED is the expected return on tag mismatch; map to kErrorSecurity.
+            ret = mbedtls_ccm_auth_decrypt(&ctx, aConfig->mPlainTextLength, aConfig->mNonce, aConfig->mNonceLength,
+                                           aHeader, aConfig->mHeaderLength, aData, aData,
+                                           aData + aConfig->mPlainTextLength, aConfig->mTagLength);
+
+            if (ret == MBEDTLS_ERR_CCM_AUTH_FAILED)
+            {
+                error = kErrorSecurity;
+            }
+            else
+            {
+                VerifyOrExit(ret == 0, error = kErrorFailed);
+            }
+        }
+    }
+
+exit:
+    mbedtls_ccm_free(&ctx);
+    return error;
+}
+
+#endif // OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE
+
 #if OPENTHREAD_FTD || OPENTHREAD_MTD
 
 // HMAC implementations

src/core/crypto/crypto_platform_psa.cpp

@@ -389,6 +389,49 @@ OT_TOOL_WEAK otError otPlatCryptoAesFree(otCryptoContext *aContext)
     return kErrorNone;
 }
 
+#if OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE
+
+OT_TOOL_WEAK otError otPlatCryptoAesCcmProcessOneShot(bool                            aEncrypt,
+                                                      const otPlatCryptoAesCcmConfig *aConfig,
+                                                      const uint8_t                  *aHeader,
+                                                      uint8_t                        *aData)
+{
+    Error           error = kErrorNone;
+    psa_status_t    status;
+    psa_algorithm_t algorithm;
+    size_t          outputLen = 0;
+
+    VerifyOrExit(aConfig != nullptr && aConfig->mNonce != nullptr && aData != nullptr, error = kErrorInvalidArgs);
+    VerifyOrExit(aConfig->mKey.mKey == nullptr, error = kErrorInvalidArgs);
+
+    algorithm = PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, aConfig->mTagLength);
+
+    if (aEncrypt)
+    {
+        // Output layout: ciphertext || tag, written in-place over the plaintext buffer.
+        status = psa_aead_encrypt(aConfig->mKey.mKeyRef, algorithm, aConfig->mNonce, aConfig->mNonceLength, aHeader,
+                                  aConfig->mHeaderLength, aData, aConfig->mPlainTextLength, aData,
+                                  aConfig->mPlainTextLength + aConfig->mTagLength, &outputLen);
+        SuccessOrExit(error = PsaToOtError(status));
+        VerifyOrExit(outputLen == aConfig->mPlainTextLength + aConfig->mTagLength, error = kErrorFailed);
+    }
+    else
+    {
+        // Input layout: ciphertext || tag contiguous at aData. Output plaintext written in-place.
+        status = psa_aead_decrypt(aConfig->mKey.mKeyRef, algorithm, aConfig->mNonce, aConfig->mNonceLength, aHeader,
+                                  aConfig->mHeaderLength, aData, aConfig->mPlainTextLength + aConfig->mTagLength, aData,
+                                  aConfig->mPlainTextLength, &outputLen);
+        error  = (status == PSA_ERROR_INVALID_SIGNATURE) ? kErrorSecurity : PsaToOtError(status);
+        SuccessOrExit(error);
+        VerifyOrExit(outputLen == aConfig->mPlainTextLength, error = kErrorFailed);
+    }
+
+exit:
+    return error;
+}
+
+#endif // OPENTHREAD_CONFIG_CRYPTO_PLATFORM_CCM_ONE_SHOT_ENABLE
+
 #if OPENTHREAD_FTD || OPENTHREAD_MTD
 
 OT_TOOL_WEAK otError otPlatCryptoHmacSha256Init(otCryptoContext *aContext)