Merge pull request #192 from tamasan238/wolfboot-202505

[JA] added appendix1-13

Author: kojo1

wolfBoot/mkdocs-ja.yml

@@ -12,7 +12,20 @@ nav:
     - "6. wolfBootの機能": chapter06.md
     - "7. wolfBootの既存プロジェクトへの統合": chapter07.md
     - "8. トラブルシューティング": chapter08.md
-    - "A. コンフィギュレーションオプション": appendix14.md
+    - "A. ATAセキュリティ": appendix01.md
+    - "B. Microsoft Azure Key Vaultを使用したファームウェアの署名": appendix02.md
+    - "C. One Time Programmable (OTP) フラッシュ領域を鍵ストアとして使用": appendix03.md
+    - "D. KeyStore構造：複数の公開鍵のサポート": appendix04.md
+    - "E. wolfBootをライブラリとしてビルド": appendix05.md
+    - "F. wolfBootローダー/アップデーター": appendix06.md
+    - "G. wolfBootを使用したMeasured Boot": appendix07.md
+    - "H. ポスト量子署名": appendix08.md
+    - "I. UARTを介したリモート外部フラッシュメモリのサポート": appendix09.md
+    - "J. Renesas製品におけるwolfBootの使用": appendix10.md
+    - "K. wolfBoot鍵ツール": appendix11.md
+    - "L. TrustZone-MセキュアドメインにおけるwolfCrypt": appendix12.md
+    - "M. wolfBoot TPMサポート": appendix13.md
+    - "N. コンフィギュレーションオプション": appendix14.md
 theme:
   name: null
   custom_dir: ../mkdocs-material/material

wolfBoot/src-ja/appendix01.md

@@ -0,0 +1,49 @@
+# ATAセキュリティ
+
+## はじめに
+
+この文書は、wolfBootがATAセキュリティ機能を活用してATAドライブをロックまたはアンロックする方法の概要を提供します。
+ATAドライブは、ハードコードされたパスワードを使用するか、TPMに封印された秘密を使用してロックできます。
+
+## 目次
+
+- ハードコードされたパスワードでディスクをアンロックする
+- TPMに封印された秘密でディスクをアンロックする
+- パスワードを無効にする
+
+## ハードコードされたパスワードでディスクをアンロックする
+
+ハードコードされたパスワードを使用してディスクをアンロックするには、`.config`ファイルで次のオプションを使用します。
+
+```
+DISK_LOCK=1
+DISK_LOCK_PASSWORD=hardcoded_password
+```
+
+ATAディスクにパスワードが設定されていない場合、最初の起動時に提供されたパスワードでディスクがロックされます。
+
+## TPMに封印された秘密でディスクをアンロックする
+
+wolfBootは、特定の条件下でのみ解除できる方法でTPMに秘密を安全に封印できます。
+詳細については、[付録M](appendix13.md)と[付録G](appendix07.md)を参照してください。
+オプション`WOLFBOOT_TPM_SEAL`と`DISK_LOCK`が有効になっている場合、wolfBootはディスクのロック解除のためのパスワードとしてTPMに封印された秘密を使用します。
+以下のオプションは、秘密の封印と解除を制御します。
+
+| オプション | 説明 |
+|-----------|----------|
+| WOLFBOOT_TPM_SEAL_KEY_ID| ポリシーに署名するために使用する鍵ID |
+| ATA_UNLOCK_DISK_KEY_NV_INDEX | 封印された秘密を保存するNVインデックス |
+| WOLFBOOT_DEBUG_REMOVE_SEALED_ON_ERROR| エラーの場合、秘密を削除し`panic()`する |
+
+`ATA_UNLOCK_DISK_KEY_NV_INDEX`に封印された秘密がない場合、新しいランダムな秘密が作成され、そのインデックスに封印されます。
+ATAドライブがロックされていない場合、最初の起動時にTPMに封印された秘密でロックされます。
+
+## パスワードを無効にする
+
+パスワードを無効にする必要がある場合、デバイスにはすでにマスターパスワードが設定されている必要があります。
+その後、次のオプションを使用してwolfBootをコンパイルすることで、ドライブからパスワードを無効にしてpanicさせることができます。
+
+```
+WOLFBOOT_ATA_DISABLE_USER_PASSWORD=1
+ATA_MASTER_PASSWORD=the_master_password
+```

wolfBoot/src-ja/appendix02.md

