Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Mem-porting perpustakaan inti PKCS11
Standar Kriptografi Kunci Publik \$111 mendefinisikan API independen platform untuk mengelola dan menggunakan token kriptografi. [PKCS 11](https://en.wikipedia.org/wiki/PKCS_11) mengacu pada standar dan yang APIs ditentukan olehnya. API kriptografi PKCS \$111 mengabstraksi penyimpanan kunci, mendapatkan/mengatur properti untuk objek kriptografi, dan semantik sesi. Ini banyak digunakan untuk memanipulasi objek kriptografi umum. Fungsinya memungkinkan perangkat lunak aplikasi untuk menggunakan, membuat, memodifikasi, dan menghapus objek kriptografi, tanpa mengekspos objek tersebut ke memori aplikasi.
Pustaka FreeRTOS dan integrasi referensi menggunakan subset dari standar antarmuka PCCKS \$111, dengan fokus pada operasi yang melibatkan kunci asimetris, pembuatan angka acak, dan hashing. Tabel di bawah ini mencantumkan kasus penggunaan dan PKCS \$111 yang diperlukan APIs untuk mendukung.
**Kasus penggunaan**
| Kasus Penggunaan | Keluarga API PKCS \$111 yang Diperlukan |
| --- | --- |
| Semua | Inisialisasi, Selesaikan, Buka/Tutup Sesi,, Login GetSlotList |
| Penyediaan | GenerateKeyPair, CreateObject, DestroyObject, InitToken, GetTokenInfo |
| TLS | Acak, Tanda, FindObject, GetAttributeValue |
| Freertos\$1TCP | Acak, Intisari |
| OTA | Verifikasi, Digest,, FindObject GetAttributeValue |
## Kapan harus mengimplementasikan modul PKCS \$111 lengkap
Menyimpan kunci pribadi dalam memori flash tujuan umum dapat menjadi nyaman dalam evaluasi dan skenario pembuatan prototipe cepat. Kami menyarankan Anda menggunakan perangkat keras kriptografi khusus untuk mengurangi ancaman pencurian data dan duplikasi perangkat dalam skenario produksi. Perangkat keras kriptografi mencakup komponen dengan fitur yang mencegah kunci rahasia kriptografi diekspor. Untuk mendukung ini, Anda harus menerapkan subset PKCS \$111 yang diperlukan untuk bekerja dengan pustaka FreeRTOS seperti yang didefinisikan dalam tabel di atas.
## Kapan menggunakan inti FreeRTOS PKCS11
PKCS11 [Pustaka inti berisi implementasi berbasis perangkat lunak dari antarmuka (API) PKCS \$111 yang menggunakan fungsionalitas kriptografi yang disediakan oleh Mbed TLS.](https://tls.mbed.org/) Ini disediakan untuk skenario prototipe dan evaluasi cepat di mana perangkat keras tidak memiliki perangkat keras kriptografi khusus. Dalam hal ini, Anda hanya perlu mengimplementasikan PKCS11 PAL inti untuk membuat implementasi PKCS11 berbasis perangkat lunak inti untuk bekerja dengan platform perangkat keras Anda.
## Porting inti PKCS11
Anda harus memiliki implementasi untuk membaca dan menulis objek kriptografi ke memori non-volatile (NVM), seperti memori flash on-board. Objek kriptografi harus disimpan di bagian NVM yang tidak diinisialisasi dan tidak dihapus pada pemrograman ulang perangkat. Pengguna PKCS11 pustaka inti akan menyediakan perangkat dengan kredensi, dan kemudian memprogram ulang perangkat dengan aplikasi baru yang mengakses kredensional ini melalui antarmuka inti. PKCS11 Port PKCS11 PAL inti harus menyediakan lokasi untuk menyimpan:
+ Sertifikat klien perangkat
+ Kunci pribadi klien perangkat
+ Kunci publik klien perangkat
+ CA root tepercaya
+ Kunci publik verifikasi kode (atau sertifikat yang berisi kunci publik verifikasi kode) untuk pembaruan boot-loader dan (OTA) yang aman over-the-air
+ Just-In-TimeSertifikat penyediaan
Sertakan [file header](https://github.com/FreeRTOS/corePKCS11/blob/main/source/include/core_pkcs11_pal.h) dan implementasikan PAL yang APIs ditentukan.
**PAL APIs**
| Fungsi | Deskripsi |
| --- | --- |
| PKCS11\$1PAL\$1inisialisasi | Menginisialisasi layer PAL. Disebut oleh PKCS11 perpustakaan inti pada awal urutan inisialisasi. |
| PKCS11\$1PAL\$1 SaveObject | Menulis data ke penyimpanan non-volatile. |
| PKCS11\$1PAL\$1 FindObject | Menggunakan PKCS \$111 `CKA_LABEL` untuk mencari objek PKCS \$111 yang sesuai di penyimpanan non-volatile, dan mengembalikan pegangan objek itu, jika ada. |
| PKCS11\$1PAL\$1 GetObjectValue | Mengambil nilai dari sebuah objek, mengingat pegangan. |
| PKCS11\$1PAL\$1 GetObjectValueCleanup | Pembersihan untuk `PKCS11_PAL_GetObjectValue` panggilan. Dapat digunakan untuk membebaskan memori yang dialokasikan dalam `PKCS11_PAL_GetObjectValue` panggilan. |
## Pengujian
Jika Anda menggunakan pustaka PKCS11 inti FreeRTOS atau mengimplementasikan subset PKCS11 APIs yang diperlukan, Anda harus lulus tes FreeRTOS. PKCS11 Tes ini jika fungsi yang diperlukan untuk pustaka FreerTOS berfungsi seperti yang diharapkan.
Bagian ini juga menjelaskan bagaimana Anda dapat menjalankan tes PKCS11 FreeRTOS secara lokal dengan tes kualifikasi.
### Prasyarat
Untuk mengatur tes FreeRTOS PKCS11 , berikut ini harus diimplementasikan.
+ Port yang didukung dari PKCS11 APIs.
+ Implementasi fungsi platform tes kualifikasi FreeRTOS yang meliputi:
+ `FRTest_ThreadCreate`
+ `FRTest_ThreadTimedJoin`
+ `FRTest_MemoryAlloc`
+ `FRTest_MemoryFree`
(Lihat file [README.md](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11) untuk Pengujian Integrasi Pustaka FreerTOS untuk PKCS \$111 pada.) GitHub
### Tes porting
+ Tambahkan [ FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11)sebagai submodul ke dalam proyek Anda. Submodul dapat ditempatkan di direktori proyek apa pun, asalkan dapat dibangun.
+ Salin `config_template/test_execution_config_template.h` dan `config_template/test_param_config_template.h` ke lokasi proyek di jalur build, dan ganti namanya menjadi `test_execution_config.h` dan`test_param_config.h`.
+ Sertakan file yang relevan ke dalam sistem build. Jika menggunakan`CMake`, `qualification_test.cmake` dan `src/pkcs11_tests.cmake` dapat digunakan untuk menyertakan file yang relevan.
+ Terapkan `UNITY_OUTPUT_CHAR` agar log keluaran pengujian dan log perangkat tidak saling bertautan.
+ Integrasikan mBEDTLS, yang memverifikasi hasil operasi cryptoki.
+ Panggilan `RunQualificationTest()` dari aplikasi.
### Mengkonfigurasi tes
PKCS11 Test suite harus dikonfigurasi sesuai dengan PKCS11 implementasi. Tabel berikut mencantumkan konfigurasi yang diperlukan oleh PKCS11 tes dalam file `test_param_config.h` header.
**PKSC11 konfigurasi uji**
| Konfigurasi | Deskripsi |
| --- | --- |
| PKCS11\$1TEST\$1RSA\$1KEY\$1DUKUNGAN | Porting mendukung fungsi kunci RSA. |
| PKCS11\$1TEST\$1EC\$1KEY\$1DUKUNGAN | Porting mendukung fungsi kunci EC. |
| PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT | Porting mendukung impor kunci pribadi. Impor kunci RSA dan EC divalidasi dalam pengujian jika fungsi kunci pendukung diaktifkan. |
| PKCS11\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT | Porting mendukung pembuatan keypair. Generasi keypair EC divalidasi dalam pengujian jika fungsi kunci pendukung diaktifkan. |
| PKCS11\$1TEST\$1PREPROVISIONED\$1SUPPORT | Porting memiliki kredensyal yang telah disediakan sebelumnya. `PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`, `PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS` dan`PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS`, adalah contoh kredensialnya. |
| PKCS11\$1TEST\$1LABEL\$1DEVICE\$1PRIVATE\$1KEY\$1FOR\$1TLS | Label kunci pribadi yang digunakan dalam pengujian. |
| PKCS11\$1TEST\$1LABEL\$1DEVICE\$1PUBLIC\$1KEY\$1FOR\$1TLS | Label kunci publik yang digunakan dalam pengujian. |
| PKCS11\$1TEST\$1LABEL\$1DEVICE\$1CERTIFICATE\$1FOR\$1TLS | Label sertifikat yang digunakan dalam tes. |
| PKCS11\$1TEST\$1JITP\$1CODEVERIFY\$1ROOT\$1CERT\$1DIDUKUNG | Porting mendukung penyimpanan untuk JITP. Setel ini ke 1 untuk mengaktifkan tes JITP`codeverify`. |
| PKCS11\$1TEST\$1LABEL\$1CODE\$1VERIFICATION\$1KEY | Label kunci verifikasi kode yang digunakan dalam pengujian JITP`codeverify`. |
| PKCS11\$1TEST\$1LABEL\$1JITP\$1CERTIFICATE | Label sertifikat JITP yang digunakan dalam tes `codeverify` JITP. |
| PKCS11\$1TEST\$1LABEL\$1ROOT\$1CERTIFICATE | Label sertifikat root yang digunakan dalam uji JITP`codeverify`. |
Pustaka FreeRTOS dan integrasi referensi harus mendukung minimal satu konfigurasi fungsi kunci seperti RSA atau tombol kurva Elliptic, dan satu mekanisme penyediaan kunci yang didukung oleh. PKCS11 APIs Tes harus mengaktifkan konfigurasi berikut:
+ Setidaknya satu dari konfigurasi fungsi kunci berikut:
+ PKCS11\$1TEST\$1RSA\$1KEY\$1DUKUNGAN
+ PKCS11\$1TEST\$1EC\$1KEY\$1DUKUNGAN
+ Setidaknya satu dari konfigurasi penyediaan kunci berikut:
+ PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT
+ PKCS11\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT
+ PKCS11\$1TEST\$1PREPROVISIONED\$1SUPPORT
Pengujian kredensi perangkat yang telah disediakan sebelumnya harus berjalan dalam kondisi berikut:
+ `PKCS11_TEST_PREPROVISIONED_SUPPORT`harus diaktifkan dan mekanisme penyediaan lainnya dinonaktifkan.
+ Hanya satu fungsi tombol, salah satu `PKCS11_TEST_RSA_KEY_SUPPORT` atau`PKCS11_TEST_EC_KEY_SUPPORT`, yang diaktifkan.
+ Siapkan label kunci yang telah disediakan sebelumnya sesuai dengan fungsi kunci Anda, termasuk`PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`, dan. `PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS` `PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS` Kredensyal ini harus ada sebelum menjalankan tes.
Pengujian mungkin perlu dijalankan beberapa kali dengan konfigurasi yang berbeda, jika implementasi mendukung kredensyal yang telah disediakan sebelumnya dan mekanisme penyediaan lainnya.
**catatan**
Objek dengan label`PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`, `PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS` dan `PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS` dihancurkan selama pengujian jika salah satu `PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT` atau `PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT` diaktifkan.
### Menjalankan tes
Bagian ini menjelaskan bagaimana Anda dapat menguji PKCS11 antarmuka secara lokal dengan tes kualifikasi. Atau, Anda juga dapat menggunakan IDT untuk mengotomatiskan eksekusi. Lihat [AWS IoT Device Tester FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) di Panduan Pengguna *FreeRTOS untuk detailnya*.
Instruksi berikut menjelaskan cara menjalankan tes:
+ Buka `test_execution_config.h` dan tentukan **CORE\$1 PKCS11 \$1TEST\$1ENABLED** ke 1.
+ Bangun dan flash aplikasi ke perangkat Anda untuk dijalankan. Hasil tes adalah output ke port serial.
Berikut ini adalah contoh hasil uji keluaran.
```
TEST(Full_PKCS11_StartFinish, PKCS11_StartFinish_FirstTest) PASS
TEST(Full_PKCS11_StartFinish, PKCS11_GetFunctionList) PASS
TEST(Full_PKCS11_StartFinish, PKCS11_InitializeFinalize) PASS
TEST(Full_PKCS11_StartFinish, PKCS11_GetSlotList) PASS
TEST(Full_PKCS11_StartFinish, PKCS11_OpenSessionCloseSession) PASS
TEST(Full_PKCS11_Capabilities, PKCS11_Capabilities) PASS
TEST(Full_PKCS11_NoObject, PKCS11_Digest) PASS
TEST(Full_PKCS11_NoObject, PKCS11_Digest_ErrorConditions) PASS
TEST(Full_PKCS11_NoObject, PKCS11_GenerateRandom) PASS
TEST(Full_PKCS11_NoObject, PKCS11_GenerateRandomMultiThread) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_CreateObject) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_FindObject) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_GetAttributeValue) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_Sign) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_FindObjectMultiThread) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_GetAttributeValueMultiThread) PASS
TEST(Full_PKCS11_RSA, PKCS11_RSA_DestroyObject) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_GenerateKeyPair) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_CreateObject) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_FindObject) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_GetAttributeValue) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_Sign) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_Verify) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_FindObjectMultiThread) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_GetAttributeValueMultiThread) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_SignVerifyMultiThread) PASS
TEST(Full_PKCS11_EC, PKCS11_EC_DestroyObject) PASS
-----------------------
27 Tests 0 Failures 0 Ignored
OK
```
Pengujian selesai ketika semua tes lulus.
**catatan**
Untuk secara resmi memenuhi syarat perangkat untuk FreeRTOS, Anda harus memvalidasi kode sumber porting perangkat dengan. AWS IoT Device Tester Ikuti petunjuk dalam [Menggunakan FreeRTOS di Panduan Pengguna FreerTOS AWS IoT Device Tester untuk](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) mengatur validasi port. AWS IoT Device Tester Untuk menguji port pustaka tertentu, grup pengujian yang benar harus diaktifkan dalam `device.json` file di AWS IoT Device Tester `configs` folder.