X-CUBE-STSE01 tarkvarapakett

Sissejuhatus

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.
• Sidumine.
• Key establishment.
• Local envelope wrapping.
• Key pair generation.

Üldine teave

• 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 on ettevõtte Arm Limited (või selle tütarettevõtete) registreeritud kaubamärk USA-s ja/või mujal.
• 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 turvaelement

STSAFE-A110 ja STSAFE-A120 on üliturvalised lahendused, mis toimivad turvalise elemendina, pakkudes autentimis- ja andmehaldusteenuseid kohalikule või kaughostile. See koosneb täielikult võtmed kätte lahendusest koos turvalise operatsioonisüsteemiga, mis töötab uusima põlvkonna turvalistel mikrokontrolleritel.
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

• Autentimine (välisseadmete, IoT ja USB Type-C® seadmete puhul).
• Turvaline kanali loomine kaughostiga, sh transpordikihi turvalisuse (TLS) käepigistus.
• Allkirja kontrollimise teenus (turvaline käivitamine ja püsivara uuendamine).
• Kasutuse jälgimine turvaliste loendurite abil.
• Kanali sidumine ja turvamine hostrakenduse protsessoriga.
• Kohalike või kaughosti ümbrike pakkimine ja lahtipakkimine.
• Kiibile sisestatud võtmepaari genereerimine.

STSecureElementi teegi (STSELib) kirjeldus

Selles jaotises kirjeldatakse STSELibi vahevara tarkvarapaketi sisu ja kasutusviisi.

Üldine kirjeldus

STSELibi vahevara on tarkvarakomponentide kogum, mis on loodud järgmiseks:

• Ühendage STSAFE-A110 ja STSAFE-A120 turvalise elemendi seade mikrokontrolleriga.
• rakendada kõige üldisemaid STSAFE-A110 ja STSAFE-A120 kasutusjuhtumeid.
• STSELibi vahevara on ST tarkvarapakettidesse täielikult integreeritud vahevara komponendina, et lisada turvaliste elementide funktsioone.
• STSELibi vahevara pakub manussüsteemide arendajale täielikku komplekti kõrgetasemelisi rakendusliidese funktsioone. See vahevara kirjeldab seadmete, lisaseadmete ja tarvikute kaubamärgi kaitsmiseks vajalike käskude loomist ja järjestust, kasutades STMicroelectronics STSAFE-A turvaliste elementide perekonda.
• See vahevara võimaldab ühe või mitme STSAFE-A sujuvat integreerimist erinevatesse host-MCU/MPU ökosüsteemidesse.
• Toetatud IDE-versioonide kohta teabe saamiseks vaadake paketi juurkaustas saadaolevaid väljalaskemärkmeid.

Arhitektuur
STSELibi vahevara koosneb kolmest tarkvaramoodulist, nagu on näidatud alloleval joonisel. Iga kiht pakub manussüsteemi arendajale erinevat süsteemi abstraktsiooni taset.

Allolev joonis näitab STSELibi vahetarkvara, mis on integreeritud standardsesse STM32Cube rakendusse ja töötab STM32 Nucleo plaadile paigaldatud X-NUCLEO-SAFEA1 või X-NUCLEO-ESE01A1 laiendusplaadil.

Joonis 2. X-CUBE-STSE01 rakenduse plokkskeem

Parima riist- ja platvormisõltumatuse tagamiseks ei ole STSELibi vahevara otse STM32Cube HAL-iga ühendatud, vaid liidese kaudu. filerakendatud rakenduse tasandil

• Rakendusliidese (API) kiht
  See tarkvarakiht on süsteemirakenduse sisenemispunkt. See pakub kõrgetasemeliste funktsioonide komplekti, mis võimaldab suhtlemist STMicroelectronics Secure Elementsiga. API-kiht pakub abstraktsiooni erinevate rakenduste jaoks, nagu turvaliste elementide haldus, autentimine, andmete salvestamine ja võtmehaldus.
• Teenusekiht
  TEENUSTE kiht pakub tooteteenuste komplekti, mis vormindab kõik sihtrühma turvalise elemendi toetatud käsud ja edastab vastuse kõrgematele API/rakenduse kihtidele. Seda kihti saab kasutada otse rakendusest (edasijõudnutele kasutajatele).
• Põhikiht
  Sisaldab ST turvalise elemendi üldist definitsiooni ja funktsioone sihtmärgiks oleva turvalise elemendiga suhtlemiseks.
  Põhikiht tegeleb sõnumite raamimisega ja pakub platvormi abstraktsiooni ülaltoodud kihtidele.

Kausta struktuur
Allolev joonis näitab X-CUBE-STSE01 kaustastruktuuri.

Demonstratsioonitarkvara

See jaotis illustreerib STSELibi vahevaral põhinevat demonstratsioonitarkvara.

Autentimine
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 mängude, mobiilitarvikute või kulumaterjalide jaoks on täpselt sama.
Demonstratsiooni eesmärgil on siin kohalikud ja kaughostid sama seade.

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.

Sidumine (hostivõtme eraldamine)
See kood ntample 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 tuleb edukalt käivitada enne kogu järgmise koodi täitmist, ntampvähem.

Käsuvoog

1. Generate the local envelope key in the STSAFE-A110 using the STSELib middleware.
   By default, this command is activated
   See toiming toimub ainult siis, kui STSAFE-A110 kohaliku ümbriku võtmepesa ei ole juba asustatud.
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.

