Dela via

Konfigurera EAP-TLS-nätverk i en app

  • Artikel

Viktigt!

Det här är dokumentationen om Azure Sphere (Legacy). Azure Sphere (Legacy) upphör den 27 september 2027 och användarna måste migrera till Azure Sphere (integrerad) vid den här tiden. Använd versionsväljaren ovanför TOC för att visa dokumentationen om Azure Sphere (integrerad).

Du kan konfigurera en EAP-TLS i ett högnivåprogram eller manuellt med hjälp av azsphere-kommandon. För att konfigurera och ansluta till nätverket använder ett program API:erna Certstore och WifiConfig .

Krav

För att konfigurera ett EAP-TLS-nätverk måste din högnivåapp inkludera lämpliga huvudfiler, aktivera de nödvändiga funktionerna i programmanifestet och ha åtkomst till de certifikat som krävs för autentisering.

Rubrikfiler

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

#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 göra det möjligt för EnterpriseWiFiConfig-funktionen 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 slutligen 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 anger alla tre funktionerna i filen app_manifest.json:

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

Certifikat

Klientcertifikatet för enheten måste vara tillgängligt på enheten. Om EAP-TLS-nätverket dessutom har konfigurerats för ömsesidig autentisering måste rotcertifikatutfärdarcertifikatet för nätverkets RADIUS-server också installeras på enheten. Båda certifikaten måste vara i .pem-format, antingen PKCS1 eller PKCS8. Se anskaffning och distribution av EAP-TLS-certifikat för att lära dig mer om certifikaten och var du kan hämta dem.

Installera certifikat

Innan appen kan konfigurera ett EAP-TLS-nätverk måste den ha åtkomst till rotcertifikatutfärdare och klientcertifikat som ska användas för autentisering. Hämta och distribuera certifikat för EAP-TLS-nätverk beskriver strategier för att hämta certifikat och läsa in dem på en enhet som PEM-filer. Det är ditt ansvar att förvärva och distribuera certifikat. Kontakta nätverksadministratören för mer information.

När certifikaten finns på enheten kan ett program installera dem för användning. Certifikatexemplet visar hur du installerar dem. Följande är de grundläggande stegen:

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

  • Om du vill installera ett rotcertifikatutfärdarcertifikat anropar du CertStore_InstallRootCACertificate. Appen tillhandahåller en pekare till certifikatinnehållet tillsammans med en identifierare som kan användas senare som ett eget namn för certifikatet. Ett rotcertifikatutfärdarcertifikat krävs om nätverket möjliggör ö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 anropar 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 samtidigt som nätverksavbrott undviks.

Konfigurera och konfigurera ett EAP-TLS-nätverk

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

För att konfigurera och konfigurera nätverket bör en app följa dessa grundläggande steg:

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

  • Ange säkerhetstypen för nätverket genom att anropa 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 anropa WifiConfig_SetSSID. Om SSID inte redan är känt kan appen söka efter det. Om nätverksmiljön sannolikt är bullrig eller om SSID kanske inte sänds bör appen aktivera riktad genomsökning genom att anropa WifiConfig_SetTargetedScanEnabled. Den kan sedan anropa 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 efter ett nätverk med WifiConfig_Security_Wpa2_EAP_TLS säkerhetstypen och sedan hämta sitt SSID.

  • Ange nätverkets konfigurationsnamn genom att anropa 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 anropa WifiConfig_SetRootCACertStoreIdentifier om nätverket kräver serverautentisering. Rotcertifikatutfärdarcertifikatet måste redan finnas på enheten.

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

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

  • Aktivera nätverket genom att anropa WifiConfig_SetNetworkEnabled.

  • Spara nätverkskonfigurationen genom att anropa WifiConfig_PersistConfig. Den här funktionen sparar nätverkskonfigurationen på enheten så att den bevaras under 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, enligt listan 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å anropa 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 anropa antingen WifiConfig_ForgetNetworkById eller WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById kopplar från nätverket om det är anslutet och tar bort det från enheten. Den uppdaterar dock inte Wi-Fi-konfigurationen, så ändringen bevaras inte i omstarten. Appen måste anropa WifiConfig_PersistConfig för att göra borttagningen permanent.

WifiConfig_ForgetAllNetworks kopplar från det anslutna nätverket och tar bort alla nätverk från enheten. Den här ändringen kvarstår under omstarten.

Exempel

  • 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.

Kommentar

Följande exempel kommer från Azure Sphere-galleriet, som är en samling oönskad programvara och maskinvaruexempel från Microsoft. Mer information finns i Azure Sphere-galleriet.