Teilen über

Einrichten eines EAP-TLS-Netzwerks in einer App

  • Artikel

Wichtig

Dies ist die Dokumentation zu Azure Sphere (Legacy). Azure Sphere (Legacy) wird am 27. September 2027 eingestellt, und Benutzer müssen bis zu diesem Zeitpunkt zu Azure Sphere (integriert) migrieren. Verwenden Sie die Versionsauswahl oberhalb des Inhaltsverzeichniss, um die Dokumentation zu Azure Sphere (Integriert) anzuzeigen.

Sie können ein EAP-TLS-Netzwerk in einer allgemeinen Anwendung konfigurieren, oder manuell mithilfe von azsphere-Befehlen. Für die Konfiguration und Herstellung einer Verbindung zum Netzwerk verwendet eine Anwendung die Certstore- und WifiConfig-APIs.

Anforderungen

Für die Konfiguration eines EAP-TLS-Netzwerks muss Ihre allgemeine App die entsprechenden Headerdateien einschließen, die erforderlichen Funktionen in ihrem Anwendungsmanifest aktivieren und Zugriff auf die Zertifikate haben, die für die Authentifizierung erforderlich sind.

Headerdateien

Ihre App muss die folgenden Header einschließen:

#include <applibs/wificonfig.h>

Wenn die Anwendung die CertStore-API aufruft, um die Zertifikate zu verwalten, muss sie auch den CertStore-Header einschließen. Dieser Header muss die WifiConfig-Funktionen, z. B. WifiConfig_GetRootCACertStoreIdentifier, die Zertifikatsinformationen abrufen, nicht verwenden.

#include <applibs/certstore.h>

Anwendungsmanifest

Das Anwendungsmanifest muss die EnterpriseWiFiConfig-Funktion aktivieren, um ein EAP-TLS-Netzwerk einzurichten. Die WifiConfig-Funktion ist außerdem erforderlich, um WifiConfig_*-Funktionen verwenden zu können, die EAP-TLS-Features nicht verwalten. Schließlich muss die App die CertStore-Funktion aktivieren, wenn sie auch Zertifikate verwaltet.

Aktivieren Sie keine Funktionen, die die Anwendung nicht benötigt. Dies würde ein Sicherheitsrisiko darstellen. Wenn die Zertifikate manuell aktualisiert werden, geben Sie CertStore nicht an. Verwenden Sie diese Funktion nur, wenn die Anwendung für das Speichern und Verwalten von Zertifikaten auf dem Gerät verantwortlich ist.

Das folgende Beispiel zeigt, wie alle drei Funktionen in der app_manifest.json-Datei festgelegt werden:

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

Zertifikate

Das Clientzertifikat für Ihr Gerät muss auf dem Gerät verfügbar sein. Zusätzlich muss das Zertifikat der Stammzertifizierungsstelle für den RADIUS-Server Ihres Netzwerks ebenfalls auf dem Gerät installiert sein, wenn das EAP-TLS für die gegenseitige Authentifizierung konfiguriert wurde. Die Zertifikate müssen im PEM-Format vorliegen und entweder die PKCS1- oder die PKCS8-Syntax aufweisen. Weitere Informationen zu den Zertifikaten und deren Abruf finden Sie unter Abrufen und Bereitstellen von Zertifikaten für EAP-TLS-Netzwerke.

Installieren von Zertifikaten

Bevor Ihre App ein EAP-TLS-Netzwerk einrichten kann, benötigt es Zugriff auf das Zertifikat der Stammzertifizierungsstelle und das Clientzertifikat für die Authentifizierung. Im Artikel Abrufen und Bereitstellen von Zertifikaten für EAP-TLS-Netzwerke werden Strategien für das Abrufen von Zertifikaten beschrieben. Außerdem wird erläutert, wie sie als PEM-Dateien auf ein Gerät geladen werden. Das Abrufen und die Bereitstellung von Zertifikaten liegt in Ihrer Verantwortung. Weitere Informationen dazu erhalten Sie von Ihrem Netzwerkadministrator.

