Partilhar via

Configurar a rede EAP-TLS numa aplicação

  • Artigo

Pode configurar um EAP-TLS numa aplicação de alto nível ou manualmente com az sphere comandos. Para configurar e ligar à rede, uma aplicação utiliza as APIs Certstore e WifiConfig .

Requisitos

Para configurar uma rede EAP-TLS, a sua aplicação de alto nível tem de incluir os ficheiros de cabeçalho adequados, ativar as capacidades necessárias no manifesto da aplicação e ter acesso aos certificados necessários para a autenticação.

Ficheiros de cabeçalho

A sua aplicação tem de incluir o seguinte cabeçalho:

#include <applibs/wificonfig.h>

Se a aplicação chamar a API CertStore para gerir certificados, também tem de incluir o cabeçalho CertStore. Este cabeçalho não é necessário para utilizar as funções WifiConfig , como WifiConfig_GetRootCACertStoreIdentifier que obtêm informações do certificado.

#include <applibs/certstore.h>

Manifesto da aplicação

O manifesto da aplicação tem de ativar a capacidade EnterpriseWiFiConfig para configurar uma rede EAP-TLS. Também tem de ter a capacidade wifiConfig de utilizar funções WifiConfig_* que não gerem funcionalidades EAP-TLS. Por fim, se a aplicação também gerir certificados, tem de ativar a capacidade CertStore.

Não ative as capacidades de que a aplicação não necessita; isto representa um risco de segurança. Se os certificados forem atualizados manualmente, não especifique o CertStore. Utilize esta capacidade apenas se a aplicação for responsável por armazenar e gerir certificados no dispositivo.

O exemplo seguinte mostra como definir as três capacidades no ficheiro app_manifest.json:

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

Certificados

O certificado de cliente do dispositivo tem de estar disponível no dispositivo. Além disso, se a rede EAP-TLS estiver configurada para autenticação mútua, o certificado de AC de Raiz para o servidor RADIUS da sua rede também tem de ser instalado no dispositivo. Ambos os certificados têm de estar no formato .pem, PKCS1 ou PKCS8. Veja Aquisição e implementação de certificados EAP-TLS para saber mais sobre os certificados e onde os obter.

Instalar certificados

Antes de a aplicação poder configurar uma rede EAP-TLS, tem de ter acesso à AC de Raiz e aos certificados de cliente para utilizar para autenticação. Adquirir e implementar certificados para redes EAP-TLS descreve estratégias para adquirir certificados e carregá-los num dispositivo como ficheiros PEM. A aquisição e implementação de certificados é da sua responsabilidade; contacte o administrador de rede para obter detalhes.

Depois de os certificados estarem no dispositivo, uma aplicação pode instalá-los para utilização. O exemplo certificados mostra como instalá-los. Seguem-se os passos básicos:

  • Certifique-se de que existe espaço suficiente no arquivo de certificados. O espaço no arquivo de certificados é limitado, pelo que a aplicação deve chamar CertStore_GetAvailableSpace antes de tentar instalar um certificado. Se não estiver disponível espaço suficiente, a aplicação deverá eliminar um certificado existente para libertar espaço para o novo. O espaço do certificado está limitado a 24 KiB.

  • Para instalar um certificado de AC de Raiz, chame CertStore_InstallRootCACertificate. A aplicação fornece um ponteiro para o conteúdo do certificado, juntamente com um identificador que pode utilizar mais tarde como um nome amigável para o certificado. É necessário um certificado de AC de raiz se a rede ativar a autenticação mútua. Os identificadores podem incluir letras maiúsculas, letras minúsculas, os dígitos 0-9, ponto final (.), hífen (-) e caráter de sublinhado (_). O comprimento máximo de um identificador é de 16 carateres.

  • Para instalar um certificado de cliente, chame CertStore_InstallClientCertificate. Tal como acontece com o certificado da AC de Raiz, a aplicação fornece um ponteiro para o conteúdo do certificado, juntamente com um identificador que pode utilizar mais tarde como um nome amigável para o certificado. A aplicação também tem de fornecer a chave privada e, se a chave estiver encriptada, a palavra-passe de encriptação.

