Настройка сети EAP-TLS в приложении
Внимание
Это документация по Azure Sphere (устаревшая версия). Служба Azure Sphere (устаревшая версия) выходит на пенсию 27 сентября 2027 г., и к этому времени пользователи должны перейти в Azure Sphere (интегрированная). Используйте селектор версий, расположенный над toC, чтобы просмотреть документацию по Azure Sphere (интегрированная).
EAP-TLS можно настроить в высокоуровневом приложении или вручную, выполнив команды azsphere. Для настройки и подключения к сети приложение использует API Certstore и WifiConfig.
Требования
Чтобы настроить сеть EAP-TLS, ваше высокоуровневое приложение должно содержать соответствующие файлы заголовков, включить необходимые возможности в манифесте приложения и получить доступ к сертификатам, необходимым для проверки подлинности.
Файлы заголовков
Приложение должно содержать следующий заголовок:
#include <applibs/wificonfig.h>
Если приложение вызывает API CertStore для управления сертификатами, оно также должно содержать заголовок CertStore. Этот заголовок не требуется для использования функций WifiConfig, таких как WifiConfig_GetRootCACertStoreIdentifier, которые извлекают сведения о сертификате.
#include <applibs/certstore.h>
Манифест приложения
Манифест приложения должен включить возможность EnterpriseWiFiConfig для настройки сети EAP-TLS. Кроме того, он должен иметь возможность WifiConfig для использования функций WifiConfig_*, которые не управляют возможностями EAP-TLS. Наконец, если приложение также управляет сертификатами, оно должно включать возможность CertStore.
Не включайте возможности, которые не требуются для приложения. Это может создать угрозу безопасности. Если сертификаты будут обновляться вручную, не указывайте CertStore. Эту возможность следует использовать только в том случае, если приложение отвечает за хранение сертификатов на устройстве и управление ими.
В следующем примере показано, как задать все три возможности в файле app_manifest.json:
"Capabilities": {
"WifiConfig" : true,
"EnterpriseWiFiConfig" : true,
"CertStore" : true
}
Сертификаты
Сертификат клиента вашего устройства должен быть доступен на устройстве. Кроме того, если сеть EAP-TLS настроена для взаимной проверки подлинности, на устройстве также должен быть установлен сертификат корневого ЦС для сервера RADIUS сети. Оба сертификата должны быть в формате PEM (PKCS1 или PKCS8). Дополнительные сведения о сертификатах и их получении см. в статье Получение и развертывание сертификатов сетей EAP-TLS.
Установка сертификатов
Прежде чем приложение сможет настроить сеть EAP-TLS, оно должно иметь доступ к корневому ЦС и сертификатам клиентов, используемым для проверки подлинности. Стратегии получения сертификатов и их загрузки на устройство в виде PEM-файлов см. в статье Получение и развертывание сертификатов для сетей EAP-TLS. За приобретение и развертывание сертификатов отвечает пользователь. Для получения дополнительных сведений обратитесь к администратору сети.
После того как сертификаты загружены на устройство, приложение может установить их для использования. В примере Сертификаты показано, как их установить. Ниже приведены основные шаги.
Убедитесь, что в хранилище сертификатов достаточно места. Место в хранилище сертификатов ограничено, поэтому приложение должно вызвать функцию CertStore_GetAvailableSpace перед попыткой установки сертификата. Если недостаточно места, приложение должно удалить существующий сертификат, чтобы освободить место для нового. Место для сертификатов ограничено до 24 КиБ.
Чтобы установить сертификат корневого ЦС, вызовите функцию CertStore_InstallRootCACertificate. Приложение предоставляет указатель на содержимое сертификата вместе с идентификатором, который позже используется в качестве понятного имени для сертификата. Сертификат корневого ЦС является обязательным, если сеть обеспечивает реализацию взаимной проверки подлинности. В состав идентификаторов могут входить прописные буквы, строчные буквы, цифры 0–9, точки (.), дефисы (-) и символы подчеркивания (_). Максимальная длина идентификатора составляет 16 знаков.
Чтобы установить сертификат клиента, вызовите функцию CertStore_InstallClientCertificate. Как и в случае с сертификатом корневого ЦС, приложение предоставляет указатель на содержимое сертификата вместе с идентификатором, который используется позже в качестве понятного имени для сертификата. Приложение должно также предоставить закрытый ключ и, если ключ зашифрован, пароль шифрования.
Чтобы обновить сертификат, приложение может использовать функцию CertStore_MoveCertificate. Эта функция перемещает один сертификат в другой, перезаписывая содержимое существующего целевого сертификата содержимым исходного сертификата. Оба сертификата должны быть уже установлены в хранилище сертификатов. Сведения о стратегиях обновления сертификатов, которые позволяют избежать простоя сети, см. в статье Жизненный цикл и обновление сертификата.
Настройка и установка сети EAP-TLS
В примере Wifi_HighLevelApp показано, как создать, настроить и включить сеть EAP-TLS. В этом примере предполагается, что сертификаты уже находятся в хранилище сертификатов, как описано в разделе Установка сертификатов.
Для настройки сети необходимо выполнить следующие основные действия в приложении:
Добавить сеть, вызвав функцию WifiConfig_AddNetwork. Эта функция просто создает сеть. Она не настраивает никаких характеристик сети.
Задать тип безопасности для сети, вызвав функцию WifiConfig_SetSecurityType. Тип безопасности для сети EAP-TLS должен быть
WifiConfig_Security_Wpa2_EAP_TLS.Задать SSID для сети, вызвав функцию WifiConfig_SetSSID. Если SSID еще не известен, приложение может проверить его наличие. Если сетевая среда имеет помехи или передача SSID может не происходить, приложение должно включить целевое сканирование, вызвав функцию WifiConfig_SetTargetedScanEnabled. Затем оно может вызвать функцию WifiConfig_TriggerScanAndGetScannedNetworkCount для поиска всех сетей, а также WifiConfig_GetScannedNetworks, чтобы получить результаты сканирования. WifiConfig_GetScannedNetworks возвращает массив структур, содержащих сведения о каждой сети. Приложение может искать результаты сети с типом безопасности
WifiConfig_Security_Wpa2_EAP_TLS, а затем получить ее SSID.Задать имя конфигурации для сети, вызвав функцию WifiConfig_SetConfigName. Имя конфигурации — это понятное имя, которое приложение может использовать для обнаружения этой конфигурации сети.
Задать имя сертификата корневого ЦС для сервера RADIUS, вызвав функцию WifiConfig_SetRootCACertStoreIdentifier, если для сети необходимо выполнить проверку подлинности сервера. Сертификат корневого ЦС уже должен присутствовать на устройстве.
Задать имя хранилища сертификатов клиента, вызвав функцию WifiConfig_SetClientCertStoreIdentifier. Сертификат клиента уже должен присутствовать на устройстве.
Задать идентификатор клиента, вызвав функцию WifiConfig_SetClientIdentity. Идентификатор клиента — это понятное имя, идентифицирующее клиентское устройство.
Включить сеть, вызвав функцию WifiConfig_SetNetworkEnabled.
Сохранить конфигурацию сети, вызвав функцию WifiConfig_PersistConfig. Эта функция сохраняет конфигурацию сети на устройстве, чтобы она сохранялась после перезагрузки.
Изменение свойств сети EAP-TLS
Приложение может изменить свойства сети, вызвав те же функции, которые использовались для их первоначальной настройки, как указано в разделе Настройка и установка сети EAP-TLS.
После изменения свойств приложение должно вызвать не только функцию WifiConfig_PersistConfig, чтобы сохранить конфигурацию, но и функцию WifiConfig_ReloadConfig для немедленного обновления сети. Это особенно важно, когда приложение обновляет сертификат.
Удаление сети EAP-TLS
Приложение может удалить сеть, вызвав либо функцию WifiConfig_ForgetNetworkById, либо функцию WifiConfig_ForgetAllNetworks.
Функция WifiConfig_ForgetNetworkById отключает сеть, если она подключена, и удаляет ее с устройства. Однако при этом конфигурация Wi-Fi не обновляется. Поэтому изменение не сохраняется в процессе перезагрузки. Приложение должно вызвать функцию WifiConfig_PersistConfig, чтобы сделать удаление безвозвратным.
Функция WifiConfig_ForgetAllNetworks отключает подключенную сеть и удаляет все сети с устройства. Это изменение сохраняется при перезагрузке.
Примеры
- Высокоуровневое приложение сертификатов. Демонстрирует использование сертификатов и управление ими в высокоуровневом приложении Azure Sphere.
- Wifi_HighLevelApp. Демонстрируется подключение к сети Wi-Fi и проверка состояния сети на устройстве MT3620.