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

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

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

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 matériel de réinitialisation. Afin de ne pas ajouter une fonction non authentifiée susceptible de contourner Admin Security, il utilise le mécanisme de récupération signée décrit ci-dessus.

Cette procédure est réservée aux cas où le nom d’utilisateur et le mot de passe administrateur ont tous deux été oubliés. Conservez les identifiants dans un emplacement sûr et n’utilisez pas la récupération pour les modifications courantes. Si vous disposez encore des identifiants actuels, modifiez-les directement dans l’onglet Security ou avec POST /api/admin/password.

1. Demandez un nouveau challenge de récupération à l’appareil :

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

2. Copiez la valeur payload complète de la réponse. Ne modifiez ni le numéro de série, ni l’adresse MAC, ni le nonce, ni les séparateurs, ni la casse.

3. Contactez l’assistance IAMMETER à l’adresse support@devicebit.com et transmettez la charge utile complète.

4. Après confirmation de la propriété ou de l’autorisation de service, IAMMETER signe la charge utile et renvoie une signature Ed25519.

5. Envoyez à l’appareil la charge utile d’origine et la signature reçue :

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

6. Après une réponse positive, Admin Security est désactivé et les anciens identifiants administrateur sont effacés. Ouvrez l’onglet Security ou appelez POST /api/admin/enable pour définir de nouveaux identifiants.

Ne redémarrez pas l’appareil et ne demandez pas un autre challenge pendant l’attente de la signature. Ces deux actions invalident la charge utile transmise et obligent à recommencer la récupération avec un nouveau challenge.