共用方式為

在應用程式中設定 EAP-TLS 網路

  • 發行項

您可以在高階應用程式中設定 EAP-TLS，或 使用 az sphere 命令手動設定。 若要設定並聯機到網路，應用程式會使用 Certstore 和 WifiConfig API。

要求

若要設定 EAP-TLS 網路，您的高階應用程式必須包含適當的頁首檔案、啟用其 應用程式資訊清單中的必要功能，以及存取驗證所需的憑證。

頁首檔案

您的應用程式必須包含下列標頭：

#include <applibs/wificonfig.h>

如果應用程式呼叫 CertStore API 管理憑證，也必須包含 CertStore 標頭。 不需要此標頭即可使用 WifiConfig 函數，例如擷取憑證資訊 的WifiConfig_GetRootCACertStoreIdentifier 。

#include <applibs/certstore.h>

應用程式資訊清單

應用程式資訊清單必須啟用 EnterpriseWiFiConfig 功能，才能設定 EAP-TLS 網路。 它也必須具備 WifiConfig 功能，才能使用不管理 EAP-TLS 功能 的WifiConfig_* 函數。 最後，如果應用程式也管理憑證，則必須啟用 CertStore 功能。

請勿啟用應用程式不需要的功能;這會帶來安全性風險。 如果憑證會手動更新，請勿指定 CertStore。 只有在應用程式負責在裝置上儲存及管理憑證時，才使用此功能。

下列範例示範如何設定 app_manifest.json 檔案中的所有三種功能：

"Capabilities": {
        "WifiConfig" : true,
        "EnterpriseWiFiConfig" : true,
        "CertStore" : true
    }

證書

您裝置的用戶端憑證必須在裝置上使用。 此外，如果 EAP-TLS 網路設定為共同驗證，您網路 RADIUS 伺服器的 Root CA 憑證也必須安裝在裝置上。 兩個憑證都必須是 .pem 格式，無論是 PKCS1 或 PKCS8。 請參閱 EAP-TLS 憑證取得與部署 ，以瞭解憑證的取得位置。

安裝憑證

在您的應用程式可以設定 EAP-TLS 網路之前，它必須具備 Root CA 和用戶端憑證的存取權，才能用於驗證。 取得及部署 EAP-TLS 網路憑證 說明取得憑證並將它們載入到裝置做為 PEM 檔案的策略。 您必須負責取得及部署憑證;請洽詢您的網路系統管理員以取得詳細資料。

憑證在裝置上之後，應用程式就可以安裝憑證供使用。 憑證範例顯示如何安裝憑證。 以下是基本步驟：

  • 確定憑證存放區有足夠的空間。 憑證儲存空間有限，因此應用程式在嘗試安裝憑證之前，應該先連 絡CertStore_GetAvailableSpace 。 如果沒有足夠的空間可用，應用程式應該刪除現有的憑證，以釋出空間給新憑證。 憑證空間限制為 24 KiB。

  • 若要安裝 Root CA 憑證，請連 絡CertStore_InstallRootCACertificate。 應用程式會提供指向憑證內容的指標以及識別碼，供日後用來做為憑證的易記名稱。 如果網路啟用共同驗證，則需要 Root CA 憑證。 識別碼可以包含大寫字母、小寫字母、數位 0-9、句號 (.) 、連字號 (-) ，以及底線 (_) 。 識別碼的長度上限為 16 個字元。

  • 若要安裝用戶端憑證，請連 絡CertStore_InstallClientCertificate。 如同跟跟 CA 憑證一樣，應用程式會提供指向憑證內容的指標，以及一個識別碼，供日後用來做為憑證的易記名稱。應用程式也必須提供私密金鑰，如果金鑰已加密，則必須提供加密密碼。

若要更新憑證，應用程式可以使用 CertStore_MoveCertificate 函數。 此函數會將一個憑證移至另一個憑證，方法是以來源憑證的內容覆寫現有目的地憑證的內容。 這兩個憑證都必須安裝在憑證存放區中。 憑證生命週期和更新 概述更新憑證同時避免網路停機的策略。