Nachdem die Zertifikate auf das Gerät geladen wurden, kann eine Anwendung sie installieren, damit sie verwendet werden können. Im Zertifikatsbeispiel sehen Sie, wie Zertifikate installiert werden. Im Folgenden sind die grundlegenden Schritte aufgeführt:

  • Sorgen Sie dafür, dass im Zertifikatspeicher genügend freier Speicherplatz zur Verfügung steht. Der Zertifikatspeicherplatz ist begrenzt. Die App sollte also CertStore_GetAvailableSpace aufrufen, bevor sie versucht, ein Zertifikat zu installieren. Wenn nicht ausreichend Speicherplatz verfügbar ist, sollte die App ein vorhandenes Zertifikat löschen, um Platz für ein neues zu schaffen. Der Zertifikatspeicherplatz ist auf 24 KiB begrenzt.

  • Rufen Sie für die Installation eines Zertifikats der Stammzertifizierungsstelle CertStore_InstallRootCACertificate auf. Die App stellt einen Zeiger auf den Zertifikatsinhalt sowie einen Bezeichner bereit, der später als Anzeigename für das Zertifikat verwendet werden kann. Ein Zertifikat der Stammzertifizierungsstelle ist erforderlich, wenn für das Netzwerk die gegenseitige Authentifizierung aktiviert ist. Bezeichner können Großbuchstaben, Kleinbuchstaben, die Zahlen 0–9, Punkte (.), Bindestriche (-) und Unterstriche (_) enthalten. Die maximale Länge des Bezeichners beträgt 16 Zeichen.

  • Rufen Sie für die Installation eines Clientzertifikats CertStore_InstallClientCertificate auf. Wie beim Zertifikat der Stammzertifizierungsstelle stellt die App einen Zeiger auf den Zertifikatsinhalt sowie einen Bezeichner bereit, der später als Anzeigename für das Zertifikat verwendet werden kann. Die App muss außerdem den privaten Schlüssel sowie, falls der Schlüssel verschlüsselt ist, das Verschlüsselungskennwort bereitstellen.

Für die Aktualisierung eines Zertifikats kann die App die CertStore_MoveCertificate-Funktion verwenden. Diese Funktion verschiebt ein Zertifikat zu einem anderen, indem die Inhalte eines vorhandenen Zielzertifikats durch die Inhalte des Quellzertifikats überschrieben werden. Beide Zertifikate müssen im Zertifikatspeicher bereits installiert worden sein. Im Artikel Lebenszyklus und Verlängerung von Zertifikaten sind Strategien für das Aktualisieren von Zertifikaten dargelegt. Außerdem wird erläutert, wie dabei Netzwerkausfälle vermieden werden können.

Konfigurieren und Einrichten eines EAP-TLS-Netzwerks

Das Wifi_HighLevelApp-Beispiel zeigt, wie Sie ein EAP-TLS-Netzwerk erstellen, konfigurieren und aktivieren. Im Beispiel wird angenommen, dass sich die Zertifikate bereits im Zertifikatspeicher befinden. Sehen Sie sich dazu den Abschnitt Installieren von Zertifikaten an.

