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

發行項
08/09/2023

CertStore API 可讓高階應用程式管理憑證用於網路驗證。 az 球形裝置憑證可讓您從命令列管理憑證。

憑證會儲存在 Azure 球體裝置上的非旋轉儲存空間中。 憑證存放區或憑證存放區最多可保存 24 個 KiB 憑證。憑證的大小上限為 8 KiB。根 CA 憑證通常大於用戶端憑證。除了使用憑證存放區，您也可以存取 Microsoft 管理的用戶端憑證。只有當裝置至少每 24 小時連線到網際網路一次時，才能使用 Microsoft 管理的用戶端憑證。

使用 Microsoft 管理的用戶端憑證

使用這兩個函數來取得用戶端憑證，並判斷它是否已準備就緒可供使用。

DeviceAuth_GetCertificatePath 傳回由作業系統管理之用戶端憑證的檔案路徑。某些文件庫需要此檔案路徑，才能載入 TLS 通訊的憑證。
Application_IsDeviceAuthReady 驗證目前應用程式的裝置驗證是否已準備就緒。

CertStore 需求

使用 CertStore API 的應用程式必須包含適當的頁首檔案，並將 CertStore 功能新增至應用程式資訊清單。

頁首檔案

在專案中包含 CertStore 標頭：

 #include <applibs\certstore.h>

應用程式資訊清單設定

若要使用憑證存放區 API，您必須將應用程式功能新 CertStore 增至應用程式資訊清單，並將值設為 true 。 Azure 球體應用程式資訊清單主題有更多有關應用程式資訊清單的詳細資料。

{
  "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'、連字號 (-) 。和底線 (_) 。無論裝置識別的憑證類型為何，每個憑證識別碼在裝置上都必須是唯一的。

每一個憑證的識別碼都會儲存在憑證存放區，並且會在全裝置使用： CertStore API、 WifiConfig API 和 Azure CLI 擴充功能。因此，如果您從命令列載入憑證，查詢、移動或刪除憑證的任何應用程式都必須使用相同的識別碼。同樣地，如果應用程式載入憑證，任何 az sphere 操作憑證的命令都必須使用相同的識別碼。如果您安裝的新憑證與任何類型的現有憑證相同，新的憑證將會覆寫現有的憑證。

謹慎

由於用戶端和 Root CA 憑證都是全系統的憑證識別碼，因此 az 球形命令或新增新憑證的函數呼叫可能會覆寫先前命令或函數呼叫所新增的憑證，而可能導致網路連線失敗。我們強烈建議您開發清楚的憑證更新程式，並謹慎選擇憑證識別碼。

將憑證新增至憑證存放區

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

CertStore_InstallClientCertificate 安裝用戶端憑證，其中包含公用憑證和私密金鑰
CertStore_InstallRootCACertificate 安裝由公用憑證組成的 Root CA 憑證

憑證必須先顯示在裝置上，應用程式才能進行安裝。憑證必須是 PKCS1 或 PKCS8 語法和 .pem 格式，才能載入到 Azure 球體裝置上。取得及部署 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 函數。

共用方式為