Portage de la bibliothèque CorePKCS11

La norme de cryptographie à clé publique #11 définit une API indépendante de la plate-forme pour gérer et utiliser des jetons cryptographiques. PIÈCES 11fait référence à la norme et aux API définies par celle-ci. L'API cryptographique PKCS #11 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 #11, 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 les API PKCS #11 requises à prendre en charge.

Cas d'utilisation
Cas d'utilisation	Famille d'API PKCS #11 requise
Tous	Initialiser, finaliser, ouvrir/fermer la session, GetSlotList, Connexion
Approvisionnement	GenerateKeyPair, CreateObject, DestroyObject, InitToken, GetTokenInfo
TLS	Aléatoire, signe, FindObject, GetAttributeValue
FreeRTOS+TCP	Aléatoire, Digest
OTA	Vérifiez, digérez, FindObject, GetAttributeValue

Quand implémenter un module PKCS #11 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 #11 requis pour fonctionner avec les bibliothèques FreeRTOS, comme indiqué dans le tableau ci-dessus.

Quand utiliser FreeRTOS CorePKCS11

La bibliothèque CorePKCS11 contient une implémentation logicielle de l'interface (API) PKCS #11 qui utilise les fonctionnalités cryptographiques fournies parIntégrer des kits TLS. 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 CorePKCS11 PAL pour que l'implémentation logicielle CorePKCS11 fonctionne avec votre plate-forme matérielle.

Code 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 bibliothèque CorePKCS11 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 CorePKCS11. Les ports PAL CorePKCS11 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 un chargeur de démarrage sécurisé et over-the-air mises à jour (OTA)

• Un certificat de provisionnement juste à temps

Inclurele fichier d'en-têteet implémentez les API PAL définies.

API PAL
Fonction	Description
PKCS11_PAL_Initialiser	Initialise la couche PAL. Appelé par la bibliothèque CorePKCS11 au début de sa séquence d'initialisation.
PKCS11_PAL_SaveObject	Écrit les données sur un espace de stockage non volatile.
PKCS11_PAL_FindObject	Utilise un CKA_LABEL PKCS #11 pour rechercher un objet PKCS #11 correspondant espace de stockage non volatile et renvoie le handle d'objet, le cas échéant.
PKCS11_PAL_GetObjectValue	Récupère la valeur d'un objet, en prenant l’exemple du handle.
PKCS11_PAL_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 FreeRTOS CorePKCS11 ou si vous implémentez le sous-ensemble requis d'API PKCS11, vous devez réussir les tests FreeRTOS PKCS11. Ils testent si les fonctions requises pour les bibliothèques FreeRTOS fonctionnent comme prévu.

Elle explique également comment exécuter les tests des kits PKCS11 des kits FreeRTOS avec les tests de qualification.

Prérequis

Pour configurer les tests FreeRTOS PKCS11, les étapes suivantes doivent être mises en œuvre.

• Un port pris en charge des API PKCS11.

• Une implémentation des fonctions de la plateforme de tests de qualification FreeRTOS, notamment les suivantes :

  • FRTest_ThreadCreate

  • FRTest_ThreadTimedJoin

  • FRTest_MemoryAlloc

  • FRTest_MemoryFree

