Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Portage de la PKCS11 bibliothèque principale La norme de cryptographie à clé publique \$111 définit une API indépendante de la plate-forme pour gérer et utiliser des jetons cryptographiques. [PKCS 11](https://en.wikipedia.org/wiki/PKCS_11) fait référence à la norme et à ce qu'elle APIs définit. L'API cryptographique PKCS \$111 fait abstraction du stockage des clés, des propriétés get/set pour les objets cryptographiques et de la sémantique des sessions. Il est largement utilisé pour manipuler des objets cryptographiques courants. Ses fonctions permettent aux logiciels d'application d'utiliser, de créer, de modifier et de supprimer des objets cryptographiques sans exposer ces objets à la mémoire de l'application. Les bibliothèques FreeRTOS et les intégrations de référence utilisent un sous-ensemble de la norme d'interface PCKS \$111, en mettant l'accent sur les opérations impliquant des clés asymétriques, la génération de nombres aléatoires et le hachage. Le tableau ci-dessous répertorie les cas d'utilisation et le PKCS \$111 requis pour être pris APIs en charge. **Cas d'utilisation** | Cas d’utilisation | Famille d'API PKCS \$111 requise | | --- | --- | | Tous | Initialiser, finaliser, ouvrir/fermer la session, se connecter GetSlotList | | Allouer | GenerateKeyPair, CreateObject, DestroyObject, InitToken, GetTokenInfo | | TLS | Aléatoire, signe FindObject, GetAttributeValue | | FreeRTOS\$1TCP | Aléatoire, Digest | | OTA | Vérifier, digérer FindObject, GetAttributeValue | ## Quand implémenter un module PKCS \$111 complet Le stockage des clés privées dans la mémoire flash à usage général peut être pratique dans les scénarios d'évaluation et de prototype rapide. Nous vous recommandons d'utiliser du matériel cryptographique dédié afin de réduire les risques de vol de données et de duplication d'appareils dans les scénarios de production. Le matériel cryptographique inclut les composants ayant des fonctionnalités qui empêchent que les clés de chiffrement secrètes soient exportées. Pour ce faire, vous devrez implémenter un sous-ensemble de PKCS \$111 requis pour fonctionner avec les bibliothèques FreeRTOS, comme indiqué dans le tableau ci-dessus. ## Quand utiliser le noyau de FreeRTOS PKCS11 [La PKCS11 bibliothèque principale contient une implémentation logicielle de l'interface (API) PKCS \$111 qui utilise les fonctionnalités cryptographiques fournies par Mbed TLS.](https://tls.mbed.org/) Cela est prévu pour les scénarios de prototypage et d'évaluation rapides dans lesquels le matériel ne dispose pas d'un matériel cryptographique dédié. Dans ce cas, il vous suffit d'implémenter le PKCS11 protocole PAL principal pour que l'implémentation PKCS11 logicielle principale fonctionne avec votre plate-forme matérielle. ## Noyau de portage PKCS11 Vous devrez disposer d'implémentations permettant de lire et d'écrire des objets cryptographiques dans de la mémoire non volatile (NVM), telle que la mémoire flash intégrée. Les objets cryptographiques doivent être stockés dans une section de la NVM qui n'est pas initialisée et qui n'est pas effacée lors de la reprogrammation du périphérique. Les utilisateurs de la PKCS11 bibliothèque principale fourniront des informations d'identification aux appareils, puis reprogrammeront le périphérique avec une nouvelle application qui accède à ces informations d'identification via l'interface principalePKCS11 . Les ports PKCS11 PAL principaux doivent fournir un emplacement pour stocker : + Le certificat client de l'appareil + La clé privée du client de l'appareil + La clé publique du client de l'appareil + Une autorité de certification racine de confiance + Une clé publique de vérification de code (ou un certificat contenant la clé publique de vérification de code) pour les mises à jour sécurisées du chargeur de démarrage et (OTA) over-the-air + Un certificat Just-In-Time de provisionnement Incluez [le fichier d'en-tête](https://github.com/FreeRTOS/corePKCS11/blob/main/source/include/core_pkcs11_pal.h) et implémentez le PAL APIs défini. **PAL APIs** | Fonction | Description | | --- | --- | | PKCS11\$1PAL\$1Initialiser | Initialise la couche PAL. Appelé par la PKCS11 bibliothèque principale au début de sa séquence d'initialisation. | | PKCS11\$1PAL\$1 SaveObject | Écrit les données sur un espace de stockage non volatile. | | PKCS11\$1PAL\$1 FindObject | Utilise un `CKA_LABEL` PKCS \$111 pour rechercher un objet PKCS \$111 correspondant espace de stockage non volatile et renvoie le handle d'objet, le cas échéant. | | PKCS11\$1PAL\$1 GetObjectValue | Récupère la valeur d'un objet, en prenant l’exemple du handle. | | PKCS11\$1PAL\$1 GetObjectValueCleanup | Effectue un nettoyage pour l'appel de `PKCS11_PAL_GetObjectValue`. Peut être utilisée pour libérer de la mémoire dédiée à un appel `PKCS11_PAL_GetObjectValue`. | ## Test Si vous utilisez la bibliothèque PKCS11 principale de FreeRTOS ou si vous implémentez le sous-ensemble PKCS11 APIs requis de, vous devez réussir les tests FreeRTOS. PKCS11 Ils testent si les fonctions requises pour les bibliothèques FreeRTOS fonctionnent comme prévu. Cette section décrit également comment exécuter localement les tests FreeRTOS PKCS11 avec les tests de qualification. ### Prérequis Pour configurer les tests FreeRTOS, les PKCS11 étapes suivantes doivent être mises en œuvre. + Un port pris en charge de PKCS11 APIs. + Une implémentation des fonctions de la plateforme de tests de qualification FreeRTOS, notamment les suivantes : + `FRTest_ThreadCreate` + `FRTest_ThreadTimedJoin` + `FRTest_MemoryAlloc` + `FRTest_MemoryFree` (Voir le fichier [README.md](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11) pour les tests d'intégration des bibliothèques FreeRTOS pour PKCS \$111 sur.) GitHub ### Tests de portage + Ajoutez-le [ FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11)en tant que sous-module à votre projet. Le sous-module peut être placé dans n'importe quel répertoire du projet, tant qu'il peut être construit. + Copiez `config_template/test_execution_config_template.h` et `config_template/test_param_config_template.h` vers un emplacement de projet dans le chemin de construction, et renommez-les en `test_execution_config.h` et`test_param_config.h`. + Incluez les fichiers pertinents dans le système de compilation. Si vous l'utilisez`CMake`, `qualification_test.cmake` et `src/pkcs11_tests.cmake` peut être utilisé pour inclure les fichiers pertinents. + Mettez en œuvre de `UNITY_OUTPUT_CHAR` manière à ce que les journaux de sortie des tests et les journaux des périphériques ne s'entrelacent pas. + Intégrez le mbedTLS, qui vérifie le résultat de l'opération cryptoki. + Appelez `RunQualificationTest()` depuis l'application. ### Configuration des tests La suite de PKCS11 tests doit être configurée en fonction de l' PKCS11 implémentation. Le tableau suivant répertorie la configuration requise par les PKCS11 tests dans le fichier `test_param_config.h` d'en-tête. **PKSC11 configurations de test** | Configuration | Description | | --- | --- | | PKCS11\$1TEST\$1RSA\$1KEY\$1SUPPORT | Le portage prend en charge les fonctions clés du RSA. | | PKCS11\$1TEST\$1EC\$1KEY\$1SUPPORT | Le portage prend en charge les fonctions clés d'EC. | | PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT | Le portage prend en charge l'importation de la clé privée. L'importation des clés RSA et EC est validée lors du test si les fonctions clés de support sont activées. | | PKCS11\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT | Le portage prend en charge la génération de paires de clés. La génération de paires de touches EC est validée lors du test si les fonctions clés de support sont activées. | | PKCS11\$1TEST\$1PREPROVISIONED\$1SUPPORT | Le portage dispose d'informations d'identification préconfigurées. `PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`, `PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS` et`PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS`, sont des exemples d'informations d'identification. | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1PRIVATE\$1KEY\$1POUR\$1TLS | L'étiquette de la clé privée utilisée lors du test. | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1PUBLIC\$1KEY\$1POUR\$1TLS | L'étiquette de la clé publique utilisée dans le test. | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1CERTIFICATE\$1POUR\$1TLS | L'étiquette du certificat utilisé lors du test. | | PKCS11\$1TEST\$1JITP\$1CODEVERIFY\$1ROOT\$1CERT\$1SUPPORTÉ | Le portage prend en charge le stockage pour JITP. Réglez ce paramètre sur 1 pour activer le `codeverify` test JITP. | | PKCS11\$1TEST\$1LABEL\$1CODE\$1VERIFICATION\$1KEY | L'étiquette de la clé de vérification du code utilisée dans le `codeverify` test JITP. | | PKCS11\$1TEST\$1LABEL\$1JITP\$1CERTIFICATE | L'étiquette du certificat JITP utilisé dans le test JITP. `codeverify` | | PKCS11\$1TEST\$1LABEL\$1ROOT\$1CERTIFICATE | L'étiquette du certificat racine utilisé dans le `codeverify` test JITP. | Les bibliothèques FreeRTOS et les intégrations de référence doivent prendre en charge au moins une configuration de fonction clé, telle que les clés RSA ou Elliptic Curve, et un mécanisme de provisionnement clé pris en charge par le. PKCS11 APIs Le test doit activer les configurations suivantes : + Au moins l'une des configurations de fonctions clés suivantes : + PKCS11\$1TEST\$1RSA\$1KEY\$1SUPPORT + PKCS11\$1TEST\$1EC\$1KEY\$1SUPPORT + Au moins l'une des principales configurations de provisionnement suivantes : + PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT + PKCS11\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT + PKCS11\$1TEST\$1PREPROVISIONED\$1SUPPORT Le test d'identification de l'appareil préconfiguré doit être exécuté dans les conditions suivantes : + `PKCS11_TEST_PREPROVISIONED_SUPPORT`doit être activé et les autres mécanismes de provisionnement doivent être désactivés. + Une seule fonction clé, l'une `PKCS11_TEST_RSA_KEY_SUPPORT` ou l'autre`PKCS11_TEST_EC_KEY_SUPPORT`, est activée. + Configurez les libellés clés préconfigurés en fonction de votre fonction principale, y compris`PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`, et`PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS`. `PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS` Ces informations d'identification doivent exister avant d'exécuter le test. Le test devra peut-être être exécuté plusieurs fois avec différentes configurations, si l'implémentation prend en charge les informations d'identification préconfigurées et d'autres mécanismes de provisionnement. **Note** Les objets portant des étiquettes `PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS` et `PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS` des étiquettes `PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS` sont détruits pendant le test si l'une `PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT` ou l'autre `PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT` est activée. ### Exécution de tests Cette section décrit comment tester localement l' PKCS11 interface avec les tests de qualification. Vous pouvez également utiliser IDT pour automatiser l'exécution. Voir [FreeRTOS dans le Guide de l'utilisateur de *FreeRTOS AWS IoT Device Tester * pour](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) plus de détails. Les instructions suivantes décrivent comment exécuter les tests : + Ouvrez `test_execution_config.h` et définissez **CORE\$1 PKCS11 \$1TEST\$1ENABLED** sur 1. + Créez et flashez l'application sur votre appareil pour l'exécuter. Les résultats du test sont transmis au port série. Voici un exemple du résultat du test de sortie. ``` 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 ``` Les tests sont terminés lorsque chacun des tests est réussi. **Note** Pour qualifier officiellement un appareil pour FreeRTOS, vous devez valider le code source porté de l'appareil avec. AWS IoT Device Tester Suivez les instructions de la section [Utilisation AWS IoT Device Tester pour FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) du Guide de l'utilisateur de FreeRTOS pour configurer la validation des ports. AWS IoT Device Tester Pour tester le port d'une bibliothèque spécifique, le groupe de test approprié doit être activé dans le `device.json` fichier du AWS IoT Device Tester `configs` dossier.