Portierung der CorePKCS11-Bibliothek

Der Public Key Cryptography Standard #11 definiert eine plattformunabhängige API zur Verwaltung und Verwendung kryptografischer Token. STCK. 11bezieht sich auf den Standard und die durch ihn definierten APIs. Die kryptografische PKCS #11 -API abstrahiert die Speicherung von Schlüsseln, ruft Eigenschaften für kryptografische Objekte ab und definiert die Sitzungssemantik. Sie wird häufig zur Manipulation gängiger kryptografischer Objekte verwendet. Seine Funktionen ermöglichen es Anwendungssoftware, kryptografische Objekte zu verwenden, zu erstellen, zu ändern und zu löschen, ohne dass diese Objekte dem Speicher der Anwendung zugänglich gemacht werden.

FreeRTOS-Bibliotheken und Referenzintegrationen verwenden eine Teilmenge des Schnittstellenstandards PCKS #11, wobei der Schwerpunkt auf Operationen liegt, die asymmetrische Schlüssel, Zufallszahlengenerierung und Hashing beinhalten. In der folgenden Tabelle sind die Anwendungsfälle und die zu unterstützenden PKCS #11 -APIs aufgeführt.

Anwendungsfälle
Anwendungsfall	Erforderliche PKCS #11 -API-Familie
Alle	Sitzung initialisieren, abschließen, öffnen/schließen, GetSlotList, Einloggen
Bereitstellung	GenerateKeyPair, CreateObject, DestroyObject, InitToken, GetTokenInfo
TLS	Zufällig, Zeichen, FindObject, GetAttributeValue
FreeRTOS+TCP	Zufällig, Digest
OTA	Verifizieren, Digest, FindObject, GetAttributeValue

Wann sollte ein vollständiges PKCS #11 -Modul implementiert werden

Die Speicherung privater Schlüssel in einem universellen Flash-Speicher kann in Evaluierungs- und Rapid-Prototyping-Szenarien nützlich sein. Wir empfehlen die Verwendung spezieller kryptografischer Hardware, um die Gefahr von Datendiebstahl und Geräteduplizierung in Produktionsszenarien zu verringern. Die kryptographische Hardware enthält Komponenten mit Funktionen, die den Export kryptographischer Geheimschlüssel verhindern. Um dies zu unterstützen, müssen Sie eine Teilmenge von PKCS #11 implementieren, die für die Arbeit mit FreeRTOS-Bibliotheken erforderlich ist, wie in der obigen Tabelle definiert.

Wann verwende ich FreeRTOS CorePKCS11

Die CorePKCS11-Bibliothek enthält eine softwarebasierte Implementierung der PKCS #11 -Schnittstelle (API), die die kryptografische Funktionalität von verwendetTLS einbetten. Dies ist für Rapid-Prototyping- und Evaluierungsszenarien vorgesehen, in denen die Hardware nicht über eine spezielle kryptografische Hardware verfügt. In diesem Fall müssen Sie nur CorePKCS11 PAL implementieren, damit die softwarebasierte CorePKCS11-Implementierung mit Ihrer Hardwareplattform funktioniert.

Portierung von CorePKCS11

Sie benötigen Implementierungen zum Lesen und Schreiben kryptografischer Objekte in nichtflüchtigen Speicher (NVM), z. B. im integrierten Flash-Speicher. Kryptografische Objekte müssen in einem NVM-Abschnitt gespeichert werden, der nicht initialisiert und bei einer Neuprogrammierung des Geräts nicht gelöscht wird. Benutzer der CorePKCS11-Bibliothek stellen Geräten Anmeldeinformationen zur Verfügung und programmieren das Gerät anschließend mit einer neuen Anwendung neu, die über die CorePKCS11-Schnittstelle auf diese Anmeldeinformationen zugreift. Die CorePKCS11 PAL-Ports müssen einen Speicherort für Folgendes bereitstellen:

• Das Geräteclient-Zertifikat

• Der private Schlüssel des Geräteclients

• Der öffentliche Schlüssel des Geräteclients

• Eine vertrauenswürdige Root-CA

• Ein öffentlicher Schlüssel zur Codeverifizierung (oder ein Zertifikat, das den öffentlichen Schlüssel zur Codeverifizierung enthält) für einen sicheren Bootloader und over-the-air (OTA) -Aktualisierungen

• Ein Just-In-Time-Bereitstellungszertifikat

Einschließendie Header-Dateiund implementieren Sie die definierten PAL-APIs.

