OpenWeave ファクトリー プロビジョニング ツール

GitHub でソースを見る

OpenWeave 工場出荷時プロビジョニング ツールは、Weave 対応デバイスにデバイスごとの永続的な構成情報をプロビジョニングする便利な手段です。工場プロビジョニング ツールは、お客様への出荷前に個々のデバイスに一意の ID と認証情報スタンプを押す製造ライン プロセスの一部として使用することを目的としています。また、デベロッパーが開発プロセスで使用する製品前段階のハードウェアをカスタマイズするためにも使用できます。

動作原理

OpenWeave 工場出荷時プロビジョニング ツールの目的は、選択した構成情報をデバイスの永続構成ストアに挿入することです。この構成情報は、デバイス ファームウェアによって実行時に取得され、使用されます。永続的なデバイス構成は通常、デバイスの内部フラッシュ内に保存されますが、データの保存方法や形式の詳細はプラットフォームによって異なります。工場プロビジョニング ツール自体は最終的なストレージ形式とは独立しており、デバイスのファームウェアのコードを使用してデータを正しい方法で書き込みます。また、このツールのユーザー インターフェースは、構成するハードウェアの種類に大きく依存していません。つまり、異なるハードウェア プラットフォームに基づく製品ライン全体で、同様の製造プロセスを採用できます。

ファクトリー プロビジョニング ツールは、JTAG ポートや SWD ポートなどのデバッグ インターフェースまたは制御インターフェースを介してターゲット デバイスに接続されているホストマシンで実行するように設計されています。このツールは、特別なエンコード形式でプロビジョニング情報をデバイスの RAM に挿入することで機能します。その後、デバイスに再起動が指示され、デバイスのファームウェアに組み込まれているポイントコードがエンコードされたデータを見つけてその完全性を検証し、格納されている値をプラットフォームに適した形式で永続ストレージに書き込みます。

挿入されたプロビジョニング データを検出して処理するオンデバイス コードは OpenWeave デバイスレイヤに組み込まれており、サポートされているすべてのプラットフォームで有効にできます。有効にすると、デバイスの起動時に、デバイスの初期化プロセスの早い段階でコードが自動的に実行されます。このコードは、RAM のプラットフォーム固有の領域をスキャンすることで動作します。メモリが比較的少ないプラットフォーム(1 M 未満など)では、スキャンは使用可能なすべての RAM を対象とします。

RAM に配置すると、プロビジョニング データは識別しやすい接頭辞でエンコードされるため、スキャン プロセス中にすばやく見つけることができます。 暗号化ハッシュに基づく整合性チェック値は、処理前にデータの有効性を確認するために使用されます。

デフォルトでは、プロビジョニング ツールは、ターゲット デバイス プラットフォームに基づいて、プロビジョニング データを挿入する RAM ロケーションを選択します。この選択は、ツールへの引数を使用してオーバーライドできます。通常、デバイス ファームウェアがプロビジョニング データの受信専用の RAM ロケーションを予約する必要はありません。通常、プロビジョニング データは他の目的に割り当てられた RAM の場所に書き込まれますが、デバイスの起動プロセスの初期段階では使用されません。よく使われるのは、初期システム スタックの一番上、またはヒープ領域の最後です。

ファクトリ プロビジョニング ツールは、一連の外部開発ツールを使用してターゲット デバイスとインターフェースします。使用するツールは、ターゲット デバイスのタイプによって異なります。現在、次の 2 つのデバイス インターフェースがサポートされています。

  • デバイスの JTAG ポートまたは SWD ポートに接続された SEGGER J-Link デバッグ プローブ
  • Espressif ESP32 に接続された USB シリアル ポート

J-Link インターフェースは SEGGER J-Link Commander ツール(JLinkExe)に依存しています。このツールは、ホストマシンに別途インストールする必要があります。

ESP32 インターフェースは、Espressif の ESP-IDF SDK の一部として提供される Espressif esptool.py コマンドに依存しています。

