Lokale Administrator-Sicherheit: Benutzerhandbuch

Lokale Administrator-Sicherheit: Benutzerhandbuch

Das Modul für lokale Administrator-Sicherheit ist in der Firmware i.91.065.3 und höher verfügbar.

Zweck

Das Modul für lokale Administrator-Sicherheit schützt das lokale Web-UI des Geräts sowie sensible lokale APIs vor unbefugtem Zugriff.

Nach Aktivierung der Funktion sind ein Administrator-Benutzername und ein Kennwort erforderlich für:

• alle Set-APIs, die auf der WEM-API-Testseite verfügbar sind;
• GET-APIs, die sensible Konfigurationsdaten zurückgeben oder sensible Operationen ausführen;
• lokale OTA-Firmware-Upload- und Upgrade-Operationen.

Dies umfasst Vorgänge wie das Ändern von Netzwerk- oder Upload-Einstellungen, das Aktualisieren der Firmware, das Neustarten des Geräts, das Zurücksetzen auf Werkseinstellungen und das Ändern anderer sensibler Konfigurationsparameter.

Das Modul bietet:

• konfigurierbare Administrator-Anmeldeinformationen;
• HTTP-Basic-Authentifizierung für geschützte lokale APIs;
• Änderungen der Anmeldeinformationen über das Web-UI oder die API;
• einen Ed25519-signaturbasierten Wiederherstellungsprozess, falls das Administrator-Kennwort vergessen wurde.

Die Funktion ist standardmäßig deaktiviert, um die Kompatibilität mit älteren Firmware-Versionen zu gewährleisten. Sie muss aktiviert und konfiguriert werden, bevor der geschützte Zugriff wirksam wird.

Das aktuelle lokale Web-UI verwendet HTTP. Die HTTP-Basic-Authentifizierung kodiert die Anmeldeinformationen, verschlüsselt sie jedoch nicht. Verwenden Sie diese Funktion nur in einem vertrauenswürdigen lokalen Netzwerk, es sei denn, das Gerät wird über einen zusätzlichen sicheren Transportmechanismus erreicht.

Administrator-Sicherheit im Web-UI konfigurieren

1. Öffnen Sie die IP-Adresse des Geräts in einem Browser.
2. Wählen Sie den Tab Security.
3. Geben Sie einen Administrator-Benutzernamen ein.
4. Geben Sie das Administrator-Kennwort ein und bestätigen Sie es.
5. Wählen Sie Enable Admin Security.

Der Benutzername und das Kennwort müssen die folgenden Regeln einhalten:

