X-CUBE-STSE01 Pūmanawa Pūmanawa

Kupu Whakataki

This user manual describes how to get started with the X-CUBE-STSE01 software package.
The X-CUBE-STSE01 software package is a software component that provides several demonstration codes, which use the STSAFE-A110 and STSAFE-A120 device features from a host microcontroller.
These demonstration codes utilize the STSELib (Secured Element middleware) built on the STM32Cube software technology to ease portability across different STM32 microcontrollers. In addition, it is MCU-agnostic for portability to other MCUs.
These demonstration codes illustrate the following features:

• Motuhēhēnga.
• Secured data storage.
• Secured usage counter.
• Takirua.
• Key establishment.
• Local envelope wrapping.
• Key pair generation.

Nga korero whanui

• The X-CUBE-STSE01 software package is a reference to integrate the STSAFE-A110 and STSAFE-A120 secure element services into a host MCU’s operating system (OS) and its application.
• It contains the STSAFE-A110 and STSAFE-A120 driver and demonstration codes to be executed on STM32 32-bit microcontrollers based on the Arm® Cortex®-M processor.
• He tohu rehita a Arm na Arm Limited (me ona apiti ranei) i te US me/ranei i etahi atu waahi.
• The X-CUBE-STSE01 software package is developed in ANSI C. Nevertheless, the platform-independent architecture allows easy portability to a variety of different platforms.
• The table below presents the definition of acronyms that are relevant for a better understanding of this document.

STSAFE-A1x0 secure element

The STSAFE-A110 and STSAFE-A120 are highly secure solution that acts as a secure element providing authentication and data management services to a local or remote host. It consists of a full turnkey solution with a secure operating system running on the latest generation of secure microcontrollers.
The STSAFE-A110 and STSAFE-A120 can be integrated in IoT (Internet of things) devices, smart-home, smart-city and industrial applications, consumer electronics devices, consumables and accessories. Its key features are

• Authentication (of peripherals, IoT and USB Type-C® devices).
• Secure channel establishment with remote host including transport layer security (TLS) handshake.
• Signature verification service (secure boot and firmware upgrade).
• Usage monitoring with secure counters.
• Pairing and secure channel with host application processor.
• Wrapping and unwrapping of local or remote host envelopes.
• On-chip key pair generation.

STSecureElement Library (STSELib) description

This section details the STSELib middleware software package content and the way to use it.

Whakaahuatanga whanui

The STSELib middleware is a set of software components designed to:

• interface the STSAFE-A110 and STSAFE-A120 secure element device with an MCU.
• implement the most generic STSAFE-A110 and STSAFE-A120 use cases.
• The STSELib middleware is fully integrated within ST software packages as a middleware component to add secure element features.
• The STSELib middleware provides a complete set of high-level Application Programming Interface functions to the embedded system developer. This Middleware abstract the build and the sequencing of the commands required to ensure device, accessories and consumable brand protection using STMicroelectronics STSAFE-A secure element family.
• This middleware allows a seamless integration of one or multiple STSAFE-A in various host MCU/MPU ecosystem.
• Tirohia nga korero tuku e waatea ana i te kōpaki pakiaka o te kete mo nga korero mo nga putanga IDE e tautokohia ana.

Hangahanga
The STSELib middleware is composed of three software modules as illustrated in the figure below. Each layer provides a different level of system abstraction to the embedded system developer.

The figure below shows the STSELib middleware integrated in a standard STM32Cube application, running on an X-NUCLEO-SAFEA1 or X-NUCLEO-ESE01A1 expansion board mounted on an STM32 Nucleo board.

Figure 2. X-CUBE-STSE01 application block diagram

To provide the best hardware and platform independence, the STSELib middleware is not directly connected to the STM32Cube HAL, but through interface files implemented at application level

• Application Programming Interface (API) layer
  This software layer is the entry point for the system application. It provides a set of high-level functions allowing interaction with STMicroelectronics Secure Elements. The Api layer provides abstraction for different application like Secure Element Management, Authentication, Data Storage, Key Management.
