IAMMETER 電力量計のローカル管理者セキュリティ：ユーザーガイド

ローカル管理者セキュリティ：ユーザーガイド

ローカル管理者セキュリティモジュールは、ファームウェア i.91.065.3 以降で利用できます。

目的

ローカル管理者セキュリティモジュールは、デバイスのローカル Web UI と機密性の高いローカル API を不正アクセスから保護します。

この機能を有効にすると、以下の操作に管理者のユーザー名とパスワードが必要になります。

WEM API テストページで利用できるすべての Set API
機密性の高い設定データを返す、または機密性の高い操作を実行する GET API
ローカル OTA ファームウェアのアップロードおよびアップグレード操作

これには、ネットワーク設定やアップロード設定の変更、ファームウェアの更新、デバイスの再起動、工場出荷時設定への復元、その他の機密性の高い設定パラメータの変更などの操作が含まれます。

このモジュールが提供する機能：

設定可能な管理者資格情報
保護されたローカル API のための HTTP ベーシック認証
Web UI または API による資格情報の変更
管理者パスワードを忘れた場合の Ed25519 署名ベースのリカバリプロセス

この機能は、以前のファームウェアとの互換性を保つため、デフォルトでは無効になっています。保護されたアクセスを有効にするには、事前にこの機能を有効化して設定する必要があります。

現在のローカル Web UI は HTTP を使用しています。HTTP ベーシック認証は資格情報をエンコードしますが、暗号化はしません。追加の安全な転送メカニズムを介してデバイスにアクセスしない限り、信頼できるローカルネットワーク上でこの機能を使用してください。

Web UI で管理者セキュリティを設定する

ブラウザでデバイスの IP アドレスを開きます。
Security タブを選択します。
管理者のユーザー名を入力します。
管理者のパスワードを入力して確認します。
Enable Admin Security を選択します。

ユーザー名とパスワードは、次のルールを満たす必要があります。

長さ：1〜32 文字
表示可能な ASCII 文字のみ
コロン（:）、二重引用符（"）、またはバックスラッシュ（\）は使用できません

管理者セキュリティが有効になると、保護されたページまたは API にアクセスした際に、ブラウザに認証プロンプトが表示されます。設定した管理者のユーザー名とパスワードを入力してください。

Security タブでは、以下の操作も行えます。

管理者のユーザー名とパスワードの変更
管理者認証が有効になっていることの確認
ポート 502 の Modbus/TCP サービスの有効化または無効化
SSDP ディスカバリの有効化または無効化
現在の資格情報で認証した後の管理者セキュリティの無効化

管理者資格情報のコントロールと Modbus TCP および SSDP サービスのスイッチを表示した IAMMETER ローカル Web UI の Security タブ

Modbus/TCP または SSDP サービスの状態の変更には、デバイスの再起動が必要です。これらの設定が以前のファームウェアで保存されたことがない場合は、後方互換性のために両方のサービスがデフォルトで有効になります。

ブラウザは、デバイスアドレスのベーシック認証資格情報をキャッシュする場合があります。パスワードを変更した後、ブラウザは最初に古い資格情報を再試行し、その後新しい認証プロンプトを表示することがあります。すべてのブラウザウィンドウを閉じるか、プライベートブラウジングウィンドウを使用すると、新しいログインを強制することもできます。

ベーシック認証を必要としない API

以下のエンドポイントは、Web UI が基本的なデバイス情報を読み込めるようにし、署名付きリカバリプロセスが動作できるようにするため、ベーシック認証ヘッダーなしで引き続き利用できます。

メソッド	エンドポイント	目的
GET	`/api/admin/status`	管理者セキュリティが有効かどうか、および署名付きリカバリがサポートされているかどうかを返します。
GET	`/api/admin/recovery_challenge`	デバイス固有の一回限りのリカバリペイロードを生成します。
GET	`/api/getbrand`	ローカル Web UI のブランディング設定を返します。
GET	`/api/monitor`	ローカル Web UI が使用する現在のデバイスおよび電力量計のモニタリングデータを返します。
GET	`/api/monitorjson`	`/api` 互換パスを介してレガシーのモニタリング応答を返します。
GET	`/monitorjson`	レガシーのモニタリング応答を返します。
GET	`/api/sntpstatus`	現在の SNTP ステータスを返します。
GET	`/info.xml`	UPnP スタイルのデバイス情報を返します。
POST	`/api/admin/recovery`	IAMMETER のリカバリ署名を検証し、忘れられた管理者資格情報をクリアします。

管理者セキュリティが現在無効になっている場合、POST /api/admin/enable もベーシック認証なしで呼び出すことができます。これは、初期セットアップに使用されるエンドポイントだからです。管理者セキュリティがすでに有効な場合は、このエンドポイントがセキュリティ設定を変更または無効化できるようにする前に、現在有効な管理者資格情報が必要です。

