حزمة برامج X-CUBE-STSE01

مقدمة

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.
• الاقتران.
• Key establishment.
• Local envelope wrapping.
• Key pair generation.

معلومات عامة

• 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 هي علامة تجارية مسجلة لشركة Arm Limited (أو الشركات التابعة لها) في الولايات المتحدة و / أو في أي مكان آخر.
• 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

يُعدّ نظاما STSAFE-A110 وSTSAFE-A120 حلاً عالي الأمان، يُوفّر خدمات المصادقة وإدارة البيانات للمضيف المحلي أو البعيد. ويتألف من حل جاهز للاستخدام بالكامل، مع نظام تشغيل آمن يعمل على أحدث جيل من المتحكمات الدقيقة الآمنة.
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

• المصادقة (للأجهزة الطرفية وأجهزة إنترنت الأشياء وأجهزة USB Type-C®).
• إنشاء قناة آمنة مع المضيف البعيد بما في ذلك مصافحة أمان طبقة النقل (TLS).
• خدمة التحقق من التوقيع (التمهيد الآمن وترقية البرامج الثابتة).
• مراقبة الاستخدام باستخدام عدادات آمنة.
• إقران القناة وتأمينها مع معالج التطبيق المضيف.
• تغليف وفك تغليف المغلفات المضيفة المحلية أو البعيدة.
• إنشاء زوج مفاتيح على الشريحة.

وصف مكتبة STSecureElement (STSELib)

يقدم هذا القسم تفاصيل حول محتوى حزمة برامج الوسيطة STSELib وطريقة استخدامها.

الوصف العام

برنامج STSELib الوسيط عبارة عن مجموعة من مكونات البرامج المصممة لـ:

• ربط جهاز العنصر الآمن STSAFE-A110 وSTSAFE-A120 بوحدة التحكم الدقيقة (MCU).
• تنفيذ حالات الاستخدام الأكثر عمومية STSAFE-A110 و STSAFE-A120.
• تم دمج برنامج STSELib الوسيط بالكامل ضمن حزم برامج ST كمكون لبرنامج وسيط لإضافة ميزات العناصر الآمنة.
• يوفر برنامج STSELib الوسيط مجموعة كاملة من وظائف واجهة برمجة التطبيقات عالية المستوى لمطوري الأنظمة المضمنة. يُلخص هذا البرنامج الوسيط عملية البناء وتسلسل الأوامر اللازمة لضمان حماية العلامة التجارية للجهاز والملحقات والمواد الاستهلاكية باستخدام عائلة عناصر STSAFE-A الآمنة من STMicroelectronics.
• يتيح برنامج الوسيط هذا التكامل السلس لواحد أو أكثر من STSAFE-A في أنظمة MCU/MPU المضيفة المختلفة.
• راجع ملاحظات الإصدار المتوفرة في المجلد الجذر للحزمة للحصول على معلومات حول إصدارات IDE المدعومة.

بنيان
يتكون برنامج STSELib الوسيط من ثلاث وحدات برمجية كما هو موضح في الشكل أدناه. توفر كل طبقة مستوى مختلفًا من تجريد النظام لمطور النظام المضمن.

يوضح الشكل أدناه برنامج STSELib الوسيط المتكامل في تطبيق STM32Cube القياسي، والذي يعمل على لوحة التوسعة X-NUCLEO-SAFEA1 أو X-NUCLEO-ESE01A1 المثبتة على لوحة STM32 Nucleo.

الشكل 2. مخطط كتلة تطبيق X-CUBE-STSE01

لتوفير أفضل استقلال للأجهزة والمنصة، لا يتم توصيل برنامج STSELib الوسيط مباشرة بـ STM32Cube HAL، ولكن من خلال الواجهة fileتم تنفيذه على مستوى التطبيق

• طبقة واجهة برمجة التطبيقات (API)
  تُعدّ طبقة البرمجيات هذه نقطة الدخول لتطبيق النظام. فهي تُوفّر مجموعة من الوظائف عالية المستوى التي تُتيح التفاعل مع عناصر STMicroelectronics الآمنة. تُوفّر طبقة واجهة برمجة التطبيقات (API) تجريدًا لتطبيقات مُختلفة، مثل إدارة العناصر الآمنة، والمصادقة، وتخزين البيانات، وإدارة المفاتيح.
