MQTTS- und HTTPS-Zertifikatsprüfung auf einem IAMMETER-Energiezähler konfigurieren

IAMMETER-Energiezähler mit Firmware i.91.065.9 oder neuer können beim Hochladen über MQTTS oder HTTPS das Serverzertifikat überprüfen. Dadurch werden sichere ausgehende Verbindungen um die Prüfung der Zertifikatskette und des Serverhostnamens ergänzt.

Dieser Artikel behandelt die TLS-Vertrauenskonfiguration, nicht MQTT-Topics, JSON-Nutzdaten oder Home Assistant Discovery. Den MQTT-Ablauf finden Sie unter MQTT-Energiezähler: IAMMETER-Daten auf Ihrem MQTT-Broker veröffentlichen.

Auf dieser Seite

• Zertifikatsprüfmodus auswählen
• Voraussetzungen und wichtige Grenzen
• Aktuellen TLS-Modus prüfen
• Prüfung mit builtin auswählen
• none für vorübergehende Diagnose auswählen
• Custom CA hochladen und auswählen
• Custom CA löschen
• IAMMETER Swagger UI verwenden
• Fehler bei der Zertifikatsprüfung beheben

Zertifikatsprüfmodus auswählen

Die MQTTS- und HTTPS-Clients von IAMMETER unterstützen drei Modi zur Prüfung des Serverzertifikats:

Diese Einstellungen gelten, wenn das IAMMETER-Gerät als TLS-Client Daten an einen MQTTS-Broker oder HTTPS-Server sendet. Sie aktivieren kein HTTPS auf dem lokalen Webserver des Geräts.

builtin

builtin ist der Standardmodus. Er gilt, solange keine TLS-Prüfeinstellung gespeichert wurde, und wird nach dem Löschen der TLS-CA-Konfiguration oder dem Zurücksetzen auf Werkseinstellungen wiederhergestellt.

Die Firmware enthält diese Root-CAs:

• DigiCert Global Root G2
• ISRG Root X1

Das Gerät prüft Zertifikatskette und Serverhostname. Der MQTTS-Broker oder HTTPS-Server muss ein Zertifikat vorlegen, dessen Kette zu einer dieser Root-CAs führt. Sein Subject Alternative Name (SAN) muss zur konfigurierten Serveradresse passen.

Wird für den Upload eine IP-Adresse verwendet, muss das Zertifikat genau diese IP-Adresse im SAN enthalten. Ein DNS-Name stimmt nicht mit einer IP-Adresse überein, auch wenn beide denselben Server bezeichnen.

custom

custom prüft Kette und Hostnamen wie builtin, vertraut jedoch dem vom Administrator hochgeladenen PEM-CA-Zertifikat. Verwenden Sie diesen Modus, wenn:

• das Serverzertifikat von einer privaten CA ausgestellt wurde;
• ein selbst signiertes Serverzertifikat verwendet wird; oder
• die benötigte öffentliche Root-CA nicht in der Firmware enthalten ist.

Laden Sie bei einer privaten PKI deren Root-CA-Zertifikat hoch. Der TLS-Server muss beim Handshake weiterhin die erforderlichen Zwischenzertifikate senden. Ein selbst signiertes Serverzertifikat kann selbst als Vertrauensanker hochgeladen werden; sein SAN muss trotzdem zum konfigurierten Hostnamen oder zur IP-Adresse passen.

none

none baut weiterhin eine verschlüsselte TLS-Verbindung auf, prüft jedoch weder Zertifikatskette noch Hostnamen. Das ähnelt dem bisherigen TLS-Verhalten ohne Serverauthentifizierung.

Dieser Modus ist anfällig für Man-in-the-Middle-Angriffe. Nutzen Sie ihn nur vorübergehend für Kompatibilität oder Diagnose. Im Produktivbetrieb sind builtin oder custom vorzuziehen.

Voraussetzungen und wichtige Grenzen

Für die TLS-CA-Konfigurations-APIs muss Local Admin Security aktiviert sein. Jede Anfrage muss den konfigurierten Administrator-Benutzernamen und das Passwort per HTTP Basic Authentication enthalten.

Der Computer mit curl oder Swagger UI muss die lokale IP-Adresse des Geräts erreichen können. MQTTS und HTTPS teilen sich einen Prüfmodus und eine Custom CA. Eine Änderung gilt daher für den jeweils verwendeten sicheren Upload-Modus.

Starten Sie das Gerät nach einer Änderung der TLS-Konfiguration neu, damit der ausgehende Client mit den neuen Einstellungen erstellt wird.

Die Beispiele verwenden folgende Platzhalter:

DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"

Ersetzen Sie diese durch die tatsächliche Geräteadresse und die Administrator-Zugangsdaten.

Aktuellen TLS-Modus prüfen

API:

GET /api/tls/ca/status

Beispiel:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  "http://$DEVICE_IP/api/tls/ca/status"

Beispielantwort:

{
  "successful": 1,
  "mode": "builtin",
  "customCaValid": 0,
  "customCaLength": 0,
  "customCaSha256": "",
  "restartRequiredAfterChange": 1
}

Die Antwort zeigt den ausgewählten Modus sowie, falls vorhanden, Länge und SHA-256-Prüfsumme der gespeicherten Custom CA.

Prüfung mit builtin auswählen

API:

POST /api/tls/ca/select

Beispiel:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/select" \
  -H "Content-Type: application/json" \
  -d '{"mode":"builtin"}'

Starten Sie das Gerät nach einer erfolgreichen Antwort neu.

none für vorübergehende Diagnose auswählen

API:

POST /api/tls/ca/select

Beispiel:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/select" \
  -H "Content-Type: application/json" \
  -d '{"mode":"none"}'

