Pakej Perisian X-CUBE-STSE01

pengenalan

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:

• Pengesahan.
• Secured data storage.
• Secured usage counter.
• Berpasangan.
• Key establishment.
• Local envelope wrapping.
• Key pair generation.

Maklumat am

• 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.
• Arm ialah tanda dagangan berdaftar Arm Limited (atau anak syarikatnya) di AS dan/atau di tempat lain.
• 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.

Unsur selamat STSAFE-A1x0

STSAFE-A110 dan STSAFE-A120 adalah penyelesaian yang sangat selamat yang bertindak sebagai elemen selamat yang menyediakan perkhidmatan pengesahan dan pengurusan data kepada hos tempatan atau jauh. Ia terdiri daripada penyelesaian turnkey penuh dengan sistem pengendalian selamat yang dijalankan pada generasi terkini mikropengawal selamat.
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

• Pengesahan (peranti, IoT dan peranti USB Type-C®).
• Penubuhan saluran selamat dengan hos jauh termasuk jabat tangan keselamatan lapisan pengangkutan (TLS).
• Perkhidmatan pengesahan tandatangan (but selamat dan peningkatan perisian tegar).
• Pemantauan penggunaan dengan kaunter selamat.
• Memadankan dan melindungi saluran dengan pemproses aplikasi hos.
• Membungkus dan membuka sampul surat hos tempatan atau jauh.
• Penjanaan pasangan kunci pada cip.

Perihalan Perpustakaan STSecureElement (STSELib).

Bahagian ini memperincikan kandungan pakej perisian middleware STSELib dan cara menggunakannya.

Penerangan umum

Perisian tengah STSELib ialah satu set komponen perisian yang direka untuk:

• antara muka peranti elemen selamat STSAFE-A110 dan STSAFE-A120 dengan MCU.
• melaksanakan kes penggunaan STSAFE-A110 dan STSAFE-A120 yang paling generik.
• Perisian tengah STSELib disepadukan sepenuhnya dalam pakej perisian ST sebagai komponen perisian tengah untuk menambah ciri elemen selamat.
• Perisian tengah STSELib menyediakan satu set lengkap fungsi Antara Muka Pengaturcaraan Aplikasi peringkat tinggi kepada pembangun sistem terbenam. Middleware ini mengabstrak binaan dan penjujukan arahan yang diperlukan untuk memastikan peranti, aksesori dan perlindungan jenama boleh guna menggunakan keluarga elemen selamat STMicroelectronics STSAFE-A.
• Perisian tengah ini membenarkan penyepaduan lancar satu atau berbilang STSAFE-A dalam pelbagai ekosistem MCU/MPU hos.
• Rujuk nota keluaran yang tersedia dalam folder akar pakej untuk maklumat tentang versi IDE yang disokong.

Seni bina
Perisian tengah STSELib terdiri daripada tiga modul perisian seperti yang digambarkan dalam rajah di bawah. Setiap lapisan menyediakan tahap abstraksi sistem yang berbeza kepada pembangun sistem terbenam.

Rajah di bawah menunjukkan perisian tengah STSELib yang disepadukan dalam aplikasi STM32Cube standard, berjalan pada papan pengembangan X-NUCLEO-SAFEA1 atau X-NUCLEO-ESE01A1 yang dipasang pada papan Nukleo STM32.

Rajah 2. Gambar rajah blok aplikasi X-CUBE-STSE01

Untuk memberikan kebebasan perkakasan dan platform terbaik, perisian tengah STSELib tidak disambungkan terus ke HAL STM32Cube, tetapi melalui antara muka files dilaksanakan di peringkat aplikasi

• Lapisan Antara Muka Pengaturcaraan Aplikasi (API).
  Lapisan perisian ini adalah titik masuk untuk aplikasi sistem. Ia menyediakan satu set fungsi peringkat tinggi yang membolehkan interaksi dengan Elemen Selamat STMicroelectronics. Lapisan Api menyediakan abstraksi untuk aplikasi yang berbeza seperti Pengurusan Elemen Selamat, Pengesahan, Penyimpanan Data, Pengurusan Kunci.
