Share via

EAP-TLS-netwerk instellen in een app

  • Artikel

U kunt een EAP-TLS configureren in een toepassing op hoog niveau of handmatig, met behulp van az sphere opdrachten. Een toepassing maakt gebruik van de Certstore- en WifiConfig-API's om het netwerk te configureren en er verbinding mee te maken.

Eisen

Als u een EAP-TLS-netwerk wilt configureren, moet uw app op hoog niveau de juiste headerbestanden bevatten, de vereiste mogelijkheden inschakelen in het toepassingsmanifest en toegang hebben tot de certificaten die vereist zijn voor verificatie.

Koptekstbestanden

Uw app moet de volgende header bevatten:

#include <applibs/wificonfig.h>

Als de toepassing de CertStore-API aanroept om certificaten te beheren, moet deze ook de CertStore-header bevatten. Deze header is niet vereist voor het gebruik van de WifiConfig-functies , zoals WifiConfig_GetRootCACertStoreIdentifier die certificaatgegevens ophalen.

#include <applibs/certstore.h>

Toepassingsmanifest

Het toepassingsmanifest moet de mogelijkheid EnterpriseWiFiConfig inschakelen om een EAP-TLS-netwerk in te stellen. Het moet ook de WifiConfig-mogelijkheid hebben om WifiConfig_*-functies te gebruiken die geen EAP-TLS-functies beheren. Als de app ook certificaten beheert, moet de functie CertStore worden ingeschakeld.

Schakel geen mogelijkheden in die niet nodig zijn voor de toepassing; dit vormt een beveiligingsrisico. Als de certificaten handmatig worden bijgewerkt, geeft u CertStore niet op. Gebruik deze mogelijkheid alleen als de toepassing verantwoordelijk is voor het opslaan en beheren van certificaten op het apparaat.

In het volgende voorbeeld ziet u hoe u alle drie de mogelijkheden in het bestand app_manifest.json instelt:

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

Certificaten

Het clientcertificaat voor uw apparaat moet beschikbaar zijn op het apparaat. Als het EAP-TLS-netwerk is geconfigureerd voor wederzijdse verificatie, moet bovendien het basis-CA-certificaat voor de RADIUS-server van uw netwerk ook op het apparaat worden geïnstalleerd. Beide certificaten moeten de .pem-indeling hebben, PKCS1 of PKCS8. Zie EAP-TLS-certificaat verkrijgen en implementeren voor meer informatie over de certificaten en waar u deze kunt verkrijgen.

Certificaten installeren

Voordat uw app een EAP-TLS-netwerk kan instellen, moet deze toegang hebben tot de basis-CA- en clientcertificaten die moeten worden gebruikt voor verificatie. Certificaten verkrijgen en implementeren voor EAP-TLS-netwerken beschrijft strategieën voor het verkrijgen van certificaten en het laden ervan op een apparaat als PEM-bestanden. Het verkrijgen en implementeren van certificaten is uw verantwoordelijkheid; neem contact op met uw netwerkbeheerder voor meer informatie.

Nadat de certificaten zich op het apparaat bevinden, kan een toepassing ze installeren voor gebruik. In het voorbeeld Certificaten ziet u hoe u ze installeert. Hier volgen de basisstappen:

  • Zorg ervoor dat er voldoende ruimte is in het certificaatarchief. De ruimte voor het certificaatarchief is beperkt, dus de app moet CertStore_GetAvailableSpace aanroepen voordat wordt geprobeerd een certificaat te installeren. Als er niet voldoende ruimte beschikbaar is, moet de app een bestaand certificaat verwijderen om ruimte te maken voor het nieuwe certificaat. De certificaatruimte is beperkt tot 24 KiB.

  • Als u een basis-CA-certificaat wilt installeren, roept u CertStore_InstallRootCACertificate aan. De app levert een aanwijzer naar de certificaatinhoud, samen met een id die later kan worden gebruikt als een beschrijvende naam voor het certificaat. Een basis-CA-certificaat is vereist als het netwerk wederzijdse verificatie inschakelt. Id's kunnen bestaan uit hoofdletters, kleine letters, de cijfers 0-9, punt (.), afbreekstreepje (-) en onderstrepingsteken (_). De maximale lengte van een id is 16 tekens.

  • Als u een clientcertificaat wilt installeren, roept u CertStore_InstallClientCertificate aan. Net als bij het basis-CA-certificaat levert de app een aanwijzer naar de certificaatinhoud, samen met een id die later kan worden gebruikt als een beschrijvende naam voor het certificaat. De app moet ook de persoonlijke sleutel en, als de sleutel is versleuteld, het versleutelingswachtwoord opgeven.

Als u een certificaat wilt bijwerken, kan de app de functie CertStore_MoveCertificate gebruiken. Met deze functie wordt het ene certificaat naar het andere verplaatst door de inhoud van een bestaand doelcertificaat te overschrijven met de inhoud van het broncertificaat. Beide certificaten moeten al zijn geïnstalleerd in het certificaatarchief. De levenscyclus en verlenging van certificaten bevatten een overzicht van strategieën voor het bijwerken van certificaten terwijl downtime van het netwerk wordt vermeden.

