Skip to content

wolfBoot鍵ツール

keygenとsignは、PCまたは自動化されたサーバー環境で使用するコマンドラインツールで、wolfBootの秘密鍵を管理し、ターゲットの初期ファームウェアとすべての更新に署名するために使用されます。

CまたはPython

ツールは、移植性の理由から、同じコマンドライン構文を使用する2つのバージョンで配布しています。

デフォルトでは、C鍵ツールがコンパイルされます。このリポジトリのMakefileとスクリプトはCツールを使用します。

C鍵ツール

鍵ツールのスタンドアロンCバージョンは、./tools/keytoolsで利用できます。

これらはtools/keytoolsでmakeを使用するか、wolfBootのルートからmake keytoolsを使用してビルドできます。

Cバージョンの鍵ツールが存在する場合、それらはwolfBootのMakefileとスクリプトによって使用されます。

Windows Visual Studio

Windows用のsign.exeとkeygen.exeツールをビルドするには、wolfBootSignTool.vcxproj Visual Studioプロジェクトを使用します。

欠落しているtarget.hに関するエラーが表示された場合、これはmakeプロセスを使用して.configに基づいて生成されるファイルです。 デルタ更新で使用されるWOLFBOOT_SECTOR_SIZEに必要です。

Python鍵ツール

Pythonツールは非推奨であり、将来のバージョンでは削除される予定であることに注意してください。

Python鍵ツールを使用するには、Pythonの環境にwolfcryptパッケージがインストールされていることを確認してください。ほとんどのシステムでは、以下のようなコマンドを実行するだけで十分です。

pip install wolfcrypt

これにより、依存関係が満たされていることが確認されます。

コマンドラインツールの使用方法

鍵生成ツール

使用法: keygen [OPTIONS] [-g new-keypair.der] [-i existing-pubkey.der] [...]

keygenは既存の新しい公開鍵で鍵ストアを埋めるために使用されます。 2つのオプションをサポートしています。

  • -g privkey.der 新しい鍵ペアを生成し、公開鍵を鍵ストアに追加し、秘密鍵を新しいファイルprivkey.derに保存します
  • -i existing.der 既存の公開鍵をexisting.derからインポートします
  • --der 生成された秘密鍵をDER形式で保存します

引数は排他的ではなく、複数の鍵で鍵ストアを埋めるために複数回繰り返すことができます。

鍵ストアで有効なアルゴリズムを選択するために、1つのオプションを指定する必要があります（例：--ed25519または--rsa3072）。 使用可能なオプションについては、署名ツールの「公開鍵署名オプション」セクションを参照してください。

鍵ジェネレーターツールによって生成されるファイルは次のとおりです。

  • Cファイルsrc/keystore.c、鍵が生成されたCコードを通じてプロビジョニングされる場合、通常はwolfBootイメージとリンクされます。
  • バイナリファイルkeystore.img、代替ストレージを通じて公開鍵をプロビジョニングするために使用できます。
  • コマンドラインから提供された各-gオプションに対する秘密鍵。

鍵ストアメカニズムの詳細については、付録Dを参照してください。

サインツール

signは、wolfBootでサポートされている形式でマニフェストヘッダーを作成することにより、署名付きファームウェアイメージを生成します。

使用法: sign [OPTIONS] IMAGE.BIN KEY.DER VERSION

IMAGE.BIN: 署名するバイナリファームウェア/ソフトウェアを含むファイル KEY.DER: バイナリイメージに署名するためのDER形式の秘密鍵ファイル VERSION: この署名されたソフトウェアに関連付けられたバージョン OPTIONS: 以下で説明される0個以上のオプション

公開鍵署名オプション

以下の引数のいずれも指定されていない場合、ツールはKEY.DERで検出された形式と鍵の長さから鍵のサイズを推測しようとします。

  • --ed25519 ファームウェアの署名にED25519を使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --ed448 ファームウェアの署名にED448を使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --ecc256 ファームウェアの署名にecc256を使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --ecc384 ファームウェアの署名にecc384を使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --ecc521 ファームウェアの署名にecc521を使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --rsa2048 ファームウェアの署名にrsa2048を使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --rsa3072 ファームウェアの署名にrsa3072を使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --rsa4096 ファームウェアの署名にrsa4096を使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --lms ファームウェアの署名にLMS/HSSを使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --xmss ファームウェアの署名にXMSS/XMSS^MTを使用します。指定されたKEY.DERファイルがこの形式であると仮定します。

  • --no-sign セキュアブート署名検証を無効にします。ブートローダーでは署名検証が実行されず、KEY.DER引数は提供しないでください。