• Lapisan perkhidmatan
  Lapisan SERVICE menyediakan satu set perkhidmatan produk yang memformat semua perintah yang disokong oleh elemen selamat yang disasarkan dan melaporkan respons kepada API/Aplikasi lapisan yang lebih tinggi. Lapisan ini boleh digunakan terus dari Aplikasi (untuk pengguna lanjutan).
• Lapisan teras
  Mengandungi definisi generik untuk Elemen Selamat ST dan fungsi untuk berkomunikasi dengan elemen selamat sasaran.
  Lapisan teras mengendalikan pembingkaian mesej serta menyediakan abstraksi platform untuk lapisan di atas.

Struktur folder
Rajah di bawah menunjukkan struktur folder X-CUBE-STSE01.

Perisian tunjuk cara

Bahagian ini menggambarkan perisian demonstrasi berdasarkan perisian tengah STSELib.

Pengesahan
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 untuk permainan, aksesori mudah alih atau bahan habis pakai, adalah sama.
Untuk tujuan demonstrasi, hos tempatan dan jauh adalah peranti yang sama di sini.

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.

Berpasangan (Peruntukan Kunci Hos)
Kod ini 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 example mesti dilaksanakan dengan jayanya sebelum melaksanakan semua kod berikut examples.

Aliran arahan

1. Generate the local envelope key in the STSAFE-A110 using the STSELib middleware.
   By default, this command is activated
   Operasi ini berlaku hanya jika slot kunci sampul tempatan STSAFE-A110 belum diisi.
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.

Penubuhan kunci (Kunci simetri AES-128 CMAC)
Demonstrasi ini menggambarkan kes di mana peranti STSAFE-A110 dipasang pada peranti (seperti peranti IoT), yang berkomunikasi dengan pelayan jauh dan perlu mewujudkan saluran selamat untuk bertukar-tukar data dengannya.
Dalam bekas iniampOleh itu, peranti STM32 memainkan peranan kedua-dua pelayan jauh (hos jauh) dan hos tempatan yang disambungkan kepada peranti STSAFE-A110.
Matlamat kes penggunaan ini adalah untuk menunjukkan cara mewujudkan rahsia kongsi antara hos tempatan dan pelayan jauh menggunakan skema Diffie-Hellman lengkung eliptik dengan kunci statik (ECDH) atau ephemeral (ECDHE) dalam STSAFE-A110
Rahsia yang dikongsi harus diperoleh selanjutnya kepada satu atau lebih kunci yang berfungsi (tidak digambarkan di sini). Kekunci kerja ini kemudiannya boleh digunakan dalam protokol komunikasi seperti TLS, contohnyaample untuk melindungi kerahsiaan, integriti dan ketulenan data yang ditukar antara hos tempatan dan pelayan jauh.

Aliran arahan
Rajah 4. Aliran arahan penubuhan utama menggambarkan aliran arahan:

• Kunci persendirian dan kunci awam hos jauh dikod keras dalam kod 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.
• STSAFE-A110/ STSAFE-A120 menghantar semula rahsia hos tempatan kepada STM32.
• The STM32 compares the two secrets and prints the result. If the secrets are the same, the secret establishment is successful.

Balut/buka sampul tempatan

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

Penjanaan pasangan kunci
Demonstrasi ini menggambarkan aliran arahan di mana peranti STSAFE-A110/STSAFE-A120 dipasang pada hos tempatan. Hos jauh meminta hos tempatan ini menjana pasangan kunci (kunci persendirian dan kunci awam) pada slot 1 dan kemudian menandatangani cabaran (nombor rawak) dengan kunci persendirian yang dijana.
Hos jauh kemudiannya dapat mengesahkan tandatangan dengan kunci awam yang dijana.
Demonstrasi ini serupa dengan demonstrasi Pengesahan dengan dua perbezaan:

