Configurar la red EAP-TLS en una aplicación

Puede configurar un EAP-TLS en una aplicación de alto nivel o manualmente, usando az sphere comandos. Para configurar y conectarse a la red, una aplicación usa las API Certstore y WifiConfig .

Requisitos

Para configurar una red EAP-TLS, su aplicación de alto nivel debe incluir los archivos de encabezado adecuados, habilitar las capacidades necesarias en su manifiesto de aplicación, y tener acceso a los certificados que se requieren para la autenticación.

Archivos de encabezado

La aplicación debe incluir el siguiente encabezado:

#include <applibs/wificonfig.h>

Si la aplicación llama a la API CertStore para administrar certificados, también debe incluir el encabezado CertStore. Este encabezado no es necesario para usar las funciones WifiConfig , como WifiConfig_GetRootCACertStoreIdentifier que recuperan información del certificado.

#include <applibs/certstore.h>

Manifiesto de la aplicación

El manifiesto de la aplicación debe habilitar la capacidad EnterpriseWiFiConfig para configurar una red EAP-TLS. También debe tener la capacidad WifiConfig para usar funciones WifiConfig_* que no administran las características EAP-TLS. Por último, si la aplicación también administra certificados, debe habilitar la funcionalidad CertStore.

No habilite las funcionalidades que la aplicación no requiere; esto supone un riesgo para la seguridad. Si los certificados se actualizarán manualmente, no especifique CertStore. Use esta funcionalidad solo si la aplicación es responsable de almacenar y administrar certificados en el dispositivo.

En el ejemplo siguiente se muestra cómo establecer las tres capacidades en el archivo app_manifest.json:

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

Certificados

El certificado de cliente del dispositivo debe estar disponible en el dispositivo. Además, si la red EAP-TLS se configura para la autenticación mutua, el certificado de CA raíz para el servidor RADIUS de su red también se debe instalar en el dispositivo. Ambos certificados deben tener el formato .pem, ya sea PKCS1 o PKCS8. Consulte adquisición e implementación de certificados EAP-TLS para aprender sobre los certificados y dónde obtenerlos.

Instalar certificados

Antes de que su aplicación pueda configurar una red EAP-TLS, debe tener acceso a la CA raíz y a los certificados de cliente para utilizar para la autenticación. Adquirir e implementar certificados para redes EAP-TLS describe estrategias para adquirir certificados y cargarlos en un dispositivo como archivos PEM. La adquisición e implementación de certificados es su responsabilidad; consulta con el administrador de red para obtener más información.

Una vez que los certificados estén en el dispositivo, una aplicación puede instalarlos para su uso. El ejemplo certificados muestra cómo instalarlos. Estos son los pasos básicos:

• Asegúrese de que hay suficiente espacio en el almacén de certificados. El espacio del almacén de certificados es limitado, por lo que la aplicación debe llamar a CertStore_GetAvailableSpace antes de intentar instalar un certificado. Si no hay suficiente espacio disponible, la aplicación debe eliminar un certificado existente para liberar espacio para el nuevo. El espacio del certificado está limitado a 24 KiB.

• Para instalar un certificado de CA raíz, llame a CertStore_InstallRootCACertificate. La aplicación proporciona un puntero al contenido del certificado junto con un identificador que puede usar más adelante como un nombre descriptivo para el certificado. Se requiere un certificado de CA raíz si la red habilita la autenticación mutua. Los identificadores pueden incluir letras mayúsculas, minúsculas, los dígitos 0-9, punto (.), guión (-) y subrayado (_). La longitud máxima de un identificador es de 16 caracteres.

• Para instalar un certificado de cliente, llame a CertStore_InstallClientCertificate. Al igual que con el certificado de CA raíz, la aplicación proporciona un puntero al contenido del certificado junto con un identificador que puede utilizar más adelante como un nombre descriptivo para el certificado. La aplicación también debe proporcionar la clave privada y, si la clave está cifrada, la contraseña de cifrado.

Para actualizar un certificado, la aplicación puede usar la función CertStore_MoveCertificate . Esta función mueve un certificado a otro sobrescribiendo el contenido de un certificado de destino existente con el contenido del certificado de origen. Ambos certificados ya deben estar instalados en el almacén de certificados. El ciclo de vida y la renovación del certificado describen las estrategias para actualizar certificados y evitar el tiempo de inactividad de la red.

