Sicurezza dell’amministrazione locale dei contatori IAMMETER: guida utente

Sicurezza dell’amministrazione locale: guida utente

Il modulo Local Admin Security è disponibile nel firmware i.91.065.3 e versioni successive.

Scopo

Il modulo protegge l’interfaccia Web locale e le API locali sensibili del dispositivo dagli accessi non autorizzati.

Dopo l’attivazione, sono necessari nome utente e password amministratore per:

• tutte le Set API disponibili nella pagina di test delle API WEM;
• le API GET che restituiscono dati di configurazione sensibili o eseguono operazioni sensibili;
• il caricamento e l’aggiornamento locale del firmware OTA.

Sono comprese operazioni come la modifica delle impostazioni di rete o di caricamento, l’aggiornamento del firmware, il riavvio del dispositivo, il ripristino delle impostazioni di fabbrica e la modifica di altri parametri sensibili.

Il modulo offre:

• credenziali amministratore configurabili;
• HTTP Basic Authentication per le API locali protette;
• modifica delle credenziali tramite interfaccia Web o API;
• procedura di recupero basata su firma Ed25519 in caso di password amministratore dimenticata.

La funzione è disattivata per impostazione predefinita per mantenere la compatibilità con i firmware precedenti. Deve essere attivata e configurata prima che la protezione degli accessi abbia effetto.

L’attuale interfaccia Web locale utilizza HTTP. HTTP Basic Authentication codifica le credenziali, ma non le cifra. Utilizza questa funzione su una rete locale attendibile, a meno che l’accesso al dispositivo non avvenga tramite un ulteriore meccanismo di trasporto sicuro.

Configurare Admin Security nell’interfaccia Web

1. Apri l’indirizzo IP del dispositivo in un browser.
2. Seleziona la scheda Security.
3. Inserisci un nome utente amministratore.
4. Inserisci e conferma la password amministratore.
5. Seleziona Enable Admin Security.

Nome utente e password devono rispettare queste regole:

• lunghezza: da 1 a 32 caratteri;
• solo caratteri ASCII visibili;
• non sono consentiti i due punti (:), le virgolette doppie (") o la barra rovesciata (\).

Dopo l’attivazione di Admin Security, il browser mostra una richiesta di autenticazione quando si accede a una pagina o API protetta. Inserisci nome utente e password configurati.

La scheda Security consente inoltre di:

• cambiare nome utente e password amministratore;
• verificare che l’autenticazione amministratore sia attiva;
• attivare o disattivare il servizio Modbus/TCP sulla porta 502;
• attivare o disattivare il rilevamento SSDP;
• disattivare Admin Security dopo l’autenticazione con le credenziali correnti.

Le modifiche allo stato dei servizi Modbus/TCP o SSDP richiedono il riavvio del dispositivo. Se queste impostazioni non sono mai state salvate da un firmware precedente, entrambi i servizi sono attivi per impostazione predefinita per garantire la retrocompatibilità.

Il browser può memorizzare nella cache le credenziali Basic Authentication per l’indirizzo del dispositivo. Dopo aver cambiato la password, potrebbe prima riprovare le vecchie credenziali e poi mostrare una nuova richiesta di autenticazione. Chiudere tutte le finestre del browser o utilizzare una finestra privata può forzare un nuovo accesso.

API che non richiedono Basic Authentication

I seguenti endpoint restano disponibili senza intestazione Basic Authentication, affinché l’interfaccia Web possa caricare le informazioni di base e la procedura di recupero firmata possa funzionare:

Anche POST /api/admin/enable può essere chiamato senza Basic Authentication quando Admin Security è disattivato, perché è l’endpoint utilizzato per la configurazione iniziale. Se Admin Security è già attivo, sono necessarie le credenziali amministratore correnti per modificare o disattivare la configurazione.

I file statici dell’interfaccia Web e le altre risorse GET esterne a /api/ non sono endpoint API e restano leggibili pubblicamente. Tutti gli altri endpoint API locali sono protetti quando Admin Security è attivo, incluse tutte le Set API, le API GET sensibili e le operazioni OTA.

Riferimento API

GET /api/admin/status

Restituisce lo stato corrente di Admin Security. Non richiede autenticazione.

Risposta di esempio:

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

Campi:

• enabled: 1 quando Admin Security è attivo; altrimenti 0.
• hasPassword: 1 quando sono state configurate credenziali amministratore.
• recoverySupported: 1 quando il firmware supporta il recupero amministratore firmato.
• modbusTcpEnabled: 1 quando il servizio Modbus/TCP sulla porta 502 è attivo.
• ssdpEnabled: 1 quando il rilevamento SSDP è attivo.

POST /api/admin/enable

Attiva o disattiva Admin Security.

Attivazione:

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

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

Esempio con curl:

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

Disattivazione:

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

{
  "enable": 0
}

Se Admin Security è già attivo, per chiamare questa API sono necessarie le credenziali Basic Authentication correnti.

Esempio:

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

POST /api/admin/password

Modifica nome utente e password amministratore. Questa API è protetta dopo l’attivazione di Admin Security.

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

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

Esempio:

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

Dopo il successo della richiesta, usa le nuove credenziali per le successive richieste protette.

GET /api/admin/check

Verifica che le credenziali Basic Authentication fornite siano valide.

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

Risposta corretta:

{
  "successful": 1
}

Credenziali mancanti o non valide producono la risposta HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Crea un payload di recupero monouso specifico del dispositivo. Non è richiesta l’autenticazione, perché questo endpoint da solo non reimposta le credenziali.

Risposta di esempio:

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

Il valore payload restituito deve essere inviato a IAMMETER quando è necessario il recupero amministratore.

La richiesta di un nuovo challenge invalida quello precedente. Un challenge viene invalidato anche dopo un recupero riuscito o il riavvio del dispositivo.

POST /api/admin/recovery

Invia il payload di recupero e la firma Ed25519 fornita da 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"
}