静的 Web UI ファイルやその他の非 /api/ GET リソースは API エンドポイントではないため、公開されたまま読み取り可能です。その他のすべてのローカル API エンドポイントは、管理者セキュリティが有効な場合、保護対象として扱われます。これには、すべての Set API、機密性の高い GET API、OTA ファームウェア操作が含まれます。

API リファレンス

GET `/api/admin/status`

現在の管理者セキュリティステータスを返します。認証は不要です。

応答例：

{
  "enabled": 1,
  "hasPassword": 1,
  "recoverySupported": 1,
  "modbusTcpEnabled": 1,
  "ssdpEnabled": 1
}

フィールド：

enabled：管理者セキュリティが有効な場合は 1、それ以外は 0。
hasPassword：管理者資格情報が設定されている場合は 1。
recoverySupported：ファームウェアが署名付き管理者リカバリをサポートしている場合は 1。
modbusTcpEnabled：ポート 502 の Modbus/TCP サービスが有効な場合は 1。
ssdpEnabled：SSDP ディスカバリが有効な場合は 1。

POST `/api/admin/enable`

管理者セキュリティを有効または無効にします。

管理者セキュリティを有効にする：

POST /api/admin/enable
Content-Type: application/json

{
  "enable": 1,
  "username": "admin",
  "password": "ExamplePassword"
}

curl を使用した例：

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

管理者セキュリティを無効にする：

POST /api/admin/enable
Authorization: Basic <base6...ype: application/json

{
  "enable": 0
}

管理者セキュリティがすでに有効な場合、この API を呼び出すには現在有効なベーシック認証資格情報が必要です。

例：

curl -X POST "http://<device-ip>/api/admin/enable" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"enable":0}'

POST `/api/admin/password`

管理者のユーザー名とパスワードを変更します。この API は、管理者セキュリティが有効になった後は保護されます。

POST /api/admin/password
Authorization: Basic <curre...ype: application/json

{
  "username": "newadmin",
  "password": "NewExamplePassword"
}

例：

curl -X POST "http://<device-ip>/api/admin/password" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"username":"newadmin","password":"NewExamplePassword"}'

リクエストが成功した後は、以降の保護されたリクエストに新しい資格情報を使用してください。

GET `/api/admin/check`

指定されたベーシック認証資格情報が有効かどうかを確認します。

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/admin/check"

成功時の応答：

{
  "successful": 1
}

資格情報がない場合や無効な場合は、HTTP 401 Unauthorized が返されます。

GET `/api/admin/recovery_challenge`

デバイス固有の一回限りのリカバリペイロードを作成します。このエンドポイント自体は資格情報をリセットしないため、認証は不要です。

応答例：

{
  "successful": 1,
  "alg": "ed25519",
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE"
}

返された payload は、管理者リカバリが必要な場合に IAMMETER に送信する必要があります。

新しいチャレンジを要求すると、以前のチャレンジは無効になります。チャレンジは、リカバリが成功した後またはデバイスが再起動された後にも無効になります。

POST `/api/admin/recovery`

リカバリペイロードと、IAMMETER から提供された Ed25519 署名を送信します。

POST /api/admin/recovery
Content-Type: application/json

{
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE",
  "signature": "128-hex-character-ed25519-signature"
}

例：

curl -X POST "http://<device-ip>/api/admin/recovery" \
  -H "Content-Type: application/json" \
  -d '{"payload":"reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE","signature":"<signature-from-IAMMETER>"}'

署名の検証に成功すると、デバイスはローカルの管理者資格情報をクリアし、管理者セキュリティを無効にします。その後、新しい管理者のユーザー名とパスワードを設定できます。

署名の検証を実行するのに十分な空きメモリがデバイスにない場合、API は次のような応答を返します。

{
  "successful": 0,
  "message": "low memory, please change to standalone mode",
  "freeMemory": 18000,
  "minFreeRequired": 28000
}

この場合は、メモリ使用量を減らしてから、再試行する前に新しいリカバリチャレンジを要求してください。パスワードが利用できず、動作モードを変更できない場合は、MQTTS または HTTPS 接続が追加のメモリを消費する前に、デバイスを再起動してリカバリを実行してください。

パスワードリカバリの仕組み

リカバリの設計では、管理者保護を回避できる可能性のある、認証なしの工場出荷時リセットコマンドを追加しないようにしています。

このプロセスでは、Ed25519 公開鍵/秘密鍵ペアを使用します。

デバイスのファームウェアには、IAMMETER のリカバリ公開鍵のみが含まれています
対応する秘密鍵は IAMMETER が保持しており、デバイスには保存されません
デバイスは、要求された操作、デバイスの SN、デバイスの MAC、および一回限りのナンスを含むペイロードを作成します
IAMMETER は、その正確なペイロードにリカバリ秘密鍵で署名します
デバイスは、埋め込まれた公開鍵で署名を検証します
現在のデバイスと現在のナンスに対する有効な署名のみが、管理者設定をクリアできます

