Configurar a rede EAP-TLS em um aplicativo

Você pode configurar um EAP-TLS em um aplicativo de alto nível ou manualmente, usando comandos azsphere. Para configurar e conectar-se à rede, um aplicativo usa as APIs Certstore e WifiConfig.

Requisitos

Para configurar uma rede EAP-TLS, seu aplicativo de alto nível precisa incluir os arquivos de cabeçalho apropriados, habilitar as funcionalidades necessárias no manifesto do aplicativo dele e ter acesso aos certificados necessários para autenticação.

Arquivos de cabeçalho

Seu aplicativo deve incluir o seguinte cabeçalho:

#include <applibs/wificonfig.h>

Se o aplicativo chamar a API CertStore para gerenciar certificados, ele também deverá incluir o cabeçalho CertStore. Esse cabeçalho não é necessário para usar as funções WifiConfig como WifiConfig_GetRootCACertStoreIdentifier que recuperam as informações do certificado.

#include <applibs/certstore.h>

Manifesto do aplicativo

O manifesto do aplicativo devem habilitar a funcionalidade EnterpriseWiFiConfig para configurar uma rede EAP-TLS. Ele também deve ter a funcionalidade WifiConfig para usar funções WifiConfig_ * que não gerenciam recursos EAP-TLS. Por fim, se o aplicativo também gerenciar certificados, ele deverá habilitar a funcionalidade CertStore.

Não habilite funcionalidades que o aplicativo não requer; isso representa um risco de segurança. Se os certificados forem atualizados manualmente, não especifique CertStore. Use essa funcionalidade somente se o aplicativo for responsável por armazenar e gerenciar certificados no dispositivo.

O seguinte exemplo mostra como definir todas as três funcionalidades no arquivo app_manifest.json:

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

Certificados

O certificado do cliente para seu dispositivo deve estar disponível no dispositivo. Além disso, se a rede EAP-TLS estiver configurada para autenticação mútua, o Certificado de Autoridade de Certificação raiz do servidor RADIUS da rede também deverá ser instalado no dispositivo. Os dois certificados devem estar no formato .pem, seja PKCS1 ou PKCS8. Confira Aquisição e implantação de certificado EAP-TLS para saber mais sobre os certificados e onde obtê-los.

Instalar certificados

Antes que seu aplicativo possa configurar uma rede EAP-TLS, ele deve ter acesso aos certificados de Autoridade de Certificação raiz e do cliente a serem usados para autenticação. Adquirir e implantar certificados para redes EAP-TLS descreve estratégias para adquirir certificados e carregá-los em um dispositivo como arquivos PEM. A aquisição e a implantação de certificados são sua responsabilidade; consulte o administrador da rede para obter detalhes.

Depois que os certificados estiverem no dispositivo, um aplicativo poderá instalá-los para uso. O exemplo Certificados mostra como instalá-los. As seguintes etapas básicas estão descritas:

• Verifique se há espaço suficiente no repositório de certificados. O espaço do repositório de certificados é limitado, portanto, o aplicativo deve chamar CertStore_GetAvailableSpace antes de tentar instalar um certificado. Se não houver espaço suficiente disponível, o aplicativo deverá excluir um certificado existente para liberar espaço para o novo. O espaço do certificado é limitado a 24 KiB.

• Para instalar um Certificado de Autoridade de Certificação raiz, chame CertStore_InstallRootCACertificate. O aplicativo fornece um ponteiro para o conteúdo do certificado junto com um identificador que ele pode usar posteriormente como um nome amigável para o certificado. Um Certificado de Autoridade de Certificação raiz será necessário se a rede habilitar a autenticação mútua. Os identificadores podem incluir letras maiúsculas, letras minúsculas, dígitos de 0 a 9, ponto final (.), hífen (-) e sublinhado (_). O comprimento máximo do identificador é 16 caracteres.

• Para instalar um certificado do cliente, chame CertStore_InstallClientCertificate. Assim como ocorre com o Certificado de Autoridade de Certificação raiz, o aplicativo fornece um ponteiro para o conteúdo do certificado junto com um identificador que ele pode usar posteriormente como um nome amigável para o certificado. O aplicativo também deverá fornecer a chave privada e, se a chave for criptografada, a senha de criptografia.

