Segurança da administração local dos medidores IAMMETER: guia do utilizador

Segurança da administração local: guia do utilizador

O módulo Local Admin Security está disponível no firmware i.91.065.3 e posteriores.

Objetivo

O módulo protege a interface Web local e as APIs locais sensíveis do dispositivo contra acessos não autorizados.

Depois de ativado, são necessários um nome de utilizador e uma palavra-passe de administrador para:

• todas as Set APIs disponíveis na página de teste das APIs WEM;
• APIs GET que devolvem dados de configuração sensíveis ou executam operações sensíveis;
• carregamento e atualização local de firmware por OTA.

Isto inclui alterar definições de rede ou carregamento, atualizar o firmware, reiniciar o dispositivo, restaurar as definições de fábrica e modificar outros parâmetros sensíveis.

O módulo oferece:

• credenciais de administrador configuráveis;
• HTTP Basic Authentication para APIs locais protegidas;
• alteração de credenciais pela interface Web ou API;
• recuperação baseada numa assinatura Ed25519 se a palavra-passe for esquecida.

A função está desativada por predefinição para manter a compatibilidade com firmware anteriores. Tem de ser ativada e configurada antes de a proteção entrar em vigor.

A interface Web local atual utiliza HTTP. O HTTP Basic Authentication codifica as credenciais, mas não as cifra. Utilize esta função numa rede local de confiança, exceto quando o dispositivo for acedido através de um mecanismo de transporte seguro adicional.

Configurar Admin Security na interface Web

1. Abra o endereço IP do dispositivo num navegador.
2. Selecione o separador Security.
3. Introduza um nome de utilizador de administrador.
4. Introduza e confirme a palavra-passe.
5. Selecione Enable Admin Security.

O nome de utilizador e a palavra-passe devem cumprir estas regras:

• comprimento de 1 a 32 caracteres;
• apenas caracteres ASCII visíveis;
• não são permitidos dois-pontos (:), aspas duplas (") ou barra invertida (\).

Após a ativação, o navegador mostra um pedido de autenticação ao aceder a uma página ou API protegida. Introduza as credenciais configuradas.

O separador Security também permite:

• alterar o nome de utilizador e a palavra-passe;
• verificar se a autenticação de administrador está ativa;
• ativar ou desativar Modbus/TCP na porta 502;
• ativar ou desativar a descoberta SSDP;
• desativar Admin Security após autenticação com as credenciais atuais.

As alterações ao estado de Modbus/TCP ou SSDP exigem o reinício do dispositivo. Se estas definições nunca tiverem sido guardadas por um firmware anterior, ambos os serviços ficam ativados por predefinição para retrocompatibilidade.

O navegador pode guardar em cache as credenciais Basic Authentication do endereço do dispositivo. Depois de alterar a palavra-passe, pode primeiro tentar as credenciais antigas e depois apresentar um novo pedido. Fechar todas as janelas ou utilizar uma janela privada também força um novo início de sessão.

APIs que não exigem Basic Authentication

Os seguintes endpoints permanecem disponíveis sem o cabeçalho Basic Authentication, para que a interface Web possa carregar informações básicas e o processo de recuperação assinado possa funcionar:

POST /api/admin/enable também pode ser chamado sem Basic Authentication quando Admin Security está desativado, pois é utilizado na configuração inicial. Se já estiver ativo, são necessárias as credenciais atuais válidas para alterar ou desativar a configuração.

Os ficheiros estáticos da interface Web e outros recursos GET fora de /api/ não são endpoints API e continuam publicamente legíveis. Todos os restantes endpoints API locais ficam protegidos quando Admin Security está ativo, incluindo todas as Set APIs, APIs GET sensíveis e operações OTA.

Referência da API

GET /api/admin/status

Devolve o estado atual. Não exige autenticação.

Exemplo:

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

Campos:

• enabled: 1 quando Admin Security está ativo; caso contrário, 0.
• hasPassword: 1 quando foram configuradas credenciais.
• recoverySupported: 1 quando o firmware suporta recuperação assinada.
• modbusTcpEnabled: 1 quando Modbus/TCP na porta 502 está ativo.
• ssdpEnabled: 1 quando a descoberta SSDP está ativa.

POST /api/admin/enable

Ativa ou desativa Admin Security.

Ativar:

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

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

Exemplo com curl:

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

Desativar:

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

{
  "enable": 0
}

Se Admin Security já estiver ativo, são necessárias as credenciais Basic Authentication atuais.

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

POST /api/admin/password

Altera o nome de utilizador e a palavra-passe. Esta API fica protegida após a ativação.

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

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

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

Depois do sucesso, utilize as novas credenciais nos pedidos protegidos seguintes.

GET /api/admin/check

Verifica se as credenciais Basic Authentication fornecidas são válidas.

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

Resposta correta:

{
  "successful": 1
}

Credenciais em falta ou inválidas resultam em HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Cria um payload de recuperação único e específico do dispositivo. Não exige autenticação porque este endpoint não redefine as credenciais por si só.

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

O payload devolvido deve ser enviado à IAMMETER quando for necessária a recuperação.

Solicitar um novo challenge invalida o anterior. Também é invalidado depois de uma recuperação bem-sucedida ou do reinício do dispositivo.

POST /api/admin/recovery

Envia o payload de recuperação e a assinatura Ed25519 fornecida pela 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"
}

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 a assinatura for válida, o dispositivo apaga as credenciais locais e desativa Admin Security. Podem então ser configuradas novas credenciais.

