Partager via

Configurer un réseau EAP-TLS dans une application

  • Article

Vous pouvez configurer un PROTOCOLE EAP-TLS dans une application de haut niveau ou manuellement à l’aide az sphere de commandes. Pour configurer et se connecter au réseau, une application utilise les API Certstore et WifiConfig .

Exigences

Pour configurer un réseau EAP-TLS, votre application de haut niveau doit inclure les fichiers d’en-tête appropriés, activer les fonctionnalités requises dans son manifeste d’application et avoir accès aux certificats requis pour l’authentification.

Fichiers d’en-tête

Votre application doit inclure l’en-tête suivant :

#include <applibs/wificonfig.h>

Si l’application appelle l’API CertStore pour gérer les certificats, elle doit également inclure l’en-tête CertStore. Cet en-tête n’est pas nécessaire pour utiliser les fonctions WifiConfig telles que les WifiConfig_GetRootCACertStoreIdentifier qui récupèrent les informations de certificat.

#include <applibs/certstore.h>

Manifeste d’application

Le manifeste de l’application doit activer la fonctionnalité EnterpriseWiFiConfig pour configurer un réseau EAP-TLS. Il doit également disposer de la fonctionnalité WifiConfig pour utiliser des fonctions WifiConfig_* qui ne gèrent pas les fonctionnalités EAP-TLS. Enfin, si l’application gère également les certificats, elle doit activer la fonctionnalité CertStore.

N’activez pas les fonctionnalités dont l’application n’a pas besoin ; cela pose un risque pour la sécurité. Si les certificats sont mis à jour manuellement, ne spécifiez pas CertStore. Utilisez cette fonctionnalité uniquement si l’application est responsable du stockage et de la gestion des certificats sur l’appareil.

L’exemple suivant montre comment définir les trois fonctionnalités dans le fichier app_manifest.json :

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

Certificats

Le certificat client de votre appareil doit être disponible sur l’appareil. En outre, si le réseau EAP-TLS est configuré pour l’authentification mutuelle, le certificat d’autorité de certification racine du serveur RADIUS de votre réseau doit également être installé sur l’appareil. Les deux certificats doivent être au format .pem, PKCS1 ou PKCS8. Consultez Acquisition et déploiement de certificats EAP-TLS pour en savoir plus sur les certificats et où les obtenir.

Installer des certificats

Pour que votre application puisse configurer un réseau EAP-TLS, elle doit avoir accès à l’autorité de certification racine et aux certificats clients à utiliser pour l’authentification. Acquérir et déployer des certificats pour les réseaux EAP-TLS décrit les stratégies d’acquisition et de chargement de certificats sur un appareil sous forme de fichiers PEM. L’acquisition et le déploiement de certificats sont de votre responsabilité; case activée avec votre administrateur réseau pour plus d’informations.

Une fois que les certificats sont sur l’appareil, une application peut les installer pour les utiliser. L’exemple Certificats montre comment les installer. Voici les étapes de base :

  • Vérifiez qu’il y a suffisamment d’espace dans le magasin de certificats. L’espace du magasin de certificats étant limité, l’application doit appeler CertStore_GetAvailableSpace avant de tenter d’installer un certificat. Si l’espace disponible n’est pas suffisant, l’application doit supprimer un certificat existant pour libérer de l’espace pour le nouveau certificat. L’espace de certificat est limité à 24 Kio.

  • Pour installer un certificat d’autorité de certification racine, appelez CertStore_InstallRootCACertificate. L’application fournit un pointeur vers le contenu du certificat, ainsi qu’un identificateur qu’elle pourra utiliser ultérieurement comme nom convivial pour le certificat. Un certificat d’autorité de certification racine est requis si le réseau active l’authentification mutuelle. Les identificateurs peuvent inclure des lettres majuscules, des lettres minuscules, des chiffres 0 à 9, un point (.), un trait d’union (-) et un trait de soulignement (_). La longueur maximale d’un identificateur est de 16 caractères.

  • Pour installer un certificat client, appelez CertStore_InstallClientCertificate. Comme avec le certificat d’autorité de certification racine, l’application fournit un pointeur vers le contenu du certificat, ainsi qu’un identificateur qu’elle pourra utiliser ultérieurement comme nom convivial pour le certificat. L’application doit également fournir la clé privée et, si la clé est chiffrée, le mot de passe de chiffrement.