設定及設定 EAP-TLS 網路

Wifi_HighLevelApp范例顯示如何建立、設定及啟用 EAP-TLS 網路。 範例假設憑證已在憑證存放區中，如 安裝憑證中所述。

若要設定和設定網路，應用程式應遵循下列基本步驟：

  • 透過撥打 WifiConfig_AddNetwork來新增網路。 此函數只會建立網路;它不會設定網路的任何特性。

  • 撥打WifiConfig_SetSecurityType來設定網路的安全性類型。 對於 EAP-TLS 網路，安全性類型必須是 WifiConfig_Security_Wpa2_EAP_TLS 。

  • 透過撥打WifiConfig_SetSSID來設定網路的 SSID。 如果 SSID 還不是已知的，應用程式可以掃描它。 如果網路環境可能吵雜，或是 SSID 可能不會廣播，應用程式應該撥打 WifiConfig_SetTargetedScanEnabled來啟用目標掃描。 然後，它可以呼叫 WifiConfig_TriggerScanAndGetScannedNetworkCount 掃描所有網路， 並WifiConfig_GetScannedNetworks 來取得掃描的結果。 WifiConfig_GetScannedNetworks 會傳回包含每個網路詳細資料的結構陣列。 應用程式可以搜尋具有 WifiConfig_Security_Wpa2_EAP_TLS 安全性類型的網路結果，然後擷取其 SSID。

  • 透過撥打WifiConfig_SetConfigName來設定網路的組 態名稱。 組態名稱是好記的名稱，應用程式可以用來識別此網路設定。

  • 如果網路需要伺服器驗證，請撥打 WifiConfig_SetRootCACertStoreIdentifier來設定 RADIUS 伺服器的 Root CA 憑證名稱。 根 CA 憑證必須已經出現在裝置上。

  • 撥打 WifiConfig_SetClientCertStoreIdentifier來設定用戶端憑證存放區名稱。 用戶端憑證必須已經存在裝置上。

  • 撥打WifiConfig_SetClientIdentity來設定用戶端身 分識別。 用戶端身分識別是識別用戶端裝置的易記名稱。

  • 透過撥打 WifiConfig_SetNetworkEnabled啟用網路。

  • 透過呼叫 WifiConfig_PersistConfig 來儲存網路 設定。 此函數會將網路設定儲存在裝置上，讓它持續重新開機。

變更 EAP-TLS 網路的屬性

應用程式可以呼叫原先設定的相同函數來變更網路屬性，如設定 和設定 EAP-TLS 網路中所列。

變更屬性之後，應用程式不僅必須連 絡WifiConfig_PersistConfig 來儲存設定，還必須連 絡WifiConfig_ReloadConfig 來立即更新網路。 當應用程式更新憑證時，這特別重要。

刪除 EAP-TLS 網路

應用程式可以透過呼叫 WifiConfig_ForgetNetworkById 或 WifiConfig_ForgetAllNetworks來刪除網路。

WifiConfig_ForgetNetworkById 連線網路並從裝置移除網路時中斷連線。 不過，它不會更新 Wi-Fi 設定，因此在重新開機時，此變更並不會持續發生。 應用程式必須呼叫 WifiConfig_PersistConfig ，才能永久移除。

WifiConfig_ForgetAllNetworks 中斷連線網路，並從裝置移除所有網路。 這項變更會在重新開機時持續發生。

樣品

  • 證書高階應用程式 - 示範如何在 Azure 球體高層級應用程式中使用和管理憑證。
  • Wifi_HighLevelApp - 示範如何連線到 Wi-Fi 網路，並檢查 MT3620 裝置上的網路狀態。

注意

下列範例來自 Azure 球體圖庫，這是來自 Microsoft 的未相關軟體和硬體範例集合。 如需詳細資訊，請參閱 Azure 球體圖庫。