Sécurité de l’administration locale des compteurs IAMMETER : guide d’utilisation

Le module Local Admin Security est disponible à partir du firmware i.91.065.3.

Sur cette page

• Objectif
• Configurer Admin Security dans l’interface Web
• API ne nécessitant pas Basic Authentication
• Référence des API
• Fonctionnement de la récupération du mot de passe
• Scénarios d’utilisation
  • Scénario 1 : définir un nom d’utilisateur et un mot de passe administrateur
  • Scénario 2 : accéder aux API protégées avec Basic Authentication
  • Scénario 3 : récupérer l’accès après l’oubli du mot de passe

Objectif

Le module protège l’interface Web locale et les API locales sensibles contre les accès non autorisés.

Après son activation, un nom d’utilisateur et un mot de passe administrateur sont nécessaires pour :

• toutes les API Set disponibles sur la page de test des API WEM ;
• les API GET qui renvoient des données de configuration sensibles ou exécutent des opérations sensibles ;
• le téléversement et la mise à jour locale du firmware par OTA.

Cela comprend notamment la modification des paramètres réseau ou de téléversement, la mise à jour du firmware, le redémarrage de l’appareil, le rétablissement des paramètres d’usine et la modification d’autres paramètres sensibles.

Le module fournit :

• des identifiants administrateur configurables ;
• HTTP Basic Authentication pour les API locales protégées ;
• la modification des identifiants depuis l’interface Web ou l’API ;
• une procédure de récupération fondée sur une signature Ed25519 en cas d’oubli du mot de passe administrateur.

Cette fonction est désactivée par défaut pour préserver la compatibilité avec les anciens firmwares. Elle doit être activée et configurée avant que la protection des accès ne prenne effet.

L’interface Web locale actuelle utilise HTTP. HTTP Basic Authentication encode les identifiants, mais ne les chiffre pas. Utilisez cette fonction sur un réseau local de confiance, sauf si l’accès à l’appareil passe par un mécanisme de transport sécurisé supplémentaire.

Configurer Admin Security dans l’interface Web

1. Ouvrez l’adresse IP de l’appareil dans un navigateur.
2. Sélectionnez l’onglet Security.
3. Saisissez un nom d’utilisateur administrateur.
4. Saisissez puis confirmez le mot de passe administrateur.
5. Sélectionnez Enable Admin Security.

Le nom d’utilisateur et le mot de passe doivent respecter les règles suivantes :

• longueur : 1 à 32 caractères ;
• uniquement des caractères ASCII visibles ;
• les deux-points (:), les guillemets doubles (") et la barre oblique inverse (\) sont interdits.

Après l’activation d’Admin Security, le navigateur affiche une demande d’authentification lors de l’accès à une page ou une API protégée. Saisissez le nom d’utilisateur et le mot de passe configurés.

L’onglet Security permet également de :

• modifier le nom d’utilisateur et le mot de passe administrateur ;
• vérifier que l’authentification administrateur est activée ;
• activer ou désactiver le service Modbus/TCP sur le port 502 ;
• activer ou désactiver la découverte SSDP ;
• désactiver Admin Security après authentification avec les identifiants actuels.

Toute modification de l’état du service Modbus/TCP ou SSDP nécessite un redémarrage de l’appareil. Si ces réglages n’ont jamais été enregistrés par un firmware antérieur, les deux services sont activés par défaut pour assurer la rétrocompatibilité.

Le navigateur peut mettre en cache les identifiants Basic Authentication associés à l’adresse de l’appareil. Après un changement de mot de passe, il peut d’abord réessayer les anciens identifiants avant d’afficher une nouvelle demande d’authentification. La fermeture de toutes les fenêtres du navigateur ou l’utilisation d’une fenêtre privée peut également forcer une nouvelle connexion.

API ne nécessitant pas Basic Authentication

Les points de terminaison suivants restent accessibles sans en-tête Basic Authentication afin que l’interface Web puisse charger les informations élémentaires de l’appareil et que la procédure de récupération signée puisse fonctionner :

POST /api/admin/enable peut également être appelé sans Basic Authentication lorsqu’Admin Security est désactivé, car ce point de terminaison sert à la configuration initiale. Si Admin Security est déjà activé, les identifiants administrateur valides actuels sont nécessaires pour modifier ou désactiver la configuration de sécurité.

Les fichiers statiques de l’interface Web et les autres ressources GET qui ne se trouvent pas sous /api/ ne sont pas des points de terminaison d’API et restent lisibles publiquement. Toutes les autres API locales sont protégées lorsqu’Admin Security est activé, y compris toutes les API Set, les API GET sensibles et les opérations OTA.

Référence des API

GET /api/admin/status

Renvoie l’état actuel d’Admin Security. Aucune authentification n’est requise.

Exemple de réponse :

{
  "enabled": 1,
  "hasPassword": 1,
  "recoverySupported": 1,
  "modbusTcpEnabled": 1,
  "ssdpEnabled": 1
}

Champs :

• enabled : 1 si Admin Security est activé, sinon 0.
• hasPassword : 1 si des identifiants administrateur ont été configurés.
• recoverySupported : 1 si le firmware prend en charge la récupération administrateur signée.
• modbusTcpEnabled : 1 si le service Modbus/TCP du port 502 est activé.
• ssdpEnabled : 1 si la découverte SSDP est activée.

POST /api/admin/enable

Active ou désactive Admin Security.

Activer Admin Security :

POST /api/admin/enable
Content-Type: application/json

{
  "enable": 1,
  "username": "admin",
  "password": "ExamplePassword"
}

Exemple avec curl :

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

Désactiver Admin Security :

POST /api/admin/enable
Authorization: Basic <base64-credentials>
Content-Type: application/json

{
  "enable": 0
}

Si Admin Security est déjà activé, les identifiants Basic Authentication valides actuels sont nécessaires pour appeler cette API.

Exemple :

curl -X POST "http://<device-ip>/api/admin/enable" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"enable":0}'

