Local Admin Security: Podręcznik użytkownika

Local Admin Security: Podręcznik użytkownika

Moduł Local Admin Security jest dostępny w oprogramowaniu sprzętowym i.91.065.3 i nowszym.

Cel

Moduł Local Admin Security chroni lokalny interfejs Web UI urządzenia oraz wrażliwe lokalne API przed nieautoryzowanym dostępem.

Po włączeniu tej funkcji, nazwa użytkownika i hasło administratora są wymagane dla:

• wszystkich Set API dostępnych na stronie WEM API Test;
• GET API, które zwracają wrażliwe dane konfiguracyjne lub wykonują wrażliwe operacje;
• lokalnych operacji przesyłania i aktualizacji oprogramowania sprzętowego OTA.

Obejmuje to operacje takie jak zmiana ustawień sieciowych lub wysyłania, aktualizacja oprogramowania sprzętowego, restart urządzenia, przywracanie ustawień fabrycznych oraz modyfikacja innych wrażliwych parametrów konfiguracyjnych.

Moduł zapewnia:

• konfigurowalne dane logowania administratora;
• HTTP Basic Authentication dla chronionych lokalnych API;
• możliwość zmiany danych logowania przez Web UI lub API;
• proces odzyskiwania oparty na podpisie Ed25519 na wypadek zapomnienia hasła administratora.

Funkcja jest domyślnie wyłączona dla zachowania zgodności z wcześniejszym oprogramowaniem sprzętowym. Musi zostać włączona i skonfigurowana, zanim chroniony dostęp zacznie obowiązywać.

Obecny lokalny interfejs Web UI korzysta z HTTP. HTTP Basic Authentication koduje dane logowania, ale ich nie szyfruje. Używaj tej funkcji w zaufanej sieci lokalnej, chyba że urządzenie jest dostępne przez dodatkowy bezpieczny mechanizm transportowy.

Konfiguracja Admin Security w Web UI

1. Otwórz adres IP urządzenia w przeglądarce.
2. Wybierz zakładkę Security.
3. Wprowadź nazwę użytkownika administratora.
4. Wprowadź i potwierdź hasło administratora.
5. Wybierz Enable Admin Security.

Nazwa użytkownika i hasło muszą spełniać następujące zasady:

