X-CUBE-STSE01 Software Package User Manual

X-CUBE-STSE01 Software Package

“

“`

UM3490
User manual
Getting started with the X-CUBE-STSE01 software package
Introduction
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: · Authentication. · Secured data storage. · Secured usage counter. · Pairing. · Key establishment. · Local envelope wrapping. · Key pair generation.

UM3490 – Rev 1 – June 2025 For further information, contact your local STMicroelectronics sales office.

www.st.com

1
Note:

UM3490
General information
General information
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 32bit microcontrollers based on the Arm® Cortex®-M processor. Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. 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.

UM3490 – Rev 1

page 2/12

UM3490
STSAFE-A1x0 secure element

2

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, smartcity 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.

UM3490 – Rev 1

page 3/12

UM3490
STSecureElement Library (STSELib)description

3

STSecureElement Library (STSELib) description

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

3.1

General description

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.

Refer to the release notes available in the package root folder for information about the supported IDE versions.

3.2

Architecture

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.

Figure 1. STSELib architecture

UM3490 – Rev 1

page 4/12

UM3490
STSecureElement Library (STSELib)description
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

3.3

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.

3.4

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).

3.5

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.

UM3490 – Rev 1

page 5/12

UM3490
STSecureElement Library (STSELib)description

3.6

Folder structure

The figure below presents the folder structure of the X-CUBE-STSE01.

Figure 3. Project file structure

UM3490 – Rev 1

page 6/12

4
4.1
Note:
4.2
Note:

UM3490
Demonstration software
Demonstration software
This section illustrates demonstration software based on the STSELib middleware.
Authentication
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 example for games, mobile accessories or consumables, is exactly the same. 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)
This code 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 STSAFEA110 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 example must be executed successfully prior to executing all the following code examples.
Command flow

UM3490 – Rev 1

page 7/12

UM3490
Demonstration software

1. Generate the local envelope key in the STSAFE-A110 using the STSELib middleware. By default, this command is activated This operation occurs only if the STSAFE-A110’s local envelope key slot is not already populated.
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.

4.3

Key establishment (Symmetric key AES-128 CMAC)

This demonstration illustrates the case where the STSAFE-A110 device is mounted on a device (such as an IoT device), which communicates with a remote server, and needs to establish a secure channel to exchange data with it.

In this example, the STM32 device plays the role of both the remote server (remote host) and the local host that is connected to the STSAFE-A110 device.

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

The shared secret should be further derived to one or more working keys (not illustrated here). These working keys can then be used in communication protocols such as TLS, for example for protecting the confidentiality, integrity and authenticity of the data that are exchanged between the local host and the remote server.

Command flow

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.

Figure 4. Key establishment command flow

UM3490 – Rev 1

page 8/12

UM3490
Demonstration software

4.4
Note:

Wrap/unwrap local envelopes
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.

4.5

Key pair generation

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.

The remote host is then able to verify the signature with the generated public key.

This demonstration is similar to the Authentication demonstration with two differences:

·

The key pair in the Authentication demonstration is already generated (on slot 0), whereas, in this example,

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.

Command flow

Note:

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.

UM3490 – Rev 1

page 9/12

UM3490
Glossary

5

Glossary

Table 1. Glossary

Abbreviation Meaning

AES

Advanced encryption standard

ANSI

American National Standards Institute

API

Application programming interface

BSP

Board support package

CA

Certification Authority

CC

Common Criteria

C-MAC

Command message authentication code

ECC

Elliptic curve cryptography

ECDH

Elliptic curve Diffie­Hellman

ECDHE Elliptic curve Diffie­Hellman – ephemeral

EWARM IAR Embedded Workbench® for Arm®

HAL

Hardware abstraction layer

I/O

Input/output

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

Internet of things

I²C

Inter-integrated circuit (IIC)

LL

Low-level drivers

MAC

Message authentication code

MCU

Microcontroller unit

MDK-ARM Keil® microcontroller development kit for Arm®

MPU

Memory protection unit

NVM

Nonvolatile memory

OS

Operating system

SE

Secure element

SHA

Secure Hash algorithm

SLA

Software license agreement

ST

STMicroelectronics

TLS

Transport layer security

USB

Universal serial bus

UM3490 – Rev 1

page 10/12

Revision history
Date 23-Jun-2025

Table 2. Document revision history

Revision 1

Initial release.

Changes

UM3490

UM3490 – Rev 1

page 11/12

UM3490
IMPORTANT NOTICE ­ READ CAREFULLY STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgment. Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of purchasers’ products. No license, express or implied, to any intellectual property right is granted by ST herein. Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product. ST and the ST logo are trademarks of ST. For additional information about ST trademarks, refer to www.st.com/trademarks. All other product or service names are the property of their respective owners. Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2025 STMicroelectronics ­ All rights reserved

UM3490 – Rev 1

page 12/12

Documents / Resources

ST X-CUBE-STSE01 Software Package [pdf] User Manual X-CUBE-STSE01 Software Package, Software Package, Software

References

• User Manual