Für das Konfigurieren und Einrichten des Netzwerks sollte eine App die folgenden grundlegenden Schritte befolgen:

  • Hinzufügen eines Netzwerks, indem WifiConfig_AddNetwork aufgerufen wird. Diese Funktion erstellt einfach ein Netzwerk. Dabei werden jedoch keine Merkmale des Netzwerks konfiguriert.

  • Festlegen des Sicherheitstyps für das Netzwerk, indem WifiConfig_SetSecurityType aufgerufen wird. Bei einem EAP-TLS-Netzwerk muss der Sicherheitstyp WifiConfig_Security_Wpa2_EAP_TLS sein.

  • Festlegen der SSID für das Netzwerk, indem WifiConfig_SetSSID aufgerufen wird. Wenn die SSID noch nicht bekannt ist, kann die App einen Scanvorgang ausführen, um sie zu ermitteln. Wenn es sich bei der Netzwerkumgebung um eine Umgebung mit starkem Rauschen handelt oder wenn die SSID möglicherweise nicht übertragen wird, sollte die App eine gezielte Überprüfung durchführen, indem WifiConfig_SetTargetedScanEnabled aufgerufen wird. Dann kann WifiConfig_TriggerScanAndGetScannedNetworkCount aufgerufen werden, um alle Netzwerke zu überprüfen, und WifiConfig_GetScannedNetworks, um die Ergebnisse der Überprüfung abzurufen. WifiConfig_GetScannedNetworks gibt ein Array von Strukturen zurück, das Details zu den einzelnen Netzwerken enthält. Die Anwendung kann in den Ergebnissen nach einem Netzwerk mit dem WifiConfig_Security_Wpa2_EAP_TLS-Sicherheitstyp suchen und dann die dazugehörige SSID abrufen.

  • Festlegen des Konfigurationsnamens für das Netzwerk, indem WifiConfig_SetConfigName aufgerufen wird. Der Konfigurationsname ist ein Anzeigename, den die App verwenden kann, um diese Netzwerkkonfiguration zu identifizieren.

  • Festlegen des Namens des Zertifikats der Stammzertifizierungsstelle für den RADIUS-Server, indem WifiConfig_SetRootCACertStoreIdentifier aufgerufen wird, wenn für das Netzwerk eine Serverauthentifizierung erforderlich ist. Das Zertifikat der Stammzertifizierungsstelle muss auf dem Gerät bereits vorhanden sein.

  • Festlegen des Namens des Clientzertifikatspeicher, indem WifiConfig_SetClientCertStoreIdentifier aufgerufen wird. Das Clientzertifikat muss auf dem Gerät bereits vorhanden sein.

  • Festlegen der Clientidentität, indem WifiConfig_SetClientIdentity aufgerufen wird. Die Clientidentität ist ein Anzeigename, der das Clientgerät identifiziert.

  • Aktivieren des Netzwerks, indem WifiConfig_SetNetworkEnabled aufgerufen wird.

  • Speichern der Netzwerkkonfiguration, indem WifiConfig_PersistConfig aufgerufen wird. Diese Funktion speichert die Netzwerkkonfiguration auf dem Gerät, damit sie auch nach einem Neustart noch vorhanden ist.

Ändern der Eigenschaften eines EAP-TLS-Netzwerks

Die App kann die Eigenschaften des Netzwerks ändern, indem dieselben Funktionen aufgerufen werden, die verwendet wurden, um sie ursprünglich festzulegen. Sehen Sie sich dazu den Abschnitt Konfigurieren und Einrichten eines EAP-TLS-Netzwerks an.

Nach der Änderung der Eigenschaften muss die App nicht nur WifiConfig_PersistConfig aufrufen, um die Konfiguration zu speichern, sondern auch WifiConfig_ReloadConfig, um das Netzwerk sofort zu aktualisieren. Dies ist besonders dann wichtig, wenn die Anwendung ein Zertifikat aktualisiert.

Löschen eines EAP-TLS-Netzwerks

Eine App kann ein Netzwerk löschen, indem entweder WifiConfig_ForgetNetworkById oder WifiConfig_ForgetAllNetworks aufgerufen wird.

WifiConfig_ForgetNetworkById trennt die Verbindung des Netzwerks, wenn es verbunden ist, und entfernt es vom Gerät. Allerdings wird die WLAN-Konfiguration nicht aktualisiert, die Änderung bleibt also nach einem Neustart nicht bestehen. Die App muss WifiConfig_PersistConfig aufrufen, damit der Entfernungsvorgang beständig ist.

WifiConfig_ForgetAllNetworks trennt die Verbindung des verbundenen Netzwerks und entfernt alle Netzwerke vom Gerät. Diese Änderung bleibt auch bei einem Neustart bestehen.

Beispiele

  • Zertifikate auf hoher Ebene – Veranschaulicht, wie Zertifikate in einer allgemeinen Azure Sphere-Anwendung verwendet und verwaltet werden.
  • Wifi_HighLevelApp – Veranschaulicht, wie Sie eine Verbindung mit einem WLAN-Netzwerk herstellen und den Netzwerkstatus auf einem MT3620-Gerät überprüfen.

Hinweis

Das folgende Beispiel stammt aus dem Azure Sphere-Katalog, der eine Sammlung nicht vorhandener Software- und Hardwarebeispiele von Microsoft ist. Weitere Informationen finden Sie im Azure Sphere-Katalog.