PAL-APIs
Funktion	Beschreibung
PKCS11_PAL_Initialize	Initialisiert die PAL-Ebene. Wird von der CorePKCS11-Bibliothek zu Beginn ihrer Initialisierungssequenz aufgerufen.
PKCS11_PAL_SaveObject	Schreibt Daten in den nichtflüchtigen Speicher.
PKCS11_PAL_FindObject	Verwendet einen PKCS # 11 CKA_LABEL, um nach einem entsprechenden PKCS #11-Objekt im nichtflüchtigen Speicher zu suchen, und gibt das Handle dieses Objekts zurück, falls es existiert.
PKCS11_PAL_GetObjectValue	Liefert den Wert eines Objekts entsprechend dem Handle.
PKCS11_PAL_GetObjectValueCleanup	Bereinigung für den PKCS11_PAL_GetObjectValue-Aufruf. Kann verwendet werden, um den in einem PKCS11_PAL_GetObjectValue-Aufruf zugewiesenen Speicherplatz freizugeben.

Testen

Wenn Sie die FreeRTOS CorePKCS11-Bibliothek verwenden oder die erforderliche Teilmenge der PKCS11-APIs implementieren, müssen Sie die FreeRTOS-PKCS11-Tests bestehen. Diese testen, ob die erforderlichen Funktionen für FreeRTOS-Bibliotheken erwartungsgemäß funktionieren.

Darüber hinaus beschreibt dieser Abschnitt, wie Sie die FreeRTOS SDK-11 Tests mit den Qualifizierungstests lokal ausführen können.

Voraussetzungen

Um die FreeRTOS PKCS11-Tests einzurichten, muss Folgendes implementiert werden.

• Ein unterstützter Port von PKCS11-APIs.

• Eine Implementierung von Funktionen der FreeRTOS-Plattform für Qualifizierungstests, die Folgendes umfassen:

  • FRTest_ThreadCreate

  • FRTest_ThreadTimedJoin

  • FRTest_MemoryAlloc

  • FRTest_MemoryFree

