Sådan konfigurerer du MQTTS- og HTTPS-certifikatverificering på en IAMMETER-energimåler

IAMMETER-energimålere med firmware i.91.065.9 og nyere kan verificere servercertifikatet, når de uploader data via MQTTS eller HTTPS. Det tilføjer kontrol af certifikatkæde og serverværtsnavn til sikre udgående forbindelser.

Artiklen fokuserer på TLS-tillidskonfiguration. Den konfigurerer ikke MQTT-emner, JSON-payloads eller Home Assistant-discovery. Se MQTT-energimåler: Publicér IAMMETER-data til din MQTT-broker for MQTT-arbejdsgangen.

På denne side

Vælg en certifikatverificeringstilstand
Krav og vigtige afgrænsninger
Kontrollér den aktuelle TLS-tilstand
Vælg builtin-verificering
Vælg none til midlertidig diagnose
Upload og vælg en brugerdefineret CA
Slet den brugerdefinerede CA
Brug IAMMETER Swagger UI
Fejlfinding af certifikatverificering

Vælg en certifikatverificeringstilstand

IAMMETERs MQTTS- og HTTPS-klienter understøtter tre tilstande til verificering af servercertifikater:

Tilstand	Certifikatkæde	Serverværtsnavn	Anvendelse
`builtin`	Verificeres med rod-CA'er i firmwaren	Verificeres	Anbefalet til offentlige tjenester med understøttet kæde
`custom`	Verificeres med brugerens PEM-rod-CA	Verificeres	Privat PKI, selvsignerede installationer eller manglende offentlige rødder
`none`	Verificeres ikke	Verificeres ikke	Kun midlertidig kompatibilitet eller diagnose

Indstillingerne gælder, når IAMMETER-enheden fungerer som TLS-klient og uploader data til en MQTTS-broker eller HTTPS-server. De aktiverer ikke HTTPS på enhedens lokale webserver.

`builtin`

builtin er standardtilstanden. Den bruges, når ingen TLS-verificeringsindstilling tidligere er gemt, og gendannes, når TLS CA-konfigurationen slettes, eller enheden fabriksnulstilles.

Firmwaren indeholder disse rod-CA'er:

DigiCert Global Root G2
ISRG Root X1

Enheden verificerer både certifikatkæden og serverværtsnavnet. MQTTS-brokeren eller HTTPS-serveren skal præsentere et certifikat med en kæde til en af disse rødder, og dets Subject Alternative Name (SAN) skal matche den konfigurerede serveradresse.

Hvis uploadadressen er en IP-adresse, skal certifikatet indeholde præcis denne IP i SAN. Et DNS-navn matcher ikke en IP-adresse, selv om begge peger på samme server.

`custom`

custom udfører samme kæde- og værtsnavnekontrol som builtin, men stoler på PEM-CA-certifikatet uploadet af administratoren. Brug det, når:

servercertifikatet er udstedt af en privat CA;
installationen bruger et selvsigneret servercertifikat; eller
den nødvendige offentlige rod-CA ikke findes i firmwaren.

Ved privat PKI uploades rod-CA-certifikatet. TLS-serveren skal stadig sende nødvendige mellemliggende certifikater under håndtrykket. Et selvsigneret servercertifikat kan uploades som tillidsanker, men SAN skal stadig matche det konfigurerede værtsnavn eller den konfigurerede IP.

`none`

none opretter stadig en krypteret TLS-forbindelse, men verificerer ikke certifikatkæde eller værtsnavn. Det svarer til ældre TLS-adfærd uden serverautentificering.

Tilstanden er sårbar over for man-in-the-middle-angreb. Brug den kun midlertidigt til kompatibilitet eller diagnose. Foretræk builtin eller custom i produktion.

Krav og vigtige afgrænsninger

TLS CA-konfigurations-API'erne kræver aktiveret Local Admin Security. Hver anmodning skal indeholde det konfigurerede administratorbrugernavn og adgangskoden via HTTP Basic Authentication.

Computeren med curl eller Swagger UI skal kunne nå enhedens lokale IP. MQTTS- og HTTPS-klienterne deler én verificeringstilstand og én brugerdefineret CA, så ændringen gælder den sikre uploadtilstand, enheden bruger.

Genstart enheden efter ændring af TLS-konfigurationen, så den udgående klient genskabes med de nye indstillinger.

Eksemplerne bruger disse pladsholdere:

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

Erstat dem med den faktiske enhedsadresse og administratoroplysningerne.

Kontrollér den aktuelle TLS-tilstand

API:

GET /api/tls/ca/status

Eksempel:

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

Eksempelsvar:

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

Svaret viser den valgte tilstand og, hvis den findes, længden og SHA-256-hashen for den gemte brugerdefinerede CA.

Vælg `builtin`-verificering

API:

POST /api/tls/ca/select

Eksempel:

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

Genstart enheden efter et vellykket svar.

Vælg `none` til midlertidig diagnose

API:

POST /api/tls/ca/select

Eksempel:

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

Svaret advarer om, at servercertifikatverificering er deaktiveret. Genstart efter tilstandsskiftet, og skift tilbage til builtin eller custom efter diagnosen.

