Configurare la rete EAP-TLS in un'appSet up EAP-TLS network in an app

È possibile configurare una rete EAP-TLS in un'applicazione di alto livello oppure manualmente, usando i comandi azsphere.You can configure an EAP-TLS in a high-level application or manually, using azsphere commands. Per configurare e connettersi alla rete, l'applicazione usa le API CertStore e WifiConfig.To configure and connect to the network, an application uses the Certstore and WifiConfig APIs.

RequisitiRequirements

Per configurare una rete EAP-TLS, l'app di alto livello deve includere i file di intestazione appropriati, abilitare le funzionalità richieste nel proprio manifesto e avere accesso ai certificati necessari per l'autenticazione.To configure an EAP-TLS network, your high-level app needs to include the appropriate header files, enable the required capabilities in its application manifest, and have access to the certificates that are required for authentication.

File di intestazioneHeader files

L'app deve includere l'intestazione seguente:Your app must include the following header:

#include <applibs/wificonfig.h>

Se l'applicazione chiama l'API CertStore per gestire i certificati, deve includere anche l'intestazione CertStore.If the application calls the CertStore API to manage certificates, it also must include the CertStore header. Questa intestazione non è necessaria per usare le funzioni WifiConfig, ad esempio WifiConfig_GetRootCACertStoreIdentifier, che recuperano le informazioni sul certificato.This header is not required to use the WifiConfig functions such as WifiConfig_GetRootCACertStoreIdentifier that retrieve certificate information.

#include <applibs/certstore.h>

Manifesto dell'applicazioneApplication manifest

Il manifesto dell'applicazione deve abilitare la funzionalità EnterpriseWiFiConfig per configurare una rete EAP-TLS.The application manifest must enable the EnterpriseWiFiConfig capability to set up an EAP-TLS network. Deve inoltre avere la funzionalità WifiConfig per usare le funzioni WifiConfig_ * che non gestiscono le funzionalità EAP-TLS.It also must have the WifiConfig capability to use WifiConfig_* functions that do not manage EAP-TLS features. Infine, se l'app gestisce anche i certificati, deve abilitare la funzionalità CertStore.Finally, if the app also manages certificates, it must enable the CertStore capability.

Non abilitare le funzionalità non necessarie per l'applicazione, altrimenti si verificano rischi per la sicurezza.Don't enable capabilities that the application doesn't require; this poses a security risk. Se i certificati verranno aggiornati manualmente, non specificare CertStore.If the certificates will be updated manually, do not specify CertStore. Usare questa funzionalità solo se l'applicazione è responsabile dell'archiviazione e della gestione dei certificati nel dispositivo.Use this capability only if the application is responsible for storing and managing certificates on the device.

L'esempio seguente illustra come impostare tutte e tre le funzionalità nel file app_manifest.json:The following example shows how to set all three capabilities in the app_manifest.json file:

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

CertificatiCertificates

Il certificato client deve essere disponibile nel dispositivo.The client certificate for your device must be available on the device. 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.In addition, if the EAP-TLS network is configured for mutual authentication, the Root CA certificate for your network's RADIUS server must also be installed on the device. Entrambi i certificati devono essere nel formato PEM, con la sintassi PKCS1 o PKCS8.Both certificates must be in the .pem format, either PKCS1 or PKCS8. Per informazioni sui certificati e su dove ottenerli, vedere Acquisizione e distribuzione di certificati EAP-TLS.See EAP-TLS certificate acquisition and deployment to learn about the certificates and where to get them.

Installare i certificatiInstall certificates

Prima di configurare una rete EAP-TLS, è necessario che l'app abbia accesso al certificato client e a quello CA radice da usare per l'autenticazione.Before your app can set up an EAP-TLS network, it must have access to the Root CA and client certificates to use for authentication. Per informazioni sulle strategie per l'acquisizione e il caricamento dei certificati in un dispositivo come file PEM, vedere Acquisire e distribuire i certificati per le reti EAP-TLS.Acquire and deploy certificates for EAP-TLS networks describes strategies for acquiring certificates and loading them onto a device as PEM files. L'acquisizione e la distribuzione dei certificati sono responsabilità dell'utente. Per informazioni dettagliate, rivolgersi all'amministratore di rete.Acquisition and deployment of certificates is your responsibility; check with your network administrator for details.

