Quand implémenter un module PKCS #11 complet Quand utiliser FreeRTOS CorePKCS11 Code de portage PKCS11 Test

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. PKCS 11 fait 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 get/set propriétés des 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	Initialisation, finalisation, Open/Close session, connexion GetSlotList
Allouer	GenerateKeyPair, CreateObject, DestroyObject, InitToken, GetTokenInfo
TLS	Aléatoire, signe FindObject, GetAttributeValue
FreeRTOS+TCP	Aléatoire, Digest
OTA	Vérifier, digérer 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 par Mbed 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 le chargeur de démarrage sécurisé et les mises à jour sans fil (OTA)
Un certificat Just-In-Time de provisionnement

Incluez le fichier d'en-tête et 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.

Cette section décrit également comment exécuter localement les tests FreeRTOS PKCS11 avec les tests de qualification.

Conditions préalables

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

(Voir le README.mdfichier pour les tests d'intégration des bibliothèques FreeRTOS pour PKCS #11 sur.) GitHub

Tests de portage

Ajoutez-le FreeRTOS-Libraries-Integration-Testsen tant que sous-module à votre projet. Le sous-module peut être placé dans n'importe quel répertoire du projet, à condition qu'il puisse ê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 ettest_param_config.h.
Incluez les fichiers pertinents dans le système de compilation. Si vous l'utilisezCMake, 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 tests PKCS11 doit être configurée conformément à l'implémentation de PKCS11. Le tableau suivant répertorie la configuration requise par les tests PKCS11 dans le fichier test_param_config.h 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_TLS` et`PKCS11_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. Réglez ce paramètre sur 1 pour activer le `codeverify` test JITP.
PKCS11_TEST_LABEL_CODE_VERIFICATION_KEY	L'étiquette de la clé de vérification du code utilisée dans le `codeverify` test JITP.
PKCS11_TEST_LABEL_JITP_CERTIFICATE	L'étiquette du certificat JITP utilisé dans le test JITP. `codeverify`
PKCS11_TEST_LABEL_ROOT_CERTIFICATE	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 les API PKCS11. Le test doit activer les configurations suivantes :

Au moins l'une des configurations de fonctions clés suivantes :
- PKCS11_TEST_RSA_KEY_SUPPORT
- PKCS11_TEST_EC_KEY_SUPPORT
Au moins l'une des principales configurations de provisionnement 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.
Seule une fonction clé, l'une PKCS11_TEST_RSA_KEY_SUPPORT ou l'autrePKCS11_TEST_EC_KEY_SUPPORT, est activée.
Configurez les libellés clés préconfigurés en fonction de votre fonction principale, y comprisPKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS, etPKCS11_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'interface PKCS11 à l'aide des 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 plus de détails.

Les instructions suivantes décrivent comment exécuter les tests :

Ouvrez test_execution_config.h et définissez CORE_PKCS11_TEST_ENABLED 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 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.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

TCP/IP

Interface de transport réseau