• Pasangan kunci dalam demonstrasi Pengesahan telah dijana (pada slot 0), sedangkan, dalam bekas iniample, 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.

Aliran arahan
Untuk tujuan demonstrasi, hos tempatan dan jauh adalah peranti yang sama di sini.

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.

Glosari

Singkatan	Maknanya
AES	Standard Penyulitan Lanjutan
ANSI	Institut Piawaian Kebangsaan Amerika
API	Antara muka pengaturcaraan aplikasi
BSP	Pakej sokongan papan
CA	Pihak Berkuasa Pensijilan
CC	Kriteria Biasa
C-MAC	Kod pengesahan mesej arahan
ECC	Kriptografi lengkung eliptik
ECDH	Elliptic curve Diffie–Hellman
ECDHE	Elliptic curve Diffie–Hellman – ephemeral
EWARM	IAR Embedded Workbench® for Arm®
HAL	Lapisan abstraksi perkakasan
I/O	Input/output
Sistem IAR®	World leader in software tools and services for embedded systems development.
IDE	Persekitaran pembangunan bersepadu. Aplikasi perisian yang menyediakan kemudahan komprehensif kepada pengaturcara komputer untuk pembangunan perisian.
IoT	Internet perkara
I²C	Litar bersepadu antara (IIC)
LL	Pemandu peringkat rendah
MAC	Kod pengesahan mesej
MCU	Unit mikropengawal
MDK-ARM	Keil® microcontroller development kit for Arm®
MPU	Unit perlindungan memori
NVM	Memori tidak menentu
OS	Sistem pengendalian
SE	Elemen selamat
SHA	Algoritma Hash selamat
SLA	Perjanjian lesen perisian
ST	STMikroelektronik
TLS	Keselamatan Lapisan Pengangkutan
USB	Bas Bersiri Universal

Sejarah semakan

tarikh	Semakan	Perubahan
23-Jun-2025	1	Keluaran awal.

NOTIS PENTING – BACA DENGAN TELITI

• STMicroelectronics NV dan anak syarikatnya (“ST”) berhak untuk membuat perubahan, pembetulan, penambahbaikan, pengubahsuaian dan penambahbaikan pada produk ST dan/atau pada dokumen ini pada bila-bila masa tanpa notis. Pembeli hendaklah mendapatkan maklumat terkini berkaitan produk ST sebelum membuat pesanan. Produk ST dijual menurut terma dan syarat jualan ST yang ada pada masa penerimaan pesanan.
• Pembeli bertanggungjawab sepenuhnya untuk pilihan, pemilihan dan penggunaan produk ST dan ST tidak bertanggungjawab untuk bantuan permohonan atau reka bentuk produk pembeli.
• Tiada lesen, nyata atau tersirat, kepada mana-mana hak harta intelek diberikan oleh ST di sini.
• Jualan semula produk ST dengan peruntukan yang berbeza daripada maklumat yang dinyatakan di sini akan membatalkan sebarang waranti yang diberikan oleh ST untuk produk tersebut.
• ST dan logo ST adalah tanda dagangan ST. Untuk maklumat tambahan tentang tanda dagangan ST, rujuk kepada www.st.com/trademarks. Semua nama produk atau perkhidmatan lain adalah hak milik pemilik masing-masing.
• Maklumat dalam dokumen ini menggantikan dan menggantikan maklumat yang dibekalkan sebelum ini dalam mana-mana versi terdahulu dokumen ini.
• © 2025 STMicroelectronics – Hak cipta terpelihara

Dokumen / Sumber

Pakej Perisian ST X-CUBE-STSE01 [pdf] Manual Pengguna Pakej Perisian X-CUBE-STSE01, Pakej Perisian, Perisian

Rujukan

• Manual Pengguna