プロビジョニングできる情報の種類

OpenWeave ファクトリー プロビジョニング ツールは、次の種類の情報をプロビジョニングできます。

  • デバイスのシリアル番号
  • メーカーが割り当てた Weave デバイス ID
  • メーカーが割り当てた Weave 証明書と秘密鍵
  • Weave ペア設定コード
  • プロダクトのリビジョン番号
  • 製造日

通常、デバイスが適切に動作するには上記のすべての情報が必要ですが、すべての情報を同時にプロビジョニングする必要はありません。したがって、さまざまな種類の情報のプロビジョニングが、製造プロセスの異なるポイントで行われる可能性があります。また、後続のプロビジョニング ステップで、以前にプロビジョニングされた値を新しい値に置き換えることもできます。

プロビジョニング情報の提供元

デバイスのプロビジョニング情報は、次の方法で工場出荷時プロビジョニング ツールに提供できます。

  • コマンドライン引数
  • プロビジョニング CSV ファイルを使用する
  • Google Nest プロビジョニング サーバーから値を取得する

コマンドライン

最も簡単な形式では、デバイスのプロビジョニング情報は、コマンドラインで OpenWeave Factory Provisioning Tool に直接指定されます。 例:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --pairing-code NESTUS --mfg-date 2019/04/01

Weave 証明書や秘密鍵などのバイナリデータ値は、Base64 文字列として指定することも、必要なデータを未加工(バイナリ)形式で格納するファイルの名前として指定することもできます。

使用可能なコマンドライン引数の一覧については、下記をご覧ください。

プロビジョニング CSV ファイル

デバイスの一括プロビジョニングに対応するために、Factory Provisioning Tool は CSV 形式のプロビジョニング データファイルからプロビジョニング データを読み取ることもできます。このファイルの列は、特定のプロビジョニング データ型(Serial_NumCertificatePrivate_Key など)に対応している必要があります。ファイル内の行には、Weave デバイス ID(Device_Id)でインデックス付けされた特定のデバイスの個別の値が指定されます。プロビジョニングする特定のデバイスの ID は、コマンドライン上で指定する必要があります。例:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --prov-csv-file ./dev-provisioning-data.csv

サポートされている CSV 列は次のとおりです。

名前 形式 説明
Device_Id 16 桁の 16 進数 Weave のデバイス ID。必須です。
Serial_Num 文字列 デバイスのシリアル番号
Certificate Base64 文字列 メーカーが割り当てた Weave デバイス証明書。
Private_Key Base64 文字列 メーカーが割り当てた Weave 秘密鍵。
Pairing_Code 文字列 Weave ペア設定コード。
Product_Rev integer 製品のリビジョン番号。
Mfg_Date YYYY/MM/DD デバイスの製造日。

CSV ファイル内の列の順序は任意です。Device_Id を除くすべての列は省略可能です。CSV ファイルに存在しない値は、単にデバイスにプロビジョニングされません。

ユーザーは、CSV ファイルに加えて、コマンドラインで個々のプロビジョニング値を指定できます。この場合、コマンドライン値がファイル内の値よりも優先されます。

Factory Provisioning Tool でサポートされている CSV ファイル形式は、weave ツールの gen-provisioning-data コマンドの出力と互換性があります。

Google Nest プロビジョニング サーバー

工場出荷時のプロビジョニング ツールは、HTTPS ベースのプロトコルを使用して、Nest プロビジョニング サーバーから特定のプロビジョニング情報を取得できます。プロビジョニング サーバー プロトコルを使用すると、メーカーが割り当てた Weave デバイス証明書、対応する秘密鍵、Weave ペア設定コードをプロビジョニング サーバーから取得できます。

プロビジョニング サーバーのネットワーク ロケーションは、プロビジョニング ツールのコマンドラインでベース URL を指定して指定します。コマンドラインで Weave デバイス ID を指定することで、目的のプロビジョニング情報を選択します。例:

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000001 \
    --prov-server https://192.168.172.2:8000/