• Service layer
  The SERVICE layer provides a set of product services that format all commands supported by the targeted secure element and reports response to higher layers API/Application. This layer can be used directly from Application (for advanced user).
• Core layer
  Contains generic definition for ST Secure Element and functions for communicating with target secure element.
  Core layer handles the framing of the messages as well as provides the platform abstraction for the above layers.

Hanganga kōpaki
The figure below presents the folder structure of the X-CUBE-STSE01.

Pūmanawa Whakaaturanga

This section illustrates demonstration software based on the STSELib middleware.

Motuhēhēnga
This demonstration illustrates the command flow where the STSAFE-A110/STSAFE-A120 is mounted on a device that authenticates to a remote host (IoT device case), the local host being used as a pass-through to the remote server.
The scenario where the STSAFE-A110/STSAFE-A120 is mounted on a peripheral that authenticates to a local host, for exampHe rite tonu te ahua mo nga keemu, nga taputapu pūkoro me nga taonga pau.
For demonstration purposes, the local and remote hosts are the same device here.

1. Extract, parse and verify the STSAFE-A110/ STSAFE-A120’s public certificate stored in the data partition zone 0 of the device in order to get the public key:
   • Read the certificate using the STSELib middleware through the STSAFE-A110/STSAFE-A120’s zone 0.
   • Parse the certificate using the cryptographic library’s parser.
   • Read the CA certificate (available through the code).
   • Parse the CA certificate using the cryptographic library’s parser.
   • Verify the certificate validity using the CA certificate through the cryptographic library.
   • Get the public key from the STSAFE-A110/STSAFE-A120 X.509 certificate.
2. Generate and verify the signature over a challenge number:
   • Generate a challenge number (random number).
   • Hash the challenge.
   • Fetch a signature over the hashed challenge using the STSAFE-A110/ STSAFE-A120 private key slot 0 through the STSELib middleware.
   • Parse the generated signature using the cryptographic library.
   • Verify the generated signature using the STSAFE-A110/STSAFE-A120’s public key through the cryptographic library.
   • When this is valid, the host knows that the peripheral or IoT is authentic.

Pairing (Host Key Provisioning)
Tenei waehere example establishes a pairing between an device and the MCU it is connected to. The pairing allows the exchanges between the device and the MCU to be authenticated (that is, signed and verified). The STSAFE-A110 device becomes usable only in combination with the MCU it is paired with.
The pairing consists of the host MCU sending a host MAC key and a host cipher key to the STSAFE-A110 Both keys are stored to the protected NVM of the STSAFE-A110 and should be stored to the flash memory of the STM32 device.
By default, in this example, the host MCU sends well-known keys to the STSAFE-A110 (see command flow below) that are highly recommended to use for demonstration purposes. The code also allows the generation of random keys.
Moreover, the code example generates a local envelope key when the corresponding slot is not already populated in the STSAFE-A110. When the local envelope slot is populated, the STSAFE-A110 device allows the host MCU to wrap/unwrap a local envelope to securely store a key on the host MCU’s side.
Note: The pairing code exampMe mahi angitu i mua i te mahi i nga waehere e whai ake neiamples.

Rere whakahau

1. Generate the local envelope key in the STSAFE-A110 using the STSELib middleware.
   By default, this command is activated
   Ka puta tenei mahi mena kaore ano te mokamoka matua o te kopaki o te rohe o STSAFE-A110 kia kapi.
2. Define two 128-bit numbers to use as the host MAC key and the host cipher key.
   By default, golden known keys are used. They have the following values:
   • Host MAC key
     0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF
   • Host Cipher Key 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF,0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF
3. Store the host MAC key and the host cipher key to their respective slot in the STSAFE-A110/STSAFE-A120.
4. Store the host MAC key and the host cipher key to the STM32’s flash memory.