Pour mettre à jour un certificat, l’application peut utiliser la fonction CertStore_MoveCertificate . Cette fonction déplace un certificat vers un autre en remplaçant le contenu d’un certificat de destination existant par le contenu du certificat source. Les deux certificats doivent déjà être installés dans le magasin de certificats. Cycle de vie et renouvellement des certificats décrit les stratégies de mise à jour des certificats tout en évitant les temps d’arrêt du réseau.

Configurer et configurer un réseau EAP-TLS

L’exemple Wifi_HighLevelApp montre comment créer, configurer et activer un réseau EAP-TLS. L’exemple suppose que les certificats se trouvent déjà dans le magasin de certificats, comme décrit dans Installer des certificats.

Pour configurer et configurer le réseau, une application doit suivre les étapes de base suivantes :

  • Ajoutez un réseau en appelant WifiConfig_AddNetwork. Cette fonction crée simplement un réseau ; il ne configure aucune caractéristique pour le réseau.

  • Définissez le type de sécurité du réseau en appelant WifiConfig_SetSecurityType. Pour un réseau EAP-TLS, le type de sécurité doit être WifiConfig_Security_Wpa2_EAP_TLS.

  • Définissez le SSID du réseau en appelant WifiConfig_SetSSID. Si le SSID n’est pas déjà connu, l’application peut le rechercher. Si l’environnement réseau est susceptible d’être bruyant ou si le SSID n’est peut-être pas diffusé, l’application doit activer l’analyse ciblée en appelant WifiConfig_SetTargetedScanEnabled. Il peut ensuite appeler WifiConfig_TriggerScanAndGetScannedNetworkCount pour rechercher tous les réseaux et WifiConfig_GetScannedNetworks pour obtenir les résultats de l’analyse. WifiConfig_GetScannedNetworks retourne un tableau de structures qui contiennent des détails sur chaque réseau. L’application peut rechercher dans les résultats un réseau avec le WifiConfig_Security_Wpa2_EAP_TLS type de sécurité, puis récupérer son SSID.

  • Définissez le nom de configuration du réseau en appelant WifiConfig_SetConfigName. Le nom de configuration est un nom convivial que l’application peut utiliser pour identifier cette configuration réseau.

  • Définissez le nom du certificat d’autorité de certification racine pour le serveur RADIUS en appelant WifiConfig_SetRootCACertStoreIdentifier, si le réseau nécessite l’authentification du serveur. Le certificat d’autorité de certification racine doit déjà être présent sur l’appareil.

  • Définissez le nom du magasin de certificats client en appelant WifiConfig_SetClientCertStoreIdentifier. Le certificat client doit déjà être présent sur l’appareil.

  • Définissez l’identité du client en appelant WifiConfig_SetClientIdentity. L’identité du client est un nom convivial qui identifie l’appareil client.

  • Activez le réseau en appelant WifiConfig_SetNetworkEnabled.

  • Enregistrez la configuration réseau en appelant WifiConfig_PersistConfig. Cette fonction enregistre la configuration réseau sur l’appareil afin qu’elle persiste pendant un redémarrage.

Modifier les propriétés d’un réseau EAP-TLS

L’application peut modifier les propriétés du réseau en appelant les mêmes fonctions que celles utilisées à l’origine pour les définir, comme indiqué dans Configurer et configurer un réseau EAP-TLS.

Après avoir modifié les propriétés, l’application doit non seulement appeler WifiConfig_PersistConfig pour enregistrer la configuration, mais également appeler WifiConfig_ReloadConfig pour mettre à jour immédiatement le réseau. Cela est particulièrement important lorsque l’application met à jour un certificat.

Supprimer un réseau EAP-TLS

Une application peut supprimer un réseau en appelant WifiConfig_ForgetNetworkById ou WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById déconnecte le réseau s’il est connecté et le supprime de l’appareil. Toutefois, il ne met pas à jour la configuration Wi-Fi, de sorte que la modification ne persiste pas pendant le redémarrage. L’application doit appeler WifiConfig_PersistConfig pour rendre la suppression définitive.

WifiConfig_ForgetAllNetworks déconnecte le réseau connecté et supprime tous les réseaux de l’appareil. Cette modification persiste lors du redémarrage.

Échantillons

Note

L’exemple suivant provient de la galerie Azure Sphere, qui est une collection d’exemples logiciels et matériels non entretenus de Microsoft. Pour plus d’informations, consultez Galerie Azure Sphere.