Dela via

Konfigurera EAP-TLS-nätverk i en app

  • Artikel

Du kan konfigurera en EAP-TLS i ett program på hög nivå eller manuellt med azsfärkommandon. För att konfigurera och ansluta till nätverket använder ett program API:erna Certstore och WifiConfig .

Krav

Om du vill konfigurera ett EAP-TLS-nätverk måste den högnivåappen innehålla rätt huvudfiler, aktivera de nödvändiga funktionerna i programmanifestet och ha åtkomst till de certifikat som krävs för autentisering.

Sidhuvudfiler

Appen måste innehålla följande sidhuvud:

#include <applibs/wificonfig.h>

Om programmet anropar CertStore-API:et för att hantera certifikat måste det även innehålla CertStore-huvudet. Det här huvudet krävs inte för att använda WifiConfig-funktionerna , till exempel WifiConfig_GetRootCACertStoreIdentifier som hämtar certifikatinformation.

#include <applibs/certstore.h>

Programmanifest

Programmanifestet måste aktivera EnterpriseWiFiConfig-funktionen för att konfigurera ett EAP-TLS-nätverk. Den måste också ha WifiConfig-funktionen för att kunna använda WifiConfig_* funktioner som inte hanterar EAP-TLS-funktioner. Om appen även hanterar certifikat måste den aktivera CertStore-funktionen.

Aktivera inte funktioner som programmet inte kräver. detta utgör en säkerhetsrisk. Om certifikaten uppdateras manuellt ska du inte ange CertStore. Använd endast den här funktionen om programmet ansvarar för att lagra och hantera certifikat på enheten.

I följande exempel visas hur du ställer in alla tre funktionerna i filen app_manifest.json:

"Capabilities": {
        "WifiConfig" : true,
        "EnterpriseWiFiConfig" : true,
        "CertStore" : true
    }

Certifikat

Klientcertifikatet för din enhet måste vara tillgängligt på enheten. Om EAP-TLS-nätverket har konfigurerats för ömsesidig autentisering måste dessutom rotcertifikatutfärdarcertifikatet för nätverkets RADIUS-server installeras på enheten. Båda certifikaten måste vara i PEM-format, antingen PKCS1 eller PKCS8. I EAP-TLS-certifikathämtning och -distribution finns mer information om certifikaten och var du hämtar dem.

Installera certifikat

Innan appen kan konfigurera ett EAP-TLS-nätverk måste den ha åtkomst till rotcertifikatutfärdaren och klientcertifikaten för autentisering. Hämta och distribuera certifikat för EAP-TLS-nätverk beskriver strategier för att skaffa certifikat och läsa in dem på en enhet som PEM-filer. Förvärv och distribution av certifikat är ditt ansvar; Kontakta nätverksadministratören om du vill ha mer information.

När certifikaten finns på enheten kan ett program installera dem för användning. I exemplet Certifikat visas hur du installerar dem. Här är de grundläggande stegen:

  • Kontrollera att det finns tillräckligt med utrymme i certifikatarkivet. Certifikatlagringsutrymmet är begränsat, så appen bör anropa CertStore_GetAvailableSpace innan det försöker installera ett certifikat. Om det inte finns tillräckligt med utrymme ska appen ta bort ett befintligt certifikat för att frigöra utrymme för det nya. Certifikatutrymmet är begränsat till 24 KiB.

  • Om du vill installera ett rotcertifikat för certifikatutfärdare anropar du CertStore_InstallRootCACertificate. Appen tillhandahåller en pekare till certifikatinnehållet tillsammans med en identifierare som kan användas senare som eget namn för certifikatet. Ett rotcertifikat för certifikatutfärdare krävs om nätverket aktiverar ömsesidig autentisering. Identifierare kan innehålla versaler, gemener, siffrorna 0–9, punkt (.), bindestreck (-) och understreck (_). Den maximala längden på en identifierare är 16 tecken.

  • Om du vill installera ett klientcertifikat ringer du CertStore_InstallClientCertificate. Precis som med rotcertifikatutfärdarcertifikatet tillhandahåller appen en pekare till certifikatinnehållet tillsammans med en identifierare som kan användas senare som ett eget namn för certifikatet. Appen måste också ange den privata nyckeln och, om nyckeln är krypterad, krypteringslösenordet.

Om du vill uppdatera ett certifikat kan appen använda funktionen CertStore_MoveCertificate . Den här funktionen flyttar ett certifikat till ett annat genom att skriva över innehållet i ett befintligt målcertifikat med innehållet i källcertifikatet. Båda certifikaten måste redan vara installerade i certifikatarkivet. Certifikatets livscykel och förnyelse beskriver strategier för att uppdatera certifikat och samtidigt undvika driftstopp i nätverket.