Quando i certificati sono disponibili nel dispositivo, l'applicazione può installarli per l'uso.After the certificates are on the device, an application can install them for use. L'esempio Certificates mostra come installarli.The Certificates sample shows how to install them. Ecco i passaggi di base:The following are the basic steps:

  • Assicurarsi che lo spazio disponibile nell'archivio certificati sia sufficiente.Make sure there's enough space in the certificate store. Lo spazio dell'archivio certificati è limitato, quindi l'app deve chiamare CertStore_GetAvailableSpace prima di provare a installare un certificato.Certificate store space is limited, so the app should call CertStore_GetAvailableSpace before it tries to install a certificate. Se non è disponibile spazio sufficiente, l'app deve eliminare un certificato esistente per fare spazio per quello nuovo.If sufficient space is not available, the app should delete an existing certificate to make room for the new one. Lo spazio dei certificati è limitato a 24 KiB.Certificate space is limited to 24 KiB.

  • Per installare un certificato CA radice, chiamare CertStore_InstallRootCACertificate.To install a Root CA certificate, call CertStore_InstallRootCACertificate. L'app fornisce un puntatore al contenuto del certificato insieme a un identificatore che può usare in seguito come nome descrittivo per il certificato.The app supplies a pointer to the certificate content along with an identifier that it can use later as a friendly name for the certificate. Se la rete consente l'autenticazione reciproca, è necessario un certificato CA radice.A Root CA certificate is required if the network enables mutual authentication. Gli identificatori possono includere lettere maiuscole, lettere minuscole, numeri da 0 a 9, punto (.), trattino (-) e carattere di sottolineatura ().Identifiers can include uppercase letters, lowercase letters, the digits 0-9, period (.), hyphen (-), and underscore (). La lunghezza massima dell'identificatore è 16 caratteri.The maximum length of an identifier is 16 characters.

  • Per installare un certificato client, chiamare CertStore_InstallClientCertificate.To install a client certificate, call CertStore_InstallClientCertificate. Come per il certificato CA radice, l'app fornisce un puntatore al contenuto del certificato insieme a un identificatore che può usare in seguito come nome descrittivo per il certificato. L'app deve anche fornire la chiave privata e, se è crittografata, la password di crittografia.As with the Root CA certificate, the app supplies a pointer to the certificate content along with an identifier that it can use later as a friendly name for the certificate.The app must also supply the private key and, if the key is encrypted, the encryption password.

Per aggiornare un certificato, l'app può usare la funzione CertStore_MoveCertificate.To update a certificate, the app can use the CertStore_MoveCertificate function. Questa funzione sposta un certificato in un altro sovrascrivendo il contenuto del certificato di destinazione esistente con il contenuto del certificato di origine.This function moves one certificate to another by overwriting the contents of an the existing destination certificate with the contents of the source certificate. Entrambi i certificati devono essere già installati nell'archivio certificati.Both certificates must already be installed in the certificate store. Per informazioni sulle strategie per l'aggiornamento dei certificati, evitando il tempo di inattività della rete, vedere Ciclo di vita e rinnovo dei certificati.Certificate life cycle and renewal outlines strategies for updating certificates while avoiding network downtime.

Impostare e configurare una rete EAP-TLSConfigure and set up an EAP-TLS network

L'esempio Wifi_HighLevelApp mostra come creare, configurare e abilitare una rete EAP-TLS.The Wifi_HighLevelApp sample shows how to create, configure, and enable an EAP-TLS network. L'esempio presuppone che i certificati siano già presenti nell'archivio certificati, come descritto in Installare i certificati.The sample assumes that the certificates are already in the certificate store, as described in Install certificates.