プロビジョニング サーバーの URL に加えて、コマンドラインで個々のプロビジョニング値を指定できます。この場合、コマンドラインで指定した値が、サーバーから返された値よりも優先されます。

出荷時プロビジョニングのサポートを有効または無効にする

デバイス ファームウェアでの OpenWeave 出荷時のプロビジョニングのサポートは、WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING コンパイル時構成オプションによって制御されます。このオプションはデフォルトで有効になっています。この機能を無効にするには、アプリの WeaveProjectConfig.h ファイル内のオプションをオーバーライドします。例:

#define WEAVE_DEVICE_CONFIG_ENABLE_FACTORY_PROVISIONING 0

通常、本番環境デバイスでデバイスのデバッグ インターフェースが適切に無効になっている場合、本番環境デバイスのファームウェアで工場出荷時のプロビジョニングを有効にすることは安全です。これは、ハードウェア手段(SOC のヒューズを飛ばすなど)またはソフトウェア(ブートプロセスの一部としてデバッグ アクセスをブロックするセキュア ブートローダなど)で実現できます。

Factory Provisioning ツールの実行

OpenWeave ファクトリー プロビジョニング ツールは、次のコマンドライン オプションをサポートしています。

オプション 説明
--target <文字列> ターゲット デバイスのタイプ。選択肢: nrf52840esp32
--load-addr <16 進数> プロビジョニング データが書き込まれるデバイスメモリ内のアドレス。
--verbose、-v 出力の詳細度レベルを調整します。複数の引数を使用して詳細情報を表示します。
--serial-num <string> デバイスのシリアル番号を設定します。
--device-id <hex-digits> メーカーによって割り当てられたデバイス ID を設定します。
--device-cert <base-64> | <file-name> メーカーが割り当てた Weave デバイス証明書を設定します。
--device-key <base-64> | <ファイル名> メーカーが割り当てた Weave デバイスの秘密鍵を設定します。
--pairing-code <string> デバイスのペア設定コードを設定します。
--product-rev <integer> デバイスの製品リビジョンを設定します。
--mfg-date <YYYY/MM/DD> | today | now デバイスの製造日を設定します。
--jlink-cmd <パス名> JLink コマンドのパス。デフォルトは「JLinkExe」です。
--jlink-if SWD | JTAG J-Link インターフェース タイプ。デフォルトは SWD です。
--jlink-speed <integer> | adaptive | auto J-Link インターフェースの速度。
--jlink-sn <string> J-Link プローブのシリアル番号。
--esptool-cmd <path-name> esptool コマンドのパス。デフォルトは「esptool.py」です。
--port <path-name> ESP32 の COM ポート デバイス名。デフォルトは /tty/USB0 です。
--speed <integer> COM ポートのボーレート。デフォルトは 115200 です。
--prov-csv-file <ファイル名> プロビジョニング CSV ファイルからデバイスのプロビジョニング データを読み取る。
--prov-server <url> プロビジョニング サーバーからデバイスのプロビジョニング データを読み取る。
--disable-server-validation HTTPS を使用する場合は、プロビジョニング サーバーから提示された証明書の検証を無効にします。

次のコマンドは、デバイス ID、シリアル番号、プロダクト リビジョン、ペア設定コードを特定の値に設定します。製造日は現在の日付に設定されます。デバイス証明書と秘密鍵は、openweave-core ソース リポジトリに付属の CSV ファイルで指定されたテスト値に設定されています。

./weave-factory-prov-tool --target nrf52840 --device-id 18B4300000000042 \
    --serial-num JAYS_DEVICE_42 --product-rev 1 --pairing-code NESTUS --mfg-date today \
    --prov-csv-file ~/projects/openweave-core/certs/development/device/test-dev-provisioning-data.csv