Come configurare la verifica dei certificati MQTTS e HTTPS su un contatore IAMMETER
I contatori IAMMETER con firmware i.91.065.9 o successivo possono verificare il certificato del server quando inviano dati tramite MQTTS o HTTPS. Questa funzione aggiunge la verifica della catena di certificati e del nome host del server alle connessioni sicure in uscita.
L’articolo riguarda la configurazione della fiducia TLS. Non configura topic MQTT, payload JSON o il rilevamento di Home Assistant. Per la pubblicazione MQTT, consulta Contatore MQTT: pubblicare i dati IAMMETER sul proprio broker MQTT.
In questa pagina
- Scegliere una modalità di verifica dei certificati
- Requisiti e limiti importanti
- Controllare la modalità TLS attuale
- Selezionare la verifica builtin
- Selezionare none per una diagnosi temporanea
- Caricare e selezionare una CA personalizzata
- Eliminare la CA personalizzata
- Usare Swagger UI IAMMETER
- Risolvere i problemi di verifica dei certificati
Scegliere una modalità di verifica dei certificati
I client MQTTS e HTTPS di IAMMETER supportano tre modalità di verifica del certificato del server:
| Modalità | Catena di certificati | Nome host del server | Uso previsto |
|---|---|---|---|
builtin |
Verificata con le CA radice integrate nel firmware | Verificato | Consigliata per servizi pubblici con una catena supportata |
custom |
Verificata con una CA radice PEM fornita dall’utente | Verificato | PKI privata, installazioni autofirmate o radici pubbliche non integrate |
none |
Non verificata | Non verificato | Solo compatibilità o diagnosi temporanea |
Queste impostazioni si applicano quando IAMMETER agisce da client TLS e invia dati a un broker MQTTS o a un server HTTPS. Non abilitano HTTPS sul server Web locale del dispositivo.
builtin
builtin è la modalità predefinita. Viene usata quando non è stata salvata alcuna impostazione di verifica TLS e viene ripristinata dopo l’eliminazione della configurazione TLS CA o il ripristino delle impostazioni di fabbrica.
Il firmware contiene queste CA radice:
- DigiCert Global Root G2
- ISRG Root X1
Il dispositivo verifica sia la catena di certificati sia il nome host del server. Il broker MQTTS o il server HTTPS deve presentare un certificato la cui catena risalga a una di queste radici; il suo Subject Alternative Name (SAN) deve corrispondere all’indirizzo del server configurato.
Se si usa un indirizzo IP per l’invio, il SAN deve contenere esattamente quell’indirizzo IP. Un nome DNS non corrisponde a un indirizzo IP, anche se entrambi identificano lo stesso server.
custom
custom esegue le stesse verifiche di catena e nome host di builtin, ma considera attendibile il certificato CA PEM caricato dall’amministratore. Usala quando:
- il certificato del server è emesso da una CA privata;
- l’installazione usa un certificato server autofirmato; oppure
- la CA radice pubblica necessaria non è inclusa nel firmware.
Per una PKI privata, carica il suo certificato CA radice. Il server TLS deve comunque inviare i certificati intermedi necessari durante l’handshake. Un certificato server autofirmato può essere caricato come ancora di fiducia, ma il suo SAN deve comunque corrispondere al nome host o all’IP configurato.
none
none stabilisce comunque una connessione TLS cifrata, ma non verifica la catena di certificati o il nome host. È simile al precedente comportamento TLS senza autenticazione del server.
Questa modalità è vulnerabile agli attacchi man-in-the-middle. Usala solo temporaneamente per compatibilità o diagnosi. In produzione preferisci builtin o custom.
Requisiti e limiti importanti
Le API di configurazione TLS CA richiedono l’attivazione di Local Admin Security. Ogni richiesta deve includere il nome utente e la password amministratore configurati tramite HTTP Basic Authentication.
Il computer che esegue curl o Swagger UI deve poter raggiungere l’IP locale del dispositivo. I client MQTTS e HTTPS condividono una modalità di verifica e una CA personalizzata: la modifica si applica quindi alla modalità di invio sicuro utilizzata dal dispositivo.
Riavvia il dispositivo dopo aver modificato la configurazione TLS, per ricreare il client in uscita con le nuove impostazioni.
Gli esempi usano questi segnaposto:
DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"
Sostituiscili con l’indirizzo effettivo del dispositivo e le credenziali amministratore.
Controllare la modalità TLS attuale
API:
GET /api/tls/ca/status
Esempio:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Esempio di risposta:
{
"successful": 1,
"mode": "builtin",
"customCaValid": 0,
"customCaLength": 0,
"customCaSha256": "",
"restartRequiredAfterChange": 1
}
La risposta indica la modalità selezionata e, se presente, la lunghezza e l’impronta SHA-256 della CA personalizzata memorizzata.
Selezionare la verifica builtin
API:
POST /api/tls/ca/select
Esempio:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"builtin"}'
Riavvia il dispositivo dopo una risposta positiva.
Selezionare none per una diagnosi temporanea
API:
POST /api/tls/ca/select
Esempio:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"none"}'
La risposta avverte che la verifica del certificato del server è disattivata. Riavvia dopo il cambio di modalità e torna a builtin o custom al termine della diagnosi.
Caricare e selezionare una CA personalizzata
Caricare una CA e selezionare custom sono operazioni distinte. Il caricamento non modifica automaticamente la modalità attiva.
Requisiti del file CA personalizzato
Il file caricato deve soddisfare tutti questi requisiti:
- formato di certificato PEM;
- corpo della richiesta grezzo, non JSON né
multipart/form-data; Content-Type: application/x-pem-file;- lunghezza da 1 a 3072 byte, inclusi intestazioni PEM, terminatori di riga e spazi;
- contiene
-----BEGIN CERTIFICATE-----e-----END CERTIFICATE-----; - non contiene una chiave privata.
Il limite di 3072 byte vale per l’intero corpo della richiesta HTTP. Un file PEM di 3072 byte viene accettato; un file di 3073 byte viene rifiutato.
Controlla la dimensione del file prima di caricarlo:
wc -c root-ca.pem
Passo 1: caricare la CA
API:
POST /api/tls/ca/upload
Esempio:
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
Esempio di risposta positiva:
{
"successful": 1,
"length": 1939,
"sha256": "64-character SHA-256 digest",
"message": "CA uploaded; select custom mode and restart"
}
Il dispositivo memorizza la CA in più blocchi KV e verifica la lunghezza e l’impronta SHA-256 salvate prima di contrassegnarla come attiva. Una scrittura interrotta non sostituisce la precedente CA valida.
Passo 2: selezionare custom
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"custom"}'
Se non è memorizzata una CA personalizzata valida, il dispositivo rifiuta la richiesta. Non passa automaticamente e senza avviso a none.
Passo 3: riavviare e verificare
Riavvia dall’interfaccia Web locale oppure usa l’API di riavvio protetta:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/restart?reset=false"
Dopo la riconnessione, interroga nuovamente lo stato:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Verifica che mode sia custom, che customCaValid sia 1 e che lunghezza e impronta SHA-256 corrispondano al certificato caricato.
Eliminare la CA personalizzata
API:
POST /api/tls/ca/delete
Esempio:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/delete"
L’eliminazione della CA personalizzata ripristina anche la modalità builtin. Riavvia il dispositivo dopo l’eliminazione.
Usare Swagger UI IAMMETER
Puoi testare le stesse API senza scrivere manualmente comandi curl:
IAMMETER WEM API Test - TLS CA
- Apri WEM API Test su un computer che possa raggiungere l’IP locale del dispositivo.
- Inserisci l’indirizzo, ad esempio
192.168.1.80, e seleziona Apply. - Seleziona Authorize e inserisci nome utente e password amministratore.
- Apri il gruppo TLS CA - Authenticated.
- Usa
GET /api/tls/ca/statusper controllare la configurazione. - Usa l’operazione di caricamento, selezione o eliminazione secondo necessità.
- Riavvia dopo aver modificato modalità o certificato.
La pagina Swagger viene eseguita nel browser e invia le richieste direttamente da quel computer al dispositivo IAMMETER. Non passa attraverso IAMMETER Cloud: il browser deve avere connettività diretta verso l’IP del dispositivo.
Risolvere i problemi di verifica dei certificati
admin security required
Attiva Local Admin Security prima di usare le API TLS CA. Queste impostazioni non possono essere modificate anonimamente.
custom CA is missing or invalid
Carica correttamente una CA PEM valida prima di selezionare custom. Interroga /api/tls/ca/status e verifica che customCaValid sia 1.
La connessione TLS fallisce in builtin o custom
Controlla tutti i punti seguenti:
- nome host o IP configurato corrispondente al SAN;
- certificato attualmente valido e ora del dispositivo corretta;
- invio dei certificati intermedi necessari da parte del server;
- CA radice selezionata che ha emesso il certificato server o lo considera attendibile tramite la catena;
- riavvio del dispositivo dopo la modifica TLS.
TLS funziona in none ma fallisce nelle modalità con verifica
Di solito indica un problema di catena di certificati, nome host, periodo di validità o orologio del dispositivo. Lasciare none attivo nasconde l’errore di autenticazione, senza risolverlo. Correggi la configurazione dei certificati oppure carica la CA radice appropriata e usa custom.
