Configurare la rete EAP-TLS in un'app

  • Articolo

È possibile configurare un EAP-TLS in un'applicazione di alto livello oppure manualmente usando az sphere i comandi. Per configurare e connettersi alla rete, un'applicazione utilizza le API Certstore e WifiConfig .

Requisiti

Per configurare una rete EAP-TLS, l'app di alto livello deve includere i file di intestazione appropriati, abilitare le funzionalità necessarie nel manifesto dell'applicazione e avere accesso ai certificati necessari per l'autenticazione.

File di intestazione

L'app deve includere l'intestazione seguente:

#include <applibs/wificonfig.h>

Se l'applicazione chiama l'API CertStore per gestire i certificati, deve includere anche l'intestazione CertStore. Questa intestazione non è necessaria per utilizzare le funzioni WifiConfig , ad esempio WifiConfig_GetRootCACertStoreIdentifier che recuperano le informazioni sul certificato.

#include <applibs/certstore.h>

Manifesto dell'applicazione

Il manifesto dell'applicazione deve abilitare la funzionalità EnterpriseWiFiConfig per configurare una rete EAP-TLS. Per usare le funzioni di WifiConfig_* che non gestiscono le funzionalità EAP-TLS, è inoltre necessario disporre della funzionalità WifiConfig. Infine, se l'app gestisce anche i certificati, deve abilitare la funzionalità CertStore.

Non abilitare le funzionalità non richieste dall'applicazione; comporta un rischio per la sicurezza. Se i certificati verranno aggiornati manualmente, non specificare CertStore. Usare questa funzionalità solo se l'applicazione è responsabile dell'archiviazione e della gestione dei certificati nel dispositivo.

L'esempio seguente mostra come impostare tutte e tre le funzionalità nel file app_manifest.json:

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

Certificati

Il certificato client per il dispositivo deve essere disponibile nel dispositivo. Inoltre, se la rete EAP-TLS è configurata per l'autenticazione reciproca, nel dispositivo deve essere installato anche il certificato CA radice per il server RADIUS della rete. Entrambi i certificati devono essere in formato .pem, PKCS1 o PKCS8. Per informazioni sui certificati e su dove ottenerli, vedere Acquisizione e distribuzione di certificati EAP-TLS .

Installare certificati

Prima che l'app possa configurare una rete EAP-TLS, deve avere accesso alla CA radice e ai certificati client da usare per l'autenticazione. L'acquisizione e la distribuzione di certificati per le reti EAP-TLS descrive le strategie per l'acquisizione e il caricamento di certificati in un dispositivo come file PEM. L'acquisizione e la distribuzione di certificati è responsabilità dell'utente; contatta l'amministratore di rete per i dettagli.

Dopo che i certificati sono sul dispositivo, un'applicazione può installarli per l'uso. L'esempio Certificati mostra come installarli. Ecco i passaggi di base:

  • Verificare che lo spazio nell'archivio certificati sia sufficiente. Lo spazio nell'archivio certificati è limitato, quindi l'app deve chiamare CertStore_GetAvailableSpace prima di installare un certificato. Se lo spazio disponibile non è sufficiente, l'app deve eliminare un certificato esistente per liberare spazio per quello nuovo. Lo spazio certificato è limitato a 24 KiB.

  • Per installare un certificato CA radice, chiamare CertStore_InstallRootCACertificate. L'app fornisce un puntatore al contenuto del certificato insieme a un identificatore che può essere usato in seguito come nome descrittivo per il certificato. Se la rete abilita l'autenticazione reciproca, è necessario un certificato CA radice. Gli identificatori possono includere lettere maiuscole, minuscole, cifre da 0 a 9, punto (.), trattino (-) e carattere di sottolineatura (_). La lunghezza massima di un identificatore è di 16 caratteri.

  • Per installare un certificato client, chiamare CertStore_InstallClientCertificate. Come per il certificato CA radice, l'app fornisce un puntatore al contenuto del certificato insieme a un identificatore che può essere usato in seguito come nome descrittivo per il certificato. L'app deve anche fornire la chiave privata e, se la chiave è crittografata, la password di crittografia.

Per aggiornare un certificato, l'app può usare la funzione CertStore_MoveCertificate . Questa funzione sposta un certificato in un altro sovrascrivendo il contenuto di un certificato di destinazione esistente con il contenuto del certificato di origine. Entrambi i certificati devono essere già installati nell'archivio certificati. Il ciclo di vita dei certificati e le strategie di struttura di rinnovo per l'aggiornamento dei certificati evitando tempi di inattività di rete.

