PKCS #11 モジュール全体を実装するタイミング FreeRTOS corePKCS11 を使用するタイミング corePKCS11 の移植テスト

corePKCS11 ライブラリの移植

公開鍵暗号標準 #11 では、暗号化トークンを管理および使用するためのプラットフォームに依存しない API が定義されています。PKCS 11 は、標準と、標準で定義された API を指します。PKCS #11 暗号化 API は、キーストレージ、暗号化オブジェクトプロパティの取得/設定、およびセッションセマンティクスを抽象化します。これは、一般的な暗号オブジェクトの操作に広く使用されています。その機能により、アプリケーションソフトウェアは、暗号化オブジェクトをアプリケーションのメモリに公開することなく使用、作成、変更、削除することができます。

FreeRTOS ライブラリとリファレンス統合は、非対称キー、乱数生成、ハッシュなどの操作に重点を置いて、PCKS #11 インターフェイス標準のサブセットを使用します。以下の表は、ユースケースとサポートする必要のある PKCS #11 API の一覧です。

ユースケース
ユースケース	必要な PKCS #11 API ファミリー
すべて	初期化、完了、セッションのオープン/クローズ、GetSlotList、ログイン
プロビジョニング	GenerateKeyPair、CreateObject、DestroyObject、InitToken、GetTokenInfo
TLS	ランダム、署名、FindObject、GetAttributeValue
FreeRTOS+TCP	ランダム、ダイジェスト
OTA	検証、ダイジェスト、FindObject、GetAttributeValue

PKCS #11 モジュール全体を実装するタイミング

汎用のフラッシュメモリにプライベートキーを格納すると、評価やラピッドプロトタイピングのシナリオで便利になります。本稼働シナリオでは、データの盗難やデバイスの複製による脅威を軽減するために、専用の暗号化ハードウェアを使用することをお勧めします。暗号化ハードウェアには、暗号化シークレットキーのエクスポートを妨げる機能を備えたコンポーネントが含まれています。これをサポートするには、上の表で定義されているように、FreeRTOS ライブラリを操作するために必要な PKCS #11 のサブセットを実装する必要があります。

FreeRTOS corePKCS11 を使用するタイミング

corePKCS11 ライブラリには、Mbed TLS が提供する暗号化機能を使用する PKCS #11 インターフェイス (API) のソフトウェアベースの実装が含まれています。これは、ハードウェアに専用の暗号化ハードウェアがない場合のラピッドプロトタイピングや評価のシナリオのために用意されています。この場合、corePKCS11 PAL を実装するだけで、corePKCS11 ソフトウェアベースの実装がユーザーのハードウェアプラットフォームで動作するようになります。

corePKCS11 の移植

オンボードフラッシュメモリなどの不揮発性メモリ (NVM) への暗号化オブジェクトの読み書きには、実装が必要です。暗号化オブジェクトは、初期化されておらず、デバイスの再プログラミングで消去されない NVM のセクションに格納する必要があります。corePKCS11 ライブラリのユーザーは、認証情報を使用してデバイスをプロビジョニングしてから、こうした認証情報にアクセスする際に corePKCS11 インターフェイスを介する新しいアプリケーションを使用して、デバイスを再プログラムします。corePKCS11 PAL 移植は、以下を保存する場所を提供する必要があります。

デバイスのクライアント証明書
デバイスのクライアントのプライベートキー
デバイスクのライアントのパブリックキー
信頼されたルート CA
安全なブートローダーと無線通信 (OTA) 更新用のコード検証パブリックキー (またはコード検証パブリックキーを含む証明書)
ジャストインタイムのプロビジョニング証明書

ヘッダーファイルを含め、定義された PAL API を実装します。

PAL API
関数	説明
PKCS11_PAL_Initialize	PAL レイヤーを初期化します。初期化シーケンスの開始時に corePKCS11 ライブラリによって呼び出されます。
PKCS11_PAL _SaveObject	データを不揮発性ストレージに書き込みます。
PKCS11_PAL_FindObject	PKCS #11 `CKA_LABEL` を使用して、不揮発性ストレージ内の対応する PKCS #11 オブジェクトを検索し、存在する場合はそのオブジェクトのハンドルを返します。
PKCS11_PAL_GetObjectValue	ハンドルを指定して、オブジェクトの値を取得します。
PKCS11_PAL_GetObjectValueCleanup	`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 #11 の FreeRTOS ライブラリ統合テストについては、README.md ファイルを参照してください。)

移植テスト

FreeRTOS-Libraries-Integration-Tests をサブモジュールとしてプロジェクトに追加します。サブモジュールは、ビルド可能な限り、プロジェクトのどのディレクトリにも配置できます。
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_TEST_RSA_KEY_SUPPORT	移植は RSA キーの機能をサポートします。
PKCS11_TEST_EC_KEY_SUPPORT	移植は EC キーの機能をサポートします。
PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT	移植はプライベートキーのインポートをサポートします。RSA キーと EC キーのインポートは、サポートしているキー機能が有効になっている場合にテストで検証されます。
PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT	移植はキーペア生成をサポートします。EC キーペア生成は、サポートしているキー機能が有効になっている場合にテストで検証されます。
PKCS11_TEST_PREPROVISIONED_SUPPORT	移植には認証情報が事前にプロビジョニングされています。認証情報の例としては、`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_JITP_CODEVERIFY_ROOT_CERT_SUPPORTED	移植は JITP のストレージをサポートします。これを 1 に設定すると、JITP `codeverify` テストが有効になります。
PKCS11_TEST_LABEL_CODE_VERIFICATION_KEY	JITP `codeverify` テストで使用されるコード検証キーのラベル。
PKCS11_TEST_LABEL_JITP_CERTIFICATE	JITP `codeverify` テストで使用される JITP 証明書のラベル。
PKCS11_TEST_LABEL_ROOT_CERTIFICATE	JITP `codeverify` テストで使用されるルート証明書のラベル。

FreeRTOS ライブラリとリファレンス統合は、RSA キーや楕円曲線キーなどのキー機能設定のうち少なくとも 1 つと、PKCS11 API がサポートするキープロビジョニングメカニズムのうち少なくとも 1 つをサポートする必要があります。テストでは以下の設定を有効にする必要があります。

次のキー機能設定のうち少なくとも 1 つ:
- PKCS11_TEST_RSA_KEY_SUPPORT
- PKCS11_TEST_EC_KEY_SUPPORT
次のキープロビジョニング設定のうち少なくとも 1 つ:
- PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT
- PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT
- PKCS11_TEST_PREPROVISIONED_SUPPORT

事前にプロビジョニングされたデバイス認証情報テストは、以下の条件で実行する必要があります。

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」を参照してください。

次の手順では、テストの実行方法について説明します。

test_execution_config.h を開いて、CORE_PKCS11_TEST_ENABLED を 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」に記載されている手順に従って、移植の検証に使う AWS IoT Device Tester を設定します。特定のライブラリのポートをテストするには、AWS IoT Device Tester configs フォルダの device.json ファイルで正しいテストグループを有効にする必要があります。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

TCP/IP

ネットワークトランスポートインターフェイス