STMicroelectronics X-CUBE-SAFEA1 Software Package User Guide

UM2646
User manual
Getting started with the X-CUBE-SAFEA1 software package
Introduction
This user manual describes how to get started with the X-CUBE-SAFEA1 software package.
The X-CUBE-SAFEA1 software package is a software component that provides several demonstration codes, which use the
STSAFE-A110 device features from a host microcontroller.
These demonstration codes utilize the STSAFE-A1xx 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
Pairing
Key establishment
Local envelope wrapping
Key pair generation
UM2646 - Rev 4 - March 2024
For further information contact your local STMicroelectronics sales office.
www.st.com
UM2646
General information
1
General information
The X-CUBE-SAFEA1 software package is a reference to integrate the STSAFE-A110 secure element services
into a host MCU's operating system (OS) and its application.
It contains the STSAFE-A110 driver and demonstration codes to be executed on STM32 32-bit microcontrollers
based on the Arm® Cortex®-M processor.
Note:
Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.
The X-CUBE-SAFEA1 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.
Note:
STSAFE-A1xx software package is integrated in X-CUBE-SAFEA1 v1.2.1 as middleware and it is integrated as
BSP for the software pack for the STM32CubeMX.
UM2646 - Rev 4
page 2/23
UM2646
STSAFE-A110 secure element
2
STSAFE-A110 secure element
The STSAFE-A110 is a 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 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
Refer to the STSAFE-A110 datasheet available on the STSAFE-A110 web page for additional information on the
device.
UM2646 - Rev 4
page 3/23
UM2646
STSAFE-A1xx middleware description
3
STSAFE-A1xx middleware description
This section details the STSAFE-A1xx middleware software package content and the way to use it.
3.1
General description
The STSAFE-A1xx middleware is a set of software components designed to:
•
•
interface the STSAFE-A110 secure element device with an MCU
implement the most generic STSAFE-A110 use cases
The STSAFE-A1xx middleware is fully integrated within ST software packages as a middleware component to
add secure element features (for example X-CUBE-SBSFU or X-CUBE-SAFEA1).
It can be downloaded from the STSAFE-A110 internet page through the Tools & Software tab or can be
downloaded from STM32CubeMX.
The software is provided as source code under an ST software license agreement (SLA0088) (see License
information for more details).
The following integrated development environments are supported:
•
IAR Embedded Workbench® for Arm® (EWARM)
•
•
•
Keil® Microcontroller Development Kit (MDK-ARM)
STM32Cube IDE (STM32CubeIDE)
System Workbench for STM32 (SW4STM32) supported in X-CUBE-SAFEA1 v1.2.1 package only
Refer to the release notes available in the package root folder for information about the supported IDE versions.
3.2
Architecture
This section describes the software components of the STSAFE-A1xx middleware software package.
The figure below presents a view of the STSAFE-A1xx middleware architecture and related interfaces.
Figure 1. STSAFE-A1xx architecture
SERVICE
CRYPTO
Isolated area
Suitable for protection by
MCU security features
(MPU, Firewall, TrustZone®, etc.)
Mbed™ TLS
SHA/AES
CORE
Cryptographic service interface
STSAFE-A1xx API
(core interface)
X-CUBECRYPTOLIB
Hardware service interface
UM2646 - Rev 4
page 4/23
UM2646
STSAFE-A1xx middleware description
The middleware features three different interfaces:
•
•
•
•
Note:
UM2646 - Rev 4
STSAFE-A1xx API: It is the main application programming interface (API), which provides full access to all
the STSAFE-A110 services exported to the upper layers (application, libraries and stacks). This interface is
also referred to as the core interface because all the exported APIs are implemented in the CORE module.
The upper layers that need to integrate the STSAFE-A1xx middleware must access the STSAFE-A110
features through this interface.
Hardware service interface: This interface is used by the STSAFE-A1xx middleware to reach the highest
hardware platform independence. It includes a set of generic functions to connect the specific MCU, IO bus
and timing functions. This structure improves the library code re-usability and guarantees easy portability to
other devices.
Defined as weak functions, these generic functions must be implemented at application level following the
example provided within the stsafea_service_interface_template.c template provided for easy integration
and customization within the upper layers.
Cryptographic service interface: This interface is used by the STSAFE-A1xx middleware to access
platform or library cryptographic functions such as SHA (secure hash algorithm) and AES (advanced
encryption standard) required by the middleware for some demonstrations.
Defined as weak functions, these cryptographic functions must be implemented at application level
following the example provided with two different templates:
–
stsafea_crypto_mbedtls_interface_template.c if the Arm® Mbed™ TLS cryptographic library is used;
–
stsafea_crypto_stlib_interface_template.c if the ST cryptographic library is used;
Alternative cryptographic libraries can be used by simply customizing the template source files. The
template files are provided for easy integration and customization within the upper layers.
Arm and Mbed are registered trademarks or trademarks of Arm Limited (or its subsidiaries) in the US and/or
elsewhere.
page 5/23
UM2646
STSAFE-A1xx middleware description
The figure below shows the STSAFE-A1xx middleware integrated in a standard STM32Cube application, running
on an X-NUCLEO-SAFEA1 expansion board mounted on an STM32 Nucleo board.
Figure 2. STSAFE-A1xx application block diagram
STSAFE-A1xx middleware in an STM32Cube application
X-CUBE-SAFEA1 block diagram for STM32CubeMX
To provide the best hardware and platform independence, the STSAFE-A1xx middleware is not directly connected
to the STM32Cube HAL, but through interface files implemented at application level
(stsafea_service_interface_template.c, stsafea_interface_conf.h).
UM2646 - Rev 4
page 6/23
UM2646
STSAFE-A1xx middleware description
3.3
CORE module
The CORE module is the core of the middleware. It implements the commands called by the upper layers
(application, libraries, stack and so on) in order to properly use the STSAFE-A1xx features.
The figure below presents a view of the CORE module architecture.
Figure 3. CORE module architecture
External upper layers
(application, libraries, stacks, etc.)
CORE
CRYPTO
internal
module
SERVICE
internal module
The CORE module is a multi-interface software component connected to:
•
•
•
Upper layers: external connection through the exported APIs described in the two tables below;
Cryptographic layer: internal connection to the CRYPTO module;
Hardware service layer: internal connection to the SERVICE module;
The STSAFE-A1xx middleware software package provides a complete API documentation of the CORE module
in the root folder (see STSAFE-A1xx_Middleware.chm file).
Refer to the STSAFE-A110 datasheet for a brief explanation of the command set, to which the command APIs
listed in the following table are related.
Table 1. CORE module exported API
API category
Initialization configuration
Function
StSafeA_Init
To create, initialize and assign the STSAFE-A1xx device handle.
StSafeA_GetVersion
To return the STSAFE-A1xx middleware revision.
StSafeA_Echo
To receive the data passed in the command.
General-purpose
commands
StSafeA_Reset
To reset the volatile attributes to their initial values.
StSafeA_GenerateRandom
To generates a number of random bytes.
StSafeA_Hibernate
To put the STSAFE-Axxx device in hibernation.
Data partition commands
UM2646 - Rev 4
StSafeA_DataPartitionQuery
page 7/23
UM2646
STSAFE-A1xx middleware description
API category
Function
Query command to retrieve the data partition configuration.
StSafeA_Decrement
To decrement the one-way counter in a counter zone.
Data partition commands
StSafeA_Read
To read data from a data partition zone.
StSafeA_Update
To update data through zone partition.
StSafeA_GenerateSignature
To return the ECDSA signature over a message digest.
StSafeA_GenerateKeyPair
Private and public key
commands
To generate a key-pair in a private key slot.
StSafeA_VerifyMessageSignature
To verify the message authentication.
StSafeA_EstablishKey
To establish a shared secret between two hosts by using asymmetric cryptography.
StSafeA_ProductDataQuery
Query command to retrieve the product data.
StSafeA_I2cParameterQuery
Query command to retrieve the I²C address and low-power mode configuration.
StSafeA_LifeCycleStateQuery
Query command to retrieve the lifecycle state (Born, Operational, Terminated, Born and Locked
or Operational and Locked).
StSafeA_HostKeySlotQuery
Query command to retrieve the host key information (presence and host C-MAC counter).
Administrative commands
StSafeA_PutAttribute
To put attributes in the STSAFE-Axxx device, such as keys, password, I²C parameters according
to the attribute TAG.
StSafeA_DeletePassword
To delete the password from its slot.
StSafeA_VerifyPassword
To verify the password and remember the outcome of the verification for future command
authorization.
StSafeA_RawCommand
To execute a raw command and receive the related response.
StSafeA_LocalEnvelopeKeySlotQuery
Query command to retrieve local envelope key information (slot number, presence and key
length) for the available key slots.
StSafeA_GenerateLocalEnvelopeKey
Local envelope commands
To generate a key in a local envelope key slot.
StSafeA_WrapLocalEnvelope
To wrap data (usually keys) that are entirely managed by the host, with a local envelope key and
the [AES key wrap] algorithm.
StSafeA_UnwrapLocalEnvelope
To unwrap a local envelope with a local envelope key.
UM2646 - Rev 4
page 8/23
UM2646
STSAFE-A1xx middleware description
Table 2. Exported STSAFE-A110 CORE module APIs
API category
Command authorization
configuration command
3.4
Function
StSafeA_CommandAuthorizationConfigurationQuery
Query command to retrieve access conditions for commands with configurable access
conditions.
SERVICE module
The SERVICE module is the low layer of the middleware. It implements a full hardware abstraction in terms of
MCU and hardware platform.
The figure below presents a view of the SERVICE module architecture.
Figure 4. SERVICE module architecture
CORE
internal module
SERVICE
External lower layers
(BSP, HAL, LL, etc.)
The SERVICE module is a dual-interface software component connected to:
•
•
External lower layers: such as BSP, HAL or LL. Weak functions must be implemented at external higher
layers and are based on the stsafea_service_interface_template.c template file;
Core layer: internal connection to the CORE module through the exported APIs described in the table
below;
The STSAFE-A1xx middleware software package provides a complete API documentation of the SERVICE
module in the root folder (see STSAFE-A1xx_Middleware.chm file).
Table 3. SERVICE module exported APIs
API category
Initialization configuration
Function
StSafeA_BSP_Init
To initialize the communication bus and the IO pins needed to operate the STSAFE-Axxx device.
StSafeA_Transmit
Low-level operation
functions
To prepare the command to be transmitted, and call the low-level bus API to be executed.
Compute and concatenate a CRC, if supported.
StSafeA_Receive
To receive data from the STSAFE-Axxx by using the low-level bus functions to retrieve
them.Check the CRC, if supported.
UM2646 - Rev 4
page 9/23
UM2646
STSAFE-A1xx middleware description
3.5
CRYPTO module
The CRYPTO module represents the cryptographic part of the middleware. It must rely on the platform's
cryptographic resources.
The CRYPTO module is completely independent of the other middleware modules and, for this reason, can be
easily encapsulated inside an isolated secure area suited to protection by MCU security features such as a
memory protection unit (MPU), a firewall or a TrustZone®.
The figure below presents a view of the CRYPTO module architecture.
Figure 5. CRYPTO module architecture
CORE
internal module
CRYPTO
External cryptographic
layers
(Mbed™ TLS,
X-CUBE-CRYPTOLIB)
The CRYPTO module is a dual-interface software component connected to:
•
an external cryptography library: Mbed TLS and X-CUBE-CRYPTOLIB are currently supported. Weak
functions must be implemented at external higher layers and are based on the:
–
–
•
stsafea_crypto_mbedtls_interface_template.c template file for the Mbed TLS cryptographic library;
stsafea_crypto_stlib_interface_template.c template file for the ST cryptographic library;
Additional cryptographic libraries can be easily supported by adapting the cryptographic interface
template file.
the core layer: internal connection to the CORE module through the exported APIs described in the table
below;
The STSAFE-A1xx middleware software package provides a complete API documentation of the CRYPTO
module in the root folder (see STSAFE-A1xx_Middleware.chm file).
Table 4. CRYPTO module exported APIs
API category
Function
StSafeA_ComputeCMAC
To compute the CMAC value. Used on the prepared command.
StSafeA_ComputeRMAC
To compute the RMAC value. Used on the received response.
StSafeA_DataEncryption
Cryptographic APIs To execute data encryption (AES CBC) on the STSAFE-Axxx data buffer.
StSafeA_DataDecryption
To execute data decryption (AES CBC) on the STSAFE-Axxx data buffer.
StSafeA_MAC_SHA_PrePostProcess
To pre- or post-process the MAC and/or SHA before transmission, or after reception of data from the
STSAFE_Axxx device.
UM2646 - Rev 4
page 10/23
UM2646
STSAFE-A1xx middleware description
3.6
Templates
This section gives a detail description of the templates available within the STSAFE-A1xx middleware software
package.
All the templates listed in the table below are provided inside the Interface folder available at the root level of
the middleware software package.
Template files are provided as examples to be copied and customized into the upper layers, in order to easily
integrate and configure the STSAFE-A1xx middleware:
•
•
Interface template files provide example implementations of the __weak functions, offered as empty or
partially empty functions inside the middleware. They must be properly implemented in the user space or in
the upper layers according to the cryptographic library and to the user's hardware choices.
Configuration template files provide an easy way to configure the STSAFE-A1xx middleware and features
that can be used in the user application, such as optimizations or specific hardware.
Table 5. Templates
Template
category
Template file
stsafea_service_interface_template.c
Example template to show how to support the hardware services required by the STSAFE-A middleware
and offered by the specific hardware, low-level library or BSP selected in the user space.
stsafea_crypto_mbedtls_interface_template.c
Interface
templates
Example template to show how to support the cryptographic services required by the STSAFE-A
middleware and offered by the Mbed TLS cryptographic library (key management, SHA, AES, etc.).
stsafea_crypto_stlib_interface_template.c
Example template to show how to support the cryptographic services required by the STSAFE-A
middleware and offered by the STM32 cryptographic library software expansion for STM32Cube (XCUBE-CRYPTOLIB) (key management, SHA, AES, etc.).
stsafea_conf_template.h
Configuration
templates
Example template to show how to configure the STSAFE-A middleware (in particular for optimizations
purposes).
stsafea_interface_conf_template.h
Example template to show how to configure and customize the interface files listed above.
Note:
UM2646 - Rev 4
The above templates are only present in the BSP folder of the X-CUBE-SAFEA1 package.
page 11/23
UM2646
STSAFE-A1xx middleware description
3.7
Folder structure
The figure below presents the folder structure of the STSAFE-A1xx middleware software package v1.2.1.
Figure 6. Project file structure
Project file structure STSAFE-A1xx middleware
Project file structure for X-CUBE-SAFEA1 for STM32CubeMX
UM2646 - Rev 4
page 12/23
UM2646
STSAFE-A1xx middleware description
3.8
How to: integration and configuration
This section describes how to integrate and configure the STSAFE-A1xx middleware in the user application.
3.8.1
Integration steps
Follow these steps to integrate the STSAFE-A1xx middleware in the desired application:
•
•
•
•
3.8.2
Step 1: Copy (and optionally rename) the stsafea_service_interface_template.c file and either of
stsafea_crypto_mbedtls_interface_template.c or stsafea_crypto_stlib_interface_template.c to the user
space according to the cryptographic library that has been added to the application (whatever the
cryptographic library selected/used by users, they can even create/implement their own cryptographic
interface file from scratch by adapting the suitable template).
Step 2: Copy (and optionally rename) the stsafea_conf_template.h and stsafea_interface_conf_template.h
files to the user space.
Step 3: Make sure to add the right includes in your main or any other user space source file that needs to
interface the STSAFE-A1xx middleware:
#include "stsafea_core.h" #include "stsafea_interface_conf.h"
Step 4: Customize the files used in the three steps above according to user preferences.
Configuration steps
In order to properly configure the STSAFE-A1xx middleware in the user application, ST provide two different
configuration template files to be copied and customized in the user space according to the user's choices:
•
•
stsafea_interface_conf_template.h: This example template is used to and shows how to configure the
cryptographic and service middleware interfaces in the user space through the following #define
statements:
–
USE_PRE_LOADED_HOST_KEYS
–
MCU_PLATFORM_INCLUDE
–
MCU_PLATFORM_BUS_INCLUDE
–
MCU_PLATFORM_CRC_INCLUDE
stsafea_conf_template.h: This example template is used to and shows how to configure the STSAFE-A
middleware through the following #define statements:
–
STSAFEA_USE_OPTIMIZATION_SHARED_RAM
–
STSAFEA_USE_OPTIMIZATION_NO_HOST_MAC_ENCRYPT
–
STSAFEA_USE_FULL_ASSERT
–
USE_SIGNATURE_SESSION (for the STSAFE-A100 only)
Follow these steps in order to integrate the STSAFE-A1xx middleware in the desired application:
•
•
UM2646 - Rev 4
Step 1: Copy (and optionally rename) the stsafea_interface_conf_template.h and stsafea_conf_template.h
files to the user space.
Step 2: Confirm or modify the #define statement of the two above-mentioned header files according to
the user platform and cryptographic choices.
page 13/23
UM2646
Demonstration software
4
Demonstration software
This section illustrates demonstration software based on the STSAFE-A1xx middleware.
4.1
Authentication
This demonstration illustrates the command flow where the STSAFE-A110 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 is mounted on a peripheral that authenticates to a local host, for example
for games, mobile accessories or consumables, is exactly the same.
Command flow
Note:
For demonstration purposes, the local and remote hosts are the same device here.
1. Extract, parse and verify the STSAFE-A110’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 STSAFE-A1xx middleware through the STSAFE-A110’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 X.509 certificate.
2. Generate and verify the signature over a challenge number:
–
–
–
–
–
–
4.2
Generate a challenge number (random number).
Hash the challenge.
Fetch a signature over the hashed challenge using the STSAFE-A110’s private key slot 0 through the
STSAFE-A1xx middleware.
Parse the generated signature using the cryptographic library.
Verify the generated signature using the STSAFE-A110’s public key through the cryptographic library.
When this is valid, the host knows that the peripheral or IoT is authentic.
Pairing
This code example establishes a pairing between an STSAFE-A110 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 example must be executed successfully prior to executing all the following code examples.
Command flow
1. Generate the local envelope key in the STSAFE-A110 using the STSAFE-A1xx middleware.
By default, this command is activated. Be aware that uncommenting the following define statements in the pa
iring.c file deactivates the local envelope key generation:
/* #define _FORCE_DEFAULT_FLASH_ */
This operation occurs only if the STSAFE-A110’s local envelope key slot is not already populated.
UM2646 - Rev 4
page 14/23
UM2646
Demonstration software
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:
0x00,0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88,0x99,0xAA,0xBB,0xCC,0xDD,0xEE,0xFF /
* Host MAC key */
0x11,0x11,0x22,0x22,0x33,0x33,0x44,0x44,0x55,0x55,0x66,0x66,0x77,0x77,0x88,0x88 /
* Host cipher key */
To activate random key generation, add the following define statement to the pairing.c file:
#define USE_HOST_KEYS_SET_BY_PAIRING_APP 1
3. Store the host MAC key and the host cipher key to their respective slot in the STSAFE-A110.
4. Store the host MAC key and the host cipher key to the STM32's flash memory.
4.3
Key establishment (establish secret)
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
Figure 7. Key establishment command flow illustrates the command flow.
•
•
•
•
•
•
•
UM2646 - Rev 4
The remote host’s private and public keys are hard-coded in the code example.
The local host sends the StSafeA_GenerateKeyPair command to the STSAFE-A110 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 and asks the STSAFE-A110 to
compute the local host’s secret using the StSafeA_EstablishKey API.
The STSAFE-A110 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.
page 15/23
UM2646
Demonstration software
Figure 7. Key establishment command flow
Remote host
STM32
Local host
STSAFE
Generate Key Pair
Generate Key Pair on slot 0xFF
Calculating the remote host’s
secret (using the remote host’s
private key and the local host’s
(STSAFE slot 0xFF) public key)
Generated STSAFE’s public key
STSAFE’s public key generated on
slot 0xFF
Remote host’s public key
Establish Key (remote Host’s
public key)
Remote host’s
secret
4.4
STM32 compares the
remote host secret to the
local host secret and
prints the result
Sending the local host’s secret
Calculating the local host’s
secret (using the local host’s
private key (STSAFE slot
0xFF) and the remote host’s
public key)
Local host’s
secret
Wrap/unwrap local envelopes
This demonstration illustrates the case where the STSAFE-A110 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 STSAFEA110'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
Note:
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 STSAFE-A110’s middleware.
3. Store the wrapped envelope.
4. Unwrap the wrapped envelope using the STSAFE-A110’s 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 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:
•
•
UM2646 - Rev 4
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 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's response to the
StSafeA_GenerateKeyPair command.
page 16/23
UM2646
Demonstration software
Command flow
Note:
For demonstration purposes, the local and remote hosts are the same device here.
1. The host sends the StSafeA_GenerateKeyPair command to the STSAFE-A110, which sends back the
public key to the host MCU.
2. The host generates a challenge (48-byte random number) using the StSafeA_GenerateRandom 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 to generate a signature of the computed hash using the
StSafeA_GenerateSignature API. The STSAFE-A110 sends back the generated signature.
5. The host verifies the generated signature with the public key sent by the STSAFE-A110 in step 1.
6. The signature verification result is printed.
UM2646 - Rev 4
page 17/23
UM2646
Revision history
Table 6. Document revision history
Date
Revision
Changes
09-Dec-2019
1
Initial release.
13-Jan-2020
2
Removed Licence information section.
Updated list of features illustrated by demonstration codes in Introduction.
Removed List of acronyms table and inserted glossary at the end.
Small text change and updated colors in Figure 1. STSAFE-A1xx architecture.
Updated Figure 2. STSAFE-A1xx application block diagram.
Updated Table 1. CORE module exported API.
07-Feb-2022
3
Removed StSafeA_InitHASH and StSafeA_ComputeHASH from Table 4. CRYPTO module exported
APIs.
Updated Section 3.8.2: Configuration steps.
Updated Section 4.2: Pairing.
Updated Section 4.3: Key establishment (establish secret).
Added Section 4.5: Key pair generation.
Small text changes.
07-Mar-2024
4
Added STSAFE-A1xx software package is integrated in X-CUBE-SAFEA1 v1.2.1 as middleware
and it is integrated as BSP for the software pack for the STM32CubeMX. and The above templates
are only present in the BSP folder of the X-CUBE-SAFEA1 package..
Updated Section 3.1: General description, Section 3.2: Architecture and Section 3.7: Folder
structure.
UM2646 - Rev 4
page 18/23
UM2646
Glossary
Glossary
AES Advanced encryption standard
OS Operating system
ANSI American National Standards Institute
SE Secure element
API Application programming interface
SHA Secure Hash algorithm
BSP Board support package
SLA Software license agreement
CA Certification Authority
ST STMicroelectronics
CC Common Criteria
TLS Transport layer security
C-MAC Command message authentication code
USB Universal serial bus
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
UM2646 - Rev 4
page 19/23
UM2646
Contents
Contents
1
General information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2
STSAFE-A110 secure element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3
STSAFE-A1xx middleware description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4
3.1
General description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.3
CORE module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.4
SERVICE module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.5
CRYPTO module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.6
Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.7
Folder structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.8
How to: integration and configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.8.1
Integration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.8.2
Configuration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Demonstration software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
4.1
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2
Pairing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3
Key establishment (establish secret) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.4
Wrap/unwrap local envelopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.5
Key pair generation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
List of tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
List of figures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
UM2646 - Rev 4
page 20/23
UM2646
List of tables
List of tables
Table 1.
Table 2.
Table 3.
Table 4.
Table 5.
Table 6.
CORE module exported API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Exported STSAFE-A110 CORE module APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
SERVICE module exported APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
CRYPTO module exported APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
UM2646 - Rev 4
page 21/23
UM2646
List of figures
List of figures
Figure 1.
Figure 2.
Figure 3.
Figure 4.
Figure 5.
Figure 6.
Figure 7.
UM2646 - Rev 4
STSAFE-A1xx architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
STSAFE-A1xx application block diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
CORE module architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
SERVICE module architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
CRYPTO module architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Project file structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Key establishment command flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
page 22/23
UM2646
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.
© 2024 STMicroelectronics – All rights reserved
UM2646 - Rev 4
page 23/23
">