ハッシュダイジェストオプション

以下のいずれも使用されない場合、デフォルトでは「--sha256」が想定されます。

  • --sha256 バイナリイメージと公開鍵のダイジェスト計算にsha256を使用します。

  • --sha348 バイナリイメージと公開鍵のダイジェスト計算にsha384を使用します。

  • --sha3 バイナリイメージと公開鍵のダイジェスト計算にsha3-384を使用します。

ターゲットパーティションID（複数パーティションイメージ、「自己更新」機能）

以下のいずれも使用されない場合、デフォルトでは「--id=1」が想定されます。 検証する単一のイメージを持つシステム（例：単一のアクティブパーティションを持つマイクロコントローラー）では、ID=1はステージングするファームウェアイメージのデフォルト識別子です。 ID=0はwolfBootの「自己更新」用に予約されており、ブートローダー自体が格納されているパーティションを指します。

  • --id N イメージパーティションIDを「N」に設定します。

  • --wolfboot-update イメージにブートローダー用の署名された自己更新パッケージが含まれていることを示します。--id 0と同等です。

対称鍵を使用した暗号化

認証のために署名していますが、デフォルトではイメージは暗号化されておらず、平文として配布されます。 外部の不揮発性メモリにファームウェアが保存されている場合、ファームウェアパッケージングから更新プロセスまでのエンドツーエンドの暗号化を使用できます。 暗号化された更新は、事前共有の秘密対称鍵を使用して、次のオプションを渡すことで生成できます。

  • --encrypt SHAREDKEY.BIN ファイルSHAREKEY.BINを使用してイメージを暗号化します。

ファイルの形式は、暗号化に選択されたアルゴリズムによって異なります。 形式が指定されておらず、--encrypt SHAREDKEY.BINオプションが存在する場合、デフォルトでは--chachaが想定されます。

以下のオプションを参照してください。

  • --chacha イメージの暗号化にChaCha20アルゴリズムを使用します。ファイルSHAREDKEY.BINは正確に44バイトのサイズであることが期待され、そのうち32バイトが鍵に、12バイトがIVの初期化に使用されます。

  • --aes128 イメージの暗号化にカウンターモードでAES-128アルゴリズムを使用します。ファイルSHAREDKEY.BINは正確に32バイトのサイズであることが期待され、そのうち16バイトが鍵に、16バイトがIVの初期化に使用されます。

  • --aes256 イメージの暗号化にカウンターモードでAES-256アルゴリズムを使用します。ファイルSHAREDKEY.BINは正確に48バイトのサイズであることが期待され、そのうち32バイトが鍵に、16バイトがIVの初期化に使用されます。

デルタ更新（既知のバージョンからの増分更新）

以下のオプションが提供されると、署名ツールを使用して増分更新が作成されます。

  • --delta BASE_SIGNED_IMG.BIN このオプションは、BASE_SIGNED_IMG.BINとIMAGE.BINから署名された新しいイメージの間のバイナリ差分ファイルを作成します。結果は_signed_diff.binで終わるファイルに保存されます。

圧縮は、Bentley–Mcllroyで行われます。

ポリシー署名（TPMでのシーリング/アンシーリング用）

ヘッダーに含めて署名するPCRマスクとダイジェストを提供します。署名鍵はダイジェストに署名するために使用されます。

  • --policy policy.bin: この引数は多目的です。 デフォルトでは、ファイルには署名される4バイトのPCRマスクとSHA2-256 PCRダイジェストが含まれている必要があります。 --manual-signを使用する場合、ファイルには4バイトのPCRマスクと署名が含まれている必要があります。 PCRマスクと署名はHDR_POLICY_SIGNATUREヘッダータグに含まれます。 最終的に署名されたポリシー（4バイトのPCRマスクを含む）のコピーが[inputname].sigに出力されます。

注意：これにはヘッダーに2つの署名が保存されるため、IMAGE_HEADER_SIZEの増加が必要になる場合があります。

マニフェストヘッダーへのカスタムフィールドの追加