Võtme loomine (sümmeetriline võti AES-128 CMAC)
See esitlus illustreerib juhtumit, kus STSAFE-A110 seade on paigaldatud seadmele (nt IoT-seadmele), mis suhtleb kaugserveriga ja peab looma sellega andmete vahetamiseks turvalise kanali.
Selles eksampSTM32 seade täidab nii kaugserveri (kaughosti) kui ka STSAFE-A110 seadmega ühendatud kohaliku hosti rolli.
Selle kasutusjuhtumi eesmärk on näidata, kuidas luua jagatud saladus kohaliku hosti ja kaugserveri vahel, kasutades elliptilise kõveraga Diffie-Hellmani skeemi staatilise (ECDH) või ajutise (ECDHE) võtmega STSAFE-A110-s.
Jagatud saladus tuleks täiendavalt tuletada ühe või mitme töövõtmega (siin pole illustreeritud). Neid tööklahve saab seejärel kasutada sideprotokollides, nagu TLS, näiteksample kohaliku hosti ja kaugserveri vahel vahetatavate andmete konfidentsiaalsuse, terviklikkuse ja autentsuse kaitsmiseks.

Käsuvoog
Joonis 4. Võtme loomise käskude voog illustreerib käskude voogu:

• Kaugmasina privaat- ja avalik võti on kõvakodeeritud koodis ntample.
• 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 saadab kohaliku hosti salakoodi tagasi STM32-le.
• The STM32 compares the two secrets and prints the result. If the secrets are the same, the secret establishment is successful.

Pakkige/lahti pakkige kohalikud ümbrikud

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

Võtmepaaride genereerimine
See demonstratsioon illustreerib käskude voogu, kus STSAFE-A110/STSAFE-A120 seade on ühendatud kohalikku hostiga. Kaughost palub sellel kohalikul hostil genereerida võtmepaari (privaatvõti ja avalik võti) 1. pesas ja seejärel allkirjastada väljakutse (juhuslik arv) genereeritud privaatvõtmega.
Seejärel saab kaughost genereeritud avaliku võtmega allkirja kontrollida.
See esitlus sarnaneb autentimise demonstratsiooniga kahe erinevusega:

• Autentimise demonstratsiooni võtmepaar on juba loodud (pesas 0), samas kui selles 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.

Käsuvoog
Demonstratsiooni eesmärgil on siin kohalikud ja kaughostid sama seade.

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.

Sõnastik

Lühend	Tähendus
AES	Täiustatud krüpteerimisstandard
ANSI	Ameerika Riiklik Standardiinstituut
API	Rakenduse programmeerimisliides
BSP	Juhatuse tugipakett
CA	Sertifitseerimisasutus
CC	Ühised kriteeriumid
C-MAC	Käsusõnumi autentimiskood
ECC	Elliptilise kõvera krüptograafia
ECDH	Elliptic curve Diffie–Hellman
ECDHE	Elliptic curve Diffie–Hellman – ephemeral
EWARM	IAR Embedded Workbench® for Arm®
HAL	Riistvara abstraktsioonikiht
I/O	Sisend/väljund
IAR Systems®	World leader in software tools and services for embedded systems development.
IDE	Integreeritud arenduskeskkond. Tarkvararakendus, mis pakub arvutiprogrammeerijatele tarkvara arendamiseks terviklikke võimalusi.
IoT	Asjade Internet
I²C	Integraallülitus (IIC)
LL	Madala taseme draiverid
MAC	Sõnumi autentimiskood
MCU	Mikrokontrolleri üksus
MDK-ARM	Keil® microcontroller development kit for Arm®
MPU	Mälu kaitseüksus
NVM	Püsimälu
OS	Operatsioonisüsteem
SE	Turvaline element
SHA	Turvaline räsialgoritm
SLA	Tarkvara litsentsileping
ST	STMikroelektroonika
TLS	Transpordikihi turvalisus
USB	Universaalne jadabuss

Läbivaatamise ajalugu

Kuupäev	Läbivaatamine	Muudatused
23. juuni 2025	1	Esialgne vabastamine.

TÄHTIS MÄRKUS – LUGEGE HOOLIKAS

• STMicroelectronics NV ja selle tütarettevõtted („ST”) jätavad endale õiguse teha ST-toodetes ja/või selles dokumendis igal ajal ilma ette teatamata muudatusi, parandusi, täiendusi, modifikatsioone ja täiendusi. Ostjad peaksid enne tellimuste esitamist hankima uusima asjakohase teabe ST-toodete kohta. ST tooteid müüakse vastavalt ST müügitingimustele, mis kehtisid tellimuse kinnitamise ajal.
• Ostjad vastutavad ainuisikuliselt ST-toodete valiku, valiku ja kasutamise eest ning ST ei vastuta rakendusabi ega ostjate toodete disaini eest.
• ST ei anna siinkohal mingit otsest ega kaudset litsentsi ühelegi intellektuaalomandi õigusele.
• ST-toodete edasimüük, mille sätted erinevad siin esitatud teabest, tühistab ST-i antud tootele antud garantii.
• ST ja ST logo on ST kaubamärgid. ST-kaubamärkide kohta lisateabe saamiseks vaadake www.st.com/trademarks. Kõik muud toote- või teenusenimed kuuluvad nende vastavatele omanikele.
• Selles dokumendis sisalduv teave asendab ja asendab selle dokumendi varasemates versioonides esitatud teabe.
• © 2025 STMicroelectronics – kõik õigused kaitstud

Dokumendid / Ressursid

ST X-CUBE-STSE01 tarkvarapakett [pdfKasutusjuhend X-CUBE-STSE01 tarkvarapakett, tarkvarapakett, tarkvara

Viited

• Kasutusjuhend