[core, services] move session keys to platform secure storage

Signed-off-by: Benjamin Grolleau <benjamin.grolleau@outlook.com>

Author: Grolleau-Benjamin

CHANGELOG.md

@@ -16,18 +16,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Renamed** `stse_Handler_t` to `stse_Handle_t` — all references to the handle type must be updated in application code ([31fb0fa](https://github.com/STMicroelectronics/STSELib/commit/31fb0fa9865828d82479e8c40fa3499c68b33fe9))
 - **API change** — all platform-level SecureElement initialization functions now require an additional `void *pArg` parameter ([51aa3f8](https://github.com/STMicroelectronics/STSELib/commit/51aa3f8114d33adfe38da6fd261e4b9a71a1fa9b))
+- **Platform AES API change** — all platform AES cryptographic functions now reference keys by secure storage index (`PLAT_UI32 key_idx`) instead of raw key pointer and length (`PLAT_UI8 *pKey, PLAT_UI16 key_length`). Affected functions: `stse_platform_aes_cmac_init`, `stse_platform_aes_cmac_compute`, `stse_platform_aes_cmac_verify`, `stse_platform_aes_cbc_enc`, `stse_platform_aes_cbc_dec`, `stse_platform_aes_ecb_enc`
+- **Renamed** `stsafea_open_host_session` to `stsafea_open_host_session_from_idx` — signature updated to accept key indices (`PLAT_UI32 host_MAC_key_idx`, `PLAT_UI32 host_cypher_key_idx`) instead of raw key pointers
 
 ### Added
 
+- `stse_platform_store_aes_key()` — new platform function to store an AES key into platform secure storage and retrieve its index
+- `stse_platform_delete_aes_key()` — new platform function to delete an AES key from platform secure storage by index
+
 ### Changed
 
 ### Deprecated
 
 ### Removed
+- `stsafea_open_host_session` function. Now replaced by `stsafea_open_host_session_from_idx` which accepts key indices instead of raw key pointers. Note that you must first store the AES keys in platform secure storage using `stse_platform_store_aes_key()` to obtain the required indices before opening a host session.
 
 ### Fixed
 
 ### Security
+- AES keys are now securely stored in platform secure storage and referenced by index, eliminating the need to handle raw key material in application memory and enhancing overall security.
 
 ---
 

core/stse_device.h

@@ -160,8 +160,8 @@ struct stse_session_t {
     union {
         struct {
             stse_Handle_t *pSTSE;
-            PLAT_UI8 *pHost_MAC_key;
-            PLAT_UI8 *pHost_cypher_key;
+            PLAT_UI32 host_MAC_key_idx;
+            PLAT_UI32 host_cypher_key_idx;
             stse_aes_key_type_t key_type;
             PLAT_UI32 MAC_counter;
         } host;

core/stse_generic_typedef.h

@@ -111,6 +111,15 @@ typedef enum stse_aes_key_type_t {
     STSE_AES_256_KT
 } stse_aes_key_type_t;
 
+/*!
+ * \enum stse_aes_key_usage_t
+ * \brief STSE AES key usage
+ */
+typedef enum stse_aes_key_usage_t {
+    STSE_AES_KEY_USAGE_MAC = 0, /**< Key used for MAC operations (CMAC) */
+    STSE_AES_KEY_USAGE_CIPHER   /**< Key used for cipher operations (CBC, ECB) */
+} stse_aes_key_usage_t;
+
 /*!
  * \enum stse_hash_algorithm_t
  * \brief STSE Hash algorithm type

core/stse_platform.h

@@ -215,14 +215,29 @@ stse_ReturnCode_t stse_platform_nist_kw_encrypt(PLAT_UI8 *pPayload, PLAT_UI32 pa
 #if defined(STSE_CONF_USE_HOST_KEY_ESTABLISHMENT) || defined(STSE_CONF_USE_SYMMETRIC_KEY_ESTABLISHMENT) || defined(STSE_CONF_USE_HOST_SESSION)
 
 /*!
- * \brief      Initialize AES CMAC computation
- * \param[in]  pKey Pointer to the key
+ * \brief      Store aes key in platform secure storage
+ * \param[in]  pKey       Pointer to the aes key
  * \param[in]  key_length Length of the key
+ * \param[in]  usage      Key usage type, used by the platform to set the appropriate key attributes in secure storage
+ * \param[out] pKey_idx   Pointer to the index assigned to the stored key in secure storage
+ * \return     \ref STSE_OK on success; \ref stse_ReturnCode_t error code otherwise
+ */
+stse_ReturnCode_t stse_platform_store_aes_key(PLAT_UI8 *pKey, PLAT_UI16 key_length, stse_aes_key_usage_t usage, PLAT_UI32 *pKey_idx);
+
+/*!
+ * \brief      Delete aes key from platform secure storage
+ * \param[in]  key_idx Index of the key to delete from secure storage
+ * \return     \ref STSE_OK on success; \ref stse_ReturnCode_t error code otherwise
+ */
+stse_ReturnCode_t stse_platform_delete_aes_key(PLAT_UI32 key_idx);
+
+/*!
+ * \brief      Initialize AES CMAC computation
+ * \param[in]  key_idx Index of the key to use for AES CMAC computation in secure storage
  * \param[in]  exp_tag_size Expected tag size
  * \return     \ref STSE_OK on success; \ref stse_ReturnCode_t error code otherwise
  */
-stse_ReturnCode_t stse_platform_aes_cmac_init(const PLAT_UI8 *pKey,
-                                              PLAT_UI16 key_length,
+stse_ReturnCode_t stse_platform_aes_cmac_init(const PLAT_UI32 key_idx,
                                               PLAT_UI16 exp_tag_size);
 
 /*!
@@ -252,77 +267,69 @@ stse_ReturnCode_t stse_platform_aes_cmac_verify_finish(PLAT_UI8 *pTag);
  * \brief      Perform an AES CMAC encryption
  * \param[in]  pPayload Pointer to Payload
  * \param[in]  payload_length Length of the payload in bytes
- * \param[in]  pKey Pointer to key
- * \param[in]  key_length Length of the key in bytes
+ * \param[in]  key_idx Index of the key to use for AES CMAC computation in secure storage
  * \param[in]  exp_tag_size Expected tag size in bytes
  * \param[out] pTag Pointer to Tag
  * \param[out] pTag_length Pointer to Tag length value output
  * \return     \ref STSE_OK on success; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_platform_aes_cmac_compute(const PLAT_UI8 *pPayload, PLAT_UI16 payload_length,
-                                                 const PLAT_UI8 *pKey, PLAT_UI16 key_length,
+                                                 const PLAT_UI32 key_idx,
                                                  PLAT_UI16 exp_tag_size,
                                                  PLAT_UI8 *pTag, PLAT_UI16 *pTag_length);
 
 /*!
  * \brief      Perform an AES CMAC decryption
  * \param[in]  pPayload Pointer to Payload
  * \param[in]  payload_length Length of the payload in bytes
- * \param[in]  pKey Pointer to key
- * \param[in]  key_length Length of the key in bytes
+ * \param[in]  key_idx Index of the key to use for AES CMAC computation in secure storage
  * \param[in]  pTag Pointer to Tag
  * \param[in]  tag_length Pointer to Tag length value output
  * \return     \ref STSE_OK on success; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_platform_aes_cmac_verify(const PLAT_UI8 *pPayload, PLAT_UI16 payload_length,
-                                                const PLAT_UI8 *pKey, PLAT_UI16 key_length,
+                                                const PLAT_UI32 key_idx,
                                                 const PLAT_UI8 *pTag, PLAT_UI16 tag_length);
 
 /*!
  * \brief      Perform an AES CBC encryption
  * \param[in]  pPlaintext Pointer to the plaintext data
  * \param[in]  plaintext_length Length of the plaintext data
  * \param[in]  pInitial_value Pointer to encryption IV
- * \param[in]  pKey Pointer to the key
- * \param[in]  key_length Length of the key
+ * \param[in]  key_idx Index of the key to use for AES encryption in secure storage
  * \param[out] pEncryptedtext Pointer to the encrypted payload
  * \param[out] pEncryptedtext_length Length of encrypted payload
  * \return     \ref STSE_OK on success; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_platform_aes_cbc_enc(const PLAT_UI8 *pPlaintext, PLAT_UI16 plaintext_length,
-                                            PLAT_UI8 *pInitial_value, const PLAT_UI8 *pKey,
-                                            PLAT_UI16 key_length, PLAT_UI8 *pEncryptedtext,
+                                            PLAT_UI8 *pInitial_value, const PLAT_UI32 key_idx, PLAT_UI8 *pEncryptedtext,
                                             PLAT_UI16 *pEncryptedtext_length);
 
 /*!
  * \brief      Perform an AES CBC decryption
  * \param[in]  pEncryptedtext Pointer to the encrypted payload
  * \param[in]  encryptedtext_length Length of encrypted payload
  * \param[in]  pInitial_value Pointer to decryption IV
- * \param[in]  pKey Pointer to the key
- * \param[in]  key_length Length of the key
+ * \param[in]  key_idx Index of the key to use for AES decryption in secure storage
  * \param[out] pPlaintext Pointer to PlainText payload
  * \param[out] pPlaintext_length Length of the PlainText payload
  * \return     \ref STSE_OK on success; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_platform_aes_cbc_dec(const PLAT_UI8 *pEncryptedtext, PLAT_UI16 encryptedtext_length,
-                                            PLAT_UI8 *pInitial_value, const PLAT_UI8 *pKey,
-                                            PLAT_UI16 key_length, PLAT_UI8 *pPlaintext,
+                                            PLAT_UI8 *pInitial_value, const PLAT_UI32 key_idx, PLAT_UI8 *pPlaintext,
                                             PLAT_UI16 *pPlaintext_length);
 
 /*!
  * \brief      Perform an AES ECB encryption
  * \param[in]  pPlaintext Pointer to the plaintext data
  * \param[in]  plaintext_length Length of the plaintext data
- * \param[in]  pKey Pointer to the key
- * \param[in]  key_length Length of the key
+ * \param[in]  key_idx Index of the key to use for AES encryption in secure storage
  * \param[out] pEncryptedtext Pointer to the encrypted payload
  * \param[out] pEncryptedtext_length Length of encrypted payload
  * \return     \ref STSE_OK on success; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_platform_aes_ecb_enc(const PLAT_UI8 *pPlaintext, PLAT_UI16 plaintext_length,
-                                            const PLAT_UI8 *pKey, PLAT_UI16 key_length,
-                                            PLAT_UI8 *pEncryptedtext, PLAT_UI16 *pEncryptedtext_length);
+                                            const PLAT_UI32 key_idx, PLAT_UI8 *pEncryptedtext, PLAT_UI16 *pEncryptedtext_length);
 
 #endif /* defined(STSE_CONF_USE_HOST_KEY_ESTABLISHMENT) || defined(STSE_CONF_USE_SYMMETRIC_KEY_ESTABLISHMENT) || defined(STSE_CONF_USE_HOST_SESSION) */
 

services/stsafea/stsafea_sessions.c

@@ -41,7 +41,7 @@
 
 #ifdef STSE_CONF_USE_HOST_SESSION
 
-stse_ReturnCode_t stsafea_open_host_session(stse_Handle_t *pSTSE, stse_session_t *pSession, PLAT_UI8 *pHost_MAC_key, PLAT_UI8 *pHost_cypher_key) {
+stse_ReturnCode_t stsafea_open_host_session_from_idx(stse_Handle_t *pSTSE, stse_session_t *pSession, PLAT_UI32 host_MAC_key_idx, PLAT_UI32 host_cypher_key_idx) {
     stse_ReturnCode_t ret;
 
     if (pSTSE == NULL) {
@@ -81,8 +81,8 @@ stse_ReturnCode_t stsafea_open_host_session(stse_Handle_t *pSTSE, stse_session_t
     }
 
     pSession->type = STSE_HOST_SESSION;
-    pSession->context.host.pHost_MAC_key = pHost_MAC_key;
-    pSession->context.host.pHost_cypher_key = pHost_cypher_key;
+    pSession->context.host.host_MAC_key_idx = host_MAC_key_idx;
+    pSession->context.host.host_cypher_key_idx = host_cypher_key_idx;
     pSession->context.host.pSTSE = pSTSE;
     pSTSE->pActive_host_session = pSession;
 
@@ -169,8 +169,7 @@ stse_ReturnCode_t stsafea_session_frame_encrypt(stse_session_t *pSession,
     /* - Perform first AES ECB round on IV */
     ret = stse_platform_aes_ecb_enc(initial_value,
                                     STSAFEA_HOST_AES_BLOCK_SIZE,
-                                    pSession->context.host.pHost_cypher_key,
-                                    (pSession->context.host.key_type == STSE_AES_128_KT) ? STSE_AES_128_KEY_SIZE : STSE_AES_256_KEY_SIZE,
+                                    pSession->context.host.host_cypher_key_idx,
                                     initial_value,
                                     &encrypted_iv_len);
     if (ret != STSE_OK) {
@@ -201,8 +200,7 @@ stse_ReturnCode_t stsafea_session_frame_encrypt(stse_session_t *pSession,
         pEnc_payload_element->pData,
         pEnc_payload_element->length,
         initial_value,
-        pSession->context.host.pHost_cypher_key,
-        (pSession->context.host.key_type == STSE_AES_128_KT) ? STSE_AES_128_KEY_SIZE : STSE_AES_256_KEY_SIZE,
+        pSession->context.host.host_cypher_key_idx,
         pEnc_payload_element->pData,
         &encrypted_payload_len);
     if (ret != 0) {
@@ -261,8 +259,7 @@ static stse_ReturnCode_t stsafea_session_frame_decrypt(stse_session_t *pSession,
     /* - Transform IV using AES ECB */
     ret = stse_platform_aes_ecb_enc(initial_value,
                                     STSAFEA_HOST_AES_BLOCK_SIZE,
-                                    pSession->context.host.pHost_cypher_key,
-                                    (pSession->context.host.key_type == STSE_AES_128_KT) ? STSE_AES_128_KEY_SIZE : STSE_AES_256_KEY_SIZE,
+                                    pSession->context.host.host_cypher_key_idx,
                                     initial_value,
                                     &out_len);
 
@@ -276,8 +273,7 @@ static stse_ReturnCode_t stsafea_session_frame_decrypt(stse_session_t *pSession,
     ret = stse_platform_aes_cbc_dec(decrypt_buffer,
                                     encrypted_payload_len,
                                     initial_value,
-                                    pSession->context.host.pHost_cypher_key,
-                                    (pSession->context.host.key_type == STSE_AES_128_KT) ? STSE_AES_128_KEY_SIZE : STSE_AES_256_KEY_SIZE,
+                                    pSession->context.host.host_cypher_key_idx,
                                     decrypt_buffer,
                                     &decrypted_payload_len);
 
@@ -333,8 +329,7 @@ static stse_ReturnCode_t stsafea_session_frame_c_mac_compute(stse_session_t *pSe
 
     /*- Initialize AES C-MAC computation */
 
-    ret = stse_platform_aes_cmac_init(pSession->context.host.pHost_MAC_key,
-                                      (pSession->context.host.key_type == STSE_AES_128_KT) ? STSE_AES_128_KEY_SIZE : STSE_AES_256_KEY_SIZE,
+    ret = stse_platform_aes_cmac_init(pSession->context.host.host_MAC_key_idx,
                                       STSAFEA_MAC_SIZE);
     if (ret != STSE_OK) {
         return ret;
@@ -425,8 +420,7 @@ static stse_ReturnCode_t stsafea_session_frame_r_mac_verify(stse_session_t *pSes
 
         /*- Initialize AES CMAC computation */
         stse_platform_aes_cmac_init(
-            pSession->context.host.pHost_MAC_key,
-            (pSession->context.host.key_type == STSE_AES_128_KT) ? STSE_AES_128_KEY_SIZE : STSE_AES_256_KEY_SIZE,
+            pSession->context.host.host_MAC_key_idx,
             STSAFEA_MAC_SIZE);
 
         /*- Perform First AES-CMAC round */

services/stsafea/stsafea_sessions.h

@@ -26,17 +26,19 @@
 #include "core/stse_return_codes.h"
 
 /*!
- * \brief 		This Core function Create a session context and associate it to STSAFE handler
- * \param[in] 	*pSession 			\ref stse_session_t Pointer to session
- * \param[in] 	*pHost_MAC_key 		Pointer to MAC key buffer to be used under the session
- * \param[in] 	*pHost_cypher_key 	Pointer to cypher key buffer to be used under the session
+ * \brief       This Core function creates a session context and associates it to STSAFE handler using keys stored in platform secure storage
+ * \param[in]   *pSTSE                  Pointer to STSE handler
+ * \param[in]   *pSession               \ref stse_session_t Pointer to session
+ * \param[in]   host_MAC_key_idx        Index of the MAC key in platform secure storage to be used under the session
+ * \param[in]   host_cypher_key_idx     Index of the cypher key in platform secure storage to be used under the session
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
- * \details 	\include{doc} stsafe_erase_context.dox
+ * \details     \include{doc} stsafe_erase_context.dox
+ * \details     \include{doc} stse_platform_store_aes_key.dox
  */
-stse_ReturnCode_t stsafea_open_host_session(stse_Handle_t *pSTSE,
-                                            stse_session_t *pSession,
-                                            PLAT_UI8 *pHost_MAC_key,
-                                            PLAT_UI8 *pHost_cypher_key);
+stse_ReturnCode_t stsafea_open_host_session_from_idx(stse_Handle_t *pSTSE,
+                                                     stse_session_t *pSession,
+                                                     PLAT_UI32 host_MAC_key_idx,
+                                                     PLAT_UI32 host_cypher_key_idx);
 
 /*!
  * \brief 		This Core function Close an existing host session context