Upload og vælg en brugerdefineret CA

Upload af en CA og valg af custom er separate handlinger. Upload ændrer ikke automatisk den aktive tilstand.

Krav til den brugerdefinerede CA-fil

Den uploadede fil skal opfylde alle disse krav:

PEM-certifikatformat;
rå anmodningskrop, ikke JSON og ikke multipart/form-data;
Content-Type: application/x-pem-file;
1 til 3072 byte inklusive PEM-overskrifter, linjeskift og blanktegn;
indeholder -----BEGIN CERTIFICATE----- og -----END CERTIFICATE-----;
indeholder ikke en privat nøgle.

Grænsen på 3072 byte gælder hele HTTP-anmodningskroppen. En PEM-fil på 3072 byte accepteres; en fil på 3073 byte afvises.

Kontrollér filstørrelsen før upload:

wc -c root-ca.pem

Trin 1: Upload CA'en

API:

POST /api/tls/ca/upload

Eksempel:

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

Eksempel på et vellykket svar:

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

Enheden gemmer CA'en i flere KV-blokke og verificerer gemt længde og SHA-256-hash, før den markeres aktiv. En afbrudt skrivning erstatter ikke den tidligere gyldige CA.

Trin 2: Vælg `custom`

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

Enheden afviser anmodningen, hvis ingen gyldig brugerdefineret CA er gemt. Den falder ikke stiltiende tilbage til none.

Trin 3: Genstart og verificér

Genstart fra enhedens lokale webgrænseflade, eller brug det beskyttede genstarts-API:

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

Når enheden er tilsluttet igen, forespørges status på ny:

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

Bekræft, at mode er custom, customCaValid er 1, og at rapporteret længde og SHA-256-hash matcher det uploadede certifikat.

Slet den brugerdefinerede CA

API:

POST /api/tls/ca/delete

Eksempel:

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

Sletning af den brugerdefinerede CA gendanner også builtin. Genstart enheden efter sletning.

Brug IAMMETER Swagger UI

De samme API'er kan testes uden manuelt at skrive curl-kommandoer:

IAMMETER WEM API Test - TLS CA

Åbn WEM API Test på en computer, der kan nå enhedens lokale IP.
Indtast enhedsadressen, eksempelvis 192.168.1.80, og vælg Apply.
Vælg Authorize, og indtast administratorbrugernavn og adgangskode.
Åbn gruppen TLS CA - Authenticated.
Brug GET /api/tls/ca/status til at undersøge konfigurationen.
Brug upload, valg eller sletning efter behov.
Genstart efter ændring af tilstand eller certifikat.

Swagger-siden kører i browseren og sender anmodninger direkte fra computeren til IAMMETER-enheden. De sendes ikke via IAMMETER Cloud som proxy, så browseren skal have direkte netværksadgang til enhedens IP.

Fejlfinding af certifikatverificering

`admin security required`

Aktivér Local Admin Security før brug af TLS CA-API'erne. Indstillingerne kan ikke ændres anonymt.

`custom CA is missing or invalid`

Upload en gyldig PEM-CA, før du vælger custom. Forespørg /api/tls/ca/status, og bekræft, at customCaValid er 1.

TLS-forbindelsen fejler i `builtin` eller `custom`

Kontrollér alle følgende punkter:

konfigureret værtsnavn eller IP matcher certifikatets SAN;
certifikatet er gyldigt nu, og enhedens tid er korrekt;
serveren sender nødvendige mellemliggende certifikater;
den valgte rod-CA har udstedt eller via kæden stoler på servercertifikatet;
enheden blev genstartet efter TLS-ændringen.

TLS virker i `none`, men fejler i verificerede tilstande

Det peger normalt på et problem med certifikatkæde, værtsnavn, gyldighedsperiode eller enhedens ur. At beholde none skjuler autentificeringsfejlen, men løser den ikke. Ret certifikatopsætningen, eller upload den rette rod-CA og brug custom.

Sådan konfigurerer du MQTTS- og HTTPS-certifikatverificering på en IAMMETER-energimåler

Vælg en certifikatverificeringstilstand

builtin

custom

none

Krav og vigtige afgrænsninger

Kontrollér den aktuelle TLS-tilstand

Vælg builtin-verificering

Vælg none til midlertidig diagnose

Upload og vælg en brugerdefineret CA

Krav til den brugerdefinerede CA-fil

Trin 1: Upload CA'en

Trin 2: Vælg custom

Trin 3: Genstart og verificér

Slet den brugerdefinerede CA

Brug IAMMETER Swagger UI

Fejlfinding af certifikatverificering

admin security required

custom CA is missing or invalid

TLS-forbindelsen fejler i builtin eller custom

TLS virker i none, men fejler i verificerede tilstande

Wi-Fi energimåler

`builtin`

`custom`

`none`

Vælg `builtin`-verificering

Vælg `none` til midlertidig diagnose

Trin 2: Vælg `custom`

`admin security required`

`custom CA is missing or invalid`

TLS-forbindelsen fejler i `builtin` eller `custom`

TLS virker i `none`, men fejler i verificerede tilstande