(Elle expliqueLisez-moi .mdfichier pour les tests d'intégration des bibliothèques FreeRTOS pour PKCS #11 sur GitHub.)

Tests de portage

• AjouterTests d'intégration des bibliothèques FreeRTOSen tant que sous-module dans votre projet. Le sous-module peut être placé dans n'importe quel répertoire du projet, tant qu'il peut être construit.

• Copierconfig_template/test_execution_config_template.hetconfig_template/test_param_config_template.hà un emplacement de projet dans le chemin de construction, et renommez-les entest_execution_config.hettest_param_config.h.

• Incluez les fichiers pertinents dans le système de compilation. Si vous utilisezCMake,qualification_test.cmakeetsrc/pkcs11_tests.cmakepeut être utilisé pour inclure les fichiers pertinents.

• Mettre en œuvreUNITY_OUTPUT_CHARafin que les journaux de sortie des tests et les journaux des appareils ne s'entrelacent pas.

• Intégrez le mbedTLS, qui vérifie le résultat de l'opération cryptoki.

• AppelRunQualificationTest()depuis l'application.

Configuration des tests

La suite de tests PKCS11 doit être configurée conformément à l'implémentation de PKCS11. Elle explique comment configurer les tests PKCS11 danstest_param_config.hfichier d'en-tête.

Configurations de test PKSC11
Configuration	Description
PKCS11_TEST_RSA_KEY_SUPPORT	Le portage prend en charge les fonctions clés du RSA.
PKCS11_TEST_EC_KEY_SUPPORT	Le portage prend en charge les fonctions clés d'EC.
PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT	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_TEST_GENERATE_KEYPAIR_SUPPORT	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_TEST_PREPROVISIONED_SUPPORT	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_TLSetPKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS, sont des exemples d'informations d'identification.
PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS	L'étiquette de la clé privée utilisée lors du test.
PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS	L'étiquette de la clé publique utilisée dans le test.
PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS	L'étiquette du certificat utilisé lors du test.
PKCS11_TEST_JITP_CODEVERIFY_ROOT_CERT_SUPPORTED	Le portage prend en charge le stockage pour JITP. Elle est réglée sur 1 pour activer le JITPcodeverifytester.
PKCS11_TEST_LABEL_CODE_VERIFICATION_KEY	L'étiquette de la clé de vérification du code utilisée dans JITPcodeverifytester.
PKCS11_TEST_LABEL_JITP_CERTIFICATE	L'étiquette du certificat JITP utilisé dans JITPcodeverifytester.
PKCS11_TEST_LABEL_ROOT_CERTIFICATE	L'étiquette du certificat racine utilisé dans JITPcodeverifytester.

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 les API PKCS11. Le test doit activer les configurations suivantes :

• Elle explique au moins les configurations des fonctions clés suivantes :

  • PKCS11_TEST_RSA_KEY_SUPPORT

  • PKCS11_TEST_EC_KEY_SUPPORT

• Elle explique au moins les configurations de provisionnement clés suivantes :

  • PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT

  • PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT

  • PKCS11_TEST_PREPROVISIONED_SUPPORT

Le test d'identification de l'appareil préconfiguré doit être exécuté dans les conditions suivantes :

• PKCS11_TEST_PREPROVISIONED_SUPPORTdoit être activé et les autres mécanismes de provisionnement doivent être désactivés.

• Une seule fonction clé, soitPKCS11_TEST_RSA_KEY_SUPPORTouPKCS11_TEST_EC_KEY_SUPPORT, elle est activée.

• Configurez les étiquettes clés préconfigurées en fonction de votre fonction principale, y comprisPKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS,PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLSetPKCS11_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 avec des étiquettesPKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS,PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLSetPKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLSsont détruits pendant le test si l'un ou l'autre des deuxPKCS11_TEST_GENERATE_KEYPAIR_SUPPORTouPKCS11_TEST_GENERATE_KEYPAIR_SUPPORTelle est activée.

Exécution de tests

Cette section décrit comment tester localement l'interface PKCS11 avec les tests de qualification. Elle peut également utiliser IDT pour automatiser l'exécution. VoirAWS IoT Device Testerpour FreeRTOSdans leGuide de l'utilisateur des FreeRTOSpour plus de détails.

Elle explique comment exécuter les tests :

• Ouverttest_execution_config.het définissezCORE_PKCS11_TEST_ENABLEDà 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.

Elle explique comment tester les résultats des tests 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 avecAWS IoT Device Tester. Elle explique commentEn utilisantAWS IoT Device Testerpour FreeRTOSdans le Guide de l'utilisateur de FreeRTOS pour configurerAWS IoT Device Testerpour la validation des ports. Pour tester le port d'une bibliothèque spécifique, le groupe de test approprié doit être activé dans ledevice.jsonfichier dans leAWS IoT Device Tester configsdossier.