Para atualizar um certificado, o aplicativo pode usar a função CertStore_MoveCertificate. Essa função move um certificado para outro, substituindo o conteúdo de um certificado de destino existente pelo conteúdo do certificado de origem. Os dois certificados já devem estar instalados no repositório de certificados. Ciclo de vida e renovação do certificado descreve as estratégias para a atualização de certificados, evitando, ao mesmo tempo, o tempo de inatividade da rede.

Configurar uma rede EAP-TLS

O exemplo Wifi_HighLevelApp mostra como criar, configurar e habilitar uma rede EAP-TLS. O exemplo pressupõe que os certificados já estejam no repositório de certificados, conforme descrito em Instalar certificados.

Para configurar a rede, um aplicativo deve seguir estas etapas básicas:

• Adicione uma rede chamando WifiConfig_AddNetwork. Essa função simplesmente cria uma rede; ela não configura nenhuma característica para ela.

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

• Defina o SSID da rede chamando WifiConfig_SetSSID. Se o SSID ainda não for conhecido, o aplicativo poderá verificar se ele existe. Se o ambiente de rede provavelmente estiver com ruído ou se o SSID não puder ser difundido, o aplicativo deverá habilitar a verificação direcionada chamando WifiConfig_SetTargetedScanEnabled. Em seguida, ele poderá chamar WifiConfig_TriggerScanAndGetScannedNetworkCount para verificar se todas as redes existem e WifiConfig_GetScannedNetworks o para obter os resultados da verificação. WifiConfig_GetScannedNetworks retorna uma matriz de estruturas que contêm detalhes sobre cada rede. O aplicativo pode pesquisar, nos resultados, uma rede com o tipo de segurança WifiConfig_Security_Wpa2_EAP_TLS e recuperar o SSID dela.

• Defina o nome da configuração da rede chamando WifiConfig_SetConfigName. O nome da configuração é um nome amigável que o aplicativo pode usar para identificar essa configuração de rede.

• Defina o nome do Certificado de Autoridade de Certificação raiz para o servidor RADIUS chamando WifiConfig_SetRootCACertStoreIdentifier, se a rede exigir autenticação do servidor. O Certificado de Autoridade de Certificação raiz já deve estar presente no dispositivo.

• Defina o nome do repositório de certificados do cliente chamando WifiConfig_SetClientCertStoreIdentifier. O certificado do cliente já deve estar presente no dispositivo.

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

• Habilite a rede chamando WifiConfig_SetNetworkEnabled.

• Salve a configuração da rede chamando WifiConfig_PersistConfig. Essa função salva a configuração da rede no dispositivo para que ela persista durante uma reinicialização.

Alterar as propriedades de uma rede EAP-TLS

O aplicativo pode alterar as propriedades da rede chamando as mesmas funções usadas para defini-las originalmente, conforme listado em Configurar uma rede EAP-TLS.

Após alterar as propriedades, o aplicativo não deve apenas chamar WifiConfig_PersistConfig para salvar a configuração, mas também deve chamar WifiConfig_ReloadConfig para atualizar a rede imediatamente. Isso é particularmente importante quando o aplicativo atualiza um certificado.

Excluir uma rede EAP-TLS

Um aplicativo pode excluir uma rede chamando WifiConfig_ForgetNetworkById ou WifiConfig_ForgetAllNetworks.

WifiConfig_ForgetNetworkById desconectará a rede se ela estiver conectada e a removerá do dispositivo. No entanto, ele não atualizará a configuração de Wi-Fi, portanto, a alteração não persistirá na reinicialização. O aplicativo deve chamar WifiConfig_PersistConfig para tornar a remoção permanente.

WifiConfig_ForgetAllNetworks desconecta a rede conectada e remove todas as redes do dispositivo. Essa alteração persiste na reinicialização.

Amostras

• Aplicativo de alto nível de certificados – demonstra como usar e gerenciar certificados em um aplicativo de alto nível do Azure Sphere.
• Wifi_HighLevelApp – Demonstra como se conectar a uma rede Wi-Fi e verificar o status da rede em um dispositivo MT3620.

• Solução EAP-TLS com o Azure Sphere – demonstra como conectar dispositivos do Azure Sphere a redes EAP-TLS.