@@ -0,0 +1,95 @@
+# Microsoft Azure Key Vaultを使用したファームウェアの署名
+
+Microsoftは、HSMに保存された鍵を使用して安全な鍵管理およびプロビジョニングツールを提供しています。
+このメカニズムは、管理された鍵を使用したペイロードの署名のサポートを含む複数の目的のための鍵管理を一元化するのに役立ちます。
+これはwolfBootと組み合わせて、複数台のデバイスに公開鍵をプロビジョニングするために使用できます。
+
+## 鍵ストアの準備
+
+wolfBootは提供される`keygen`コマンドラインツールを使用して、鍵ストアに公開鍵をインポートできます。
+`keygen`は生のECC鍵とASN.1形式（.der）の両方をサポートしています。
+
+Azureでは、デバイスをプロビジョニングするためにASN.1形式で公開鍵をダウンロードできます。
+wolfBootでのファームウェア認証に使用する各公開鍵を取得するには、以下を使用します。
+
+```sh
+az keyvault key download --vault-name <vault-name> -n test-signing-key-1 -e DER -f public-key-1.der
+```
+
+鍵ストアは、`keygen`の`-i`（インポート）オプションを使用して公開鍵をインポートして作成できます。
+このオプションは、鍵ストアにさらに多くの鍵を追加するために複数回繰り返すことができます。
+
+```sh
+./tools/keytools/keygen --ecc256 -i public-key-1.der [-i public-key-2.der ...]
+```
+
+## wolfBoot用のファームウェアイメージの署名
+
+任意の外部HSMを使用した署名操作は、[付録B](appendix02.md)の関連セクションに記載されているように、3つのステップで実行されます。
+このセクションでは、Azure Key Vaultを使用してファームウェアイメージに署名する手順について説明します。
+
+### SHA256ダイジェストの取得
+
+ステップ1では、`--sha-only`引数を加えて`./sign`ツールを呼び出し、署名するダイジェストを生成します。
+Vault内で選択した署名鍵に関連付けられた公開鍵を提供する必要があります。
+
+```sh
+./tools/keytools/sign --ecc256 --sha-only --sha256 test-app/image.bin public-key-1.der 1
+```
+
+https RESTリクエストに適合させるために、取得したダイジェストはbase64を使用してエンコードする必要があります。
+
+```sh
+DIGEST=$(cat test-app/image_v1_digest.bin | base64url_encode)
+```
+
+変数`DIGEST`には、リクエストに添付できる鍵の印刷可能なエンコーディングが保存されています。
+
+### Key Vaultを使用してダイジェストに署名するためのHTTPSリクエスト
+
+リクエストを準備するために、まずVaultからアクセストークンを取得し、変数に保存します。
+
+```sh
+ACCESS_TOKEN=$(az account get-access-token --resource "https://vault.azure.net" --query "accessToken" -o tsv)
+```
+
+選択したKey Vaultに関連付けられたURLを使用します。
+
+```sh
+KEY_IDENTIFIER="https://<vault-name>.vault.azure.net/keys/test-signing-key"
+```
+
+cURLを使用してリクエストを実行し、結果を変数に保存します。
+
+```sh
+SIGNING_RESULT=$(curl -X POST \
+    -s "${KEY_IDENTIFIER}/sign?api-version=7.4" \
+    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
+    -H "Content-Type:application/json" \
+    -H "Accept:application/json" \
+    -d "{\"alg\":\"ES256\",\"value\":\"${DIGEST}\"}")
+echo $SIGNING_RESULT
+```
+
+結果の`.value`フィールドには（base64でエンコードされた）署名が含まれています。
+レスポンスから署名を抽出するには、JSONパーサーを使用できます。
+
+```sh
+SIGNATURE=$(jq -jn "$SIGNING_RESULT|.value")
+```
+
+署名はbase64からバイナリにデコードできるようになり、`sign`ツールはその署名をマニフェストヘッダーに組み込むことができます。
+
+```sh
+echo $SIGNATURE| base64url_decode > test-app/image_v1_digest.sig
+```
+
+### 最終ステップ：署名されたファームウェアイメージの作成
+
+HSM 3ステップの第3段階では、`--manual-sign`オプションとAzure REST APIを通じて取得した署名が必要です。
+
+```sh
+./tools/keytools/sign --ecc256 --sha256 --manual-sign test-app/image.bin test-signin-key_pub.der 1 test-app/image_v1_digest.sig
+```
+
+結果のバイナリファイル`image_v1_signed.bin`には、wolfBootによって認証およびステージングできる署名付きファームウェアイメージが保存されます。

wolfBoot/src-ja/appendix03.md