Configurare e configurare una rete EAP-TLS

Nell'esempio Wifi_HighLevelApp viene illustrato come creare, configurare e abilitare una rete EAP-TLS. L'esempio presuppone che i certificati siano già presenti nell'archivio certificati, come descritto in Installare i certificati.

Per configurare e configurare la rete, un'app deve seguire questi passaggi di base:

  • Aggiungi una rete chiamando WifiConfig_AddNetwork. Questa funzione crea semplicemente una rete; non configura alcuna caratteristica per la rete.

  • Impostare il tipo di sicurezza per la rete chiamando WifiConfig_SetSecurityType. Per una rete EAP-TLS, il tipo di sicurezza deve essere WifiConfig_Security_Wpa2_EAP_TLS.

  • Impostare l'SSID per la rete chiamando WifiConfig_SetSSID. Se l'SSID non è già noto, l'app può cercarlo. Se è probabile che l'ambiente di rete sia rumoroso o se l'SSID potrebbe non essere trasmesso, l'app deve abilitare l'analisi mirata chiamando WifiConfig_SetTargetedScanEnabled. Può quindi chiamare WifiConfig_TriggerScanAndGetScannedNetworkCount per cercare tutte le reti e WifiConfig_GetScannedNetworks per ottenere i risultati dell'analisi. WifiConfig_GetScannedNetworks restituisce una matrice di strutture che contengono dettagli su ogni rete. L'applicazione può cercare nei risultati una rete con il WifiConfig_Security_Wpa2_EAP_TLS tipo di sicurezza e quindi recuperare il suo SSID.

  • Impostare il nome di configurazione per la rete chiamando WifiConfig_SetConfigName. Il nome della configurazione è un nome descrittivo che l'app può usare per identificare questa configurazione di rete.

  • Impostare il nome del certificato CA radice per il server RADIUS chiamando WifiConfig_SetRootCACertStoreIdentifier, se la rete richiede l'autenticazione del server. Il certificato CA radice deve essere già presente nel dispositivo.

  • Impostare il nome dell'archivio certificati client chiamando WifiConfig_SetClientCertStoreIdentifier. Il certificato client deve essere già presente nel dispositivo.

  • Impostare l'identità del client chiamando WifiConfig_SetClientIdentity. L'identità client è un nome descrittivo che identifica il dispositivo client.

  • Abilitare la rete chiamando WifiConfig_SetNetworkEnabled.

  • Salvare la configurazione di rete chiamando WifiConfig_PersistConfig. Questa funzione salva la configurazione di rete nel dispositivo in modo che persista durante un riavvio.

Modificare le proprietà di una rete EAP-TLS

L'app può modificare le proprietà della rete chiamando le stesse funzioni usate per impostarle originariamente, come indicato in Configurare e configurare una rete EAP-TLS.

Dopo aver modificato le proprietà, l'app non solo deve chiamare WifiConfig_PersistConfig per salvare la configurazione, ma deve anche chiamare WifiConfig_ReloadConfig per aggiornare immediatamente la rete. Ciò è particolarmente importante quando l'applicazione aggiorna un certificato.

Eliminare una rete EAP-TLS

Un'app può eliminare una rete chiamando WifiConfig_ForgetNetworkById o WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById disconnette la rete se è connessa e la rimuove dal dispositivo. Tuttavia, non aggiorna la configurazione Wi-Fi, quindi la modifica non viene mantenuta durante il riavvio. L'app deve chiamare WifiConfig_PersistConfig per rendere permanente la rimozione.

WifiConfig_ForgetAllNetworks disconnette la rete connessa e rimuove tutte le reti dal dispositivo. Questa modifica persiste nel riavvio.

Campioni

  • App di alto livello Certificati - Mostra come usare e gestire i certificati in un'applicazione di alto livello Azure Sphere.
  • Wifi_HighLevelApp : viene illustrato come connettersi a una rete Wi-Fi e controllare lo stato della rete in un dispositivo MT3620.

Nota

Il seguente esempio proviene dalla Raccolta sfere di Azure, che è una raccolta di campioni hardware e software non mantenuti di Microsoft. Per ulteriori informazioni, vedi Raccolta sfere di Azure.