Udostępnij za pośrednictwem

Konfigurowanie sieci EAP-TLS w aplikacji

  • Artykuł

Za pomocą az sphere poleceń można skonfigurować protokół EAP-TLS w aplikacji wysokiego poziomu lub ręcznie. Aby skonfigurować sieć i nawiązać z nią połączenie, aplikacja korzysta z interfejsów API Certstore i WifiConfig .

Wymagania

Aby skonfigurować sieć EAP-TLS, aplikacja wysokiego poziomu musi zawierać odpowiednie pliki nagłówków, włączyć wymagane funkcje w swoim manifeście aplikacji i mieć dostęp do certyfikatów wymaganych do uwierzytelniania.

Pliki nagłówków

Aplikacja musi zawierać następujący nagłówek:

#include <applibs/wificonfig.h>

Jeśli aplikacja wywołuje interfejs API CertStore do zarządzania certyfikatami, musi również zawierać nagłówek CertStore. Ten nagłówek nie jest wymagany do korzystania z funkcji WifiConfig , takich jak WifiConfig_GetRootCACertStoreIdentifier pobierające informacje o certyfikatach.

#include <applibs/certstore.h>

Manifest aplikacji

Manifest aplikacji musi włączyć funkcję EnterpriseWiFiConfig w celu skonfigurowania sieci EAP-TLS. Musi również mieć możliwość WifiConfig do korzystania z funkcji WifiConfig_*, które nie zarządzają funkcjami EAP-TLS. Na koniec, jeśli aplikacja również zarządza certyfikatami, musi włączyć funkcję CertStore.

Nie włączaj funkcji, których aplikacja nie wymaga. stanowi to zagrożenie dla bezpieczeństwa. Jeśli certyfikaty zostaną zaktualizowane ręcznie, nie należy określać certStore. 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 funkcje 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, na urządzeniu musi być również zainstalowany certyfikat głównego urzędu certyfikacji serwera RADIUS twojej sieci. Oba certyfikaty muszą mieć format pem — PKCS1 lub PKCS8. Zobacz Uzyskiwanie i wdrażanie certyfikatów EAP-TLS , aby dowiedzieć się więcej o certyfikatach i o tym, gdzie je uzyskać.

Instalowanie certyfikatów

Zanim aplikacja będzie mogła skonfigurować sieć EAP-TLS, musi mieć dostęp do głównego urzędu certyfikacji i certyfikatów klienta, aby można było używać jej do uwierzytelniania. Uzyskiwanie i wdrażanie certyfikatów dla sieci EAP-TLS opisuje strategie uzyskiwania certyfikatów i ładowania ich na urządzeniu jako pliki PEM. Za uzyskiwanie i wdrażanie certyfikatów odpowiada twoja odpowiedzialność; skontaktuj się z administratorem sieci, aby uzyskać szczegółowe informacje.

Po zainstalowaniu certyfikatów na urządzeniu aplikacja może je zainstalować do użycia. W przykładzie certyfikatów pokazano, jak je zainstalować. Poniżej przedstawiono podstawowe kroki:

  • Upewnij się, że w magazynie certyfikatów jest wystarczająca ilość miejsca. Miejsce w magazynie certyfikatów jest ograniczone, więc aplikacja powinna wywołać CertStore_GetAvailableSpace przed próbą zainstalowania certyfikatu. Jeśli nie ma wystarczającej ilości miejsca, aplikacja powinna usunąć istniejący certyfikat, aby zwolnić miejsce dla nowego certyfikatu. Ilość miejsca na certyfikatach 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 być później używany jako przyjazna nazwa 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 od 0 do 9, kropkę (.), łącznik (-) i podkreślenie (_). Maksymalna długość identyfikatora wynosi 16 znaków.

  • Aby zainstalować certyfikat klienta, zadzwoń do 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żywać 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ą już być zainstalowane w magazynie certyfikatów. Cykl życia certyfikatów i odnawianie określa strategie aktualizacji certyfikatów, unikając przestojów w sieci.

