Управление сертификатами в высокоуровневых приложениях

Статья
09/27/2024

Внимание

Это документация по Azure Sphere (устаревшая версия). Служба Azure Sphere (устаревшая версия) выходит на пенсию 27 сентября 2027 г., и к этому времени пользователи должны перейти в Azure Sphere (интегрированная). Используйте селектор версий, расположенный над toC, чтобы просмотреть документацию по Azure Sphere (интегрированная).

API CertStore позволяет высокоуровневому приложению управлять сертификатами для проверки подлинности сети. Сертификат устройства azsphere позволяет управлять сертификатами из командной строки.

Сертификаты хранятся в энергонезависимом хранилище на устройстве Azure Sphere. Хранилище сертификатов может содержать до 24 КиБ сертификатов. Максимальный размер сертификата составляет 8 КиБ. Сертификаты корневого ЦС обычно больше, чем сертификаты клиента. Помимо использования хранилища сертификатов, вы также можете получить доступ к сертификату клиента, управляемому корпорацией Майкрософт. Сертификат клиента, управляемый корпорацией Майкрософт, будет доступен только для использования, если устройство подключено к Интернету по крайней мере один раз каждые 24 часа.

Использование сертификата клиента, управляемого корпорацией Майкрософт

Используйте эти две функции для получения сертификата клиента и определения готовности к использованию.

DeviceAuth_GetCertificatePath возвращает путь к файлу сертификата клиента, управляемого ОС. Этот путь к файлу требуется некоторым библиотекам для загрузки сертификата для обмена данными TLS.
Application_IsDeviceAuthReady проверить, готова ли проверка подлинности устройства для текущего приложения.

Требования к CertStore

Приложения, использующие API CertStore, должны содержать соответствующие файлы заголовков. Кроме того, возможность CertStore должна быть включена в соответствующий манифест приложения.

Файлы заголовков

Включите в проект заголовок CertStore, выполнив следующую команду:

 #include <applibs\certstore.h>

Параметры в манифесте приложения

Для использования API хранилища сертификатов необходимо добавить параметр CertStore в манифест приложения и присвоить этому параметру значение true. Дополнительные сведения о манифесте приложения Azure Sphere см. здесь.

{
  "SchemaVersion": 1,
  "Name" : "Mt3620App3",
  "ComponentId" : "bb267cbd-4d2a-4937-8dd8-3603f48cb8f6",
  "EntryPoint": "/bin/app",
  "CmdArgs": [],
   "Capabilities": {
    "AllowedConnections": [],
    "AllowedTcpServerPorts": [],
    "AllowedUdpServerPorts": [],
    "CertStore" : true,
    "Gpio": [],
    "Uart": [],
    "EnterpriseWifiConfig": true,
    "WifiConfig": true,
    "NetworkConfig": false,
    "SystemTime": true
  }
}

Идентификаторы сертификатов

Каждый сертификат связан с идентификатором сертификата. Идентификатор сертификата — это строка из 1–16 символов, которая уникально идентифицирует сертификат на устройстве. Допустимые символы: строчные буквы (a–z), заглавные буквы (A–Z), цифры (0–9), дефис (-) и символ подчеркивания (_). Каждый идентификатор сертификата должен быть уникальным на устройстве независимо от типа сертификата, который он идентифицирует.

Идентификатор каждого сертификата сохраняется в хранилище сертификатов и используется на уровне устройства: API CertStore , API WifiConfig и azsphere CLI. Следовательно, если вы загрузили сертификат из командной строки, все приложения, которые запрашивают, перемещают или удаляют этот сертификат, должны использовать один и тот же идентификатор. Аналогичным образом, если приложение загружает сертификат, все команды azsphere, которые управляют сертификатом, должны использовать тот же идентификатор. Если установить новый сертификат с идентификатором, который соответствует идентификатору существующего сертификата любого типа, новый сертификат перезапишет существующий.

Внимание

Так как идентификаторы сертификатов клиента и сертификатов корневого ЦС используются во всей системе, команда azsphere или вызов функции, который добавляет новый сертификат, могут перезаписать сертификат, который был добавлен более ранней командой или вызовом функции. Это может привести к сбоям сетевого подключения. Настоятельно рекомендуется разрабатывать четкие процедуры обновления сертификатов и тщательно выбирать идентификаторы сертификатов.

