在高階應用程式中管理憑證

發行項
10/23/2024

重要

這是 Azure Sphere （舊版）檔。 Azure Sphere（舊版）將於 2027 年 9 月 27 日淘汰，且使用者此時必須移轉至 Azure Sphere（整合式）。 使用位於 TOC 上方的版本選取器來檢視 Azure Sphere （整合式）檔。

CertStore API 可讓高階應用程式管理憑證，以用於網路驗證。 azsphere device certificate 可讓您從命令行管理憑證。

憑證會儲存在 Azure Sphere 裝置上的非揮發記憶體中。 證書存儲或證書存儲最多可以保存 24 KiB 的憑證。憑證的大小上限為 8 KiB。根 CA 憑證通常大於用戶端憑證。除了使用憑證存放區之外，您也可以存取受Microsoft管理的客戶端憑證。 Microsoft管理的客戶端憑證只能在裝置至少每 24 小時連線到因特網一次時使用。

使用受Microsoft管理的客戶端憑證

使用這兩個函式來取得客戶端憑證，並判斷它是否可供使用。

DeviceAuth_GetCertificatePath傳回作業系統所管理客戶端憑證的檔案路徑。某些連結庫需要此檔案路徑，才能載入 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） 相關聯。憑證標識碼是 1-16 個字元的字串，可唯一識別裝置上的憑證。有效字元為 'a'-'z'、'A'-'Z'、'0'-'9'、連字元（-）。和底線（_）。無論裝置所識別的憑證類型為何，每個憑證標識碼都必須是唯一的。

每個憑證的標識碼都會儲存在證書存儲中，而且全裝置使用：由 CertStore API、 WifiConfig API 和 azsphere CLI 使用。因此，如果您從命令行載入憑證，任何查詢、移動或刪除該憑證的應用程式都必須使用相同的標識符。同樣地，如果應用程式載入憑證，任何操作憑證的 azsphere 命令都必須使用相同的標識符。如果您安裝具有與任何類型現有憑證相同標識符的新憑證，新憑證將會覆寫現有的憑證。

警告

因為憑證標識碼是用戶端和根 CA 憑證的系統範圍，因此 azsphere 命令或新增憑證的函式呼叫可以覆寫先前命令或函數調用所新增的憑證，可能會導致網路連線失敗。強烈建議您開發明確的憑證更新程式，並仔細選擇憑證標識碼。

將憑證新增至證書存儲

若要將憑證新增至證書存儲，應用程式會呼叫下列其中一個函式：

CertStore_InstallClientCertificate安裝客戶端憑證，其中包含公開憑證和私鑰
CertStore_InstallRootCACertificate安裝根 CA 憑證，其中包含公用憑證

憑證必須存在於裝置上，應用程式才能安裝它。憑證必須是 PKCS1 或 PKCS8 語法和 .pem 格式，才能載入 Azure Sphere 裝置。取得和部署 EAP-TLS 網路的憑證說明如何取得憑證，並將其載入裝置。 Microsoft不提供憑證。

安裝憑證會將它新增至證書存儲，並讓它可用於驗證。在證書存儲中，憑證是由索引管理，而且可以透過索引擷取。索引值的範圍是從 0 到（CertStore_GetCertificateCount - 1）。

應用程式可以藉由呼叫 CertStore_GetCertificateIdentifierAt 函式，以在特定索引取得憑證的標識碼。然後，它可以使用呼叫中的憑證標識碼來取得憑證的相關信息、移動或刪除憑證，以及使用憑證進行驗證。

取得憑證資訊

CertStore API 包含數個函式，可傳回預存憑證的相關信息：

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);
}

使用憑證進行網路驗證

WifiConfig API 提供可設定並傳回針對特定Wi-Fi組態啟用的憑證的函式。如需高階應用程式如何設定使用憑證進行驗證的 EAP-TLS 網路的詳細資訊，請參閱在應用程式中設定 EAP-TLS 網路。

憑證範例

憑證範例應用程式會顯示應用程式如何使用 CertStore 函式。

共用方式為