Como configurar a verificação de certificados MQTTS e HTTPS num medidor IAMMETER
Os medidores IAMMETER com firmware i.91.065.9 ou posterior podem verificar o certificado do servidor ao enviar dados por MQTTS ou HTTPS. Esta função acrescenta a verificação da cadeia de certificados e do nome do servidor às ligações seguras de saída.
Este artigo aborda a configuração de confiança TLS. Não configura tópicos MQTT, payloads JSON nem a descoberta do Home Assistant. Para o processo de publicação MQTT, consulte Medidor MQTT: publicar dados IAMMETER no seu broker MQTT.
Nesta página
- Escolher um modo de verificação de certificados
- Requisitos e limites importantes
- Verificar o modo TLS atual
- Selecionar a verificação builtin
- Selecionar none para diagnóstico temporário
- Carregar e selecionar uma CA personalizada
- Eliminar a CA personalizada
- Utilizar o Swagger UI IAMMETER
- Resolver problemas de verificação de certificados
Escolher um modo de verificação de certificados
Os clientes MQTTS e HTTPS do IAMMETER suportam três modos de verificação do certificado do servidor:
| Modo | Cadeia de certificados | Nome do servidor | Utilização prevista |
|---|---|---|---|
builtin |
Verificada com as CA raiz integradas no firmware | Verificado | Recomendado para serviços públicos com uma cadeia suportada |
custom |
Verificada com uma CA raiz PEM fornecida pelo utilizador | Verificado | PKI privada, instalações autoassinadas ou raízes públicas não incluídas |
none |
Não verificada | Não verificado | Apenas compatibilidade ou diagnóstico temporário |
Estas definições aplicam-se quando o dispositivo IAMMETER atua como cliente TLS e envia dados para um broker MQTTS ou servidor HTTPS. Não ativam HTTPS no servidor Web local do dispositivo.
builtin
builtin é o modo predefinido. É utilizado quando nenhuma definição de verificação TLS foi guardada e é reposto após eliminar a configuração TLS CA ou restaurar as definições de fábrica.
O firmware contém estas CA raiz:
- DigiCert Global Root G2
- ISRG Root X1
O dispositivo verifica a cadeia de certificados e o nome do servidor. O broker MQTTS ou servidor HTTPS deve apresentar um certificado cuja cadeia termine numa destas raízes, e o seu Subject Alternative Name (SAN) deve corresponder ao endereço configurado.
Se o endereço de envio for um IP, o SAN do certificado deve conter exatamente esse IP. Um nome DNS não corresponde a um endereço IP, mesmo quando ambos apontam para o mesmo servidor.
custom
custom verifica a cadeia e o nome do servidor tal como builtin, mas confia no certificado CA PEM carregado pelo administrador. Utilize-o quando:
- o certificado do servidor é emitido por uma CA privada;
- a instalação utiliza um certificado de servidor autoassinado; ou
- a CA raiz pública necessária não está incluída no firmware.
Para uma PKI privada, carregue o respetivo certificado CA raiz. O servidor TLS deve continuar a enviar os certificados intermédios necessários durante o handshake. Um certificado de servidor autoassinado pode ser carregado como âncora de confiança, mas o seu SAN deve continuar a corresponder ao nome ou IP configurado.
none
none continua a estabelecer uma ligação TLS encriptada, mas não verifica a cadeia de certificados nem o nome do servidor. É semelhante ao comportamento TLS anterior sem autenticação do servidor.
Este modo é vulnerável a ataques man-in-the-middle. Utilize-o apenas temporariamente por compatibilidade ou diagnóstico. Em produção, prefira builtin ou custom.
Requisitos e limites importantes
As APIs de configuração TLS CA exigem a ativação de Local Admin Security. Cada pedido deve incluir o nome de utilizador e a palavra-passe de administrador configurados através de HTTP Basic Authentication.
O computador com curl ou Swagger UI deve conseguir aceder ao IP local do dispositivo. Os clientes MQTTS e HTTPS partilham um modo de verificação e uma CA personalizada, pelo que qualquer alteração se aplica ao modo de envio seguro utilizado.
Reinicie o dispositivo depois de alterar a configuração TLS para recriar o cliente de saída com as novas definições.
Os exemplos utilizam estes valores de substituição:
DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"
Substitua-os pelo endereço real do dispositivo e pelas credenciais de administrador.
Verificar o modo TLS atual
API:
GET /api/tls/ca/status
Exemplo:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Exemplo de resposta:
{
"successful": 1,
"mode": "builtin",
"customCaValid": 0,
"customCaLength": 0,
"customCaSha256": "",
"restartRequiredAfterChange": 1
}
A resposta indica o modo selecionado e, quando existe uma CA personalizada guardada, o seu comprimento e resumo SHA-256.
Selecionar a verificação builtin
API:
POST /api/tls/ca/select
Exemplo:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"builtin"}'
Reinicie o dispositivo após uma resposta bem-sucedida.
Selecionar none para diagnóstico temporário
API:
POST /api/tls/ca/select
Exemplo:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"none"}'
A resposta avisa que a verificação do certificado do servidor está desativada. Reinicie após alterar o modo e volte a builtin ou custom depois do diagnóstico.
Carregar e selecionar uma CA personalizada
Carregar uma CA e selecionar custom são operações separadas. O carregamento não altera automaticamente o modo ativo.
Requisitos do ficheiro de CA personalizada
O ficheiro carregado deve cumprir todos estes requisitos:
- formato de certificado PEM;
- corpo do pedido em bruto, sem JSON nem
multipart/form-data; Content-Type: application/x-pem-file;- comprimento de 1 a 3072 bytes, incluindo cabeçalhos PEM, fins de linha e espaços;
- contém
-----BEGIN CERTIFICATE-----e-----END CERTIFICATE-----; - não contém uma chave privada.
O limite de 3072 bytes aplica-se ao corpo completo do pedido HTTP. Um ficheiro PEM de 3072 bytes é aceite; um de 3073 bytes é rejeitado.
Verifique o tamanho do ficheiro antes de o carregar:
wc -c root-ca.pem
Passo 1: carregar a CA
API:
POST /api/tls/ca/upload
Exemplo:
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
Exemplo de resposta bem-sucedida:
{
"successful": 1,
"length": 1939,
"sha256": "64-character SHA-256 digest",
"message": "CA uploaded; select custom mode and restart"
}
O dispositivo guarda a CA em vários blocos KV e verifica o comprimento e o resumo SHA-256 guardados antes de a marcar como ativa. Uma escrita interrompida não substitui a CA válida anterior.
Passo 2: selecionar custom
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"custom"}'
O dispositivo rejeita este pedido se não houver uma CA personalizada válida guardada. Não muda silenciosamente para none.
Passo 3: reiniciar e verificar
Reinicie na interface Web local ou utilize a API de reinício protegida:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/restart?reset=false"
Depois de o dispositivo voltar a ligar-se, consulte novamente o estado:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Confirme que mode é custom, que customCaValid é 1 e que o comprimento e o resumo SHA-256 correspondem ao certificado carregado.
Eliminar a CA personalizada
API:
POST /api/tls/ca/delete
Exemplo:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/delete"
Eliminar a CA personalizada também repõe o modo builtin. Reinicie o dispositivo após a eliminação.
Utilizar o Swagger UI IAMMETER
Pode testar as mesmas APIs sem escrever manualmente comandos curl:
IAMMETER WEM API Test - TLS CA
- Abra WEM API Test num computador que consiga aceder ao IP local do dispositivo.
- Introduza o endereço, por exemplo
192.168.1.80, e selecione Apply. - Selecione Authorize e introduza o nome de utilizador e a palavra-passe de administrador.
- Abra o grupo TLS CA - Authenticated.
- Utilize
GET /api/tls/ca/statuspara consultar a configuração atual. - Utilize a operação de carregamento, seleção ou eliminação conforme necessário.
- Reinicie após alterar o modo ou o certificado.
A página Swagger funciona no navegador e envia pedidos diretamente desse computador para o dispositivo IAMMETER. Não encaminha os pedidos através do IAMMETER Cloud; o navegador precisa de conectividade direta ao IP do dispositivo.
Resolver problemas de verificação de certificados
admin security required
Ative Local Admin Security antes de utilizar as APIs TLS CA. Estas definições não podem ser alteradas anonimamente.
custom CA is missing or invalid
Carregue com sucesso uma CA PEM válida antes de selecionar custom. Consulte /api/tls/ca/status e confirme que customCaValid é 1.
A ligação TLS falha em builtin ou custom
Verifique todos estes pontos:
- o nome ou IP configurado corresponde ao SAN do certificado;
- o certificado está atualmente válido e a hora do dispositivo está correta;
- o servidor envia os certificados intermédios necessários;
- a CA raiz selecionada emitiu o certificado do servidor ou confia nele através da cadeia;
- o dispositivo foi reiniciado depois da alteração TLS.
TLS funciona em none, mas falha nos modos com verificação
Isto indica normalmente um problema na cadeia de certificados, nome do servidor, período de validade ou relógio do dispositivo. Manter none ativo esconde a falha de autenticação, mas não a resolve. Corrija a instalação do certificado ou carregue a CA raiz adequada e utilize custom.