Konfigurowanie i konfigurowanie sieci EAP-TLS

Przykład Wifi_HighLevelApp pokazuje, jak utworzyć, skonfigurować i włączyć sieć EAP-TLS. W przykładzie założono, ż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 czynności:

  • Dodaj sieć, dzwoniąc do WifiConfig_AddNetwork. Ta funkcja po prostu tworzy sieć; nie konfiguruje żadnych cech sieci.

  • Ustaw typ zabezpieczeń sieci, dzwoniąc do WifiConfig_SetSecurityType. W przypadku sieci EAP-TLS typ zabezpieczeń musi mieć wartość WifiConfig_Security_Wpa2_EAP_TLS.

  • Ustaw identyfikator SSID sieci, dzwoniąc do WifiConfig_SetSSID. Jeśli identyfikator SSID nie jest jeszcze znany, aplikacja może go przeskanować. Jeśli środowisko sieciowe może być głośne lub identyfikator SSID może nie być emitowany, aplikacja powinna włączyć skanowanie kierowane, wywołując WifiConfig_SetTargetedScanEnabled. Następnie może zadzwonić do WifiConfig_TriggerScanAndGetScannedNetworkCount , aby wykonać skanowanie w poszukiwaniu wszystkich sieci i WifiConfig_GetScannedNetworks , aby uzyskać wyniki skanowania. WifiConfig_GetScannedNetworks zwraca tablicę struktur zawierających szczegóły dotyczące każdej sieci. Aplikacja może wyszukać wyniki dla sieci o typie WifiConfig_Security_Wpa2_EAP_TLS zabezpieczeń, a następnie pobrać identyfikator SSID.

  • Ustaw nazwę konfiguracji sieci, dzwoniąc do WifiConfig_SetConfigName. Nazwa konfiguracji to przyjazna nazwa, za pomocą których aplikacja może identyfikować tę konfigurację 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 już być obecny na urządzeniu.

  • Ustaw nazwę magazynu certyfikatów klienta, dzwoniąc do WifiConfig_SetClientCertStoreIdentifier. Certyfikat klienta musi już być obecny na urządzeniu.

  • Ustaw tożsamość klienta, wywołując WifiConfig_SetClientIdentity. Tożsamość klienta to przyjazna nazwa identyfikująca urządzenie klienckie.

  • Włącz sieć, dzwoniąc do WifiConfig_SetNetworkEnabled.

  • Zapisz konfigurację sieci, dzwoniąc do WifiConfig_PersistConfig. Ta funkcja zapisuje konfigurację sieci na urządzeniu, dzięki czemu jest zachowywana podczas ponownego uruchamiania.

Zmienianie właściwości sieci EAP-TLS

Aplikacja może zmieniać właściwości sieci, wywołując te same funkcje, które zostały użyte do ich pierwotnego ustawienia, jak wymieniono w temacie Konfigurowanie i konfigurowanie sieci EAP-TLS.

Po zmianie właściwości aplikacja musi nie tylko wywołać WifiConfig_PersistConfig , aby zapisać konfigurację, ale także musi 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ć, dzwoniąc do WifiConfig_ForgetNetworkById lub WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById odłącza sieć, jeśli jest podłączona, i usuwa ją z urządzenia. Nie aktualizuje ona jednak konfiguracji Wi-Fi, więc zmiana nie jest zachowywana podczas ponownego uruchamiania. Aplikacja musi zadzwonić do WifiConfig_PersistConfig , aby trwale usunąć.

WifiConfig_ForgetAllNetworks odłącza połączoną sieć i usuwa wszystkie sieci z urządzenia. Ta zmiana będzie się powtarzać podczas ponownego uruchamiania.

Próbki

Uwaga

Poniższa próbka pochodzi z galerii Azure Sphere Gallery, która jest kolekcją nieupoczętowanych próbek oprogramowania i sprzętu firmy Microsoft. Aby uzyskać więcej informacji, zobacz Azure Sphere Gallery.