Die Antwort warnt davor, dass die Serverzertifikatsprüfung deaktiviert ist. Starten Sie das Gerät nach dem Moduswechsel neu und wechseln Sie nach der Diagnose zurück zu builtin oder custom.

Custom CA hochladen und auswählen

Das Hochladen einer CA und die Auswahl von custom sind getrennte Vorgänge. Ein CA-Upload ändert den aktiven Modus nicht automatisch.

Anforderungen an die Custom-CA-Datei

Die hochgeladene Datei muss alle folgenden Anforderungen erfüllen:

• PEM-Zertifikatsformat;
• unverarbeiteter Request-Body, weder JSON noch multipart/form-data;
• Content-Type: application/x-pem-file;
• 1 bis 3072 Bytes einschließlich PEM-Kopfzeilen, Zeilenenden und Leerzeichen;
• enthält -----BEGIN CERTIFICATE----- und -----END CERTIFICATE-----;
• enthält keinen privaten Schlüssel.

Das Limit von 3072 Bytes gilt für den gesamten HTTP-Request-Body. Eine PEM-Datei mit 3072 Bytes wird akzeptiert, eine Datei mit 3073 Bytes abgelehnt.

Prüfen Sie die Dateigröße vor dem Hochladen:

wc -c root-ca.pem

Schritt 1: CA hochladen

API:

POST /api/tls/ca/upload

Beispiel:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/upload" \
  -H "Content-Type: application/x-pem-file" \
  --data-binary @root-ca.pem

Beispiel einer erfolgreichen Antwort:

{
  "successful": 1,
  "length": 1939,
  "sha256": "64-character SHA-256 digest",
  "message": "CA uploaded; select custom mode and restart"
}

Das Gerät speichert die CA in mehreren KV-Blöcken und prüft gespeicherte Länge und SHA-256-Prüfsumme, bevor es sie als aktiv markiert. Ein unterbrochener Schreibvorgang ersetzt die bisherige gültige CA nicht.

Schritt 2: custom auswählen

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/select" \
  -H "Content-Type: application/json" \
  -d '{"mode":"custom"}'

Ist keine gültige Custom CA gespeichert, lehnt das Gerät diese Anfrage ab. Es fällt nicht unbemerkt auf none zurück.

Schritt 3: Neustarten und prüfen

Starten Sie das Gerät über seine lokale Weboberfläche neu oder verwenden Sie die geschützte Neustart-API:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  "http://$DEVICE_IP/api/restart?reset=false"

Fragen Sie nach dem erneuten Verbindungsaufbau den Status nochmals ab:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  "http://$DEVICE_IP/api/tls/ca/status"

Prüfen Sie, ob mode auf custom und customCaValid auf 1 steht und ob Länge und SHA-256-Prüfsumme mit dem hochgeladenen Zertifikat übereinstimmen.

Custom CA löschen

API:

POST /api/tls/ca/delete

Beispiel:

curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
  -X POST "http://$DEVICE_IP/api/tls/ca/delete"

Beim Löschen der Custom CA wird auch der Modus auf builtin zurückgesetzt. Starten Sie das Gerät danach neu.

IAMMETER Swagger UI verwenden

Dieselben APIs lassen sich ohne manuell geschriebene curl-Befehle testen:

IAMMETER WEM API Test - TLS CA

1. Öffnen Sie WEM API Test auf einem Computer, der die lokale IP-Adresse des Geräts erreicht.
2. Geben Sie die Geräteadresse ein, zum Beispiel 192.168.1.80, und wählen Sie Apply.
3. Wählen Sie Authorize und geben Sie Administrator-Benutzernamen und Passwort ein.
4. Öffnen Sie die Gruppe TLS CA - Authenticated.
5. Prüfen Sie die aktuelle Konfiguration mit GET /api/tls/ca/status.
6. Verwenden Sie je nach Bedarf Hochladen, Auswählen oder Löschen.
7. Starten Sie das Gerät nach Änderungen am Modus oder Zertifikat neu.

Swagger läuft im Browser und sendet Anfragen von diesem Computer direkt an das IAMMETER-Gerät. Die Anfragen werden nicht über IAMMETER Cloud weitergeleitet. Der Browser benötigt deshalb direkten Netzwerkzugriff auf die Geräte-IP.

Fehler bei der Zertifikatsprüfung beheben

admin security required

Aktivieren Sie Local Admin Security vor der Nutzung der TLS-CA-APIs. Diese Einstellungen können nicht anonym geändert werden.

custom CA is missing or invalid

Laden Sie vor der Auswahl von custom erfolgreich eine gültige PEM-CA hoch. Fragen Sie /api/tls/ca/status ab und prüfen Sie, ob customCaValid den Wert 1 hat.

TLS-Verbindung schlägt mit builtin oder custom fehl

Prüfen Sie alle folgenden Punkte:

• Der konfigurierte Hostname oder die IP-Adresse passt zum Zertifikats-SAN.
• Das Zertifikat ist aktuell gültig und die Gerätezeit stimmt.
• Der Server sendet die erforderlichen Zwischenzertifikate.
• Die gewählte Root-CA hat das Serverzertifikat ausgestellt oder vertraut ihm über dessen Kette.
• Das Gerät wurde nach der TLS-Änderung neu gestartet.

TLS funktioniert mit none, aber nicht mit geprüften Modi

Das deutet normalerweise auf ein Problem mit Zertifikatskette, Hostnamen, Gültigkeitszeitraum oder Geräteuhr hin. none verbirgt den Authentifizierungsfehler, behebt ihn aber nicht. Korrigieren Sie die Zertifikatsinstallation oder laden Sie die passende Root-CA hoch und verwenden Sie custom.