Configurar y configurar una red EAP-TLS

La Wifi_HighLevelApp muestra cómo crear, configurar y habilitar una red EAP-TLS. En el ejemplo se supone que los certificados ya están en el almacén de certificados, como se describe en Instalar certificados.

Para configurar y configurar la red, una aplicación debe seguir estos pasos básicos:

• Agregue una red llamando a WifiConfig_AddNetwork. Esta función simplemente crea una red; no configura ninguna característica para la red.

• Establezca el tipo de seguridad de la red llamando a WifiConfig_SetSecurityType. Para una red EAP-TLS, el tipo de seguridad debe ser WifiConfig_Security_Wpa2_EAP_TLS.

• Establezca el SSID para la red llamando a WifiConfig_SetSSID. Si aún no se conoce el SSID, la aplicación puede buscarlo. Si es probable que el entorno de red sea ruidoso o que el SSID no se difunda, la aplicación debe habilitar la detección dirigida llamando a WifiConfig_SetTargetedScanEnabled. A continuación, puede llamar a WifiConfig_TriggerScanAndGetScannedNetworkCount para buscar todas las redes y WifiConfig_GetScannedNetworks para obtener los resultados del análisis. WifiConfig_GetScannedNetworks devuelve una matriz de estructuras que contienen detalles sobre cada red. La aplicación puede buscar en los resultados una red con el WifiConfig_Security_Wpa2_EAP_TLS tipo de seguridad y luego recuperar su SSID.

• Establezca el nombre de configuración para la red llamando a WifiConfig_SetConfigName. El nombre de configuración es un nombre descriptivo que la aplicación puede usar para identificar esta configuración de red.

• Establezca el nombre del certificado de CA raíz para el servidor RADIUS llamando a WifiConfig_SetRootCACertStoreIdentifier, si la red requiere autenticación del servidor. El certificado de CA raíz ya debe estar presente en el dispositivo.

• Establezca el nombre del almacén de certificados de cliente llamando a WifiConfig_SetClientCertStoreIdentifier. El certificado de cliente debe estar ya presente en el dispositivo.

• Establezca la identidad del cliente llamando a WifiConfig_SetClientIdentity. La identidad de cliente es un nombre descriptivo que identifica el dispositivo cliente.

• Habilite la red llamando a WifiConfig_SetNetworkEnabled.

• Guarde la configuración de red llamando a WifiConfig_PersistConfig. Esta función guarda la configuración de red en el dispositivo para que persista durante un reinicio.

Cambiar las propiedades de una red EAP-TLS

La aplicación puede cambiar las propiedades de la red llamando a las mismas funciones usadas originalmente para establecerlas, como se muestra en Configurar y configurar una red EAP-TLS.

Después de cambiar las propiedades, la aplicación no solo debe llamar a WifiConfig_PersistConfig para guardar la configuración, sino que también debe llamar a WifiConfig_ReloadConfig para actualizar la red inmediatamente. Esto es especialmente importante cuando la aplicación actualiza un certificado.

Eliminar una red EAP-TLS

Una aplicación puede eliminar una red llamando a WifiConfig_ForgetNetworkById o WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById desconecta la red si está conectada y la quita del dispositivo. Sin embargo, no actualiza la configuración de Wi-Fi, por lo que el cambio no se conserva en el reinicio. La aplicación debe llamar a WifiConfig_PersistConfig para que la eliminación sea permanente.

WifiConfig_ForgetAllNetworks desconecta la red conectada y quita todas las redes del dispositivo. Este cambio continúa durante el reinicio.

Muestras

• Aplicación de alto nivel de certificados : muestra cómo usar y administrar certificados en una aplicación de alto nivel de Azure Sphere.
• Wifi_HighLevelApp : muestra cómo conectarse a una red Wi-Fi y comprobar el estado de la red en un dispositivo MT3620.

• Solución EAP-TLS con Azure Sphere - Demuestra cómo conectar los dispositivos azure sphere a las redes EAP-TLS.