Добавление сертификата в хранилище сертификатов

Чтобы добавить сертификат в хранилище сертификатов, приложение вызывает одну из следующих функций:

Функция CertStore_InstallClientCertificate устанавливает сертификат клиента, который состоит из открытого сертификата и закрытого ключа.
Функция CertStore_InstallRootCACertificate устанавливает сертификат корневого ЦС, который состоит из открытого сертификата.

Сертификат должен присутствовать на устройстве, прежде чем приложение сможет его установить. Для загрузки на устройство Azure Sphere сертификаты должны иметь синтаксис PKCS1 или PKCS8 и формат PEM. Сведения о получении сертификатов и загрузке их на устройство см. в статье Получение и развертывание сертификатов для сетей EAP-TLS. Корпорация Майкрософт не предоставляет сертификаты.

При установке сертификат добавляется в хранилище сертификатов и становится доступным для выполнения проверки подлинности. В хранилище сертификатов управление сертификатами и их извлечение осуществляется по индексу. Диапазон значений индекса варьируется от 0 до (CertStore_GetCertificateCount — 1).

Приложение может получить идентификатор сертификата по определенному индексу, вызвав функцию CertStore_GetCertificateIdentifierAt. Затем оно может использовать идентификатор сертификата в вызовах для получения сведений о сертификате, перемещения или удаления сертификата, а также для использования сертификата для проверки подлинности.

Получение сведений о сертификате

API CertStore содержит несколько функций, которые возвращают сведения о сохраненном сертификате:

Функция CertStore_GetCertificateNotBefore возвращает время, когда сертификат становится действительным.
Функция CertStore_GetCertificateNotAfter возвращает время окончания срока действия сертификата.
Функция CertStore_GetCertificateIssuerName возвращает имя издателя сертификата.
Функция CertStore_GetCertificateSubjectName возвращает имя субъекта сертификата (что защищает сертификат).

Значения времени "не раньше" и "не позже" полезны при управлении жизненным циклом и обновлениями сертификата. Дополнительные сведения см. в статье Жизненный цикл и обновление сертификата.

Переименование или удаление сертификата

Чтобы переименовать или удалить сертификат, приложение вызывает функцию CertStore_MoveCertificate или CertStore_DeleteCertificate.

Функция CertStore_MoveCertificate переименовывает сертификат, изменяя его идентификатор. Так как идентификаторы сертификатов должны быть уникальными на устройстве, при переименовании сертификата путем присвоения ему идентификатора другого сертификата другой сертификат будет удален. Например, если хранилище сертификатов содержит MyCert и YourCert, то перемещение MyCert в YourCert приведет к получению одного сертификата с идентификатором YourCert, который содержит данные из прежнего MyCert. Ошибка не возвращается.

Функция CertStore_DeleteCertificate удаляет один сертификат. Удаление сертификата приводит к повторному индексированию остальных сертификатов, начиная с 0. Поэтому, чтобы удалить все сертификаты из хранилища сертификатов, необходимо создать цикл на основе числа сертификатов, но удалять сертификат с индексом 0 в каждой итерации. При попытке удалить сертификат в индексе, который больше не используется, функция CertStore_GetCertificateIdentifierAt возвращает значение ERANGE.

Следующий метод работает правильно:

for (int i = 0; i < CertStore_GetCertificateCount(); i++) {
    struct CertStore_Identifier id;
    result = CertStore_GetCertificateIdentifierAt(0, &id);
    CertStore_DeleteCertificate(id.identifier);
}

Использование сертификата для проверки подлинности сети

API WifiConfig предоставляет функции, которые задают и возвращают сертификаты, включенные для конкретной конфигурации Wi-Fi. Сведения о том, как высокоуровневое приложение может настроить сеть EAP-TLS, использующую сертификаты для проверки подлинности, см. здесь.

Пример сертификата

Сведения об использовании функций CertStore приложением см. в примере приложения сертификатов.

Поделиться через