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

Статья
08/09/2023

API CertStore позволяет приложению высокого уровня управлять сертификатами для использования в сетевой проверке подлинности. Az sphere device certificate позволяет управлять сертификатами из командной строки.

Сертификаты хранятся в неизменяемом хранилище на устройстве 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
  }
}

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

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

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

Осторожностью

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

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

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

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

Сертификат должен присутствовать на устройстве, прежде чем приложение сможет установить его. Сертификаты должны быть в синтаксисе PKCS1 или PKCS8 и в формате PEM для загрузки на устройство Azure Sphere. Получение и развертывание сертификатов для сетей 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 и , перемещение MyCert в приводит к YourCert получению одного сертификата с идентификатором YourCert, который содержит данные из предыдущего MyCertYourCert. Ошибка не возвращается.

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, которая использует сертификаты для проверки подлинности, см. в статье Настройка сети EAP-TLS в приложении .

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

В примере приложения Certificates показано, как приложение может использовать функции CertStore.