Konfigurera och konfigurera ett EAP-TLS-nätverk

I exemplet Wifi_HighLevelApp visas hur du skapar, konfigurerar och aktiverar ett EAP-TLS-nätverk. I exemplet förutsätts att certifikaten redan finns i certifikatarkivet, enligt beskrivningen i Installera certifikat.

Om du vill konfigurera och konfigurera nätverket ska en app följa de här grundläggande stegen:

  • Lägg till ett nätverk genom att ringa WifiConfig_AddNetwork. Den här funktionen skapar helt enkelt ett nätverk. den inte konfigurera några egenskaper för nätverket.

  • Ange säkerhetstyp för nätverket genom att ringa WifiConfig_SetSecurityType. För ett EAP-TLS-nätverk måste säkerhetstypen vara WifiConfig_Security_Wpa2_EAP_TLS.

  • Ange SSID för nätverket genom att ringa WifiConfig_SetSSID. Om SSID inte redan är känt kan appen söka efter det. Om nätverksmiljön troligtvis är bullrig eller om SSID kanske inte sänds, ska appen aktivera riktad genomsökning genom att ringa WifiConfig_SetTargetedScanEnabled. Den kan sedan ringa WifiConfig_TriggerScanAndGetScannedNetworkCount för att söka efter alla nätverk och WifiConfig_GetScannedNetworks för att få resultatet av genomsökningen. WifiConfig_GetScannedNetworks returnerar en matris med strukturer som innehåller information om varje nätverk. Programmet kan söka i resultatet för ett nätverk med WifiConfig_Security_Wpa2_EAP_TLS säkerhetstypen och sedan hämta sitt SSID.

  • Ange nätverkets konfigurationsnamn genom att ringa WifiConfig_SetConfigName. Konfigurationsnamnet är ett eget namn som appen kan använda för att identifiera den här nätverkskonfigurationen.

  • Ange namnet på rotcertifikatutfärdarcertifikatet för RADIUS-servern genom att ringa WifiConfig_SetRootCACertStoreIdentifier om nätverket kräver serverautentisering. Rotcertifikatutfärdarcertifikatet måste redan finnas på enheten.

  • Ange namnet på klientcertifikatarkivet genom att ringa WifiConfig_SetClientCertStoreIdentifier. Klientcertifikatet måste redan finnas på enheten.

  • Ange klientidentiteten genom att ringa WifiConfig_SetClientIdentity. Klientidentiteten är ett eget namn som identifierar klientenheten.

  • Aktivera nätverket genom att ringa WifiConfig_SetNetworkEnabled.

  • Spara nätverkskonfigurationen genom att ringa WifiConfig_PersistConfig. Med den här funktionen sparas nätverkskonfigurationen på enheten så att den bevaras vid en omstart.

Ändra egenskaperna för ett EAP-TLS-nätverk

Appen kan ändra nätverkets egenskaper genom att anropa samma funktioner som användes för att ange dem, som i Konfigurera och konfigurera ett EAP-TLS-nätverk.

När du har ändrat egenskaper måste appen inte bara anropa WifiConfig_PersistConfig för att spara konfigurationen, utan måste också ringa WifiConfig_ReloadConfig för att uppdatera nätverket omedelbart. Detta är särskilt viktigt när programmet uppdaterar ett certifikat.

Ta bort ett EAP-TLS-nätverk

En app kan ta bort ett nätverk genom att ringa antingen WifiConfig_ForgetNetworkById eller WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById kopplar från nätverket om det är anslutet och tar bort det från enheten. Men konfigurationen av Wi-Fi uppdateras inte, så ändringen bevaras inte vid omstart. Appen måste ringa WifiConfig_PersistConfig för att borttagningen ska bli permanent.

WifiConfig_ForgetAllNetworks kopplar från det anslutna nätverket och tar bort alla nätverk från enheten. Den här ändringen finns kvar vid omstart.

Prover

  • Högnivåapp för certifikat – Visar hur du använder och hanterar certifikat i ett azure sphere-program på hög nivå.
  • Wifi_HighLevelApp – Visar hur du ansluter till ett Wi-Fi nätverk och kontrollerar nätverksstatusen på en MT3620-enhet.

Observera

Följande exempel är från Azure Sphere Gallery, som är en samling oavsiktliga programvaru- och maskinvaruprov från Microsoft. Mer information finns i Azure Sphere Gallery.