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

發行項
09/27/2024

重要

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

您可以在高階應用程式中設定 EAP-TLS，或使用 azsphere 命令手動設定。若要設定並連線到網路，應用程式會使用 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伺服器的根CA憑證也必須安裝在裝置上。這兩個憑證都必須採用 .pem 格式，即 PKCS1 或 PKCS8。請參閱 EAP-TLS 憑證取得和部署，以了解憑證及其取得位置。

安裝憑證

在您的應用程式可以設定 EAP-TLS 網路之前，它必須能夠存取要用於驗證的根 CA 和客戶端憑證。取得和部署 EAP-TLS 網路的憑證說明取得憑證的策略，並將其載入裝置作為 PEM 檔案。取得和部署憑證是您的責任;請洽詢您的網路管理員以取得詳細數據。

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

請確定證書存儲中有足夠的空間。證書存儲空間有限，因此應用程式應該先呼叫 CertStore_GetAvailableSpace ，再嘗試安裝憑證。如果沒有足夠的空間，應用程式應該刪除現有的憑證，為新的憑證騰出空間。憑證空間限制為 24 KiB。
若要安裝根 CA 憑證，請呼叫 CertStore_InstallRootCACertificate。應用程式會提供憑證內容的指標，以及稍後可用來作為憑證易記名稱的標識碼。如果網路啟用相互驗證，則需要根 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伺服器的根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 Sphere 高階應用程式中使用和管理憑證。
Wifi_HighLevelApp - 示範如何連線到Wi-Fi網路，並檢查MT3620裝置上的網路狀態。

注意

下列範例來自 Azure Sphere 資源庫，這是來自 Microsoft 的未協調軟體和硬體範例集合。如需詳細資訊，請參閱 Azure Sphere 資源庫。

使用 Azure Sphere 的 EAP-TLS 解決方案 - 示範如何將 Azure Sphere 裝置連線到 EAP-TLS 網路。

共用方式為