Konfigurowanie weryfikacji certyfikatów MQTTS i HTTPS w liczniku IAMMETER
Liczniki IAMMETER z oprogramowaniem i.91.065.9 lub nowszym mogą weryfikować certyfikat serwera podczas wysyłania danych przez MQTTS lub HTTPS. Funkcja ta dodaje weryfikację łańcucha certyfikatów i nazwy hosta serwera do bezpiecznych połączeń wychodzących.
Ten artykuł dotyczy konfiguracji zaufania TLS. Nie opisuje konfiguracji tematów MQTT, danych JSON ani wykrywania Home Assistant. Informacje o publikowaniu przez MQTT zawiera artykuł Licznik MQTT: publikowanie danych IAMMETER na własnym brokerze MQTT.
Na tej stronie
- Wybór trybu weryfikacji certyfikatów
- Wymagania i ważne ograniczenia
- Sprawdzanie bieżącego trybu TLS
- Wybór weryfikacji builtin
- Wybór none do tymczasowej diagnostyki
- Przesyłanie i wybór własnego CA
- Usuwanie własnego CA
- Korzystanie ze Swagger UI IAMMETER
- Rozwiązywanie problemów z weryfikacją certyfikatów
Wybór trybu weryfikacji certyfikatów
Klienci MQTTS i HTTPS w IAMMETER obsługują trzy tryby weryfikacji certyfikatu serwera:
| Tryb | Łańcuch certyfikatów | Nazwa hosta serwera | Zastosowanie |
|---|---|---|---|
builtin |
Weryfikowany przy użyciu głównych CA wbudowanych w oprogramowanie | Weryfikowana | Zalecany dla usług publicznych z obsługiwanym łańcuchem certyfikatów |
custom |
Weryfikowany przy użyciu głównego CA w formacie PEM dostarczonego przez użytkownika | Weryfikowana | Prywatna PKI, wdrożenia z certyfikatem samopodpisanym lub publiczne CA nieobecne w oprogramowaniu |
none |
Nieweryfikowany | Nieweryfikowana | Wyłącznie zgodność lub tymczasowa diagnostyka |
Ustawienia dotyczą sytuacji, gdy urządzenie IAMMETER działa jako klient TLS i wysyła dane do brokera MQTTS lub serwera HTTPS. Nie włączają HTTPS na lokalnym serwerze WWW urządzenia.
builtin
builtin to tryb domyślny. Obowiązuje, gdy nie zapisano ustawienia weryfikacji TLS, a także jest przywracany po usunięciu konfiguracji TLS CA lub przywróceniu ustawień fabrycznych urządzenia.
Oprogramowanie zawiera następujące główne CA:
- DigiCert Global Root G2
- ISRG Root X1
Urządzenie weryfikuje łańcuch certyfikatów i nazwę hosta serwera. Broker MQTTS lub serwer HTTPS musi przedstawić certyfikat, którego łańcuch prowadzi do jednego z tych głównych CA, a pole Subject Alternative Name (SAN) musi odpowiadać skonfigurowanemu adresowi serwera.
Jeśli adresem docelowym jest adres IP, SAN certyfikatu musi zawierać dokładnie ten adres IP. Nazwa DNS nie jest zgodna z adresem IP, nawet jeśli oba wskazują ten sam serwer.
custom
custom przeprowadza taką samą weryfikację łańcucha i nazwy hosta jak builtin, ale ufa certyfikatowi CA PEM przesłanemu przez administratora. Użyj go, gdy:
- certyfikat serwera został wydany przez prywatny CA;
- wdrożenie korzysta z samopodpisanego certyfikatu serwera; lub
- wymagany publiczny główny CA nie jest wbudowany w oprogramowanie.
W przypadku prywatnej PKI prześlij jej certyfikat główny. Serwer TLS nadal musi wysyłać wymagane certyfikaty pośrednie podczas uzgadniania połączenia. Samopodpisany certyfikat serwera można przesłać jako kotwicę zaufania, ale jego SAN nadal musi odpowiadać skonfigurowanej nazwie hosta lub adresowi IP.
none
none nadal tworzy szyfrowane połączenie TLS, ale nie weryfikuje łańcucha certyfikatów ani nazwy hosta. Jest to podobne do wcześniejszego działania TLS bez uwierzytelniania serwera.
Ten tryb jest podatny na ataki typu man-in-the-middle. Używaj go tylko tymczasowo w celu zapewnienia zgodności lub diagnostyki. W środowisku produkcyjnym wybierz builtin lub custom.
Wymagania i ważne ograniczenia
Interfejsy API konfiguracji TLS CA wymagają włączenia Local Admin Security. Każde żądanie musi zawierać skonfigurowaną nazwę użytkownika i hasło administratora przekazane przez HTTP Basic Authentication.
Komputer z curl lub Swagger UI musi mieć dostęp do lokalnego adresu IP urządzenia. Klienci MQTTS i HTTPS współdzielą jeden tryb weryfikacji i jeden własny CA, więc zmiana dotyczy używanego przez urządzenie trybu bezpiecznego wysyłania danych.
Po zmianie konfiguracji TLS uruchom urządzenie ponownie, aby odtworzyć klienta wychodzącego z nowymi ustawieniami.
W przykładach użyto następujących wartości zastępczych:
DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"
Zastąp je rzeczywistym adresem urządzenia i danymi logowania administratora.
Sprawdzanie bieżącego trybu TLS
API:
GET /api/tls/ca/status
Przykład:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Przykładowa odpowiedź:
{
"successful": 1,
"mode": "builtin",
"customCaValid": 0,
"customCaLength": 0,
"customCaSha256": "",
"restartRequiredAfterChange": 1
}
Odpowiedź pokazuje wybrany tryb oraz długość i skrót SHA-256 własnego CA, jeśli został zapisany.
Wybór weryfikacji builtin
API:
POST /api/tls/ca/select
Przykład:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"builtin"}'
Po otrzymaniu odpowiedzi potwierdzającej powodzenie uruchom urządzenie ponownie.
Wybór none do tymczasowej diagnostyki
API:
POST /api/tls/ca/select
Przykład:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"none"}'
Odpowiedź ostrzega, że weryfikacja certyfikatu serwera jest wyłączona. Po zmianie trybu uruchom urządzenie ponownie, a po zakończeniu diagnostyki wróć do builtin lub custom.
Przesyłanie i wybór własnego CA
Przesłanie CA i wybór custom to osobne operacje. Przesłanie CA nie przełącza automatycznie aktywnego trybu.
Wymagania dotyczące pliku własnego CA
Przesyłany plik musi spełniać wszystkie poniższe wymagania:
- format certyfikatu PEM;
- surowa treść żądania, nie JSON ani
multipart/form-data; Content-Type: application/x-pem-file;- długość od 1 do 3072 bajtów, łącznie z nagłówkami PEM, znakami końca wiersza i białymi znakami;
- obecność
-----BEGIN CERTIFICATE-----i-----END CERTIFICATE-----; - brak klucza prywatnego.
Limit 3072 bajtów dotyczy całej treści żądania HTTP. Plik PEM o rozmiarze 3072 bajtów jest akceptowany; plik o rozmiarze 3073 bajtów jest odrzucany.
Sprawdź rozmiar pliku przed przesłaniem:
wc -c root-ca.pem
Krok 1: prześlij CA
API:
POST /api/tls/ca/upload
Przykład:
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
Przykładowa odpowiedź potwierdzająca powodzenie:
{
"successful": 1,
"length": 1939,
"sha256": "64-character SHA-256 digest",
"message": "CA uploaded; select custom mode and restart"
}
Urządzenie zapisuje CA w kilku blokach KV i sprawdza zapisaną długość oraz skrót SHA-256 przed oznaczeniem go jako aktywnego. Przerwanie zapisu nie zastępuje poprzedniego prawidłowego CA.
Krok 2: wybierz custom
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"custom"}'
Urządzenie odrzuca to żądanie, jeśli nie zapisano prawidłowego własnego CA. Nie przełącza się automatycznie na none bez powiadomienia.
Krok 3: uruchom ponownie i sprawdź
Uruchom urządzenie ponownie z lokalnego interfejsu WWW lub użyj chronionego API restartu:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/restart?reset=false"
Po ponownym połączeniu urządzenia jeszcze raz odczytaj stan:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
Sprawdź, czy mode ma wartość custom, customCaValid ma wartość 1, a długość i skrót SHA-256 odpowiadają przesłanemu certyfikatowi.
Usuwanie własnego CA
API:
POST /api/tls/ca/delete
Przykład:
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/delete"
Usunięcie własnego CA przywraca również tryb builtin. Po usunięciu uruchom urządzenie ponownie.
Korzystanie ze Swagger UI IAMMETER
Te same API można przetestować bez ręcznego pisania poleceń curl:
IAMMETER WEM API Test - TLS CA
- Otwórz stronę WEM API Test na komputerze mającym dostęp do lokalnego adresu IP urządzenia.
- Wprowadź adres urządzenia, na przykład
192.168.1.80, i wybierz Apply. - Wybierz Authorize i podaj nazwę użytkownika oraz hasło administratora.
- Otwórz grupę TLS CA - Authenticated.
- Użyj
GET /api/tls/ca/status, aby sprawdzić bieżącą konfigurację. - W razie potrzeby użyj operacji przesyłania, wyboru lub usuwania.
- Po zmianie trybu lub certyfikatu uruchom urządzenie ponownie.
Strona Swagger działa w przeglądarce i wysyła żądania bezpośrednio z tego komputera do urządzenia IAMMETER. Nie przekazuje żądań przez IAMMETER Cloud, dlatego przeglądarka musi mieć bezpośredni dostęp sieciowy do adresu IP urządzenia.
Rozwiązywanie problemów z weryfikacją certyfikatów
admin security required
Włącz Local Admin Security przed użyciem API TLS CA. Tych ustawień nie można zmieniać anonimowo.
custom CA is missing or invalid
Przed wyborem custom pomyślnie prześlij prawidłowy CA w formacie PEM. Odczytaj /api/tls/ca/status i potwierdź, że customCaValid wynosi 1.
Połączenie TLS nie działa w trybie builtin lub custom
Sprawdź wszystkie poniższe punkty:
- skonfigurowana nazwa hosta lub adres IP odpowiada polu SAN certyfikatu;
- certyfikat jest obecnie ważny, a zegar urządzenia jest ustawiony prawidłowo;
- serwer wysyła wymagane certyfikaty pośrednie;
- wybrany główny CA wydał certyfikat serwera lub stanowi jego ostateczne źródło zaufania w łańcuchu;
- urządzenie zostało ponownie uruchomione po zmianie TLS.
TLS działa z none, ale nie działa z weryfikacją
Zwykle wskazuje to na problem z łańcuchem certyfikatów, nazwą hosta, okresem ważności lub zegarem urządzenia. Pozostawienie none ukrywa błąd uwierzytelniania, lecz go nie naprawia. Popraw wdrożenie certyfikatu lub prześlij właściwy główny CA i użyj custom.