Key establishment (Symmetric key AES-128 CMAC)
Ko tenei whakaaturanga e whakaatu ana i te keehi i whakauruhia ai te taputapu STSAFE-A110 ki runga i tetahi taputapu (penei i te taputapu IoT), e korero ana ki te tūmau mamao, me te whakarite i tetahi hongere haumaru hei whakawhiti raraunga ki a ia.
I roto i tenei exampNa, ko te taputapu STM32 te mahi a te tūmau mamao (kaiwhakahaere mamao) me te kaihautu rohe e hono ana ki te taputapu STSAFE-A110.
The goal of this use case is to show how to establish a shared secret between the local host and the remote server using the elliptic curve Diffie-Hellman scheme with a static (ECDH) or ephemeral (ECDHE) key in the STSAFE-A110
Ko te mea ngaro tiritiri me ahu mai ano ki tetahi, neke atu ranei o nga taviri mahi (kaore e whakaatuhia ki konei). Ka taea te whakamahi i enei taviri mahi i roto i nga kawa korero penei i te TLS, hei tauiraample mo te tiaki i te muna, te pono me te pono o nga raraunga e whakawhitihia ana i waenga i te kaihautu rohe me te tūmau mamao.

Rere whakahau
The Figure 4. Key establishment command flow illustrates the command flow:

• The remote host’s private and public keys are hard coded in the code example.
• The local host sends the Generate Keypair command to the STSAFE-A110/STSAFE-A120 to generate the key pair on its ephemeral slot (slot 0xFF).
• The STSAFE-A110 sends back the public key (which corresponds to slot 0xFF) to the STM32 (representing the remote host).
• The STM32 computes the remote host’s secret (using the STSAFE device’s public key and the remote host’s private key).
• The STM32 sends the remote host’s public key to the STSAFE-A110/STSAFE-A120 and asks the STSAFE-A110/STSAFE-A120 to compute the local host’s secret using the API.
• The STSAFE-A110/ STSAFE-A120 sends back the local host’s secret to the STM32.
• The STM32 compares the two secrets and prints the result. If the secrets are the same, the secret establishment is successful.

Takaia/ wetekina nga kopaki o te rohe

• This demonstration illustrates the case where the STSAFE-A110/STSAFE-A120 wraps/unwraps the local envelope in order to securely store a secret to any non-volatile memory (NVM).
• Encryption/decryption keys can be securely stored in that manner to additional memory or within the STSAFE-A110/STSAFE-A120’s user data memory.
• The wrapping mechanism is used to protect a secret or plain text. The output of wrapping is an envelope encrypted with an AES key wrap algorithm, and that contains the key or plain text to be protected. Command flow
• The local and remote hosts are the same device here.

1. Generate random data assimilated to a local envelope.
2. Wrap the local envelope using the STSELib middleware API.
3. Store the wrapped envelope.
4.  Unwrap the wrapped envelope using the STSELIB middleware.
5.  Compare the unwrapped envelope to the initial local envelope. They should be equal.

Whakatupuranga takirua matua
This demonstration illustrates the command flow where the STSAFE-A110/STSAFE-A120 device is mounted on a local host. A remote host asks this local host to generate a key pair (a private key and a public key) on slot 1 and then to sign a challenge (random number) with the generated private key.
Ka taea e te kaihautu mamao te manatoko i te hainatanga me te taviri tūmatanui i hangaia.
He rite tenei whakaaturanga ki te whakaaturanga Motuhēhēnga e rua ngā rerekētanga:

• Ko te takirua matua i roto i te whakaaturanga Motuhēhēnga kua oti kē te hanga (i runga i te mokamoka 0), engari, i tenei o muaample, we generate the key pair on slot 1. The STSAFE-A110/STSAFE-A120 device can also generate the key pair on slot 0xFF, but only for key establishment purposes.
• The public key in the Authentication demonstration is extracted from the certificate in zone 0. In this example, the public key is sent back with the STSAFE-A110/STSAFE-A120 response to the Generate Keypair command.

Rere whakahau
For demonstration purposes, the local and remote hosts are the same device here.

