Skip to content

Dev/v1.2.0 auth refactor #81

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Grolleau-Benjamin wants to merge 3 commits into
base: dev/1.2.0
Choose a base branch
from
Open

Dev/v1.2.0 auth refactor #81

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6da3a36
[doc] fix link to stsafe-a120-sdk
Grom- Mar 25, 2026
5a7bbd7
[doc] introduce CHANGELOG file
Grolleau-Benjamin Apr 9, 2026
dc93a1c
[core, services] move session keys to platform secure storage
Grolleau-Benjamin Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
41 changes: 41 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
7 changes: 6 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
4 changes: 2 additions & 2 deletions core/stse_device.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,8 +161,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;
Expand Down
9 changes: 9 additions & 0 deletions core/stse_generic_typedef.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,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
Expand Down
51 changes: 29 additions & 22 deletions core/stse_platform.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);

/*!
Expand Down Expand Up @@ -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) */

Expand Down
24 changes: 9 additions & 15 deletions services/stsafea/stsafea_sessions.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,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) {
Expand Down Expand Up @@ -76,8 +76,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;

Expand Down Expand Up @@ -164,8 +164,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) {
Expand Down Expand Up @@ -196,8 +195,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) {
Expand Down Expand Up @@ -256,8 +254,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);

Expand All @@ -271,8 +268,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);

Expand Down Expand Up @@ -328,8 +324,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;
Expand Down Expand Up @@ -420,8 +415,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 */
Expand Down
20 changes: 11 additions & 9 deletions services/stsafea/stsafea_sessions.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down