Configuración de una red EAP-TLS en una aplicación
Importante
Esta es la documentación de Azure Sphere (heredado). Azure Sphere (heredado) se retira el 27 de septiembre de 2027 y los usuarios deben migrar a Azure Sphere (integrado) en este momento. Use el selector de versiones situado encima de la TOC para ver la documentación de Azure Sphere (integrado).
Una red EAP-TLS se puede configurar en una aplicación de alto nivel o bien de forma manual mediante comandos azsphere. Para configurar y conectarse a la red, una aplicación usa las API Certstore y WifiConfig.
Para configurar una red EAP-TLS, la aplicación de alto nivel debe incluir los archivos de encabezado adecuados, habilitar las funcionalidades requeridas en el manifiesto de aplicación y tener acceso a los certificados necesarios para la autenticación.
La aplicación debe incluir el siguiente encabezado:
#include <applibs/wificonfig.h>
Si la aplicación llama a CertStore API para administrar los certificados, también debe incluir el encabezado CertStore. Este encabezado no es necesario para usar las funciones WifiConfig, como WifiConfig_GetRootCACertStoreIdentifier, que recupera la información del certificado.
#include <applibs/certstore.h>
El manifiesto de aplicación debe habilitar la funcionalidad EnterpriseWiFiConfig para configurar una red EAP-TLS. También debe disponer de la funcionalidad WifiConfig para usar las funciones WifiConfig_* que no administran las características de EAP-TLS. Por último, si la aplicación también administra certificados, debe habilitar la funcionalidad CertStore.
No habilite funcionalidades que la aplicación no necesite, esto supone un riesgo para la seguridad. Si los certificados se van a actualizar manualmente, no especifique CertStore. Use esta funcionalidad solo si la aplicación es responsable de almacenar y administrar los certificados en el dispositivo.
En el ejemplo siguiente se muestra cómo establecer las tres funcionalidades en el archivo app_manifest.json:
"Capabilities": {
"WifiConfig" : true,
"EnterpriseWiFiConfig" : true,
"CertStore" : true
}
El certificado de cliente del dispositivo debe estar disponible en el dispositivo. Además, si la red EAP-TLS está configurada para la autenticación mutua, también debe estar instalado en el dispositivo el certificado de entidad de certificación raíz del servidor RADIUS de la red. Ambos certificados deben estar en formato .pem, ya sea PKCS1 o PKCS8. Consulte Adquisición e implementación de certificados EAP-TLS para obtener información sobre los certificados y dónde obtenerlos.
Antes de que la aplicación pueda configurar una red EAP-TLS, debe tener acceso a la entidad de certificación raíz y a los certificados de cliente que se usarán para la autenticación. En Adquisición e implementación de certificados para redes EAP-TLS, se describen estrategias para adquirir certificados y cargarlos en un dispositivo como archivos PEM. La adquisición e implementación de certificados es su responsabilidad, consulte con el administrador de la red para más información.
Una vez que los certificados están en el dispositivo, una aplicación puede instalarlos para su uso. En el ejemplo Certificados se muestra cómo instalarlos. Estos son los pasos básicos:
Asegúrese de que hay espacio suficiente 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 dejar espacio para el nuevo. El espacio de certificados está limitado a 24 KiB.
Para instalar un certificado de entidad de certificación raíz, llame a CertStore_InstallRootCACertificate. La aplicación proporciona un puntero al contenido del certificado junto con un identificador que se puede usar más adelante como un nombre descriptivo para el certificado. Se requiere un certificado de entidad de certificación raíz si la red habilita la autenticación mutua. Los identificadores pueden incluir letras mayúsculas, letras minúsculas, los dígitos 0-9, el punto (.), el guion (-) y el carácter de 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 entidad de certificación raíz, la aplicación proporciona un puntero al contenido del certificado junto con un identificador que se puede usar 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 y sobrescribe el contenido del certificado de destino existente con el contenido del certificado de origen. Ambos certificados ya deben estar instalados en el almacén de certificados. En Ciclo de vida y renovación del certificado se describen las estrategias para actualizar certificados y evitar un tiempo de inactividad de la red.
En el ejemplo Wifi_HighLevelApp se 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 Instalación de certificados.
Para instalar y configurar la red, una aplicación debe seguir estos pasos básicos:
Agregue una red mediante una llamada a WifiConfig_AddNetwork. Esta función simplemente crea una red, no configura ninguna característica de la red.
Establezca el tipo de seguridad de la red mediante una llamada a WifiConfig_SetSecurityType. En el caso de una red EAP-TLS, el tipo de seguridad debe ser
WifiConfig_Security_Wpa2_EAP_TLS.Establezca el SSID de la red mediante una llamada a WifiConfig_SetSSID. Si el SSID todavía no se conoce, la aplicación puede buscarlo. Si es probable que el entorno de red tenga ruido o si no se puede difundir el SSID, la aplicación debe habilitar el examen dirigido mediante una llamada a WifiConfig_SetTargetedScanEnabled. A continuación, puede llamar a WifiConfig_TriggerScanAndGetScannedNetworkCount para examinar todas las redes y a WifiConfig_GetScannedNetworks para obtener los resultados del examen. 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 tipo de seguridad
WifiConfig_Security_Wpa2_EAP_TLSy, a continuación, recuperar su SSID.Establezca el nombre de configuración de la red mediante una llamada a WifiConfig_SetConfigName. El nombre de configuración es un nombre descriptivo que la aplicación puede utilizar para identificar esta configuración de red.
Si la red requiere autenticación de servidor, establezca el nombre del certificado de entidad de certificación raíz del servidor RADIUS mediante una llamada a WifiConfig_SetRootCACertStoreIdentifier. El certificado de entidad de certificación raíz ya debe estar presente en el dispositivo.
Establezca el nombre del almacén de certificados de cliente mediante una llamada a WifiConfig_SetClientCertStoreIdentifier. El certificado de cliente ya debe estar presente en el dispositivo.
Establezca la identidad del cliente mediante una llamada a WifiConfig_SetClientIdentity. La identidad del cliente es un nombre descriptivo que identifica el dispositivo cliente.
Habilite la red mediante una llamada a WifiConfig_SetNetworkEnabled.
Guarde la configuración de red mediante una llamada a WifiConfig_PersistConfig. Esta función guarda la configuración de red en el dispositivo para que se conserve después de un reinicio.
La aplicación puede cambiar las propiedades de la red mediante una llamada a las mismas funciones usadas para establecerlas originalmente, como se indica en Instalación y configuración de 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.
Una aplicación puede eliminar una red mediante una llamada a WifiConfig_ForgetNetworkById o una llamada a WifiConfig_ForgetAllNetworks.
WifiConfig_ForgetNetworkById desconecta la red si está conectada y la elimina del dispositivo. Sin embargo, no actualiza la configuración Wi-Fi, por lo que el cambio no se conserva después de un reinicio. La aplicación debe llamar a WifiConfig_PersistConfig para que la eliminación sea permanente.
WifiConfig_ForgetAllNetworks desconecta la red conectada y elimina todas las redes del dispositivo. Este cambio se conserva después de un reinicio.
- 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.
Nota
El ejemplo siguiente es de la Galería de Azure Sphere, que es una colección de ejemplos de hardware y software no retenidos de Microsoft. Para más información, consulte Galería de Azure Sphere.