• Länge: 1 bis 32 Zeichen;
• nur sichtbare ASCII-Zeichen;
• ein Doppelpunkt (:), Anführungszeichen (") oder Backslash (\) ist nicht zulässig.

Nachdem die Administrator-Sicherheit aktiviert ist, zeigt der Browser eine Authentifizierungsaufforderung an, wenn eine geschützte Seite oder API aufgerufen wird. Geben Sie den konfigurierten Administrator-Benutzernamen und das Kennwort ein.

Der Tab Security kann auch verwendet werden, um:

• den Administrator-Benutzernamen und das Kennwort zu ändern;
• zu überprüfen, ob die Administrator-Authentifizierung aktiviert ist;
• den Modbus/TCP-Dienst auf Port 502 zu aktivieren oder zu deaktivieren;
• die SSDP-Erkennung zu aktivieren oder zu deaktivieren;
• die Administrator-Sicherheit nach Authentifizierung mit den aktuellen Anmeldeinformationen zu deaktivieren.

Änderungen am Modbus/TCP- oder SSDP-Dienststatus erfordern einen Neustart des Geräts. Falls diese Einstellungen noch nie von einer früheren Firmware gespeichert wurden, sind beide Dienste standardmäßig aus Gründen der Abwärtskompatibilität aktiviert.

Browser können Basic-Authentifizierungs-Anmeldeinformationen für die Geräteadresse zwischenspeichern. Nach dem Ändern des Kennworts versucht der Browser möglicherweise zuerst die alten Anmeldeinformationen und zeigt dann eine neue Authentifizierungsaufforderung an. Das Schließen aller Browserfenster oder die Verwendung eines privaten Browserfensters kann ebenfalls eine neue Anmeldung erzwingen.

APIs, die keine Basic-Authentifizierung erfordern

Die folgenden Endpunkte bleiben ohne Basic-Authentifizierungs-Header verfügbar, damit das Web-UI grundlegende Geräteinformationen laden kann und der signierte Wiederherstellungsprozess funktionieren kann:

POST /api/admin/enable ist auch ohne Basic-Authentifizierung aufrufbar, wenn die Administrator-Sicherheit derzeit deaktiviert ist, da dies der Endpunkt ist, der für die Ersteinrichtung verwendet wird. Wenn die Administrator-Sicherheit bereits aktiviert ist, sind die aktuell gültigen Administrator-Anmeldeinformationen erforderlich, bevor dieser Endpunkt die Sicherheitskonfiguration ändern oder deaktivieren kann.

Statische Web-UI-Dateien und andere Nicht-/api/ GET-Ressourcen sind keine API-Endpunkte und bleiben öffentlich lesbar. Alle anderen lokalen API-Endpunkte gelten bei aktivierter Administrator-Sicherheit als geschützt, einschließlich aller Set-APIs, sensibler GET-APIs und OTA-Firmware-Operationen.

API-Referenz

GET /api/admin/status

Gibt den aktuellen Administrator-Sicherheitsstatus zurück. Eine Authentifizierung ist nicht erforderlich.

Beispielantwort:

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

Felder:

• enabled: 1, wenn die Administrator-Sicherheit aktiviert ist; andernfalls 0.
• hasPassword: 1, wenn Administrator-Anmeldeinformationen konfiguriert wurden.
• recoverySupported: 1, wenn die signierte Administrator-Wiederherstellung von der Firmware unterstützt wird.
• modbusTcpEnabled: 1, wenn der Modbus/TCP-Dienst auf Port 502 aktiviert ist.
• ssdpEnabled: 1, wenn die SSDP-Erkennung aktiviert ist.

POST /api/admin/enable

Aktiviert oder deaktiviert die Administrator-Sicherheit.

Administrator-Sicherheit aktivieren:

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

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

Beispiel mit curl:

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

Administrator-Sicherheit deaktivieren:

POST /api/admin/enable
Authorization: Basic <base64...>
Content-Type: application/json

{
  "enable": 0
}

Wenn die Administrator-Sicherheit bereits aktiviert ist, sind die aktuell gültigen Basic-Authentifizierungs-Anmeldeinformationen erforderlich, um diese API aufzurufen.

Beispiel:

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

POST /api/admin/password

Ändert den Administrator-Benutzernamen und das Kennwort. Diese API ist geschützt, nachdem die Administrator-Sicherheit aktiviert wurde.

POST /api/admin/password
Authorization: Basic <aktuelle...>
Content-Type: application/json

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

Beispiel:

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

Nach erfolgreicher Anfrage verwenden Sie die neuen Anmeldeinformationen für nachfolgende geschützte Anfragen.

GET /api/admin/check

Überprüft, ob die übermittelten Basic-Authentifizierungs-Anmeldeinformationen gültig sind.

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

Erfolgreiche Antwort:

{
  "successful": 1
}

Fehlende oder ungültige Anmeldeinformationen führen zu HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Erstellt eine gerätespezifische, einmalige Wiederherstellungs-Nutzdaten. Eine Authentifizierung ist nicht erforderlich, da dieser Endpunkt allein keine Anmeldeinformationen zurücksetzt.

Beispielantwort:

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

Die zurückgegebenen payload-Daten müssen an IAMMETER gesendet werden, wenn eine Administrator-Wiederherstellung erforderlich ist.

Das Anfordern einer neuen Challenge macht die vorherige Challenge ungültig. Eine Challenge wird auch nach einer erfolgreichen Wiederherstellung oder einem Geräteneustart ungültig.

POST /api/admin/recovery

Übermittelt die Wiederherstellungs-Nutzdaten und die von IAMMETER bereitgestellte Ed25519-Signatur.

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

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

Beispiel:

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>"}'

Wenn die Signaturprüfung erfolgreich ist, löscht das Gerät die lokalen Administrator-Anmeldeinformationen und deaktiviert die Administrator-Sicherheit. Anschließend können ein neuer Administrator-Benutzername und ein neues Kennwort konfiguriert werden.

Wenn das Gerät nicht über genügend freien Arbeitsspeicher verfügt, um die Signaturprüfung durchzuführen, gibt die API eine ähnliche Antwort wie die folgende zurück:

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

Reduzieren Sie in diesem Fall die Speichernutzung und fordern Sie vor einem erneuten Versuch eine neue Wiederherstellungs-Challenge an. Wenn das Kennwort nicht verfügbar ist und der Betriebsmodus nicht geändert werden kann, starten Sie das Gerät neu und führen Sie die Wiederherstellung durch, bevor eine MQTTS- oder HTTPS-Verbindung zusätzlichen Speicher verbraucht.

Wie die Kennwort-Wiederherstellung funktioniert

Das Wiederherstellungsdesign vermeidet das Hinzufügen eines nicht authentifizierten Factory-Reset-Befehls, der den Administrator-Schutz umgehen könnte.

Der Prozess verwendet ein Ed25519-öffentliches/privates Schlüsselpaar:

• die Geräte-Firmware enthält nur den öffentlichen IAMMETER-Wiederherstellungsschlüssel;
• der entsprechende private Schlüssel wird von IAMMETER aufbewahrt und nicht auf dem Gerät gespeichert;
• das Gerät erstellt Nutzdaten, die die angeforderte Operation, die Geräte-SN, die Geräte-MAC und eine einmalige Nonce enthalten;
• IAMMETER signiert genau diese Nutzdaten mit dem privaten Wiederherstellungsschlüssel;
• das Gerät überprüft die Signatur mit seinem eingebetteten öffentlichen Schlüssel;
• nur eine gültige Signatur für das aktuelle Gerät und die aktuelle Nonce kann die Administrator-Konfiguration löschen.

Die Nonce wird nur im RAM gespeichert. Sie wird ungültig, wenn das Gerät neu gestartet wird, wenn eine andere Challenge angefordert wird oder nach einer erfolgreichen Wiederherstellung. Daher können alte Nutzdaten und Signaturen nicht für eine spätere Wiederherstellungssitzung wiederverwendet werden.

Anwendungsszenarien

Szenario 1: Einen Administrator-Benutzernamen und ein Kennwort festlegen

Die einfachste Methode ist das Web-UI:

1. Öffnen Sie http://<device-ip>/.
2. Öffnen Sie den Tab Security.
3. Geben Sie den neuen Administrator-Benutzernamen und das Kennwort ein.
4. Bestätigen Sie das Kennwort.
5. Aktivieren Sie die Administrator-Sicherheit.

Derselbe Vorgang kann über POST /api/admin/enable durchgeführt werden:

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

Überprüfen Sie das Ergebnis:

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

Szenario 2: Zugriff auf geschützte APIs mit Basic-Authentifizierung

Für jede nachfolgende geschützte Anfrage senden Sie den Administrator-Benutzernamen und das Kennwort im HTTP-Basic-Authentifizierungs-Header.

Der Header-Wert wird wie folgt konstruiert:

Authorization: Basic Base64(...)

Zum Beispiel werden die Anmeldeinformationen admin:ExamplePassword zuerst kombiniert und dann Base64-kodiert. Die meisten HTTP-Clients führen dies automatisch durch.

Mit curl:

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

Mit einem expliziten Header:

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

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

Für eine JSON-POST-Anfrage:

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

Der Browser verarbeitet diesen Header automatisch, nachdem der Administrator die Anmeldeinformationen in der Basic-Authentifizierungsaufforderung eingegeben hat.

Das aktuelle Web-UI lädt Firmware an POST /api/ota_successful.html hoch. Der Legacy-Endpunkt POST /ota_successful.html bleibt für ältere Web-UI-Versionen und externe Tools verfügbar. Beide Endpunkte erfordern eine Basic-Authentifizierung, wenn die Administrator-Sicherheit aktiviert ist.

Die Web-UI-Tabs verhalten sich wie folgt, wenn die Authentifizierungsaufforderung geschlossen wird:

• Settings und Wi-Fi können ihre geschützten Konfigurations-APIs nicht laden und zeigen eine Administrator-Authentifizierungsmeldung an.
• System kann weiterhin SN, MAC und Firmware-Version anzeigen, da diese Werte vom öffentlichen /api/monitor-Endpunkt bezogen wurden. Der OTA-Upload bleibt geschützt.
• Security kann weiterhin den Basisstatus anzeigen, da /api/admin/status öffentlich ist. Änderungen an Anmeldeinformationen und Dienstschaltern bleiben geschützt.

Szenario 3: Zugriff nach Vergessen des Kennworts wiederherstellen

Das Gerät verfügt über keinen Hardware-Reset-Knopf. Um das Hinzufügen einer nicht authentifizierten Reset-Funktion zu vermeiden, die die Administrator-Sicherheit umgehen könnte, verwendet das Gerät den oben beschriebenen signierten Wiederherstellungsmechanismus.

Dieses Verfahren ist nur für Fälle vorgesehen, in denen sowohl der Administrator-Benutzername als auch das Kennwort vergessen wurden. Bewahren Sie die konfigurierten Anmeldeinformationen an einem sicheren Ort auf und vermeiden Sie es, sich für routinemäßige Kennwortänderungen auf den Wiederherstellungsprozess zu verlassen. Wenn die aktuellen Anmeldeinformationen noch verfügbar sind, ändern Sie sie direkt über den Tab Security oder mit POST /api/admin/password.

1. Fordern Sie eine neue Wiederherstellungs-Challenge vom Gerät an:

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

2. Kopieren Sie den vollständigen payload-Wert aus der Antwort. Bearbeiten Sie nicht die SN, MAC, Nonce, Trennzeichen oder die Groß-/Kleinschreibung.

3. Kontaktieren Sie den IAMMETER-Support unter support@devicebit.com und übermitteln Sie die vollständigen Nutzdaten.

4. Nach Bestätigung des Eigentums oder der Service-Autorisierung signiert IAMMETER die Nutzdaten und gibt eine Ed25519-Signatur zurück.

5. Übermitteln Sie die ursprünglichen Nutzdaten und die zurückgegebene Signatur an das Gerät:

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

6. Nach einer erfolgreichen Antwort wird die Administrator-Sicherheit deaktiviert und die vorherigen Administrator-Anmeldeinformationen werden gelöscht. Öffnen Sie den Tab Security oder rufen Sie POST /api/admin/enable auf, um neue Anmeldeinformationen festzulegen.

Starten Sie das Gerät nicht neu und fordern Sie keine weitere Challenge an, während Sie auf die Signatur warten. Beide Aktionen machen die übermittelten Nutzdaten ungültig, und der Wiederherstellungsprozess muss mit einer neuen Challenge neu gestartet werden.