Set up EAP-TLS network in an app

  • Article

You can configure an EAP-TLS in a high-level application or manually, using az sphere commands. To configure and connect to the network, an application uses the Certstore and WifiConfig APIs.

Requirements

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.

Header files

Your app must include the following header:

#include <applibs/wificonfig.h>

If the application calls the CertStore API to manage certificates, it also must include the CertStore header. This header is not required to use the WifiConfig functions such as WifiConfig_GetRootCACertStoreIdentifier that retrieve certificate information.

#include <applibs/certstore.h>

Application manifest

The application manifest must enable the EnterpriseWiFiConfig capability to set up an EAP-TLS network. It also must have the WifiConfig capability to use WifiConfig_* functions that do not manage EAP-TLS features. Finally, if the app also manages certificates, it must enable the CertStore capability.

Don't enable capabilities that the application doesn't require; this poses a security risk. If the certificates will be updated manually, do not specify CertStore. Use this capability only if the application is responsible for storing and managing certificates on the device.

The following example shows how to set all three capabilities in the app_manifest.json file:

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

Certificates

The client certificate for your device must be available on the device. 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. Both certificates must be in the .pem format, either PKCS1 or PKCS8. See EAP-TLS certificate acquisition and deployment to learn about the certificates and where to get them.

Install certificates

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. Acquire and deploy certificates for EAP-TLS networks describes strategies for acquiring certificates and loading them onto a device as PEM files. Acquisition and deployment of certificates is your responsibility; check with your network administrator for details.

After the certificates are on the device, an application can install them for use. The Certificates sample shows how to install them. The following are the basic steps:

  • Make sure there's enough space in the certificate store. Certificate store space is limited, so the app should call CertStore_GetAvailableSpace before it tries to install a certificate. If sufficient space is not available, the app should delete an existing certificate to make room for the new one. Certificate space is limited to 24 KiB.

  • To install a Root CA certificate, call CertStore_InstallRootCACertificate. 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. A Root CA certificate is required if the network enables mutual authentication. Identifiers can include uppercase letters, lowercase letters, the digits 0-9, period (.), hyphen (-), and underscore (_). The maximum length of an identifier is 16 characters.

  • To install a client certificate, call CertStore_InstallClientCertificate. 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.

To update a certificate, the app can use the CertStore_MoveCertificate function. This function moves one certificate to another by overwriting the contents of an the existing destination certificate with the contents of the source certificate. Both certificates must already be installed in the certificate store. Certificate life cycle and renewal outlines strategies for updating certificates while avoiding network downtime.

Configure and set up an EAP-TLS network

The Wifi_HighLevelApp sample shows how to create, configure, and enable an EAP-TLS network. The sample assumes that the certificates are already in the certificate store, as described in Install certificates.

To configure and set up the network, an app should follow these basic steps:

  • Add a network by calling WifiConfig_AddNetwork. This function simply creates a network; it does not configure any characteristics for the network.

  • Set the security type for the network by calling WifiConfig_SetSecurityType. For an EAP-TLS network, the security type must be WifiConfig_Security_Wpa2_EAP_TLS.

  • Set the SSID for the network by calling WifiConfig_SetSSID. If the SSID isn't already known, the app can scan for it. 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. It can then call WifiConfig_TriggerScanAndGetScannedNetworkCount to scan for all networks and WifiConfig_GetScannedNetworks to get the results of the scan. WifiConfig_GetScannedNetworks returns an array of structures that contain details about each network. The application can search the results for a network with the WifiConfig_Security_Wpa2_EAP_TLS security type and then retrieve its SSID.

  • Set the configuration name for the network by calling WifiConfig_SetConfigName. The configuration name is a friendly name that the app can use to identify this network configuration.

  • Set the name of the Root CA certificate for the RADIUS server by calling WifiConfig_SetRootCACertStoreIdentifier, if the network requires server authentication. The Root CA certificate must already be present on the device.

  • Set the name of the client certificate store by calling WifiConfig_SetClientCertStoreIdentifier. The client certificate must already be present on the device.

  • Set the client identity by calling WifiConfig_SetClientIdentity. The client identity is a friendly name that identifies the client device.

  • Enable the network by calling WifiConfig_SetNetworkEnabled.

  • Save the network configuration by calling WifiConfig_PersistConfig. This function saves the network configuration on the device so that it persists over a reboot.

Change the properties of an EAP-TLS network

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.

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. This is particularly important when the application updates a certificate.

Delete an EAP-TLS network

An app can delete a network by calling either WifiConfig_ForgetNetworkById or WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById disconnects the network if it's connected and removes it from the device. However, it doesn't update the Wi-Fi configuration, so the change doesn't persist across reboot. The app must call WifiConfig_PersistConfig to make the removal permanent.

WifiConfig_ForgetAllNetworks disconnects the connected network and removes all networks from the device. This change persists across reboot.

Samples

  • Certificates high-level app - Demonstrates how to use and manage certificates in an Azure Sphere high-level application.
  • Wifi_HighLevelApp - Demonstrates how to connect to a Wi-Fi network and check the network status on an MT3620 device.

Note

The following sample is from the Azure Sphere Gallery, which is a collection of unmaintained software and hardware samples from Microsoft. For more information, see Azure Sphere Gallery.