Een EAP-TLS-netwerk configureren en instellen

In het Wifi_HighLevelApp voorbeeld ziet u hoe u een EAP-TLS-netwerk maakt, configureert en inschakelt. In het voorbeeld wordt ervan uitgegaan dat de certificaten zich al in het certificaatarchief bevinden, zoals beschreven in Certificaten installeren.

Als u het netwerk wilt configureren en instellen, moet een app deze basisstappen volgen:

  • Voeg een netwerk toe door WifiConfig_AddNetwork aan te roepen. Met deze functie maakt u gewoon een netwerk; er worden geen kenmerken voor het netwerk geconfigureerd.

  • Stel het beveiligingstype voor het netwerk in door WifiConfig_SetSecurityType aan te roepen. Voor een EAP-TLS-netwerk moet het beveiligingstype zijn WifiConfig_Security_Wpa2_EAP_TLS.

  • Stel de SSID voor het netwerk in door WifiConfig_SetSSID aan te roepen. Als de SSID nog niet bekend is, kan de app ernaar scannen. Als de netwerkomgeving waarschijnlijk luidruchtig is of als de SSID mogelijk niet wordt uitgezonden, moet de app gericht scannen inschakelen door WifiConfig_SetTargetedScanEnabled aan te roepen. Vervolgens kan WifiConfig_TriggerScanAndGetScannedNetworkCount worden aangeroepen om te scannen naar alle netwerken en WifiConfig_GetScannedNetworks om de resultaten van de scan op te halen. WifiConfig_GetScannedNetworks retourneert een matrix met structuren die details over elk netwerk bevatten. De toepassing kan de resultaten voor een netwerk doorzoeken met het beveiligingstype en vervolgens de WifiConfig_Security_Wpa2_EAP_TLS SSID ophalen.

  • Stel de configuratienaam voor het netwerk in door WifiConfig_SetConfigName aan te roepen. De configuratienaam is een beschrijvende naam die de app kan gebruiken om deze netwerkconfiguratie te identificeren.

  • Stel de naam in van het basis-CA-certificaat voor de RADIUS-server door WifiConfig_SetRootCACertStoreIdentifier aan te roepen, als het netwerk serververificatie vereist. Het basis-CA-certificaat moet al aanwezig zijn op het apparaat.

  • Stel de naam van het clientcertificaatarchief in door WifiConfig_SetClientCertStoreIdentifier aan te roepen. Het clientcertificaat moet al aanwezig zijn op het apparaat.

  • Stel de client-identiteit in door WifiConfig_SetClientIdentity aan te roepen. De client-id is een beschrijvende naam die het clientapparaat identificeert.

  • Schakel het netwerk in door WifiConfig_SetNetworkEnabled aan te roepen.

  • Sla de netwerkconfiguratie op door WifiConfig_PersistConfig aan te roepen. Met deze functie wordt de netwerkconfiguratie op het apparaat opgeslagen, zodat deze blijft bestaan na het opnieuw opstarten.

De eigenschappen van een EAP-TLS-netwerk wijzigen

De app kan de eigenschappen van het netwerk wijzigen door dezelfde functies aan te roepen die zijn gebruikt om ze oorspronkelijk in te stellen, zoals vermeld in Een EAP-TLS-netwerk configureren en instellen.

Nadat de eigenschappen zijn gewijzigd, moet de app niet alleen WifiConfig_PersistConfig aanroepen om de configuratie op te slaan, maar ook WifiConfig_ReloadConfig aanroepen om het netwerk onmiddellijk bij te werken. Dit is met name belangrijk wanneer de toepassing een certificaat bijwerken.

Een EAP-TLS-netwerk verwijderen

Een app kan een netwerk verwijderen door WifiConfig_ForgetNetworkById of WifiConfig_ForgetAllNetworks aan te roepen.

WifiConfig_ForgetNetworkById verbreekt de verbinding met het netwerk als het is verbonden en verwijdert het van het apparaat. De configuratie van de Wi-Fi wordt echter niet bijgewerkt, zodat de wijziging niet blijft bestaan tijdens het opnieuw opstarten. De app moet WifiConfig_PersistConfig aanroepen om de verwijdering permanent te maken.

WifiConfig_ForgetAllNetworks verbreekt de verbinding met het verbonden netwerk en verwijdert alle netwerken van het apparaat. Deze wijziging blijft bestaan tijdens het opnieuw opstarten.

Monsters

  • Certificaten-app op hoog niveau : laat zien hoe u certificaten gebruikt en beheert in een toepassing op hoog niveau van Azure Sphere.
  • Wifi_HighLevelApp : laat zien hoe u verbinding maakt met een Wi-Fi netwerk en de netwerkstatus op een MT3620-apparaat controleert.

Opmerking

Het volgende voorbeeld is afkomstig uit de Azure Sphere-galerie, een verzameling niet-onderhouden software- en hardwarevoorbeelden van Microsoft. Zie Azure Sphere Gallery voor meer informatie.