POST /api/admin/password

Modifie le nom d’utilisateur et le mot de passe administrateur. Cette API est protégée après l’activation d’Admin Security.

POST /api/admin/password
Authorization: Basic <current-base64-credentials>
Content-Type: application/json

{
  "username": "newadmin",
  "password": "NewExamplePassword"
}

Exemple :

curl -X POST "http://<device-ip>/api/admin/password" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"username":"newadmin","password":"NewExamplePassword"}'

Après la réussite de la requête, utilisez les nouveaux identifiants pour les requêtes protégées suivantes.

GET /api/admin/check

Vérifie si les identifiants Basic Authentication fournis sont valides.

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/admin/check"

Réponse en cas de réussite :

{
  "successful": 1
}

Des identifiants absents ou non valides produisent la réponse HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Crée une charge utile de récupération à usage unique propre à l’appareil. Aucune authentification n’est requise, car ce point de terminaison ne réinitialise pas les identifiants à lui seul.

Exemple de réponse :

{
  "successful": 1,
  "alg": "ed25519",
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE"
}

La valeur payload renvoyée doit être transmise à IAMMETER lorsqu’une récupération administrateur est nécessaire.

Toute nouvelle demande de challenge invalide le précédent. Un challenge est également invalidé après une récupération réussie ou le redémarrage de l’appareil.

POST /api/admin/recovery

Envoie la charge utile de récupération et la signature Ed25519 fournie par IAMMETER.

POST /api/admin/recovery
Content-Type: application/json

{
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE",
  "signature": "128-hex-character-ed25519-signature"
}

Exemple :

curl -X POST "http://<device-ip>/api/admin/recovery" \
  -H "Content-Type: application/json" \
  -d '{"payload":"reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE","signature":"<signature-from-IAMMETER>"}'

Si la signature est valide, l’appareil efface les identifiants administrateur locaux et désactive Admin Security. Un nouveau nom d’utilisateur et un nouveau mot de passe peuvent alors être configurés.

Si l’appareil ne dispose pas d’assez de mémoire libre pour vérifier la signature, l’API renvoie une réponse semblable à :

{
  "successful": 0,
  "message": "low memory, please change to standalone mode",
  "freeMemory": 18000,
  "minFreeRequired": 28000
}

Dans ce cas, réduisez l’utilisation de la mémoire et demandez un nouveau challenge avant de réessayer. Si le mot de passe n’est pas disponible et que le mode de fonctionnement ne peut pas être modifié, redémarrez l’appareil et effectuez la récupération avant qu’une connexion MQTTS ou HTTPS ne consomme de la mémoire supplémentaire.

Fonctionnement de la récupération du mot de passe

La conception de la récupération évite d’ajouter une commande de réinitialisation d’usine non authentifiée qui pourrait contourner la protection administrateur.

Le processus utilise une paire de clés publique/privée Ed25519 :