• طبقة الخدمة
  توفر طبقة الخدمة مجموعة من خدمات المنتج التي تُنسّق جميع الأوامر التي يدعمها عنصر الأمان المُستهدف، وتُبلغ عن استجابات لواجهات برمجة التطبيقات/التطبيقات ذات الطبقات الأعلى. يُمكن استخدام هذه الطبقة مُباشرةً من التطبيق (للمستخدمين المُتقدمين).
• الطبقة الأساسية
  يحتوي على تعريف عام لعنصر ST Secure ووظائف للتواصل مع عنصر الأمان المستهدف.
  تتولى الطبقة الأساسية مهمة تأطير الرسائل بالإضافة إلى توفير تجريد المنصة للطبقات المذكورة أعلاه.

هيكل المجلد
يوضح الشكل أدناه بنية المجلد الخاصة بـX-CUBE-STSE01.

برنامج مظاهرة

يوضح هذا القسم برنامجًا توضيحيًا يعتمد على برنامج الوسيط STSELib.

المصادقة
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 exampبالنسبة للألعاب أو ملحقات الهاتف المحمول أو المواد الاستهلاكية، فهو نفسه تمامًا.
لأغراض العرض التوضيحي، المضيفين المحليين والبعيدين هم نفس الجهاز هنا.

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.

الاقتران (توفير مفتاح المضيف)
هذا الرمز السابقample 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 exampيجب تنفيذ le بنجاح قبل تنفيذ كافة التعليمات البرمجية التالية على سبيل المثالampليز.

تدفق الأوامر

1. Generate the local envelope key in the STSAFE-A110 using the STSELib middleware.
   By default, this command is activated
   تحدث هذه العملية فقط إذا لم يتم ملء فتحة مفتاح المغلف المحلي الخاصة بـ STSAFE-A110 بالفعل.
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.

إنشاء المفتاح (المفتاح المتماثل AES-128 CMAC)
يوضح هذا العرض التوضيحي الحالة التي يتم فيها تثبيت جهاز STSAFE-A110 على جهاز (مثل جهاز IoT)، الذي يتصل بخادم بعيد، ويحتاج إلى إنشاء قناة آمنة لتبادل البيانات معه.
في هذا المثال السابقample، يلعب جهاز STM32 دور كل من الخادم البعيد (المضيف البعيد) والمضيف المحلي المتصل بجهاز STSAFE-A110.
الهدف من حالة الاستخدام هذه هو إظهار كيفية إنشاء سر مشترك بين المضيف المحلي والخادم البعيد باستخدام مخطط Diffie-Hellman المنحني الإهليلجي مع مفتاح ثابت (ECDH) أو مؤقت (ECDHE) في STSAFE-A110
يجب أن يتم استخلاص السر المشترك من مفتاح عمل واحد أو أكثر (غير موضح هنا). يمكن بعد ذلك استخدام مفاتيح العمل هذه في بروتوكولات الاتصال مثل TLS، على سبيل المثالampلحماية سرية وسلامة وصحة البيانات التي يتم تبادلها بين المضيف المحلي والخادم البعيد.

تدفق الأوامر
يوضح الشكل 4. تدفق أمر إنشاء المفتاح تدفق الأوامر:

• يتم ترميز المفاتيح العامة والخاصة للمضيف البعيد في الكود السابقampليه.
• 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 سر المضيف المحلي إلى STM32.
• The STM32 compares the two secrets and prints the result. If the secrets are the same, the secret establishment is successful.

لف/فك المظاريف المحلية

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

توليد زوج المفاتيح
يوضح هذا العرض التوضيحي سير الأوامر عند تثبيت جهاز STSAFE-A110/STSAFE-A120 على مضيف محلي. يطلب المضيف البعيد من هذا المضيف المحلي إنشاء زوج مفاتيح (مفتاح خاص ومفتاح عام) على الفتحة 1، ثم توقيع تحدٍّ (رقم عشوائي) باستخدام المفتاح الخاص المُولّد.
يستطيع المضيف البعيد بعد ذلك التحقق من التوقيع باستخدام المفتاح العام الذي تم إنشاؤه.
يشبه هذا العرض التوضيحي عرض المصادقة مع اختلافين:

