Configurar a rede EAP-TLS em um aplicativo

  • Artigo

Você pode configurar um EAP-TLS em um aplicativo de alto nível ou manualmente, usando az sphere comandos. Para configurar e se conectar à 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 os recursos necessários em seu manifesto de aplicativo 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 do 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 informações de certificado.

#include <applibs/certstore.h>

Manifesto do aplicativo

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

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

O exemplo a seguir mostra como definir todos os três recursos 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 AC raiz do servidor RADIUS da sua rede também deverá ser instalado no dispositivo. Ambos os certificados devem estar no formato .pem, PKCS1 ou PKCS8. Consulte 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 à AC raiz e certificados de 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. Aquisição e implantação de certificados é sua responsabilidade; marcar com o administrador de 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. Veja a seguir as etapas básicas:

  • 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 o espaço suficiente não estiver disponível, o aplicativo deverá excluir um certificado existente para abrir espaço para o novo. O espaço de certificado é limitado a 24 KiB.

  • Para instalar um certificado de AC 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 AC raiz será necessário se a rede habilitar a autenticação mútua. Os identificadores podem incluir letras maiúsculas, letras minúsculas, os dígitos 0-9, período (.), hifen (-) e sublinhado (_). O comprimento máximo de um identificador é de 16 caracteres.

  • Para instalar um certificado de cliente, chame CertStore_InstallClientCertificate. Assim como acontece com o certificado de AC Raiz, o aplicativo fornece um ponteiro para o conteúdo do certificado, juntamente com um identificador que ele pode usar posteriormente como um nome amigável para o certificado. O aplicativo também deve 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 com o conteúdo do certificado de origem. Ambos os certificados já devem ser instalados no repositório de certificados. O ciclo de vida do certificado e a renovação descrevem estratégias para atualizar certificados, evitando o tempo de inatividade da rede.

Configurar e 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 e configurar a rede, um aplicativo deve seguir estas etapas básicas:

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

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

  • Defina o SSID para a rede chamando WifiConfig_SetSSID. Se o SSID ainda não for conhecido, o aplicativo poderá examiná-lo. Se o ambiente de rede provavelmente for barulhento ou se o SSID não puder ser transmitido, o aplicativo deverá habilitar a verificação direcionada chamando WifiConfig_SetTargetedScanEnabled. Em seguida, ele pode chamar WifiConfig_TriggerScanAndGetScannedNetworkCount para verificar todas as redes e WifiConfig_GetScannedNetworks 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 os resultados de uma rede com o WifiConfig_Security_Wpa2_EAP_TLS tipo de segurança e, em seguida, recuperar seu SSID.

  • Defina o nome da configuração para a 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 AC raiz para o servidor RADIUS chamando WifiConfig_SetRootCACertStoreIdentifier, se a rede exigir autenticação do servidor. O certificado de AC 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 cliente.

  • Habilite a rede chamando WifiConfig_SetNetworkEnabled.

  • Salve a configuração de rede chamando WifiConfig_PersistConfig. Essa função salva a configuração de 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 e configurar uma rede EAP-TLS.

Depois de 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 desconecta a rede se ela estiver conectada e a remova do dispositivo. No entanto, ele não atualiza a configuração Wi-Fi, portanto, a alteração não persiste entre a 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 em toda a reinicialização.

Amostras

Nota

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