@@ -0,0 +1,187 @@
+# One Time Programmable (OTP) フラッシュ領域を鍵ストアとして使用
+
+一部のマイクロコントローラーは、一度だけ書き込みが可能で消去できないフラッシュメモリの特別な領域を提供しています。
+
+この機能は、ファームウェア更新イメージを認証するために必要な公開鍵を保存する場合に特に便利です。
+公開鍵は自由に配布できる暗号鍵であり、ファームウェア更新イメージの署名を検証するために使用されます。
+公開鍵をOTP領域に保存することで、それらが不変であり改ざんできないことを保証できます。
+
+## OTPを鍵ストアとしてアクセスするためのwolfBootのコンパイル
+
+OTP領域を鍵ストアとして使用するには、`FLASH_OTP_KEYSTORE`オプションを有効にしてwolfBootをコンパイルする必要があります。
+このオプションはデフォルトでは無効であり、鍵ストアはwolfBootバイナリ自体に組み込まれています。
+
+wolfBootがOTP領域を鍵ストアとして使用する場合、実行時にOTP領域から公開鍵を読み取ります。
+公開鍵は、格納されている鍵の数、各鍵のサイズ、その他の情報を含む最初の16バイトヘッダーの後にOTP領域に格納されます。
+
+wolfBootが起動時や更新時にファームウェアイメージの認証を開始するためには、次のセクションで説明するように、公開鍵を別のステップでOTP領域にプロビジョニングする必要があります。
+
+ターゲットデバイスに応じて、OTP領域コンテンツのバイナリイメージを準備するか、`otp-keystore-primer`ファームウェアを使用してターゲットに直接鍵をプロビジョニングできます。
+
+## OTP領域コンテンツのイメージの作成
+
+OTP領域のコンテンツのバイナリイメージを作成できます。
+結果のファイル（`otp.bin`）は、ターゲットOTP領域への書き込みを可能にする任意の外部ツールを使用して手動でプロビジョニングできます。
+
+現在の鍵ストアコンテンツを使用してotp-keystore-genツールをコンパイルするには、次のようにします。
+
+```sh
+make otpgen
+```
+
+そして、イメージファイル`otp.bin`を作成するには、次のようにします。
+
+```sh
+./tools/keytools/otp/otp-keystore-gen
+```
+
+## OTP領域への公開鍵の直接プロビジョニング（プライマー）
+
+`.config`ファイルで`FLASH_OTP_KEYSTORE`オプションを有効にした後、「`make`」を実行してwolfBootをコンパイルすると、`tools/keytools/otp`の下に`otp-keystore-primer`という追加アプリケーションが生成されます。
+このアプリケーションはOTP領域に公開鍵をプロビジョニングするために使用されます。
+このアプリケーションをマイクロコントローラーにフラッシュすることで、鍵ストア（以前に`keygen`によって生成された）に含まれる公開鍵がOTP領域に書き込まれます。
+
+`otp-keystore-primer`アプリケーションは埋め込まれた公開鍵で生成されます。
+鍵は`keygen`コマンドによって生成された`keystore.c`ファイルから取得されます。
+`otp-keystore-primer`アプリケーションは`keystore.c`ファイルから公開鍵を読み取り、OTP領域に書き込みます。
+
+`keygen`アプリケーションで新しい`keystore.c`を生成した後、`make otp`を実行することで、`otp-keystore-primer`アプリケーションを再度生成できます。
+
+> [!警告]
+> `otp-keystore-primer`アプリケーションは一回限りのアプリケーションです。アプリケーションがターゲットで実行されると、公開鍵がOTP領域に書き込まれ、それらを消去することは不可能になります。したがって、公開鍵をOTP領域にプロビジョニングする前に、公開鍵が正しいことを確認し、関連する秘密鍵が安全に保存されていることを確認することが重要です。誤って秘密鍵を紛失すると、OTP領域に保存されている公開鍵は使用できなくなります。
+
+> [!注意]
+> **`otp-keystore-primer`アプリケーションを使用する際は十分注意してください。ご自身の責任で使用してください。**
+
+## 例
+
+### STM32H5 OTP KeyStore
+
+NULCLEO-STM32H563ZI（TrustZone（PKCS11経由）、DualBank、PQ LMSによる署名）の場合
+
+1) 設定と鍵ツールをセットアップする
+
+```sh
+cp config/examples/stm32h5-tz-dualbank-otp-lms.config .config
+make include/target.h
+make keytools
+```
+
+2) OTPに書き込む鍵を生成する
+
+ - `./examples/keytools/keygen --lms -g 1.key -g 2.key -g 3.key -g 4.key -g 5.key`
+
+3) 生成された鍵と`src/keystore.c`をバックアップする
+
+ - wolfBootツリー外の安全な場所に保存する
+
+4) 使用する署名鍵を設定する
+
+ - 生成された鍵の1つを`wolfboot_signing_private_key.der`にコピーする
+ - `cp 1.key wolfboot_signing_private_key.der`
+
+5) OTP鍵ストアをセットアップする
+
+ OTP鍵ストアプライマーをフラッシュする
+ 
+ - `make otp`を実行する
+ - `./tools/keytools/otp/otp-keystore-primer.bin`を`0x08000000`にフラッシュする
+ - ツールを切断してリセットボタンを押す
+ - プライマーが実行され、keystore.cをOTPにフラッシュし、それらのブロックに書き込み保護を有効にする
+
+ または
+
+ 外部ツールを使用してOTP（otp.bin）を生成してフラッシュする
+ 
+ - `make otpgen`を実行する
+ - `./tools/keytools/otp/otp-keystore-gen`を実行してotp.binファイルを生成する
+ - STM32CubeProgrammerなどの外部ツールを使用してotp.binを`0x08FFF000`にプログラムする
+
+6) OTP鍵ストアを検証する
+
+ - アドレス`0x08FFF000`のメモリを読み取る（ASCII「`WOLFBOOT`」で始まるはずです）
+ - 通常はSTM32CubeProgrammerを使用する
+
+7) オプションバイトを設定する
+
+ - ユーザー構成2 -> TrustZone有効（TZEN=0xB4）
+ - Bank1 - フラッシュウォーターマークエリア（`SECWM1_START=0x00`、`SECWM1_END=0x1F`）
+ - Bank2 - フラッシュウォーターマークエリア（`SECWM2_START=0x00`、`SECWM2_END=0x1F`）
+
+8) デバイスの一括消去
+
+ - STM32CubeProgrammer -> フルチップ消去
+
+9) `make`を使用してwolfBootとテストアプリケーションをビルドする
+
+10) wolfBootとtest-appをフラッシュする
+
+- `wolfboot.bin`を`0x0C000000`にフラッシュする
+- `test-app/image_v1_signed.bin`を`0x08040000`にフラッシュする
+
+11) 切断して再起動すると、赤色LEDが点灯するはず。
+
+12) コンソール用にNUCLEOボード上のUSB UARTに接続する
+
+コマンドラインを探索する（helpを実行）
+
+```sh
+========================
+STM32H5 wolfBoot demo Application
+Copyright 2024 wolfSSL Inc
+GPL v3
+Version : 0x1
+========================
+
+cmd> help
+help : shows this help message
+info : display information about the system and partitions
+success : confirm a successful update
+pkcs11 : enable and test crypto calls with PKCS11 in secure mode
+random : generate a random number
+timestamp : print the current timestamp
+benchmark : run the wolfCrypt benchmark
+test : run the wolfCrypt test
+update : update the firmware via XMODEM
+reboot : reboot the system
+```
+
+13) 更新をテストする
+
+ - ファームウェアの新しいバージョンに署名する：`./tools/keytools/sign --lms test-app/image.bin wolfboot_signing_private_key.der 2`
+ - シェルで「update」コマンドを実行し、xmodem転送を待つ
+ - 「minicom」や「CoolTerm」などのxmodemをサポートするシリアルターミナルを使用する。
+   * `/dev/ttyACM0`で`minicom`を実行し、「CTRL+A; S」を使用してファイル転送を開始する
+   * xmodemを選択し、新しい署名付きファームウェアファイル`test-app/image_v2_signed.bin`に移動する
+ - 転送中、黄色のLEDが点滅する。
+ - 緑色のLEDはUART RXと同期しているため薄暗い
+ - 転送の終わりに、新しいイメージが更新パーティションに配置される。
+ - ボードをリセットして新しいファームウェアをインストールし、新しいバージョン番号を確認する。
+
+更新出力の例：
+
+```sh
+cmd> update
+Erasing update partition...Done.
+Waiting for XMODEM transfer...
+.................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
+
+
+
+
+End of transfer. ret: 0
+New firmware version: 0x2
+Triggering update...
+Update completed successfully.
+
+cmd> reboot
+
+========================
+STM32H5 wolfBoot demo Application
+Copyright 2024 wolfSSL Inc
+GPL v3
+Version : 0x2
+========================
+
+cmd>
+```