1. The host sends the Generate Keypair command to the STSAFE-A110/STSAFE-A120 which sends back the public key to the host MCU.
2. The host generates a challenge (48-byte random number) using the Generate Random API. The STSAFE-A110 sends back the generated random number.
3. The host computes the hash of the generated number using the cryptographic library.
4. The host asks the STSAFE-A110/STSAFE-A120 to generate a signature of the computed hash using the
   Generate Signature API. The STSAFE-A110/ STSAFE-A120 sends back the generated signature.
5. The host verifies the generated signature with the public key sent by the STSAFE-A110/ STSAFE-A120 in step 1.
6. The signature verification result is printed.

Papakupu

Whakapoto	Te tikanga
AES	Paerewa Whakamunatanga Arā Atu Anō
ANSI	American National Standards Institute
API	Atanga papatono tono
BSP	Mōkihi tautoko poari
CA	Mana Tiwhikete
CC	Paearu noa
C-MAC	Command message authentication code
ECC	Whakamupatotanga ānau elliptic
ECDH	Elliptic curve Diffie–Hellman
ECDHE	Elliptic curve Diffie–Hellman – ephemeral
EWARM	IAR Embedded Workbench® for Arm®
HAL	Papanga tangohanga taputapu
I/O	Whakauru/putanga
IAR Systems®	World leader in software tools and services for embedded systems development.
IDE	Integrated development environment. A software application that provides comprehensive facilities to computer programmers for software development.
IoT	Ipurangi o nga mea
I²C	Inter-integrated circuit (IIC)
LL	Low-level drivers
MAC	Message authentication code
MCU	Waehikohikohikohiko
MDK-ARM	Keil® microcontroller development kit for Arm®
MPU	Wae tiaki mahara
NVM	Te mahara korekore
OS	Pūnaha whakahaere
SE	Huānga haumaru
SHA	Secure Hash algorithm
SLA	Whakaaetanga raihana rorohiko
ST	STMicroelectronics
TLS	Haumarutanga Paparanga Waka
USB	Pahi Tuturu Ao

Hītori arotakenga

Rā	Arotakenga	Huringa
23-Hune-2025	1	Tukunga tuatahi.

WHAKAMAHI WHAKAMAHI - KAUPAPA KAUPAPA

• Ko te STMicroelectronics NV me ona apiti ("ST") te mana ki te whakarereke, whakatikatika, whakapainga, whakarereke me nga whakapainga ki nga hua ST me tenei tuhinga ranei i nga wa katoa kaore he panui. Me whiwhi nga kaihoko i nga korero hou e pa ana ki nga hua ST i mua i te tuku ota. Ka hokona nga hua ST i runga i nga tikanga me nga tikanga o te hokonga a ST i te wa o te ota whakaae.
• Ko nga Kaihoko anake te kawenga mo te kowhiringa, te kowhiringa me te whakamahi i nga hua ST me te ST karekau he kawenga mo te awhina tono me te hoahoa o nga hua a nga kaihoko.
• Karekau he raihana, he mea whakaatu, he tohu ranei, ki tetahi mana taonga hinengaro ka tukuna e ST i konei.
• Ko te hokonga ano o nga hua ST me nga tikanga rereke mai i nga korero kua whakatakotoria i konei ka whakakorehia he raihana kua tukuna e ST mo taua hua.
• Ko te ST me te tohu ST he tohu tohu na ST. Mo etahi atu korero mo nga tohu hokohoko ST, tirohia www.st.com/marks. Ko etahi atu ingoa hua, ingoa ratonga ranei no ratou ake rangatira.
• Ko nga korero kei roto i tenei tuhinga ka whakakapi me te whakakapi i nga korero i tukuna i mua i nga momo putanga o mua o tenei tuhinga.
• © 2025 STMicroelectronics – Pūmau te mana

Tuhinga / Rauemi

ST X-CUBE-STSE01 Software Package [pdf] Pukapuka Kaiwhakamahi X-CUBE-STSE01 Software Package, Software Package, Software

Tohutoro

• Pukapuka Kaiwhakamahi