Configurer un réseau EAP-TLS dans une application

Vous pouvez configurer un réseau EAP-TLS dans une application de haut niveau ou manuellement en utilisant des commandes azsphere. Pour configurer et se connecter au réseau, une application utilise les API Certstore et WifiConfig.

Spécifications

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 nécessaires dans son manifeste d’application et avoir accès aux certificats nécessaires 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 comme WifiConfig_GetRootCACertStoreIdentifier qui récupèrent les informations des certificats.

#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 les 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, car ceci présente un risque de sécurité. Si les certificats seront 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 l’ensemble des trois fonctionnalités dans le fichier app_manifest.json :

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

Certificats

Le certificat client pour 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 pour votre réseau doit également être installé sur l’appareil. Les deux certificats doivent être au format .pem, PKCS1 ou PKCS8. Pour plus d’informations sur les certificats et leur obtention, consultez Acquisition et déploiement de certificats EAP-TLS.

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 pour l’acquisition de certificats et pour leur chargement sur un appareil en tant que fichiers PEM. L’acquisition et le déploiement de certificats relèvent de votre responsabilité : pour plus d’informations, contactez votre administrateur réseau.

Une fois que les certificats se trouvent sur l’appareil, une application peut les installer en vue de leur utilisation. L’exemple Certificates 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’y 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. L’espace pour les certificats 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 peut utiliser ultérieurement comme nom convivial pour le certificat. Un certificat d’autorité de certification racine est nécessaire si le réseau permet l’authentification mutuelle. Les identificateurs peuvent inclure des lettres majuscules, des lettres minuscules, les chiffres de 0 à 9, des points (.), des tirets (-) et des traits 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 peut 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 du 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 paramétrer 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 paramétrer le réseau, une application doit suivre les étapes de base suivantes :

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

• Définir le type de sécurité pour le 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éfinir le SSID du réseau en appelant WifiConfig_SetSSID. Si le SSID n’est pas encore connu, l’application peut le rechercher. Si l’environnement réseau est susceptible d’être bruyant ou si le SSID n’est pas diffusé, l’application doit activer une recherche ciblée en appelant WifiConfig_SetTargetedScanEnabled. Elle peut ensuite appeler WifiConfig_TriggerScanAndGetScannedNetworkCount pour rechercher tous les réseaux, puis WifiConfig_GetScannedNetworks pour obtenir les résultats de la recherche. 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 type de sécurité WifiConfig_Security_Wpa2_EAP_TLS, puis récupérer son SSID.

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

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

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

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

• Activer le réseau en appelant WifiConfig_SetNetworkEnabled.

• Enregistrer la configuration réseau en appelant WifiConfig_PersistConfig. Cette fonction enregistre la configuration réseau sur l’appareil pour qu’elle soit conservée après 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 pour les définir à l’origine, comme indiqué dans Configurer et paramétrer un réseau EAP-TLS.

Après avoir modifié les propriétés, l’application ne doit pas seulement appeler WifiConfig_PersistConfig pour enregistrer la configuration, mais elle doit aussi appeler WifiConfig_ReloadConfig pour mettre à jour le réseau immédiatement. Ceci est particulièrement important quand 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. Elle ne met cependant pas à jour la configuration du Wi-Fi : la modification n’est donc pas conservée après un redémarrage. L’application doit appeler WifiConfig_PersistConfig pour rendre la suppression permanente.

WifiConfig_ForgetAllNetworks déconnecte le réseau connecté et supprime tous les réseaux de l’appareil. Cette modification est conservée après un redémarrage.

Exemples

• Application générale de certificats : montre comment utiliser et gérer des certificats dans une application de haut niveau Azure Sphere.
• Wifi_HighLevelApp : montre comment se connecter à un réseau Wi-Fi et vérifier l’état du réseau sur un appareil MT3620.

• Solution EAP-TLS avec Azure Sphere : montre comment connecter des appareils Azure Sphere à des réseaux EAP-TLS.