ナンスは RAM にのみ保存されます。ナンスは、デバイスが再起動したとき、別のチャレンジが要求されたとき、またはリカバリが 1 回成功した後に無効になります。したがって、古いペイロードと署名を後日のリカバリセッションで再利用することはできません。

使用シナリオ

シナリオ 1：管理者のユーザー名とパスワードを設定する

最も簡単な方法は Web UI です。

http://<device-ip>/ を開きます。
Security タブを開きます。
新しい管理者のユーザー名とパスワードを入力します。
パスワードを確認します。
管理者セキュリティを有効にします。

同じ操作は POST /api/admin/enable でも実行できます。

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

結果を確認する：

curl "http://<device-ip>/api/admin/status"

シナリオ 2：ベーシック認証で保護された API にアクセスする

以降の保護されたリクエストごとに、HTTP ベーシック認証ヘッダーで管理者のユーザー名とパスワードを送信します。

ヘッダー値は次のように構成されます。

Authorization: Basic Base64...nFor example, the credentials `admin:ExamplePassword` are combined first and then Base64 encoded. Most HTTP clients perform this automatically.

curl を使用する場合：

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/getadv"

明示的なヘッダーを使用する場合：

TOKEN=$(printf '%s' 'admin:ExamplePassword' | base64)

curl "http://<device-ip>/api/getadv" \
  -H "Authorization: Basic ***"

JSON POST リクエストの場合：

curl -X POST "http://<device-ip>/api/setadv" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '<setadv-json-body>'

管理者がベーシック認証プロンプトに資格情報を入力すると、ブラウザはこのヘッダーを自動的に処理します。

現在の Web UI は、ファームウェアを POST /api/ota_successful.html にアップロードします。レガシーの POST /ota_successful.html エンドポイントは、古い Web UI バージョンおよび外部ツール向けに引き続き利用できます。管理者セキュリティが有効な場合、両方のエンドポイントでベーシック認証が必要です。

認証プロンプトが閉じられた場合の Web UI タブの動作は次のとおりです。

Settings と Wi-Fi は、保護された設定 API を読み込むことができず、管理者認証メッセージを表示します。
System は、SN、MAC、ファームウェアバージョンを引き続き表示できます。これらの値は公開エンドポイント /api/monitor から取得されるためです。OTA アップロードは引き続き保護されています。
Security は、/api/admin/status が公開されているため、基本的なステータスを引き続き表示できます。資格情報の変更とサービスのスイッチ変更は引き続き保護されています。

シナリオ 3：パスワードを忘れた後のアクセスを回復する

デバイスにはハードウェアのリセットボタンがありません。管理者セキュリティを回避できる可能性のある認証なしのリセット機能を追加しないために、デバイスは上記の署名付きリカバリメカニズムを使用します。

この手順は、管理者のユーザー名とパスワードの両方を忘れてしまった場合のみを対象としています。設定した資格情報は安全な場所に保管し、日常的な資格情報の変更でリカバリプロセスに頼らないようにしてください。現在の資格情報がまだ利用できる場合は、Security タブまたは POST /api/admin/password から直接変更してください。

デバイスから新しいリカバリチャレンジを要求します。
```
curl "http://<device-ip>/api/admin/recovery_challenge"
```
応答から完全な payload 値をコピーします。SN、MAC、ナンス、区切り文字、英字の大文字小文字は編集しないでください。
IAMMETER サポート（support@devicebit.com）に連絡し、完全なペイロードを提出してください。
所有者またはサービスの承認が確認された後、IAMMETER がペイロードに署名し、Ed25519 署名を返します。

元のペイロードと返された署名をデバイスに送信します。

curl -X POST "http://<device-ip>/api/admin/recovery" \
  -H "Content-Type: application/json" \
  -d '{"payload":"<original-payload>","signature":"<signature-from-IAMMETER>"}'

成功した応答の後、管理者セキュリティは無効になり、以前の管理者資格情報はクリアされます。Security タブを開くか、POST /api/admin/enable を呼び出して、新しい資格情報を設定してください。

署名を待っている間は、デバイスを再起動したり、別のチャレンジを要求したりしないでください。いずれの操作も送信済みのペイロードを無効にするため、リカバリプロセスを新しいチャレンジで最初からやり直す必要があります。

IAMMETER 電力量計のローカル管理者セキュリティ：ユーザーガイド

ローカル管理者セキュリティ：ユーザーガイド

目的

Web UI で管理者セキュリティを設定する

ベーシック認証を必要としない API

API リファレンス

GET /api/admin/status

POST /api/admin/enable

POST /api/admin/password

GET /api/admin/check

GET /api/admin/recovery_challenge

POST /api/admin/recovery