(SieheREADME.mdDatei für die Integrationstests der FreeRTOS-Bibliotheken für PKCS #11 auf GitHub.)

Tests portieren

• Fügt hinzuFreeRTOS-Bibliotheken — Integrationstestsals Submodul in Ihr Projekt. Das Submodul kann in einem beliebigen Verzeichnis des Projekts platziert werden, sofern es erstellt werden kann.

• Kopierenconfig_template/test_execution_config_template.hundconfig_template/test_param_config_template.hzu einem Projektspeicherort im Build-Pfad und benennen sie um intest_execution_config.hundtest_param_config.h.

• Fügen Sie relevante Dateien in das Build-System ein. Wenn Sie verwendenCMake,qualification_test.cmakeundsrc/pkcs11_tests.cmakekann verwendet werden, um relevante Dateien einzuschließen.

• ImplementierenUNITY_OUTPUT_CHARsodass Testausgabeprotokolle und Geräteprotokolle nicht ineinander überlappen.

• Integrieren Sie das MbedTLS, das das Ergebnis des Cryptoki-Vorgangs verifiziert.

• Rufen Sie anRunQualificationTest()aus der Anwendung.

Tests konfigurieren

Die PKCS11-Testsuite muss entsprechend der PKCS11-Implementierung konfiguriert werden. Darüber hinaus beschreibt die folgende Tabelle die für PKCS11-Tests in dertest_param_config.hHeader-Datei.

PKSC11-Testkonfigurationen
Konfiguration	Beschreibung
PKCS11_TEST_RSA_KEY_SUPPORT	Die Portierung unterstützt RSA-Schlüsselfunktionen.
PKCS11_TEST_EC_KEY_SUPPORT	Die Portierung unterstützt EC-Schlüsselfunktionen.
PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT	Die Portierung unterstützt den Import des privaten Schlüssels. Der Import von RSA- und EC-Schlüsseln wird im Test validiert, wenn die unterstützenden Schlüsselfunktionen aktiviert sind.
PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT	Die Portierung unterstützt die Generierung von Schlüsselpaaren. Die Generierung von EC-Schlüsselpaaren wird im Test validiert, wenn die unterstützenden Tastenfunktionen aktiviert sind.
PKCS11_TEST_PREPROVISIONED_SUPPORT	Für die Portierung wurden vorab Anmeldeinformationen bereitgestellt.PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS,PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLSundPKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS, sind Beispiele für die Referenzen.
PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS	Die Bezeichnung des privaten Schlüssels, der im Test verwendet wurde.
PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS	Die Bezeichnung des öffentlichen Schlüssels, der im Test verwendet wurde.
PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS	Die Bezeichnung des im Test verwendeten Zertifikats.
PKCS11_TEST_JITP_CODEVERIFY_ROOT_CERT_SUPPORTED	Die Portierung unterstützt Speicher für JITP. Stellen Sie diesen Wert auf 1, um das JITP zu aktivierencodeverifytesten.
PKCS11_TEST_LABEL_CODE_VERIFICATION KEY	Die Bezeichnung des in JITP verwendeten Code-Bestätigungsschlüsselscodeverifytesten.
PKCS11_TEST_LABEL_JITP_CERTIFICATE	Die Bezeichnung des in JITP verwendeten JITP-Zertifikatscodeverifytesten.
PKCS11_TEST_LABEL_ROOT_CERTIFICATE	Die Bezeichnung des in JITP verwendeten Stammzertifikatscodeverifytesten.

FreeRTOS-Bibliotheken und Referenzintegrationen müssen mindestens eine Tastenfunktionskonfiguration wie RSA oder Elliptic Curve Keys sowie einen von den PKCS11-APIs unterstützten Schlüsselbereitstellungsmechanismus unterstützen. Der Test muss die folgenden Konfigurationen ermöglichen:

• Mindestens eine der folgenden Tastenfunktionskonfigurationen:

  • PKCS11_TEST_RSA_KEY_SUPPORT

  • PKCS11_TEST_EC_KEY_SUPPORT

• Darüber hinaus beschreibt dieser Abschnitt mindestens eine der wichtigsten Bereitstellungskonfigurationen:

  • PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT

  • PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT

  • PKCS11_TEST_PREPROVISIONED_SUPPORT

Der Test der vorab bereitgestellten Geräte-Anmeldeinformationen muss unter den folgenden Bedingungen ausgeführt werden:

• PKCS11_TEST_PREPROVISIONED_SUPPORTmuss aktiviert und andere Bereitstellungsmechanismen deaktiviert sein.

• Entweder nur eine SchlüsselfunktionPKCS11_TEST_RSA_KEY_SUPPORToderPKCS11_TEST_EC_KEY_SUPPORT, ist aktiviert.

• Richten Sie die vorab bereitgestellten Tastenbeschriftungen entsprechend Ihrer Schlüsselfunktion ein, einschließlichPKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS,PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLSundPKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS. Diese Anmeldeinformationen müssen vorhanden sein, bevor der Test ausgeführt wird.

Der Test muss möglicherweise mehrmals mit unterschiedlichen Konfigurationen ausgeführt werden, wenn die Implementierung vorab bereitgestellte Anmeldeinformationen und andere Bereitstellungsmechanismen unterstützt.

Anmerkung

Die Objekte mit BeschriftungenPKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS,PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLSundPKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLSwerden während des Tests zerstört, wenn entwederPKCS11_TEST_GENERATE_KEYPAIR_SUPPORToderPKCS11_TEST_GENERATE_KEYPAIR_SUPPORTist aktiviert.

Ausführen von Tests

In diesem Abschnitt wird beschrieben, wie Sie die PKCS11-Schnittstelle mit den Qualifikationstests lokal testen können. Darüber hinaus können Sie IDT verwenden, um die Ausführung zu automatisieren. SieheAWS IoT Device Testerfür FreeRTOSin derFreeRTOS-Benutzerhandbuchfür Einzelheiten.

Darüber hinaus beschreibt die folgende Anleitung, wie die Tests durchgeführt werden:

• Öffnentest_execution_config.hund definiereCORE_PKCS11_TEST_ENABLEDbis 1.

• Erstellen Sie die Anwendung und flashen Sie sie auf Ihr Gerät, um sie auszuführen. Die Testergebnisse werden an die serielle Schnittstelle ausgegeben.

Darüber hinaus beschreibt dieser Abschnitt ein Beispiel für das ausgegebene Testergebnis.

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
    

Der Test ist abgeschlossen, wenn alle Tests erfolgreich absolviert wurden.

Anmerkung

Um ein Gerät offiziell für FreeRTOS zu qualifizieren, müssen Sie den portierten Quellcode des Geräts mit validierenAWS IoT Device Tester. Folgen Sie den Anweisungen inBenutzenAWS IoT Device Testerfür FreeRTOSim FreeRTOS User Guide zur EinrichtungAWS IoT Device Testerfür die Portvalidierung. Um den Port einer bestimmten Bibliothek zu testen, muss die richtige Testgruppe in derdevice.jsonDatei imAWS IoT Device Tester configsOrdner.