Per impostare e configurare la rete, un'app dovrà seguire questi passaggi di base:To configure and set up the network, an app should follow these basic steps:

  • Aggiungere una rete chiamando WifiConfig_AddNetwork.Add a network by calling WifiConfig_AddNetwork. Questa funzione crea semplicemente una rete, senza configurarne le caratteristiche.This function simply creates a network; it does not configure any characteristics for the network.

  • Impostare il tipo di sicurezza per la rete chiamando WifiConfig_SetSecurityType.Set the security type for the network by calling WifiConfig_SetSecurityType. Per una rete EAP-TLS, il tipo di sicurezza deve essere WifiConfig_Security_Wpa2_EAP_TLS.For an EAP-TLS network, the security type must be WifiConfig_Security_Wpa2_EAP_TLS.

  • Impostare l'SSID della rete chiamando WifiConfig_SetSSID.Set the SSID for the network by calling WifiConfig_SetSSID. Se l'SSID non è già noto, l'app può eseguire un'analisi per trovarlo.If the SSID isn't already known, the app can scan for it. Se l'ambiente di rete è rumoroso o se non è possibile trasmettere l'SSID, l'app deve abilitare l'analisi mirata chiamando WifiConfig_SetTargetedScanEnabled.If the network environment is likely to be noisy or if the SSID might not be broadcast, the app should enable targeted scanning by calling WifiConfig_SetTargetedScanEnabled. Può quindi chiamare WifiConfig_TriggerScanAndGetScannedNetworkCount per analizzare tutte le reti e WifiConfig_GetScannedNetworks per ottenere i risultati dell'analisi.It can then call WifiConfig_TriggerScanAndGetScannedNetworkCount to scan for all networks and WifiConfig_GetScannedNetworks to get the results of the scan. WifiConfig_GetScannedNetworks restituisce una matrice di strutture che contengono dettagli su ogni rete.WifiConfig_GetScannedNetworks returns an array of structures that contain details about each network. L'applicazione può cercare nei risultati una rete con il tipo di sicurezza WifiConfig_Security_Wpa2_EAP_TLS e quindi recuperare il relativo SSID.The application can search the results for a network with the WifiConfig_Security_Wpa2_EAP_TLS security type and then retrieve its SSID.

  • Impostare il nome della configurazione per la rete chiamando WifiConfig_SetConfigName.Set the configuration name for the network by calling WifiConfig_SetConfigName. Il nome della configurazione è un nome descrittivo che l'app può usare per identificare questa configurazione di rete.The configuration name is a friendly name that the app can use to identify this network configuration.

  • Impostare il nome del certificato CA radice per il server RADIUS chiamando WifiConfig_SetRootCACertStoreIdentifier, se la rete richiede l'autenticazione del server.Set the name of the Root CA certificate for the RADIUS server by calling WifiConfig_SetRootCACertStoreIdentifier, if the network requires server authentication. Il certificato CA radice deve essere già presente nel dispositivo.The Root CA certificate must already be present on the device.

  • Impostare il nome dell'archivio certificati client chiamando WifiConfig_SetClientCertStoreIdentifier.Set the name of the client certificate store by calling WifiConfig_SetClientCertStoreIdentifier. Il certificato client deve essere già presente nel dispositivo.The client certificate must already be present on the device.

  • Impostare l'identità del client chiamando WifiConfig_SetClientIdentity.Set the client identity by calling WifiConfig_SetClientIdentity. L'identità del client è un nome descrittivo che identifica il dispositivo client.The client identity is a friendly name that identifies the client device.

  • Abilitare la rete chiamando WifiConfig_SetNetworkEnabled.Enable the network by calling WifiConfig_SetNetworkEnabled.

  • Salvare la configurazione di rete chiamando WifiConfig_PersistConfig.Save the network configuration by calling WifiConfig_PersistConfig. Questa funzione salva la configurazione di rete nel dispositivo, in modo che venga mantenuta dopo il riavvio.This function saves the network configuration on the device so that it persists over a reboot.

Cambiare le proprietà di una rete EAP-TLSChange the properties of an EAP-TLS network

L'app può cambiare le proprietà della rete chiamando le stesse funzioni usate per impostarla in origine, come descritto in Impostare e configurare una rete EAP-TLS.The app can change the properties of the network by calling the same functions used to originally set them, as listed in Configure and set up an EAP-TLS network.

Dopo aver cambiato le proprietà, l'app deve chiamare non solo WifiConfig_PersistConfig per salvare la configurazione, ma anche WifiConfig_ReloadConfig per aggiornare immediatamente la rete.After changing properties, the app must not only call WifiConfig_PersistConfig to save the configuration, but also must call WifiConfig_ReloadConfig to update the network immediately. Questa procedura è particolarmente importante quando l'applicazione aggiorna un certificato.This is particularly important when the application updates a certificate.

Eliminare una rete EAP-TLSDelete an EAP-TLS network

Un'app può eliminare una rete chiamando WifiConfig_ForgetNetworkById o WifiConfig_ForgetAllNetworks.An app can delete a network by calling either WifiConfig_ForgetNetworkById or WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById disconnette la rete, se è connessa, e la rimuove dal dispositivo.WifiConfig_ForgetNetworkById disconnects the network if it's connected and removes it from the device. Tuttavia, non aggiorna la configurazione Wi-Fi, quindi la modifica non viene mantenuta dopo il riavvio.However, it doesn't update the Wi-Fi configuration, so the change doesn't persist across reboot. Per rendere permanente la rimozione, l'app deve chiamare WifiConfig_PersistConfig.The app must call WifiConfig_PersistConfig to make the removal permanent.

WifiConfig_ForgetAllNetworks disconnette la rete connessa e rimuove tutte le reti dal dispositivo.WifiConfig_ForgetAllNetworks disconnects the connected network and removes all networks from the device. Questa modifica viene mantenuta dopo il riavvio.This change persists across reboot.

EsempiSamples