翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # corePKCS11 ライブラリの移植 公開鍵暗号標準 \$111 では、暗号化トークンを管理および使用するためのプラットフォームに依存しない API が定義されています。[PKCS 11](https://en.wikipedia.org/wiki/PKCS_11) は、標準と、標準で定義された API を指します。PKCS \$111 暗号化 API は、キーストレージ、暗号化オブジェクトプロパティの取得/設定、およびセッションセマンティクスを抽象化します。これは、一般的な暗号オブジェクトの操作に広く使用されています。その機能により、アプリケーションソフトウェアは、暗号化オブジェクトをアプリケーションのメモリに公開することなく使用、作成、変更、削除することができます。 FreeRTOS ライブラリとリファレンス統合は、非対称キー、乱数生成、ハッシュなどの操作に重点を置いて、PCKS \$111 インターフェイス標準のサブセットを使用します。以下の表は、ユースケースとサポートする必要のある PKCS \$111 API の一覧です。 **ユースケース** | ユースケース | 必要な PKCS \$111 API ファミリー | | --- | --- | | すべて | 初期化、完了、セッションのオープン/クローズ、GetSlotList、ログイン | | プロビジョニング | GenerateKeyPair、CreateObject、DestroyObject、InitToken、GetTokenInfo | | TLS | ランダム、署名、FindObject、GetAttributeValue | | FreeRTOS\$1TCP | ランダム、ダイジェスト | | OTA | 検証、ダイジェスト、FindObject、GetAttributeValue | ## PKCS \$111 モジュール全体を実装するタイミング 汎用のフラッシュメモリにプライベートキーを格納すると、評価やラピッドプロトタイピングのシナリオで便利になります。本稼働シナリオでは、データの盗難やデバイスの複製による脅威を軽減するために、専用の暗号化ハードウェアを使用することをお勧めします。暗号化ハードウェアには、暗号化シークレットキーのエクスポートを妨げる機能を備えたコンポーネントが含まれています。これをサポートするには、上の表で定義されているように、FreeRTOS ライブラリを操作するために必要な PKCS \$111 のサブセットを実装する必要があります。 ## FreeRTOS corePKCS11 を使用するタイミング corePKCS11 ライブラリには、[Mbed TLS](https://tls.mbed.org/) が提供する暗号化機能を使用する PKCS \$111 インターフェイス (API) のソフトウェアベースの実装が含まれています。これは、ハードウェアに専用の暗号化ハードウェアがない場合のラピッドプロトタイピングや評価のシナリオのために用意されています。この場合、corePKCS11 PAL を実装するだけで、corePKCS11 ソフトウェアベースの実装がユーザーのハードウェアプラットフォームで動作するようになります。 ## corePKCS11 の移植 オンボードフラッシュメモリなどの不揮発性メモリ (NVM) への暗号化オブジェクトの読み書きには、実装が必要です。暗号化オブジェクトは、初期化されておらず、デバイスの再プログラミングで消去されない NVM のセクションに格納する必要があります。corePKCS11 ライブラリのユーザーは、認証情報を使用してデバイスをプロビジョニングしてから、こうした認証情報にアクセスする際に corePKCS11 インターフェイスを介する新しいアプリケーションを使用して、デバイスを再プログラムします。corePKCS11 PAL 移植は、以下を保存する場所を提供する必要があります。 + デバイスのクライアント証明書 + デバイスのクライアントのプライベートキー + デバイスクのライアントのパブリックキー + 信頼されたルート CA + 安全なブートローダーと無線通信 (OTA) 更新用のコード検証パブリックキー (またはコード検証パブリックキーを含む証明書) + ジャストインタイムのプロビジョニング証明書 [ヘッダーファイル](https://github.com/FreeRTOS/corePKCS11/blob/main/source/include/core_pkcs11_pal.h)を含め、定義された PAL API を実装します。 **PAL API** | 関数 | 説明 | | --- | --- | | PKCS11\$1PAL\$1Initialize | PAL レイヤーを初期化します。初期化シーケンスの開始時に corePKCS11 ライブラリによって呼び出されます。 | | PKCS11\$1PAL\$1SaveObject | データを不揮発性ストレージに書き込みます。 | | PKCS11\$1PAL\$1FindObject | PKCS \$111 `CKA_LABEL` を使用して、不揮発性ストレージ内の対応する PKCS \$111 オブジェクトを検索し、存在する場合はそのオブジェクトのハンドルを返します。 | | PKCS11\$1PAL\$1GetObjectValue | ハンドルを指定して、オブジェクトの値を取得します。 | | PKCS11\$1PAL\$1GetObjectValueCleanup | `PKCS11_PAL_GetObjectValue` 呼び出しのクリーンアップ。`PKCS11_PAL_GetObjectValue` 呼び出しで割り当てられたメモリを解放するために使用できます。 | ## テスト FreeRTOS corePKCS11 ライブラリを使用するか、PKCS11 API の必要なサブセットを実装する場合は、FreeRTOS PKCS11 テストに合格する必要があります。これらは、FreeRTOS ライブラリに必要な関数が期待どおりに動作するかどうかをテストします。 このセクションでは、認定テストを使用して FreeRTOS PKCS11 テストをローカルで実行する方法についても説明します。 ### 前提条件 FreeRTOS PKCS11 テストをセットアップするには、以下を実装する必要があります。 + サポートされている PKCS11 API のポート。 + FreeRTOS 認定の実装では、以下を含むプラットフォーム機能がテストされます。 + `FRTest_ThreadCreate` + `FRTest_ThreadTimedJoin` + `FRTest_MemoryAlloc` + `FRTest_MemoryFree` (GitHub の PKCS \$111 の FreeRTOS ライブラリ統合テストについては、[README.md](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11) ファイルを参照してください。) ### 移植テスト + [FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11) をサブモジュールとしてプロジェクトに追加します。サブモジュールは、ビルド可能な限り、プロジェクトのどのディレクトリにも配置できます。 + `config_template/test_execution_config_template.h` と `config_template/test_param_config_template.h` をビルドパス内のプロジェクトの場所にコピーし、名前を `test_execution_config.h` と `test_param_config.h` に変更します。 + 関連ファイルをビルドシステムに含めます。`CMake` を使用している場合は、`qualification_test.cmake` と `src/pkcs11_tests.cmake` を使用して関連ファイルを含めることができます。 + テスト出力ログとデバイスログがインターリーブしないように、`UNITY_OUTPUT_CHAR` を実装します。 + MbedTLS を統合し、これにより cryptoki オペレーションの結果を検証します。 + アプリケーションから `RunQualificationTest()` を呼び出します。 ### テストの設定 PKCS11 テストスイートは、PKCS11 実装に従って設定する必要があります。次の表は、PKCS11 テストに必要な `test_param_config.h` ヘッダーファイル内の設定を示しています。 **PKSC11 テスト設定** | 設定 | 説明 | | --- | --- | | PKCS11\$1TEST\$1RSA\$1KEY\$1SUPPORT | 移植は RSA キーの機能をサポートします。 | | PKCS11\$1TEST\$1EC\$1KEY\$1SUPPORT | 移植は EC キーの機能をサポートします。 | | PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT | 移植はプライベートキーのインポートをサポートします。RSA キーと EC キーのインポートは、サポートしているキー機能が有効になっている場合にテストで検証されます。 | | PKCS11\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT | 移植はキーペア生成をサポートします。EC キーペア生成は、サポートしているキー機能が有効になっている場合にテストで検証されます。 | | PKCS11\$1TEST\$1PREPROVISIONED\$1SUPPORT | 移植には認証情報が事前にプロビジョニングされています。認証情報の例としては、`PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`、`PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS`、`PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS` が挙げられます。 | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1PRIVATE\$1KEY\$1FOR\$1TLS | テストで使用されるプライベートキーのラベル。 | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1PUBLIC\$1KEY\$1FOR\$1TLS | テストで使用されるパブリックキーのラベル。 | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1CERTIFICATE\$1FOR\$1TLS | テストで使用される証明書のラベル。 | | PKCS11\$1TEST\$1JITP\$1CODEVERIFY\$1ROOT\$1CERT\$1SUPPORTED | 移植は JITP のストレージをサポートします。これを 1 に設定すると、JITP `codeverify` テストが有効になります。 | | PKCS11\$1TEST\$1LABEL\$1CODE\$1VERIFICATION\$1KEY | JITP `codeverify` テストで使用されるコード検証キーのラベル。 | | PKCS11\$1TEST\$1LABEL\$1JITP\$1CERTIFICATE | JITP `codeverify` テストで使用される JITP 証明書のラベル。 | | PKCS11\$1TEST\$1LABEL\$1ROOT\$1CERTIFICATE | JITP `codeverify` テストで使用されるルート証明書のラベル。 | FreeRTOS ライブラリとリファレンス統合は、RSA キーや楕円曲線キーなどのキー機能設定のうち少なくとも 1 つと、PKCS11 API がサポートするキープロビジョニングメカニズムのうち少なくとも 1 つをサポートする必要があります。テストでは以下の設定を有効にする必要があります。 + 次のキー機能設定のうち少なくとも 1 つ: + PKCS11\$1TEST\$1RSA\$1KEY\$1SUPPORT + PKCS11\$1TEST\$1EC\$1KEY\$1SUPPORT + 次のキープロビジョニング設定のうち少なくとも 1 つ: + PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT + PKCS11\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT + PKCS11\$1TEST\$1PREPROVISIONED\$1SUPPORT 事前にプロビジョニングされたデバイス認証情報テストは、以下の条件で実行する必要があります。 + `PKCS11_TEST_PREPROVISIONED_SUPPORT` を有効にし、他のプロビジョニングメカニズムを無効にする必要があります。 + 有効になっているのは、`PKCS11_TEST_RSA_KEY_SUPPORT` または `PKCS11_TEST_EC_KEY_SUPPORT` のどちらか 1 つのキー機能だけです。 + ユーザーのキー機能に応じて、`PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`、`PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS`、`PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS` など、事前にプロビジョニングされたキーラベルを設定します。テストを実行する前に、これらの認証情報が存在している必要があります。 実装が事前にプロビジョニングされた認証情報やその他のプロビジョニングメカニズムをサポートしている場合、テストを異なる設定で複数回実行する必要がある場合があります。 **注記** ラベル付きオブジェクト `PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`、`PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS`、`PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS` は、`PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT` または `PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT` のどちらか 1 つが有効になっている場合、テスト中に破棄されます。 ### テストを実行する このセクションでは、認定テストを使用して PKCS11 インターフェイスをローカルでテストする方法について説明します。または、IDT を使用して実行を自動化することもできます。詳細については、「FreeRTOS ユーザーガイド」の「[AWS IoT Device Tester for FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html)」を参照してください。 次の手順では、テストの実行方法について説明します。 + `test_execution_config.h` を開いて、**CORE\$1PKCS11\$1TEST\$1ENABLED** を 1 に定義します。 + アプリケーションをビルドし、デバイスにフラッシュして実行します。テスト結果はシリアルポートに出力されます。 次は出力されたテスト結果の例です。 ``` 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 ``` すべてのテストに合格したら、テストは完了です。 **注記** デバイスを正式に FreeRTOS 向けに資格認定するには、AWS IoT Device Tester でデバイスの移植されたソースコードを検証する必要があります。「FreeRTOS ユーザーガイド」の「[Using AWS IoT Device Tester for FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html)」に記載されている手順に従って、移植の検証に使う AWS IoT Device Tester を設定します。特定のライブラリのポートをテストするには、AWS IoT Device Tester `configs` フォルダの `device.json` ファイルで正しいテストグループを有効にする必要があります。