Para atualizar um certificado, a aplicação pode utilizar a função CertStore_MoveCertificate . Esta função move um certificado para outro ao substituir o conteúdo de um certificado de destino existente com o conteúdo do certificado de origem. Ambos os certificados já têm de estar instalados no arquivo de certificados. O ciclo de vida do certificado e a renovação descrevem estratégias para atualizar certificados, evitando simultaneamente o período de indisponibilidade da rede.

Configurar e configurar uma rede EAP-TLS

O exemplo de Wifi_HighLevelApp mostra como criar, configurar e ativar uma rede EAP-TLS. O exemplo pressupõe que os certificados já estão no arquivo de certificados, conforme descrito em Instalar certificados.

Para configurar e configurar a rede, uma aplicação deve seguir estes passos básicos:

  • Adicione uma rede ao chamar WifiConfig_AddNetwork. Esta função cria simplesmente uma rede; não configura quaisquer características para a rede.

  • Defina o tipo de segurança da rede ao chamar WifiConfig_SetSecurityType. Para uma rede EAP-TLS, o tipo de segurança tem de ser WifiConfig_Security_Wpa2_EAP_TLS.

  • Defina o SSID para a rede ao chamar WifiConfig_SetSSID. Se o SSID ainda não for conhecido, a aplicação pode analisá-lo. Se o ambiente de rede for provavelmente ruidoso ou se o SSID não for difundido, a aplicação deve ativar a análise direcionada ao chamar WifiConfig_SetTargetedScanEnabled. Em seguida, pode chamar WifiConfig_TriggerScanAndGetScannedNetworkCount para procurar todas as redes e WifiConfig_GetScannedNetworks para obter os resultados da análise. WifiConfig_GetScannedNetworks devolve uma matriz de estruturas que contêm detalhes sobre cada rede. A aplicação pode procurar nos resultados uma rede com o WifiConfig_Security_Wpa2_EAP_TLS tipo de segurança e, em seguida, obter o SSID.

  • Defina o nome da configuração da rede ao chamar WifiConfig_SetConfigName. O nome da configuração é um nome amigável que a aplicação pode utilizar para identificar esta configuração de rede.

  • Defina o nome do certificado da AC de Raiz para o servidor RADIUS ao chamar WifiConfig_SetRootCACertStoreIdentifier, se a rede necessitar de autenticação de servidor. O certificado da AC de raiz já tem de estar presente no dispositivo.

  • Defina o nome do arquivo de certificados de cliente ao chamar WifiConfig_SetClientCertStoreIdentifier. O certificado de cliente já tem de estar presente no dispositivo.

  • Defina a identidade do cliente ao chamar WifiConfig_SetClientIdentity. A identidade do cliente é um nome amigável que identifica o dispositivo cliente.

  • Ative a rede ao chamar WifiConfig_SetNetworkEnabled.

  • Guarde a configuração de rede ao chamar WifiConfig_PersistConfig. Esta função guarda a configuração de rede no dispositivo para que persista durante um reinício.

Alterar as propriedades de uma rede EAP-TLS

A aplicação pode alterar as propriedades da rede ao chamar as mesmas funções utilizadas para as definir originalmente, conforme listado em Configurar e configurar uma rede EAP-TLS.

Depois de alterar as propriedades, a aplicação não só pode chamar WifiConfig_PersistConfig para guardar a configuração, como também tem de chamar WifiConfig_ReloadConfig para atualizar a rede imediatamente. Isto é particularmente importante quando a aplicação atualiza um certificado.

Eliminar uma rede EAP-TLS

Uma aplicação pode eliminar uma rede ao chamar WifiConfig_ForgetNetworkById ou WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById desliga a rede se estiver ligada e remove-a do dispositivo. No entanto, não atualiza a configuração do Wi-Fi, pelo que a alteração não persiste durante o reinício. A aplicação tem de chamar WifiConfig_PersistConfig para tornar a remoção permanente.

WifiConfig_ForgetAllNetworks desliga a rede ligada e remove todas as redes do dispositivo. Esta alteração persiste durante o reinício.

Exemplos

Nota

O exemplo seguinte é da Galeria do Azure Sphere, que é uma coleção de exemplos de software e hardware não suportados da Microsoft. Para obter mais informações, veja Galeria do Azure Sphere.