カスタムタグで設定される値を提供します

  • --custom-tlv tag len val: マニフェストヘッダーにTLVエントリを追加します。tagによって識別されるタイプに対応し、長さlenバイトで、値valを割り当てます。 値は10進数または16進数（'0x'が前に付いている）です。タグは16ビットの数字です。 有効なタグは0x0030から0xFEFEの範囲です。

  • --custom-tlv-buffer tag value: 任意の長さのTLVエントリをマニフェストヘッダーに追加します。tagによって識別されるタイプに対応し、値valueを割り当てます。タグは16ビットの数字です。有効なタグは0x0030から0xFEFEの範囲です。長さは暗黙的であり、値の長さです。 値引数は16進文字列の形式です。例えば、--custom-tlv-buffer 0x0030 AABBCCDDEE はタグ0x0030、長さ5、値0xAABBCCDDEEのTLVエントリを追加します。

  • --custom-tlv-string tag ascii-string: 任意の長さのTLVエントリをマニフェストヘッダーに追加します。tagによって識別されるタイプに対応し、ascii-stringの値を割り当てます。タグは16ビットの数字です。有効なタグは0x0030から0xFEFEの範囲です。長さは暗黙的であり、ascii-stringの長さです。ascii-string引数は文字列の形式です。 例えば、--custom-tlv-string 0x0030 "Version-1"はタグ0x0030、 長さ9、値Version-1のTLVエントリを追加します。

外部プロビジョニングツールを使用した三段階の署名

秘密鍵がアクセス可能でない場合でも、サードパーティツールを使用してペイロードに署名できます。 署名メカニズムは3つのフェーズに分けることができます。

  • フェーズ1: イメージのshaダイジェストのみを作成し、サードパーティツールによって署名できる中間ファイルを準備します。

これは次のオプションを使用して行われます。

  • --sha-only このオプションが選択されると、署名ツールは署名する必要があるマニフェストの一部を含む中間イメージを作成し、_digest.binで終わるファイルを作成します。この場合、KEY.DERにはフェーズ2でファームウェアに署名するために使用される鍵の公開部分が含まれています。

  • フェーズ2: 中間イメージ*_digest.binは外部ツール、HSM、またはサードパーティの署名サービスによって署名されます。その後、署名はそのraw形式でエクスポートされ、ファイル（例：IMAGE_SIGNATURE.SIG）にコピーされます。

  • フェーズ3: 次のオプションを使用して、最終的な認証済みファームウェアイメージを構築します。このイメージには、前面にマニフェストヘッダーが含まれています。

  • --manual-sign このオプションが提供されると、KEY.DER引数にはフェーズ2でファームウェアの署名に使用された鍵の公開部分が含まれています。このオプションには、VERSION後に1つの追加引数が必要で、これは前のフェーズの出力であった署名のファイル名、つまりIMAGE_SIGNATURE.SIGである必要があります。

実際の例については、以下のセクションをご覧ください。

使用例

ファームウェアへの署名

  1. 署名に使用する秘密鍵を./wolfboot_signing_private_key.derにロードします。
  2. 非対称アルゴリズム、ハッシュアルゴリズム、署名するファイル、鍵、バージョンを指定して署名ツールを実行します。
./tools/keytools/sign --rsa2048 --sha256 test-app/image.bin wolfboot_signing_private_key.der 1

注：最後の引数は「バージョン」番号です。

外部秘密鍵（HSM）を使用したファームウェアへの署名

外部鍵ソースを使用してファームウェアに手動で署名するための手順は次の通りです。

# Create file with Public Key
openssl rsa -inform DER -outform DER -in my_key.der -out rsa2048_pub.der -pubout

# Add the public key to the wolfBoot keystore using `keygen -i`
./tools/keytools/keygen --rsa2048 -i rsa2048_pub.der

# Generate Hash to Sign
./tools/keytools/sign --rsa2048 --sha-only --sha256 test-app/image.bin rsa2048_pub.der 1

# Sign hash Example (here is where you would use an HSM)
openssl pkeyutl -sign -keyform der -inkey my_key.der -in test-app/image_v1_digest.bin > test-app/image_v1.sig

# Generate final signed binary
./tools/keytools/sign --rsa2048 --sha256 --manual-sign test-app/image.bin rsa2048_pub.der 1 test-app/image_v1.sig

# Combine into factory image (0xc0000 is the WOLFBOOT_PARTITION_BOOT_ADDRESS)
tools/bin-assemble/bin-assemble factory.bin 0x0 wolfboot.bin \
                              0xc0000 test-app/image_v1_signed.bin

Azure Key Vaultを使用したファームウェアへの署名

付録Bを参照してください。