• le firmware de l’appareil contient uniquement la clé publique de récupération IAMMETER ;
• la clé privée correspondante est conservée par IAMMETER et n’est pas stockée sur l’appareil ;
• l’appareil crée une charge utile contenant l’opération demandée, le numéro de série, l’adresse MAC et un nonce à usage unique ;
• IAMMETER signe cette charge utile exacte avec la clé privée de récupération ;
• l’appareil vérifie la signature avec sa clé publique intégrée ;
• seule une signature valide pour l’appareil et le nonce actuels peut effacer la configuration administrateur.

Le nonce est stocké uniquement en RAM. Il devient invalide au redémarrage de l’appareil, lorsqu’un autre challenge est demandé ou après une récupération réussie. Une ancienne charge utile et sa signature ne peuvent donc pas être réutilisées pour une session ultérieure.

Scénarios d’utilisation

Scénario 1 : définir un nom d’utilisateur et un mot de passe administrateur

La méthode la plus simple consiste à utiliser l’interface Web :

1. Ouvrez http://<device-ip>/.
2. Ouvrez l’onglet Security.
3. Saisissez le nouveau nom d’utilisateur et le nouveau mot de passe administrateur.
4. Confirmez le mot de passe.
5. Activez Admin Security.

La même opération peut être effectuée par POST /api/admin/enable :

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

Vérifiez le résultat :

curl "http://<device-ip>/api/admin/status"

Scénario 2 : accéder aux API protégées avec Basic Authentication

Pour chaque requête protégée suivante, envoyez le nom d’utilisateur et le mot de passe administrateur dans l’en-tête HTTP Basic Authentication.

La valeur de l’en-tête est construite comme suit :

Authorization: Basic Base64(username:password)

Par exemple, les identifiants admin:ExamplePassword sont d’abord associés, puis encodés en Base64. La plupart des clients HTTP le font automatiquement.

Avec curl :

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/getadv"

Avec un en-tête explicite :

TOKEN=$(printf '%s' 'admin:ExamplePassword' | base64)

curl "http://<device-ip>/api/getadv" \
  -H "Authorization: Basic ${TOKEN}"

Pour une requête JSON POST :

curl -X POST "http://<device-ip>/api/setadv" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '<setadv-json-body>'

Le navigateur gère automatiquement cet en-tête après la saisie des identifiants dans la demande Basic Authentication.

L’interface Web actuelle envoie le firmware à POST /api/ota_successful.html. L’ancien point de terminaison POST /ota_successful.html reste disponible pour les anciennes versions de l’interface et les outils externes. Les deux exigent Basic Authentication lorsqu’Admin Security est activé.

Si la demande d’authentification est fermée, les onglets de l’interface Web se comportent comme suit :

• Settings et Wi-Fi ne peuvent pas charger leurs API de configuration protégées et affichent un message d’authentification administrateur ;
• System peut toujours afficher le numéro de série, l’adresse MAC et la version du firmware, car ces valeurs proviennent du point de terminaison public /api/monitor. Le téléversement OTA reste protégé ;
• Security peut toujours afficher l’état de base, car /api/admin/status est public. Les changements d’identifiants et de services restent protégés.

Scénario 3 : récupérer l’accès après l’oubli du mot de passe

L’appareil ne possède pas de bouton de réinitialisation matériel. Pour éviter une fonction de réinitialisation non authentifiée qui pourrait contourner Admin Security, il utilise un mécanisme de récupération signé et propre à l’appareil.

Utilisez cette procédure uniquement si vous avez oublié les identifiants administrateur. Si vous connaissez encore les identifiants actuels, modifiez-les dans l’onglet Security ou avec POST /api/admin/password.

Suivez le guide complet de récupération du mot de passe Admin Security, étape par étape

La procédure de récupération est la suivante :

1. Générez une charge utile à usage unique avec GET /api/admin/recovery_challenge.
2. Connectez-vous à l’application Admin Recovery du système IAMMETER Contributor. Le service vérifie que votre compte est autorisé à gérer le numéro de série de l’appareil et renvoie une signature Ed25519 pour cette charge utile exacte.
3. Envoyez la charge utile inchangée et la signature à POST /api/admin/recovery. Après vérification réussie, Admin Security est désactivé et les anciens identifiants administrateur locaux sont effacés.

Ne redémarrez pas l’appareil, n’actualisez pas la page du challenge et ne demandez pas d’autre challenge avant la fin de la récupération. Chacune de ces actions invalide le nonce actuel : vous devrez recommencer avec une nouvelle charge utile.

Le guide de récupération dédié comprend des captures d’écran, des commandes curl complètes, le dépannage des signatures rejetées et la procédure de récupération en cas de mémoire insuffisante.