Konfigurowanie sieci EAP-TLS w aplikacji
Ważne
Jest to dokumentacja usługi Azure Sphere (starsza wersja). Usługa Azure Sphere (starsza wersja) zostanie wycofana 27 września 2027 r., a użytkownicy muszą przeprowadzić migrację do usługi Azure Sphere (zintegrowanej) do tej pory. Użyj selektora wersji znajdującego się powyżej spisu treści, aby wyświetlić dokumentację usługi Azure Sphere (zintegrowaną).
Protokół EAP-TLS można skonfigurować w aplikacji wysokiego poziomu lub ręcznie przy użyciu poleceń azsphere. Aby skonfigurować sieć i połączyć się z nią, aplikacja używa interfejsów API Certstore i WifiConfig .
Wymagania
Aby skonfigurować sieć protokołu EAP-TLS, aplikacja wysokiego poziomu musi zawierać odpowiednie pliki nagłówków, włączyć wymagane możliwości w manifeście aplikacji i mieć dostęp do certyfikatów wymaganych do uwierzytelniania.
Pliki nagłówkowe
Aplikacja musi zawierać następujący nagłówek:
#include <applibs/wificonfig.h>
Jeśli aplikacja wywołuje interfejs API CertStore w celu zarządzania certyfikatami, musi również zawierać nagłówek CertStore. Ten nagłówek nie jest wymagany do używania funkcji WifiConfig , takich jak WifiConfig_GetRootCACertStoreIdentifier , które pobierają informacje o certyfikacie.
#include <applibs/certstore.h>
Manifest aplikacji
Manifest aplikacji musi włączyć funkcję EnterpriseWiFiConfig, aby skonfigurować sieć protokołu EAP-TLS. Musi również mieć funkcję WifiConfig, aby korzystać z funkcji WifiConfig_*, które nie zarządzają funkcjami protokołu EAP-TLS. Na koniec, jeśli aplikacja zarządza również certyfikatami, musi włączyć funkcję CertStore.
Nie włączaj możliwości, których aplikacja nie wymaga; stanowi to zagrożenie bezpieczeństwa. Jeśli certyfikaty zostaną zaktualizowane ręcznie, nie określ magazynu certyfikatów. Tej funkcji należy używać tylko wtedy, gdy aplikacja jest odpowiedzialna za przechowywanie certyfikatów na urządzeniu i zarządzanie nimi.
W poniższym przykładzie pokazano, jak ustawić wszystkie trzy możliwości w pliku app_manifest.json:
"Capabilities": {
"WifiConfig" : true,
"EnterpriseWiFiConfig" : true,
"CertStore" : true
}
Certyfikaty
Certyfikat klienta urządzenia musi być dostępny na urządzeniu. Ponadto, jeśli sieć EAP-TLS jest skonfigurowana do wzajemnego uwierzytelniania, certyfikat głównego urzędu certyfikacji dla serwera RADIUS sieci musi być również zainstalowany na urządzeniu. Oba certyfikaty muszą mieć format PKCS1 lub PKCS8. Zobacz Uzyskiwanie i wdrażanie certyfikatów protokołu EAP-TLS, aby dowiedzieć się więcej o certyfikatach i poznać ich lokalizację.
Instalowanie certyfikatów
Aby aplikacja mogła skonfigurować sieć protokołu EAP-TLS, musi mieć dostęp do głównego urzędu certyfikacji i certyfikatów klienta do użycia na potrzeby uwierzytelniania. Uzyskiwanie i wdrażanie certyfikatów dla sieci EAP-TLS opisuje strategie uzyskiwania certyfikatów i ładowania ich na urządzenie jako pliki PEM. Pozyskiwanie i wdrażanie certyfikatów jest Twoim obowiązkiem; Aby uzyskać szczegółowe informacje, zapoznaj się z administratorem sieci.
Po zainstalowaniu certyfikatów na urządzeniu aplikacja może je zainstalować do użycia. W przykładzie Certyfikaty pokazano, jak je zainstalować. Poniżej przedstawiono podstawowe kroki:
Upewnij się, że w magazynie certyfikatów jest wystarczająca ilość miejsca. Ilość miejsca w magazynie certyfikatów jest ograniczona, dlatego aplikacja powinna wywoływać CertStore_GetAvailableSpace przed próbą zainstalowania certyfikatu. Jeśli ilość miejsca jest niedostępna, aplikacja powinna usunąć istniejący certyfikat, aby zwolnić miejsce dla nowego. Przestrzeń certyfikatu jest ograniczona do 24 KiB.
Aby zainstalować certyfikat głównego urzędu certyfikacji, wywołaj CertStore_InstallRootCACertificate. Aplikacja dostarcza wskaźnik do zawartości certyfikatu wraz z identyfikatorem, który może później używać jako przyjaznej nazwy certyfikatu. Certyfikat głównego urzędu certyfikacji jest wymagany, jeśli sieć umożliwia wzajemne uwierzytelnianie. Identyfikatory mogą zawierać wielkie litery, małe litery, cyfry 0–9, kropkę (.), łącznik (-) i podkreślenie (_). Maksymalna długość identyfikatora to 16 znaków.
Aby zainstalować certyfikat klienta, wywołaj CertStore_InstallClientCertificate. Podobnie jak w przypadku certyfikatu głównego urzędu certyfikacji aplikacja dostarcza wskaźnik do zawartości certyfikatu wraz z identyfikatorem, którego może użyć później jako przyjaznej nazwy certyfikatu. Aplikacja musi również podać klucz prywatny i, jeśli klucz jest zaszyfrowany, hasło szyfrowania.
Aby zaktualizować certyfikat, aplikacja może użyć funkcji CertStore_MoveCertificate. Ta funkcja przenosi jeden certyfikat do innego, zastępując zawartość istniejącego certyfikatu docelowego zawartością certyfikatu źródłowego. Oba certyfikaty muszą być już zainstalowane w magazynie certyfikatów. Cykl życia certyfikatu i odnawianie przedstawia strategie aktualizowania certyfikatów przy jednoczesnym unikaniu przestojów sieci.
Konfigurowanie i konfigurowanie sieci protokołu EAP-TLS
W przykładzie Wifi_HighLevelApp pokazano , jak tworzyć, konfigurować i włączać sieć protokołu EAP-TLS. W przykładzie przyjęto założenie, że certyfikaty znajdują się już w magazynie certyfikatów, zgodnie z opisem w temacie Instalowanie certyfikatów.
Aby skonfigurować i skonfigurować sieć, aplikacja powinna wykonać następujące podstawowe kroki:
Dodaj sieć, wywołując WifiConfig_AddNetwork. Ta funkcja po prostu tworzy sieć; nie konfiguruje żadnych cech sieci.
Ustaw typ zabezpieczeń dla sieci, wywołując WifiConfig_SetSecurityType. W przypadku sieci EAP-TLS typ zabezpieczeń musi mieć wartość
WifiConfig_Security_Wpa2_EAP_TLS.Ustaw identyfikator SSID dla sieci, wywołując WifiConfig_SetSSID. Jeśli identyfikator SSID nie jest jeszcze znany, aplikacja może ją zeskanować. Jeśli środowisko sieciowe może być hałaśliwe lub jeśli identyfikator SSID może nie być emitowany, aplikacja powinna włączyć ukierunkowane skanowanie przez wywołanie WifiConfig_SetTargetedScanEnabled. Następnie może wywołać WifiConfig_TriggerScanAndGetScannedNetworkCount, aby wyszukać wszystkie sieci i WifiConfig_GetScannedNetworks, aby uzyskać wyniki skanowania. WifiConfig_GetScannedNetworks zwraca tablicę struktur, które zawierają szczegółowe informacje o każdej sieci. Aplikacja może wyszukać wyniki dla sieci z typem zabezpieczeń
WifiConfig_Security_Wpa2_EAP_TLS, a następnie pobrać jego identyfikator SSID.Ustaw nazwę konfiguracji dla sieci, wywołując WifiConfig_SetConfigName. Nazwa konfiguracji to przyjazna nazwa, która może być używana przez aplikację do identyfikowania tej konfiguracji sieci.
Ustaw nazwę certyfikatu głównego urzędu certyfikacji dla serwera RADIUS, wywołując WifiConfig_SetRootCACertStoreIdentifier, jeśli sieć wymaga uwierzytelniania serwera. Certyfikat głównego urzędu certyfikacji musi być już obecny na urządzeniu.
Ustaw nazwę magazynu certyfikatów klienta, wywołując WifiConfig_SetClientCertStoreIdentifier. Certyfikat klienta musi być już obecny na urządzeniu.
Ustaw tożsamość klienta przez wywołanie WifiConfig_SetClientIdentity. Tożsamość klienta jest przyjazną nazwą identyfikującą urządzenie klienckie.
Włącz sieć, wywołując WifiConfig_SetNetworkEnabled.
Zapisz konfigurację sieci, wywołując WifiConfig_PersistConfig. Ta funkcja zapisuje konfigurację sieci na urządzeniu, dzięki czemu będzie się powtarzać po ponownym uruchomieniu.
Zmienianie właściwości sieci EAP-TLS
Aplikacja może zmienić właściwości sieci, wywołując te same funkcje, które zostały pierwotnie ustawione, zgodnie z opisem w temacie Konfigurowanie i konfigurowanie sieci protokołu EAP-TLS.
Po zmianie właściwości aplikacja musi nie tylko wywołać WifiConfig_PersistConfig, aby zapisać konfigurację, ale także wywołać WifiConfig_ReloadConfig, aby natychmiast zaktualizować sieć. Jest to szczególnie ważne, gdy aplikacja aktualizuje certyfikat.
Usuwanie sieci EAP-TLS
Aplikacja może usunąć sieć, wywołując WifiConfig_ForgetNetworkById lub WifiConfig_ForgetAllNetworks.
WifiConfig_ForgetNetworkById rozłącza sieć, jeśli jest połączona i usuwa ją z urządzenia. Nie aktualizuje jednak konfiguracji sieci Wi-Fi, więc zmiana nie jest utrwalana podczas ponownego uruchamiania. Aplikacja musi wywołać WifiConfig_PersistConfig , aby usunięcie było trwałe.
WifiConfig_ForgetAllNetworks rozłącza połączoną sieć i usuwa wszystkie sieci z urządzenia. Ta zmiana będzie się powtarzać po ponownym uruchomieniu.
Przykłady
- Aplikacja wysokiego poziomu certyfikatów — pokazuje, jak używać certyfikatów i zarządzać nimi w aplikacji wysokiego poziomu usługi Azure Sphere.
- Wifi_HighLevelApp — pokazuje, jak nawiązać połączenie z siecią Wi-Fi i sprawdzić stan sieci na urządzeniu MT3620.
Uwaga
Poniższy przykład pochodzi z galerii usługi Azure Sphere, która jest kolekcją niezamierzonych przykładów oprogramowania i sprzętu firmy Microsoft. Aby uzyskać więcej informacji, zobacz Galeria usługi Azure Sphere.