Esempio:

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>"}'

Se la verifica della firma riesce, il dispositivo cancella le credenziali amministratore locali e disattiva Admin Security. È quindi possibile configurare nuovi nome utente e password.

Se il dispositivo non dispone di memoria libera sufficiente per verificare la firma, l’API restituisce una risposta simile:

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

In questo caso, riduci l’uso della memoria e richiedi un nuovo challenge prima di riprovare. Se la password non è disponibile e non è possibile cambiare la modalità operativa, riavvia il dispositivo ed esegui il recupero prima che una connessione MQTTS o HTTPS consumi ulteriore memoria.

Come funziona il recupero della password

Il sistema evita di aggiungere un comando di ripristino di fabbrica non autenticato che potrebbe aggirare la protezione amministratore.

La procedura utilizza una coppia di chiavi pubblica/privata Ed25519:

• il firmware contiene soltanto la chiave pubblica di recupero IAMMETER;
• la chiave privata corrispondente è conservata da IAMMETER e non sul dispositivo;
• il dispositivo crea un payload con l’operazione richiesta, il numero di serie, l’indirizzo MAC e un nonce monouso;
• IAMMETER firma esattamente questo payload con la chiave privata di recupero;
• il dispositivo verifica la firma con la chiave pubblica incorporata;
• solo una firma valida per il dispositivo e il nonce correnti può cancellare la configurazione amministratore.

Il nonce viene conservato solo nella RAM. Diventa non valido al riavvio, quando si richiede un altro challenge o dopo un recupero riuscito. Un vecchio payload e la relativa firma non possono quindi essere riutilizzati in una sessione successiva.

Scenari di utilizzo

Scenario 1: impostare nome utente e password amministratore

Il metodo più semplice è l’interfaccia Web:

1. Apri http://<device-ip>/.
2. Apri la scheda Security.
3. Inserisci il nuovo nome utente e la nuova password amministratore.
4. Conferma la password.
5. Attiva Admin Security.

La stessa operazione può essere eseguita tramite 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"}'

Verifica il risultato:

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

Scenario 2: accedere alle API protette con Basic Authentication

Per ogni successiva richiesta protetta, invia nome utente e password amministratore nell’intestazione HTTP Basic Authentication.

Il valore dell’intestazione viene costruito così:

Authorization: Basic Base64(username:password)

Ad esempio, le credenziali admin:ExamplePassword vengono prima unite e poi codificate in Base64. La maggior parte dei client HTTP lo fa automaticamente.

Con curl:

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

Con un’intestazione esplicita:

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

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

Per una richiesta JSON POST:

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

Il browser gestisce automaticamente questa intestazione dopo che l’amministratore inserisce le credenziali nella richiesta Basic Authentication.

L’attuale interfaccia Web carica il firmware su POST /api/ota_successful.html. Il vecchio endpoint POST /ota_successful.html resta disponibile per le precedenti versioni dell’interfaccia e per gli strumenti esterni. Entrambi richiedono Basic Authentication quando Admin Security è attivo.

Se la richiesta di autenticazione viene chiusa, le schede si comportano così:

• Settings e Wi-Fi non possono caricare le API di configurazione protette e mostrano un messaggio di autenticazione amministratore;
• System può continuare a mostrare numero di serie, MAC e versione firmware perché questi dati provengono dall’endpoint pubblico /api/monitor. Il caricamento OTA resta protetto;
• Security può mostrare lo stato di base perché /api/admin/status è pubblico. Le modifiche delle credenziali e degli interruttori dei servizi restano protette.

Scenario 3: recuperare l’accesso dopo aver dimenticato la password

Il dispositivo non dispone di un pulsante fisico di reset. Per evitare una funzione non autenticata che possa aggirare Admin Security, utilizza il meccanismo di recupero firmato descritto sopra.

Questa procedura è destinata solo ai casi in cui siano stati dimenticati sia il nome utente sia la password. Conserva le credenziali in un luogo sicuro e non affidarti al recupero per le modifiche ordinarie. Se le credenziali correnti sono ancora disponibili, modificale direttamente dalla scheda Security o con POST /api/admin/password.

1. Richiedi un nuovo challenge di recupero:

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

2. Copia il valore payload completo della risposta. Non modificare SN, MAC, nonce, separatori o maiuscole/minuscole.

3. Contatta l’assistenza IAMMETER all’indirizzo support@devicebit.com e invia il payload completo.

4. Dopo aver verificato la proprietà o l’autorizzazione all’assistenza, IAMMETER firma il payload e restituisce una firma Ed25519.

5. Invia al dispositivo il payload originale e la firma ricevuta:

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

6. Dopo una risposta corretta, Admin Security viene disattivato e le precedenti credenziali vengono cancellate. Apri la scheda Security o chiama POST /api/admin/enable per configurare nuove credenziali.

Non riavviare il dispositivo e non richiedere un altro challenge mentre attendi la firma. Entrambe le azioni invalidano il payload inviato e obbligano a ricominciare il recupero con un nuovo challenge.