MQTTS- en HTTPS-certificaatverificatie configureren op een IAMMETER-energiemeter
IAMMETER-energiemeters met firmware i.91.065.9 of nieuwer kunnen het servercertificaat controleren bij het uploaden via MQTTS of HTTPS. Dit voegt controle van de certificaatketen en serverhostnaam toe aan beveiligde uitgaande verbindingen.
Dit artikel behandelt de TLS-vertrouwensconfiguratie, niet MQTT-topics, JSON-payloads of Home Assistant Discovery. Zie voor MQTT-publicatie MQTT-energiemeter: IAMMETER-gegevens publiceren naar uw MQTT-broker.
Op deze pagina
- Een certificaatverificatiemodus kiezen
- Vereisten en belangrijke grenzen
- De huidige TLS-modus controleren
- builtin-verificatie selecteren
- none selecteren voor tijdelijke diagnose
- Een Custom CA uploaden en selecteren
- De Custom CA verwijderen
- IAMMETER Swagger UI gebruiken
- Problemen met certificaatverificatie oplossen
Een certificaatverificatiemodus kiezen
De MQTTS- en HTTPS-clients van IAMMETER ondersteunen drie modi voor verificatie van het servercertificaat:
| Modus | Certificaatketen | Serverhostnaam | Beoogd gebruik |
|---|---|---|---|
builtin |
Gecontroleerd met root-CA’s in de firmware | Gecontroleerd | Aanbevolen voor openbare diensten met een ondersteunde keten |
custom |
Gecontroleerd met een aangeleverde PEM-root-CA | Gecontroleerd | Private PKI, zelfondertekende installaties of ontbrekende openbare roots |
none |
Niet gecontroleerd | Niet gecontroleerd | Alleen tijdelijke compatibiliteit of diagnose |
Deze instellingen gelden wanneer het IAMMETER-apparaat als TLS-client gegevens naar een MQTTS-broker of HTTPS-server uploadt. Ze schakelen HTTPS op de lokale webserver van het apparaat niet in.
builtin
builtin is de standaardmodus. Deze geldt zolang geen TLS-verificatie-instelling is opgeslagen en wordt hersteld na het verwijderen van de TLS-CA-configuratie of het terugzetten naar fabrieksinstellingen.
De firmware bevat deze root-CA’s:
- DigiCert Global Root G2
- ISRG Root X1
Het apparaat controleert zowel de certificaatketen als de serverhostnaam. De MQTTS-broker of HTTPS-server moet een certificaat aanbieden waarvan de keten naar een van deze roots leidt. De Subject Alternative Name (SAN) moet overeenkomen met het ingestelde serveradres.
Bij een IP-adres als uploadadres moet exact dat IP-adres in de SAN staan. Een DNS-naam komt niet overeen met een IP-adres, ook niet wanneer beide dezelfde server aanwijzen.
custom
custom voert dezelfde keten- en hostnaamcontrole uit als builtin, maar vertrouwt het door de beheerder geüploade PEM-CA-certificaat. Gebruik dit wanneer:
- het servercertificaat door een private CA is uitgegeven;
- de installatie een zelfondertekend servercertificaat gebruikt; of
- de benodigde openbare root-CA niet in de firmware zit.
Upload voor een private PKI het root-CA-certificaat. De TLS-server moet tijdens de handshake nog steeds de benodigde tussenliggende certificaten meesturen. Een zelfondertekend servercertificaat kan zelf als vertrouwensanker worden geüpload, maar de SAN moet blijven overeenkomen met de ingestelde hostnaam of het IP-adres.
none
none maakt nog steeds een versleutelde TLS-verbinding, maar controleert de certificaatketen en hostnaam niet. Dit lijkt op het eerdere TLS-gedrag zonder serverauthenticatie.
Deze modus is kwetsbaar voor man-in-the-middle-aanvallen. Gebruik hem alleen tijdelijk voor compatibiliteit of diagnose. Kies in productie bij voorkeur builtin of custom.
Vereisten en belangrijke grenzen
Voor de TLS-CA-configuratie-API’s moet Local Admin Security zijn ingeschakeld. Elk verzoek moet de ingestelde beheerdersnaam en het wachtwoord via HTTP Basic Authentication bevatten.
De computer met curl of Swagger UI moet het lokale IP-adres van het apparaat kunnen bereiken. MQTTS en HTTPS delen één verificatiemodus en één Custom CA. Een wijziging geldt dus voor de beveiligde uploadmodus die het apparaat gebruikt.
Herstart het apparaat na een TLS-wijziging, zodat de uitgaande client opnieuw met de nieuwe instellingen wordt aangemaakt.
De voorbeelden gebruiken deze plaatsaanduidingen:
DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"
Vervang ze door het echte apparaatadres en de beheerdersgegevens.
De huidige TLS-modus controleren
API:
GET /api/tls/ca/status
Voorbeeld:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Voorbeeldantwoord:
{
"successful": 1,
"mode": "builtin",
"customCaValid": 0,
"customCaLength": 0,
"customCaSha256": "",
"restartRequiredAfterChange": 1
}
Het antwoord vermeldt de geselecteerde modus en, indien aanwezig, de lengte en SHA-256-hash van de opgeslagen Custom CA.
builtin-verificatie selecteren
API:
POST /api/tls/ca/select
Voorbeeld:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"builtin"}'
Herstart het apparaat na een succesvol antwoord.
none selecteren voor tijdelijke diagnose
API:
POST /api/tls/ca/select
Voorbeeld:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"none"}'
Het antwoord waarschuwt dat servercertificaatverificatie is uitgeschakeld. Herstart na de moduswijziging en schakel na de diagnose terug naar builtin of custom.
Een Custom CA uploaden en selecteren
Een CA uploaden en custom selecteren zijn afzonderlijke handelingen. Uploaden wijzigt de actieve modus niet automatisch.
Vereisten voor het Custom-CA-bestand
Het geüploade bestand moet aan alle volgende eisen voldoen:
- PEM-certificaatformaat;
- onbewerkte verzoekinhoud, geen JSON en geen
multipart/form-data; Content-Type: application/x-pem-file;- 1 tot en met 3072 bytes, inclusief PEM-headers, regeleinden en witruimte;
- bevat
-----BEGIN CERTIFICATE-----en-----END CERTIFICATE-----; - bevat geen privésleutel.
De limiet van 3072 bytes geldt voor de volledige HTTP-verzoekinhoud. Een PEM-bestand van 3072 bytes wordt geaccepteerd; een bestand van 3073 bytes wordt geweigerd.
Controleer vóór het uploaden de bestandsgrootte:
wc -c root-ca.pem
Stap 1: de CA uploaden
API:
POST /api/tls/ca/upload
Voorbeeld:
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
Voorbeeld van een succesvol antwoord:
{
"successful": 1,
"length": 1939,
"sha256": "64-character SHA-256 digest",
"message": "CA uploaded; select custom mode and restart"
}
Het apparaat bewaart de CA in meerdere KV-blokken en controleert de opgeslagen lengte en SHA-256-hash voordat deze als actief wordt gemarkeerd. Een onderbroken schrijfactie vervangt de eerdere geldige CA niet.
Stap 2: custom selecteren
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"custom"}'
Het apparaat weigert dit verzoek als er geen geldige Custom CA is opgeslagen. Het valt niet ongemerkt terug op none.
Stap 3: herstarten en controleren
Herstart via de lokale webinterface of gebruik de beveiligde herstart-API:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/restart?reset=false"
Vraag na het opnieuw verbinden de status nogmaals op:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Controleer of mode op custom staat, customCaValid op 1 staat en lengte en SHA-256-hash overeenkomen met het geüploade certificaat.
De Custom CA verwijderen
API:
POST /api/tls/ca/delete
Voorbeeld:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/delete"
Verwijderen van de Custom CA herstelt ook de modus builtin. Herstart daarna het apparaat.
IAMMETER Swagger UI gebruiken
U kunt dezelfde API’s testen zonder handmatig curl-opdrachten te schrijven:
IAMMETER WEM API Test - TLS CA
- Open WEM API Test op een computer die het lokale IP-adres van het apparaat kan bereiken.
- Voer het apparaatadres in, bijvoorbeeld
192.168.1.80, en kies Apply. - Kies Authorize en voer de beheerdersnaam en het wachtwoord in.
- Open de groep TLS CA - Authenticated.
- Controleer de configuratie met
GET /api/tls/ca/status. - Gebruik naar behoefte uploaden, selecteren of verwijderen.
- Herstart na wijziging van de modus of het certificaat.
De Swagger-pagina draait in de browser en stuurt verzoeken vanaf die computer rechtstreeks naar het IAMMETER-apparaat. Ze worden niet via IAMMETER Cloud doorgestuurd. De browser heeft dus directe netwerktoegang tot het apparaat-IP nodig.
Problemen met certificaatverificatie oplossen
admin security required
Schakel Local Admin Security in voordat u de TLS-CA-API’s gebruikt. Deze instellingen kunnen niet anoniem worden gewijzigd.
custom CA is missing or invalid
Upload met succes een geldige PEM-CA voordat u custom selecteert. Vraag /api/tls/ca/status op en controleer of customCaValid de waarde 1 heeft.
TLS-verbinding mislukt met builtin of custom
Controleer alle volgende punten:
- de ingestelde hostnaam of het IP-adres komt overeen met de SAN;
- het certificaat is momenteel geldig en de apparaatklok klopt;
- de server stuurt de benodigde tussenliggende certificaten mee;
- de geselecteerde root-CA heeft het servercertificaat uitgegeven of vertrouwt het via de keten;
- het apparaat is na de TLS-wijziging herstart.
TLS werkt met none, maar niet met verificatie
Dit wijst meestal op een probleem met de certificaatketen, hostnaam, geldigheidsperiode of apparaatklok. none ingeschakeld laten verbergt de authenticatiefout, maar lost die niet op. Corrigeer de certificaatinstallatie of upload de juiste root-CA en gebruik custom.
