Configurer la vérification des certificats MQTTS et HTTPS sur un compteur IAMMETER
Les compteurs IAMMETER équipés du firmware i.91.065.9 ou ultérieur peuvent vérifier le certificat du serveur lorsqu’ils envoient des données par MQTTS ou HTTPS. Cette fonction ajoute la vérification de la chaîne de certificats et du nom d’hôte du serveur aux connexions sortantes sécurisées.
Cet article traite de la configuration de la confiance TLS. Il ne configure ni les topics MQTT, ni les charges utiles JSON, ni la découverte Home Assistant. Pour la publication MQTT, consultez Compteur MQTT : publier les données IAMMETER vers votre broker MQTT.
Sur cette page
- Choisir un mode de vérification des certificats
- Prérequis et limites importantes
- Vérifier le mode TLS actuel
- Sélectionner la vérification builtin
- Sélectionner none pour un diagnostic temporaire
- Téléverser et sélectionner une CA personnalisée
- Supprimer la CA personnalisée
- Utiliser Swagger UI IAMMETER
- Résoudre les problèmes de vérification des certificats
Choisir un mode de vérification des certificats
Les clients MQTTS et HTTPS d’IAMMETER prennent en charge trois modes de vérification du certificat du serveur :
| Mode | Chaîne de certificats | Nom d’hôte du serveur | Utilisation prévue |
|---|---|---|---|
builtin |
Vérifiée avec les autorités racines intégrées au firmware | Vérifié | Recommandé pour les services publics utilisant une chaîne prise en charge |
custom |
Vérifiée avec une autorité racine PEM fournie par l’utilisateur | Vérifié | PKI privée, déploiements auto-signés ou racines publiques absentes du firmware |
none |
Non vérifiée | Non vérifié | Compatibilité ou diagnostic temporaire uniquement |
Ces réglages s’appliquent lorsque l’appareil IAMMETER agit comme client TLS et envoie des données vers un broker MQTTS ou un serveur HTTPS. Ils n’activent pas HTTPS sur le serveur Web local de l’appareil.
builtin
builtin est le mode par défaut. Il s’applique lorsqu’aucun réglage de vérification TLS n’a été enregistré et est rétabli après suppression de la configuration TLS CA ou réinitialisation de l’appareil aux paramètres d’usine.
Le firmware contient les autorités racines suivantes :
- DigiCert Global Root G2
- ISRG Root X1
L’appareil vérifie la chaîne de certificats et le nom d’hôte du serveur. Le broker MQTTS ou le serveur HTTPS doit présenter un certificat dont la chaîne aboutit à l’une de ces racines, et son champ Subject Alternative Name (SAN) doit correspondre à l’adresse de serveur configurée.
Si l’adresse d’envoi est une adresse IP, le SAN du certificat doit contenir exactement cette adresse IP. Un nom DNS ne correspond pas à une adresse IP, même s’ils désignent le même serveur.
custom
custom effectue les mêmes vérifications de chaîne et de nom d’hôte que builtin, mais fait confiance au certificat CA PEM téléversé par l’administrateur. Utilisez-le lorsque :
- le certificat du serveur est délivré par une CA privée ;
- le déploiement utilise un certificat de serveur auto-signé ; ou
- l’autorité racine publique nécessaire n’est pas intégrée au firmware.
Pour une PKI privée, téléversez son certificat racine. Le serveur TLS doit toujours transmettre les certificats intermédiaires nécessaires pendant la négociation. Un certificat de serveur auto-signé peut être téléversé comme ancre de confiance, mais son SAN doit toujours correspondre au nom d’hôte ou à l’adresse IP configurés.
none
none établit toujours une connexion TLS chiffrée, mais ne vérifie ni la chaîne de certificats ni le nom d’hôte. Ce fonctionnement est similaire à l’ancien comportement TLS sans authentification du serveur.
Ce mode est vulnérable aux attaques de l’homme du milieu (man-in-the-middle). Utilisez-le uniquement de manière temporaire pour la compatibilité ou le diagnostic. Préférez builtin ou custom en production.
Prérequis et limites importantes
Les API de configuration TLS CA nécessitent l’activation de Local Admin Security. Chaque requête doit inclure le nom d’utilisateur et le mot de passe administrateur configurés au moyen de HTTP Basic Authentication.
L’ordinateur exécutant curl ou Swagger UI doit pouvoir atteindre l’adresse IP locale de l’appareil. Les clients MQTTS et HTTPS partagent un mode de vérification et une CA personnalisée : toute modification s’applique donc au mode d’envoi sécurisé utilisé par l’appareil.
Redémarrez l’appareil après toute modification de la configuration TLS afin de recréer le client sortant avec les nouveaux réglages.
Les exemples utilisent les valeurs de substitution suivantes :
DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"
Remplacez-les par l’adresse réelle de l’appareil et les identifiants administrateur.
Vérifier le mode TLS actuel
API:
GET /api/tls/ca/status
Exemple :
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Exemple de réponse :
{
"successful": 1,
"mode": "builtin",
"customCaValid": 0,
"customCaLength": 0,
"customCaSha256": "",
"restartRequiredAfterChange": 1
}
La réponse indique le mode sélectionné et, lorsqu’une CA personnalisée est enregistrée, sa longueur et son empreinte SHA-256.
Sélectionner la vérification builtin
API:
POST /api/tls/ca/select
Exemple :
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"builtin"}'
Redémarrez l’appareil après une réponse positive.
Sélectionner none pour un diagnostic temporaire
API:
POST /api/tls/ca/select
Exemple :
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"none"}'
La réponse avertit que la vérification du certificat du serveur est désactivée. Redémarrez l’appareil après le changement de mode et revenez à builtin ou custom après le diagnostic.
Téléverser et sélectionner une CA personnalisée
Le téléversement d’une CA et la sélection de custom sont deux opérations distinctes. Téléverser une CA ne change pas automatiquement le mode actif.
Exigences du fichier de CA personnalisée
Le fichier téléversé doit respecter toutes ces exigences :
- format de certificat PEM ;
- corps de requête brut, ni JSON ni
multipart/form-data; Content-Type: application/x-pem-file;- longueur comprise entre 1 et 3072 octets, en-têtes PEM, fins de ligne et espaces compris ;
- présence de
-----BEGIN CERTIFICATE-----et-----END CERTIFICATE-----; - absence de clé privée.
La limite de 3072 octets concerne l’ensemble du corps de la requête HTTP. Un fichier PEM de 3072 octets est accepté ; un fichier de 3073 octets est rejeté.
Vérifiez la taille du fichier avant le téléversement :
wc -c root-ca.pem
Étape 1 : téléverser la CA
API:
POST /api/tls/ca/upload
Exemple :
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
Exemple de réponse positive :
{
"successful": 1,
"length": 1939,
"sha256": "64-character SHA-256 digest",
"message": "CA uploaded; select custom mode and restart"
}
L’appareil enregistre la CA dans plusieurs blocs KV et vérifie la longueur et l’empreinte SHA-256 enregistrées avant de la marquer comme active. Une écriture interrompue ne remplace pas la CA valide précédente.
Étape 2 : sélectionner custom
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"custom"}'
L’appareil rejette cette requête si aucune CA personnalisée valide n’est enregistrée. Il ne bascule pas silencieusement vers none.
Étape 3 : redémarrer et vérifier
Redémarrez l’appareil depuis son interface Web locale, ou utilisez l’API de redémarrage protégée :
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/restart?reset=false"
Une fois l’appareil reconnecté, interrogez à nouveau son état :
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Vérifiez que mode vaut custom, que customCaValid vaut 1 et que la longueur et l’empreinte SHA-256 correspondent au certificat téléversé.
Supprimer la CA personnalisée
API:
POST /api/tls/ca/delete
Exemple :
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/delete"
La suppression de la CA personnalisée rétablit aussi le mode builtin. Redémarrez l’appareil après la suppression.
Utiliser Swagger UI IAMMETER
Vous pouvez tester les mêmes API sans écrire manuellement les commandes curl :
IAMMETER WEM API Test - TLS CA
- Ouvrez la page WEM API Test sur un ordinateur pouvant atteindre l’adresse IP locale de l’appareil.
- Saisissez l’adresse de l’appareil, par exemple
192.168.1.80, puis sélectionnez Apply. - Sélectionnez Authorize et saisissez le nom d’utilisateur et le mot de passe administrateur.
- Ouvrez le groupe TLS CA - Authenticated.
- Utilisez
GET /api/tls/ca/statuspour consulter la configuration actuelle. - Utilisez l’opération de téléversement, de sélection ou de suppression selon le besoin.
- Redémarrez l’appareil après toute modification du mode ou du certificat.
La page Swagger s’exécute dans le navigateur et envoie directement les requêtes de cet ordinateur à l’appareil IAMMETER. Elle ne relaie pas les requêtes via IAMMETER Cloud : le navigateur doit donc avoir un accès réseau direct à l’adresse IP de l’appareil.
Résoudre les problèmes de vérification des certificats
admin security required
Activez Local Admin Security avant d’utiliser les API TLS CA. Ces réglages ne peuvent pas être modifiés anonymement.
custom CA is missing or invalid
Téléversez avec succès une CA PEM valide avant de sélectionner custom. Interrogez /api/tls/ca/status et vérifiez que customCaValid vaut 1.
La connexion TLS échoue avec builtin ou custom
Vérifiez tous les points suivants :
- le nom d’hôte ou l’adresse IP configurés correspondent au SAN du certificat ;
- le certificat est actuellement valide et l’heure de l’appareil est correcte ;
- le serveur envoie les certificats intermédiaires nécessaires ;
- la CA racine sélectionnée a délivré le certificat du serveur ou lui accorde sa confiance via la chaîne ;
- l’appareil a été redémarré après la modification TLS.
TLS fonctionne avec none, mais échoue avec les modes vérifiés
Cela indique généralement un problème de chaîne de certificats, de nom d’hôte, de période de validité ou d’horloge de l’appareil. Conserver none masque l’échec d’authentification sans le résoudre. Corrigez le déploiement du certificat ou téléversez la CA racine appropriée et utilisez custom.