• تم بالفعل إنشاء زوج المفاتيح في العرض التوضيحي للمصادقة (في الفتحة 0)، بينما في هذا المثالample, 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.

تدفق الأوامر
لأغراض العرض التوضيحي، المضيفين المحليين والبعيدين هم نفس الجهاز هنا.

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.

المصطلحات

اختصار	معنى
AES	معيار التشفير المتقدم
المعهد الوطني الأمريكي للمعايير	المعهد الوطني الأمريكي للمعايير
واجهة برمجة التطبيقات	واجهة برمجة التطبيقات
ب س ب	حزمة دعم المجلس
CA	هيئة التصديق
CC	المعايير المشتركة
C-ماك	رمز مصادقة رسالة الأمر
إي سي سي	تشفير المنحنى الإهليلجي
ECDH	Elliptic curve Diffie–Hellman
التعليم في مرحلة الطفولة المبكرة والصحة واللياقة البدنية	Elliptic curve Diffie–Hellman – ephemeral
إوارم	IAR Embedded Workbench® for Arm®
هال	طبقة المواد الصلبة
إدخال/إخراج	الإدخال/الإخراج
أنظمة IAR®	World leader in software tools and services for embedded systems development.
بيئة تطوير متكاملة	بيئة تطوير متكاملة. تطبيق برمجي يوفر إمكانيات شاملة لمبرمجي الحاسوب لتطوير البرمجيات.
إنترنت الأشياء	إنترنت الأشياء
أي²سي	الدائرة المتكاملة (IIC)
LL	برامج تشغيل منخفضة المستوى
ماك	رمز مصادقة الرسالة
وحدة تحكم دقيقة	وحدة متحكم دقيق
MDK-ARM	Keil® microcontroller development kit for Arm®
وحدة المعالجة المركزية	وحدة حماية الذاكرة
لا يوجد	الذاكرة غير المتطايرة
OS	نظام التشغيل
SE	عنصر آمن
شا	خوارزمية التجزئة الآمنة
اتفاقية مستوى الخدمة	اتفاقية ترخيص البرامج
ST	شركة إس تي ميكروإلكترونيكس
بروتوكول TLS	أمان طبقة النقل
USB	الناقل التسلسلي العالمي

تاريخ المراجعة

تاريخ	المراجعة	التغييرات
23 يونيو 2025	1	الإصدار الأولي.

إشعار هام – اقرأ بعناية

• تحتفظ شركة STMicroelectronics NV والشركات التابعة لها ("ST") بالحق في إجراء تغييرات وتصحيحات وتعزيزات وتعديلات وتحسينات على منتجات ST و/أو هذه الوثيقة في أي وقت دون إشعار. يجب على المشترين الحصول على أحدث المعلومات ذات الصلة بمنتجات ST قبل تقديم الطلبات. تُباع منتجات ST وفقًا لشروط وأحكام البيع الخاصة بشركة ST السارية وقت إقرار الطلب.
• يعتبر المشترون مسؤولين بشكل كامل عن اختيار منتجات ST واختيارها واستخدامها، ولا تتحمل شركة ST أي مسؤولية عن مساعدة التطبيق أو تصميم منتجات المشترين.
• لا يتم منح أي ترخيص، صريحًا أو ضمنيًا، لأي حق من حقوق الملكية الفكرية من قبل شركة ST هنا.
• إن إعادة بيع منتجات ST بأحكام مختلفة عن المعلومات الواردة هنا يؤدي إلى إبطال أي ضمان تمنحه شركة ST لهذا المنتج.
• ST وشعار ST هما علامتان تجاريتان لشركة ST. لمزيد من المعلومات حول العلامات التجارية لشركة ST، راجع www.st.com/trademarks. جميع أسماء المنتجات أو الخدمات الأخرى هي ملك لأصحابها.
• تحل المعلومات الواردة في هذه الوثيقة محل المعلومات المقدمة مسبقًا في أي إصدارات سابقة من هذه الوثيقة.
• © 2025 STMicroelectronics – جميع الحقوق محفوظة

المستندات / الموارد

حزمة برامج ST X-CUBE-STSE01 [بي دي اف] دليل المستخدم حزمة برامج X-CUBE-STSE01، حزمة برامج، برنامج

مراجع

• دليل المستخدم