• długość: od 1 do 32 znaków;
• tylko widoczne znaki ASCII;
• dwukropek (:), cudzysłów (") lub odwrotny ukośnik (\) są niedozwolone.

Po włączeniu Admin Security przeglądarka wyświetli monit uwierzytelniania przy dostępie do chronionej strony lub API. Wprowadź skonfigurowaną nazwę użytkownika i hasło administratora.

Zakładka Security może być również używana do:

• zmiany nazwy użytkownika i hasła administratora;
• weryfikacji, czy uwierzytelnianie administratora jest włączone;
• włączania lub wyłączania usługi Modbus/TCP na porcie 502;
• włączania lub wyłączania wykrywania SSDP;
• wyłączania Admin Security po uwierzytelnieniu bieżącymi danymi logowania.

Zmiany stanu usługi Modbus/TCP lub SSDP wymagają restartu urządzenia. Jeśli te ustawienia nie były wcześniej zapisane przez starsze oprogramowanie sprzętowe, obie usługi domyślnie są włączone dla zachowania wstecznej zgodności.

Przeglądarki mogą buforować dane logowania Basic Authentication dla adresu urządzenia. Po zmianie hasła przeglądarka może najpierw spróbować użyć starych danych logowania, a następnie wyświetlić nowy monit uwierzytelniania. Zamknięcie wszystkich okien przeglądarki lub użycie okna prywatnego może również wymusić nowe logowanie.

API, które nie wymagają Basic Authentication

Następujące endpointy pozostają dostępne bez nagłówka Basic Authentication, aby interfejs Web UI mógł załadować podstawowe informacje o urządzeniu, a proces odzyskiwania z podpisem mógł działać:

POST /api/admin/enable jest również wywoływalne bez Basic Authentication, gdy Admin Security jest aktualnie wyłączone, ponieważ jest to endpoint używany do początkowej konfiguracji. Jeśli Admin Security jest już włączone, wymagane są aktualne ważne dane logowania administratora, zanim ten endpoint będzie mógł zmienić lub wyłączyć konfigurację zabezpieczeń.

Statyczne pliki Web UI oraz inne zasoby GET niebędące /api/ pozostają publicznie dostępne. Wszystkie inne lokalne endpointy API są traktowane jako chronione, gdy Admin Security jest włączone, w tym wszystkie Set API, wrażliwe GET API oraz operacje OTA.

API Reference

GET /api/admin/status

Zwraca bieżący stan Admin Security. Uwierzytelnianie nie jest wymagane.

Przykładowa odpowiedź:

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

Pola:

• enabled: 1 gdy Admin Security jest włączone; w przeciwnym razie 0.
• hasPassword: 1 gdy dane logowania administratora zostały skonfigurowane.
• recoverySupported: 1 gdy odzyskiwanie administratora z podpisem jest obsługiwane przez oprogramowanie sprzętowe.
• modbusTcpEnabled: 1 gdy usługa Modbus/TCP na porcie 502 jest włączona.
• ssdpEnabled: 1 gdy wykrywanie SSDP jest włączone.

POST /api/admin/enable

Włącza lub wyłącza Admin Security.

Włączenie Admin Security:

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

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

Przykład z curl:

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

Wyłączenie Admin Security:

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

{
  "enable": 0
}

Jeśli Admin Security jest już włączone, do wywołania tego API wymagane są aktualne ważne dane logowania Basic Authentication.

Przykład:

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

POST /api/admin/password

Zmienia nazwę użytkownika i hasło administratora. To API jest chronione po włączeniu Admin Security.

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

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

Przykład:

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

Po pomyślnym wykonaniu żądania, używaj nowych danych logowania do kolejnych chronionych żądań.

GET /api/admin/check

Sprawdza, czy podane dane logowania Basic Authentication są prawidłowe.

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

Pomyślna odpowiedź:

{
  "successful": 1
}

Brakujące lub nieprawidłowe dane logowania skutkują odpowiedzią HTTP 401 Unauthorized.

GET /api/admin/recovery_challenge

Tworzy jednorazowy ładunek odzyskiwania specyficzny dla urządzenia. Uwierzytelnianie nie jest wymagane, ponieważ ten endpoint sam w sobie nie resetuje danych logowania.

Przykładowa odpowiedź:

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

Zwrócony payload musi zostać wysłany do IAMMETER w celu odzyskania dostępu administratora.

Żądanie nowego challenge'a unieważnia poprzedni challenge. Challenge jest również unieważniany po pomyślnym odzyskaniu dostępu lub restarcie urządzenia.

POST /api/admin/recovery

Przesyła ładunek odzyskiwania oraz podpis Ed25519 dostarczony przez IAMMETER.

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

{
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE",
  "signature": "128-znakowy-podpis-ed25519"
}

Przykład:

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":"<podpis-z-IAMMETER>"}'

Jeśli weryfikacja podpisu powiedzie się, urządzenie czyści lokalne dane logowania administratora i wyłącza Admin Security. Można wtedy skonfigurować nową nazwę użytkownika i hasło administratora.

Jeśli urządzenie nie ma wystarczającej ilości wolnej pamięci do przeprowadzenia weryfikacji podpisu, API zwraca odpowiedź podobną do:

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

W takim przypadku zmniejsz użycie pamięci i poproś o nowy challenge odzyskiwania przed ponowną próbą. Jeśli hasło jest niedostępne, a tryb pracy nie może zostać zmieniony, uruchom ponownie urządzenie i przeprowadź odzyskiwanie, zanim połączenie MQTTS lub HTTPS zużyje dodatkową pamięć.

Jak działa odzyskiwanie hasła

Projekt odzyskiwania unika dodawania nieuwierzytelnionego polecenia resetowania fabrycznego, które mogłoby ominąć ochronę administratora.

Proces wykorzystuje parę kluczy publiczny/prywatny Ed25519:

• oprogramowanie sprzętowe urządzenia zawiera tylko publiczny klucz odzyskiwania IAMMETER;
• odpowiadający mu klucz prywatny jest przechowywany przez IAMMETER i nie jest zapisany na urządzeniu;
• urządzenie tworzy ładunek zawierający żądaną operację, numer seryjny (SN) urządzenia, adres MAC urządzenia oraz jednorazowy nonce;
• IAMMETER podpisuje ten dokładny ładunek prywatnym kluczem odzyskiwania;
• urządzenie weryfikuje podpis za pomocą wbudowanego klucza publicznego;
• tylko ważny podpis dla bieżącego urządzenia i bieżącego nonce może wyczyścić konfigurację administratora.

Nonce jest przechowywany tylko w pamięci RAM. Staje się nieważny po restarcie urządzenia, po zażądaniu innego challenge'a lub po jednym pomyślnym odzyskaniu dostępu. Dlatego stary ładunek i podpis nie mogą być ponownie użyte do późniejszej sesji odzyskiwania.

Scenariusze użycia

Scenariusz 1: Ustawienie nazwy użytkownika i hasła administratora

Najprostszą metodą jest Web UI:

1. Otwórz http://<device-ip>/.
2. Otwórz zakładkę Security.
3. Wprowadź nową nazwę użytkownika i hasło administratora.
4. Potwierdź hasło.
5. Włącz Admin Security.

Tę samą operację można wykonać przez 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"}'

Zweryfikuj wynik:

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

Scenariusz 2: Dostęp do chronionych API z Basic Authentication

Dla każdego kolejnego chronionego żądania wyślij nazwę użytkownika i hasło administratora w nagłówku HTTP Basic Authentication.

Wartość nagłówka jest konstruowana w następujący sposób:

Authorization: Basic Base64...

Na przykład dane logowania admin:ExamplePassword są najpierw łączone, a następnie kodowane Base64. Większość klientów HTTP wykonuje to automatycznie.

Używając curl:

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

Używając jawnego nagłówka:

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

curl "http://<device-ip>/api/getadv" \
  -H "Authorization: Basic ***"

Dla żądania JSON POST:

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

Przeglądarka obsługuje ten nagłówek automatycznie po wprowadzeniu przez administratora danych logowania w monicie Basic Authentication.

Obecny Web UI przesyła oprogramowanie sprzętowe do POST /api/ota_successful.html. Starszy endpoint POST /ota_successful.html pozostaje dostępny dla starszych wersji Web UI i narzędzi zewnętrznych. Oba endpointy wymagają Basic Authentication, gdy Admin Security jest włączone.

Zakładki Web UI zachowują się następująco po zamknięciu monitu uwierzytelniania:

• Settings i Wi-Fi nie mogą załadować swoich chronionych API konfiguracyjnych i wyświetlają komunikat o uwierzytelnianiu administratora.
• System może nadal wyświetlić SN, MAC i wersję oprogramowania sprzętowego, ponieważ te wartości zostały pobrane z publicznego endpointu /api/monitor. Przesyłanie OTA pozostaje chronione.
• Security może nadal wyświetlić podstawowy stan, ponieważ /api/admin/status jest publiczny. Zmiany danych logowania i przełączników usług pozostają chronione.

Scenariusz 3: Odzyskanie dostępu po zapomnieniu hasła

Urządzenie nie ma sprzętowego przycisku resetowania. Aby uniknąć dodania nieuwierzytelnionej funkcji resetowania, która mogłaby ominąć Admin Security, urządzenie korzysta z mechanizmu odzyskiwania z podpisem opisanego powyżej.

Ta procedura jest przeznaczona wyłącznie dla przypadków, gdy zarówno nazwa użytkownika, jak i hasło administratora zostały zapomniane. Przechowuj skonfigurowane dane logowania w bezpiecznym miejscu i unikaj polegania na procesie odzyskiwania w przypadku rutynowych zmian danych logowania. Jeśli bieżące dane logowania są nadal dostępne, zmień je bezpośrednio z zakładki Security lub za pomocą POST /api/admin/password.

1. Poproś o nowy challenge odzyskiwania z urządzenia:

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

2. Skopiuj całą wartość payload z odpowiedzi. Nie edytuj SN, MAC, nonce, separatorów ani wielkości liter.

3. Skontaktuj się z pomocą techniczną IAMMETER na adres support@devicebit.com i prześlij kompletny ładunek.

4. Po potwierdzeniu własności lub autoryzacji usługi, IAMMETER podpisuje ładunek i zwraca podpis Ed25519.

5. Prześlij oryginalny ładunek i zwrócony podpis do urządzenia:

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

6. Po pomyślnej odpowiedzi Admin Security zostaje wyłączone, a poprzednie dane logowania administratora są usuwane. Otwórz zakładkę Security lub wywołaj POST /api/admin/enable, aby ustawić nowe dane logowania.

Nie restartuj urządzenia ani nie żądaj kolejnego challenge'a podczas oczekiwania na podpis. Każda z tych czynności unieważnia przesłany ładunek, a proces odzyskiwania musi zostać rozpoczęty od nowa z nowym challenge'em.