在高级应用程序中管理证书

项目
08/09/2023

CertStore API 允许高级应用程序管理用于网络身份验证的证书。 azsphere 设备证书允许从命令行管理证书。

证书存储在 Azure Sphere 设备上的非易失性存储中。 证书存储或证书存储最多可以容纳 24 KiB 的证书。证书的最大大小为 8 KiB。根 CA 证书通常大于客户端证书。除了使用证书存储，还可以访问 Microsoft 托管的客户端证书。仅当设备至少每 24 小时连接到 Internet 一次时，Microsoft 托管的客户端证书才可用。

使用 Microsoft 托管的客户端证书

使用这两个函数获取客户端证书并确定它是否可供使用。

DeviceAuth_GetCertificatePath 返回由 OS 管理的客户端证书的文件路径。某些库需要此文件路径来加载 TLS 通信的证书。
Application_IsDeviceAuthReady 验证当前应用程序的设备身份验证是否已准备就绪。

CertStore 要求

使用 CertStore API 的应用程序必须包含相应的头文件，并将 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

每个证书都与 证书标识符 (ID) 相关联。证书 ID 是一个 1-16 个字符的字符串，用于唯一标识设备上的证书。有效字符为“a”-“z”、“A”-“Z”、“0”-'9“、连字符 (-) 。和下划线 (_) 。无论标识的证书类型如何，每个证书 ID 在设备中都必须是唯一的。

每个证书的标识符保存在证书存储中，并在设备范围内使用：由 CertStore API、 WifiConfig API 和 azsphere CLI 使用。因此，如果从命令行加载证书，则查询、移动或删除该证书的任何应用程序都必须使用相同的 ID。同样，如果应用加载证书，则操作证书的任何 azsphere 命令都必须使用相同的 ID。如果安装与任何类型的现有证书具有相同 ID 的新证书，则新证书将覆盖现有证书。

谨慎

由于证书 ID 在系统范围内适用于客户端和根 CA 证书，因此添加新证书的 azsphere 命令或函数调用可能会覆盖由早期命令或函数调用添加的证书，从而导致网络连接失败。强烈建议你制定明确的证书更新过程，并仔细选择证书 ID。

将证书添加到证书存储

若要将证书添加到证书存储，应用会调用以下函数之一：

CertStore_InstallClientCertificate 安装客户端证书，其中包含一个公共证书和一个私钥
CertStore_InstallRootCACertificate 安装根 CA 证书，该证书由公共证书组成

该证书必须存在于设备上，然后应用才能安装它。证书必须采用 PKCS1 或 PKCS8 语法和 .pem 格式才能加载到 Azure Sphere 设备。获取和部署 EAP-TLS 网络的证书介绍了如何获取证书并将其加载到设备上。 Microsoft 不提供证书。

安装证书会将其添加到证书存储区，并使其可用于身份验证。在证书存储中，证书按索引管理，可以按索引检索。索引值的范围从 0 到 (CertStore_GetCertificateCount - 1) 。

应用可以通过调用 CertStore_GetCertificateIdentifierAt 函数获取特定索引处的证书 ID。然后，它可以在调用中使用证书 ID 来获取有关证书的信息、移动或删除证书，以及使用证书进行身份验证。

获取证书信息

CertStore API 包含多个函数，这些函数返回有关存储的证书的信息：

CertStore_GetCertificateNotBefore 获取证书生效的时间
CertStore_GetCertificateNotAfter 获取证书过期的时间
CertStore_GetCertificateIssuerName 获取证书颁发者的名称
CertStore_GetCertificateSubjectName 获取证书使用者的名称;即证书保护的内容

在管理证书生存期和更新时，“非之前”和“非后”时间非常有用。有关详细信息，请参阅证书生命周期和续订。

重命名或删除证书

若要重命名或删除证书，应用会调用 CertStore_MoveCertificate 或 CertStore_DeleteCertificate。

CertStore_MoveCertificate 通过更改证书 ID 来重命名证书。由于证书 ID 在设备上必须是唯一的，因此，通过为证书提供与另一个证书相同的 ID 来重命名证书会删除该证书。例如，如果证书存储包含 MyCert 和 YourCert，则移动到 YourCertMyCert 将生成一个 ID 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);
}

使用证书进行网络身份验证

WifiConfig API 提供设置和返回为特定 Wi-Fi 配置启用的证书的函数。有关高级应用程序如何设置使用证书进行身份验证的 EAP-TLS 网络的详细信息，请参阅在应用中设置 EAP-TLS 网络。

证书示例

证书示例应用程序演示了应用程序如何使用 CertStore 函数。

通过