Se não houver memória livre suficiente para verificar a assinatura, a API devolve uma resposta semelhante:

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

Nesse caso, reduza a utilização de memória e solicite um novo challenge. Se a palavra-passe não estiver disponível e o modo não puder ser alterado, reinicie o dispositivo e efetue a recuperação antes que uma ligação MQTTS ou HTTPS consuma memória adicional.

Como funciona a recuperação da palavra-passe

O processo evita adicionar um comando de reposição de fábrica não autenticado que possa contornar a proteção.

Utiliza um par de chaves pública/privada Ed25519:

• o firmware contém apenas a chave pública de recuperação IAMMETER;
• a chave privada correspondente é mantida pela IAMMETER e não é guardada no dispositivo;
• o dispositivo cria um payload com a operação, SN, MAC e um nonce de utilização única;
• a IAMMETER assina esse payload com a chave privada;
• o dispositivo verifica a assinatura com a chave pública incorporada;
• apenas uma assinatura válida para o dispositivo e nonce atuais pode apagar a configuração.

O nonce é guardado apenas na RAM. Torna-se inválido quando o dispositivo reinicia, quando é solicitado outro challenge ou após uma recuperação bem-sucedida. Um payload e assinatura antigos não podem ser reutilizados.

Cenários de utilização

Cenário 1: definir nome de utilizador e palavra-passe

O método mais simples é a interface Web:

1. Abra http://<device-ip>/.
2. Abra o separador Security.
3. Introduza o novo nome de utilizador e palavra-passe.
4. Confirme a palavra-passe.
5. Ative Admin Security.

A mesma operação pode ser feita com 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"}'

Verifique:

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

Cenário 2: aceder a APIs protegidas com Basic Authentication

Em cada pedido protegido, envie o nome de utilizador e a palavra-passe no cabeçalho HTTP Basic Authentication.

Authorization: Basic Base64(username:password)

As credenciais admin:ExamplePassword são combinadas e codificadas em Base64. A maioria dos clientes HTTP fá-lo automaticamente.

Com curl:

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

Com cabeçalho explícito:

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

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

Para um pedido JSON POST:

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

O navegador gere este cabeçalho automaticamente depois de o administrador introduzir as credenciais.

A interface Web atual carrega firmware para POST /api/ota_successful.html. O endpoint antigo POST /ota_successful.html permanece disponível para versões anteriores e ferramentas externas. Ambos exigem Basic Authentication quando Admin Security está ativo.

Se o pedido de autenticação for fechado:

• Settings e Wi-Fi não conseguem carregar as APIs protegidas e mostram uma mensagem de autenticação;
• System continua a mostrar SN, MAC e versão do firmware, obtidos pelo endpoint público /api/monitor. O carregamento OTA permanece protegido;
• Security mostra o estado básico através de /api/admin/status. Alterações de credenciais e serviços permanecem protegidas.

Cenário 3: recuperar acesso após esquecer a palavra-passe

O dispositivo não tem botão físico de reposição. Para evitar uma função não autenticada que contorne Admin Security, utiliza o mecanismo de recuperação assinado descrito acima.

Este processo destina-se apenas a casos em que foram esquecidos o nome de utilizador e a palavra-passe. Guarde as credenciais em segurança e não dependa da recuperação para alterações rotineiras. Se ainda tiver as credenciais, altere-as no separador Security ou com POST /api/admin/password.

1. Solicite um novo challenge:

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

2. Copie o valor completo de payload. Não altere SN, MAC, nonce, separadores ou maiúsculas/minúsculas.

3. Contacte o suporte IAMMETER em support@devicebit.com e envie o payload completo.

4. Após confirmar a propriedade ou autorização de serviço, a IAMMETER assina o payload e devolve uma assinatura Ed25519.

5. Envie o payload original e a assinatura ao dispositivo:

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

6. Após uma resposta correta, Admin Security é desativado e as credenciais anteriores são apagadas. Abra Security ou chame POST /api/admin/enable para definir novas credenciais.

Não reinicie o dispositivo nem solicite outro challenge enquanto aguarda a assinatura. Qualquer uma destas ações invalida o payload e obriga a iniciar novamente a recuperação.