refactor(init): Add device power-on sequence in device management

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,10 @@
 ## IMPORTANT INFORMATION
 
+### PR Checklist
+
+- [ ] I have updated the CHANGELOG.md file with a description of my changes.
+- [ ] I have signed the Contributor License Agreement (CLA).
+
 ### Contributor License Agreement (CLA)
 * The Pull Request feature will be considered by STMicroelectronics after the signature of a **Contributor License Agreement (CLA)** by the submitter.
 * If you did not sign such agreement, please follow the steps mentioned in the [CONTRIBUTING.md](CONTRIBUTING.md) file.

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Note:** This changelog starts from version v1.2.0. For prior releases, refer to the
+> [GitHub Releases page](https://github.com/STMicroelectronics/STSELib/releases).
+
+---
+
+## [Unreleased](https://github.com/STMicroelectronics/STSELib/compare/v1.1.7...HEAD) - v1.2.0
+
+### Breaking Changes
+
+- **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.
+
+---
+
+## [V1.1.7 — March 4, 2026](https://github.com/STMicroelectronics/STSELib/releases/tag/v1.1.7)

README.md

@@ -64,10 +64,15 @@ Following applicative project can be used as reference for STSELib integration a
 - STSAFE-A
     - [stsafe-a-sdk](https://github.com/STMicroelectronics/STSAFE-A120-sdk)
     - [wolfssl-examples](https://github.com/wolfSSL/wolfssl-examples/tree/master/stsafe) developed and maintained by [WolfSSL](https://www.wolfssl.com/)
-    - [Zephyr_st-stsafe-a1xx](https://github.com/catie-aq/zephyr_st-stsafe-a1xx) developed and maintained by [CATIE](https://www.catie.fr/language/en/home/)
+    - [zephyr_st-stsafe-a1xx](https://github.com/catie-aq/zephyr_st-stsafe-a1xx) developed and maintained by [CATIE](https://www.catie.fr/language/en/home/)
 
 
 - STSAFE-L
     - [STSAFE-L_echo](https://github.com/STMicroelectronics/STSAFE-L_echo)
     - [STSAFE-L_device_authentication](https://github.com/STMicroelectronics/STSAFE-L_device_authentication)
     - [STSAFE-L_secure_data_storage](https://github.com/STMicroelectronics/STSAFE-L_secure_data_storage)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the full history of changes.
+For releases prior to v1.2.0, refer to the [GitHub Releases page](https://github.com/STMicroelectronics/STSELib/releases).

api/stse_aes.c

@@ -21,7 +21,7 @@
 #include "api/stse_aes.h"
 
 stse_ReturnCode_t stse_aes_ecb_encrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 message_length,
     PLAT_UI8 *pPlaintext_message,
@@ -43,7 +43,7 @@ stse_ReturnCode_t stse_aes_ecb_encrypt(
 }
 
 stse_ReturnCode_t stse_aes_ecb_decrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 message_length,
     PLAT_UI8 *pEncrypted_message,
@@ -65,7 +65,7 @@ stse_ReturnCode_t stse_aes_ecb_decrypt(
 }
 
 stse_ReturnCode_t stse_aes_ccm_encrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI8 *pNonce,
@@ -96,7 +96,7 @@ stse_ReturnCode_t stse_aes_ccm_encrypt(
 }
 
 stse_ReturnCode_t stse_aes_ccm_encrypt_start(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 Nonce_length,
     PLAT_UI8 *pNonce,
@@ -134,7 +134,7 @@ stse_ReturnCode_t stse_aes_ccm_encrypt_start(
 }
 
 stse_ReturnCode_t stse_aes_ccm_encrypt_process(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
     PLAT_UI16 message_chunk_length,
@@ -158,7 +158,7 @@ stse_ReturnCode_t stse_aes_ccm_encrypt_process(
 }
 
 stse_ReturnCode_t stse_aes_ccm_encrypt_finish(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
@@ -186,7 +186,7 @@ stse_ReturnCode_t stse_aes_ccm_encrypt_finish(
 }
 
 stse_ReturnCode_t stse_aes_ccm_decrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI8 *pNonce,
@@ -220,7 +220,7 @@ stse_ReturnCode_t stse_aes_ccm_decrypt(
 }
 
 stse_ReturnCode_t stse_aes_gcm_encrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 IV_length,
@@ -254,7 +254,7 @@ stse_ReturnCode_t stse_aes_gcm_encrypt(
 }
 
 stse_ReturnCode_t stse_aes_ccm_decrypt_start(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 Nonce_length,
     PLAT_UI8 *pNonce,
@@ -288,7 +288,7 @@ stse_ReturnCode_t stse_aes_ccm_decrypt_start(
 }
 
 stse_ReturnCode_t stse_aes_ccm_decrypt_process(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
     PLAT_UI16 message_chunk_length,
@@ -312,7 +312,7 @@ stse_ReturnCode_t stse_aes_ccm_decrypt_process(
 }
 
 stse_ReturnCode_t stse_aes_ccm_decrypt_finish(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
@@ -342,7 +342,7 @@ stse_ReturnCode_t stse_aes_ccm_decrypt_finish(
 }
 
 stse_ReturnCode_t stse_aes_gcm_encrypt_start(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 IV_length,
     PLAT_UI8 *pIV,
@@ -372,7 +372,7 @@ stse_ReturnCode_t stse_aes_gcm_encrypt_start(
 }
 
 stse_ReturnCode_t stse_aes_gcm_encrypt_process(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
     PLAT_UI16 message_chunk_length,
@@ -396,7 +396,7 @@ stse_ReturnCode_t stse_aes_gcm_encrypt_process(
 }
 
 stse_ReturnCode_t stse_aes_gcm_encrypt_finish(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
@@ -424,7 +424,7 @@ stse_ReturnCode_t stse_aes_gcm_encrypt_finish(
 }
 
 stse_ReturnCode_t stse_aes_gcm_decrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 IV_length,
@@ -460,7 +460,7 @@ stse_ReturnCode_t stse_aes_gcm_decrypt(
 }
 
 stse_ReturnCode_t stse_aes_gcm_decrypt_start(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 IV_length,
     PLAT_UI8 *pIV,
@@ -490,7 +490,7 @@ stse_ReturnCode_t stse_aes_gcm_decrypt_start(
 }
 
 stse_ReturnCode_t stse_aes_gcm_decrypt_process(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
     PLAT_UI16 message_chunk_length,
@@ -514,7 +514,7 @@ stse_ReturnCode_t stse_aes_gcm_decrypt_process(
 }
 
 stse_ReturnCode_t stse_aes_gcm_decrypt_finish(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,

api/stse_aes.h

@@ -43,7 +43,7 @@
  * \details 	\include{doc} stse_aes_ecb_encrypt.dox
  */
 stse_ReturnCode_t stse_aes_ecb_encrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 message_length,
     PLAT_UI8 *pPlaintext_message,
@@ -61,7 +61,7 @@ stse_ReturnCode_t stse_aes_ecb_encrypt(
  * \details 	\include{doc} stse_aes_ecb_decrypt.dox
  */
 stse_ReturnCode_t stse_aes_ecb_decrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 message_length,
     PLAT_UI8 *pEncrypted_message,
@@ -86,7 +86,7 @@ stse_ReturnCode_t stse_aes_ecb_decrypt(
  * \details 	\include{doc} stse_aes_ccm_encrypt.dox
  */
 stse_ReturnCode_t stse_aes_ccm_encrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI8 *pNonce,
@@ -118,7 +118,7 @@ stse_ReturnCode_t stse_aes_ccm_encrypt(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_ccm_encrypt_start(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 Nonce_length,
     PLAT_UI8 *pNonce,
@@ -144,7 +144,7 @@ stse_ReturnCode_t stse_aes_ccm_encrypt_start(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_ccm_encrypt_process(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
     PLAT_UI16 message_chunk_length,
@@ -165,7 +165,7 @@ stse_ReturnCode_t stse_aes_ccm_encrypt_process(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_ccm_encrypt_finish(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
@@ -192,7 +192,7 @@ stse_ReturnCode_t stse_aes_ccm_encrypt_finish(
  * \details 	\include{doc} stse_aes_ccm_decrypt.dox
  */
 stse_ReturnCode_t stse_aes_ccm_decrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI8 *pNonce,
@@ -221,7 +221,7 @@ stse_ReturnCode_t stse_aes_ccm_decrypt(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_ccm_decrypt_start(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 Nonce_length,
     PLAT_UI8 *pNonce,
@@ -245,7 +245,7 @@ stse_ReturnCode_t stse_aes_ccm_decrypt_start(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_ccm_decrypt_process(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
     PLAT_UI16 message_chunk_length,
@@ -267,7 +267,7 @@ stse_ReturnCode_t stse_aes_ccm_decrypt_process(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_ccm_decrypt_finish(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
@@ -294,7 +294,7 @@ stse_ReturnCode_t stse_aes_ccm_decrypt_finish(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_gcm_encrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 IV_length,
@@ -321,7 +321,7 @@ stse_ReturnCode_t stse_aes_gcm_encrypt(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_gcm_encrypt_start(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 IV_length,
     PLAT_UI8 *pIV,
@@ -343,7 +343,7 @@ stse_ReturnCode_t stse_aes_gcm_encrypt_start(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_gcm_encrypt_process(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
     PLAT_UI16 message_chunk_length,
@@ -364,7 +364,7 @@ stse_ReturnCode_t stse_aes_gcm_encrypt_process(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_gcm_encrypt_finish(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
@@ -391,7 +391,7 @@ stse_ReturnCode_t stse_aes_gcm_encrypt_finish(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_gcm_decrypt(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 IV_length,
@@ -419,7 +419,7 @@ stse_ReturnCode_t stse_aes_gcm_decrypt(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_gcm_decrypt_start(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 slot_number,
     PLAT_UI16 IV_length,
     PLAT_UI8 *pIV,
@@ -441,7 +441,7 @@ stse_ReturnCode_t stse_aes_gcm_decrypt_start(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_gcm_decrypt_process(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,
     PLAT_UI16 message_chunk_length,
@@ -463,7 +463,7 @@ stse_ReturnCode_t stse_aes_gcm_decrypt_process(
  * \return \ref STSE_OK on success ; \ref stse_ReturnCode_t error code otherwise
  */
 stse_ReturnCode_t stse_aes_gcm_decrypt_finish(
-    stse_Handler_t *pSTSE,
+    stse_Handle_t *pSTSE,
     PLAT_UI8 authentication_tag_length,
     PLAT_UI16 associated_data_chunk_length,
     PLAT_UI8 *pAssociated_data_chunk,