快速入門：布建 X.509 憑證模擬裝置

發行項
03/19/2024

在本快速入門中，您會在 Windows 電腦上建立模擬裝置。模擬裝置已設定為使用 X.509 憑證證明進行驗證。設定裝置之後，您可以使用 Azure IoT 中樞裝置布建服務，將其布建到IoT中樞。

如果您不熟悉布建程式，請檢閱布建概觀。此外，請確定您已完成使用 Azure 入口網站設定 IoT 中樞裝置布建服務中的步驟，再繼續進行。

本快速入門示範以 Windows 為基礎的工作站解決方案。不過，您也可以在 Linux 上執行程式。如需Linux範例，請參閱教學課程：布建異地延遲。

必要條件

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
使用 Azure 入口網站完成設定 IoT 中樞裝置布建服務中的步驟。

下列必要條件適用於 Windows 開發環境。針對 Linux 或 macOS，請參閱 SDK 檔中準備開發環境的適當章節。

安裝 Visual Studio 2022，並啟用「使用 C++進行桌面開發」工作負載。也支援 Visual Studio 2015、Visual Studio 2017 和 Visual Studio 19。針對 Linux 或 macOS，請參閱 SDK 檔中準備開發環境的適當章節。
安裝最新的 CMake 組建系統。請務必檢查將 CMake 可執行檔新增至路徑的選項。

重要

在開始CMake安裝之前，請先確認已安裝Visual Studio必要條件（Visual Studio和「使用 C++進行桌面開發」工作負載。一旦必要條件就緒，並確認下載后，請安裝 CMake 建置系統。此外，請注意，舊版的 CMake 建置系統無法產生本文中使用的解決方案檔案。請務必使用最新版本的 CMake。

下列必要條件適用於 Windows 開發環境。針對 Linux 或 macOS，請參閱 SDK 檔中準備開發環境的適當章節。

在 Windows 電腦上安裝 .NET SDK 6.0 或更新版本。您可以使用下列命令來檢查您的版本。
```
dotnet --info
```

下列必要條件適用於 Windows 開發環境。針對 Linux 或 macOS，請參閱 SDK 檔中準備開發環境的適當章節。

在您的電腦上安裝 Node.js v4.0 或更新版本。

下列必要條件適用於 Windows 開發環境。

您電腦上的 Python 3.6 或更新版本。

下列必要條件適用於 Windows 開發環境。針對 Linux 或 macOS，請參閱 SDK 檔中準備開發環境的適當章節。

在您的電腦上安裝 Java SE 開發工具套件 8 或更新版本。
下載並安裝 Maven。

安裝最新版本的 Git。請確定 Git 已新增至命令視窗可存取的環境變數。請參閱 Software Freedom Conservancy 的 Git 用戶端工具，以取得要安裝之最新版 git 的工具，其中包括 Git Bash，您可以用來與本機 Git 存放庫互動的命令行應用程式。
請確定您的電腦已安裝 OpenSSL 。在 Windows 上，您的 Git 安裝包含 OpenSSL 的安裝。您可以從 Git Bash 提示字元存取 OpenSSL。若要確認已安裝 OpenSSL，請開啟 Git Bash 提示字元，然後輸入 openssl version。

注意

除非您熟悉 OpenSSL，且已在 Windows 電腦上安裝它，否則建議您從 Git Bash 提示字元使用 OpenSSL。或者，您可以選擇下載原始程式碼並建置 OpenSSL。若要深入瞭解，請參閱 OpenSSL 下載頁面。或者，您可以從第三方預先建置 OpenSSL。若要深入瞭解，請參閱 OpenSSL Wiki。 Microsoft 不保證從第三方下載之套件的有效性。如果您選擇建置或下載 OpenSSL，請確定您的路徑可存取 OpenSSL 二進位檔，且OPENSSL_CNF環境變數設定為 openssl.cnf 檔案的路徑。
開啟 Windows 命令提示字元和 Git Bash 提示字元。

本快速入門中的步驟假設您使用 Windows 計算機和 Git 一部分安裝的 OpenSSL 安裝。您可以使用 Git Bash 提示來發出 OpenSSL 命令，並針對其他所有專案發出 Windows 命令提示字元。如果您使用 Linux，您可以從 Bash 殼層發出所有命令。

準備您的開發環境

在本節中，您會準備用來建置 Azure IoT C SDK 的開發環境。範例程式代碼會在裝置的開機順序期間嘗試布建裝置。

開啟網頁瀏覽器，然後移至 Azure IoT C SDK 的 [發行] 頁面。
選取頁面頂端的 [ 卷標 ] 索引標籤。
複製最新版 Azure IoT C SDK 的標籤名稱。
在您的 Windows 命令提示字元中，執行下列命令來複製最新版的 Azure IoT 裝置 SDK for C GitHub 存放庫。將取代 <release-tag> 為您在上一個步驟中複製的標記，例如： lts_01_2023。
```
git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
此作業可能需要幾分鐘的時間才能完成。
工作完成時，請從 azure-iot-sdk-c 目錄執行下列命令：
```
mkdir cmake
cd cmake
```
程式代碼範例會使用 X.509 憑證，透過 X.509 驗證提供證明。執行下列命令，以建置開發平台專屬的 SDK 版本，其中包含裝置布建用戶端。模擬裝置的 Visual Studio 解決方案會在目錄中產生 cmake 。

在下列命令中指定與搭配 -Dhsm_custom_lib 使用的路徑時，請務必使用您先前建立之目錄中連結庫的 cmake 絕對路徑。顯示的路徑假設您已在 C 磁碟驅動器的根目錄中複製 C SDK。如果您使用另一個目錄，請據以調整路徑。
- Windows
- Linux
```
cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=c:/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/Debug/custom_hsm_example.lib ..
```
```
cmake -Duse_prov_client:BOOL=ON -Dhsm_custom_lib=/home/<USER>/azure-iot-sdk-c/cmake/provisioning_client/samples/custom_hsm_example/custom_hsm_example.a ..
```

提示

如果 cmake 找不到您的 C++ 編譯程式，您可以在執行上述命令時收到建置錯誤。如果發生這種情況，請嘗試在 Visual Studio 命令提示字元中執行命令。

建置成功時，最後幾個輸出行看起來會類似下列輸出：

-- Building for: Visual Studio 17 2022
-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.22000.
-- The C compiler identification is MSVC 19.32.31329.0
-- The CXX compiler identification is MSVC 19.32.31329.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: C:/azure-iot-sdk-c/cmake

在您的 Windows 命令提示字元中，使用下列命令複製適用於 C# 的 Azure IoT SDK GitHub 存放庫：

git clone https://github.com/Azure/azure-iot-sdk-csharp.git

在 Windows 命令提示字元中，使用下列命令複製適用於 Node.js GitHub 存放庫的 Azure IoT SDK：

git clone https://github.com/Azure/azure-iot-sdk-node.git

在您的 Windows 命令提示字元中，使用下列命令複製適用於 Python 的 Azure IoT 裝置 SDK GitHub 存放庫：

git clone -b v2 https://github.com/Azure/azure-iot-sdk-python.git --recursive

注意

本教學課程中使用的範例位於 azure-iot-sdk-python 存放庫的 v2 分支中。 Python SDK 的 V3 可在 Beta 中使用。

在您的 Windows 命令提示字元中，使用下列命令複製適用於 Java GitHub 的 Azure IoT 範例存放庫：
```
git clone https://github.com/Azure/azure-iot-sdk-java.git --recursive
```
移至根 azure-iot-sdk-java 目錄並建置項目以下載所有必要的套件。
```
cd azure-iot-sdk-java
mvn install -DskipTests=true
```

建立自我簽署 X.509 裝置憑證

在本節中，您會使用 OpenSSL 來建立自我簽署的 X.509 憑證和私鑰。此憑證會上傳至您的布建服務實例，並由服務驗證。

警告

在本快速入門中，使用以 OpenSSL 建立的憑證，只用於開發測試。請勿在生產環境中使用這些憑證。這些憑證會在 30 天后到期，而且可能包含硬式編碼的密碼，例如 1234。若要瞭解如何取得適合用於生產環境的憑證，請參閱 Azure IoT 中樞檔中的如何取得 X.509 CA 憑證。

在 Git Bash 提示字元中執行本節中的步驟。

在 Git Bash 提示字元中，流覽至您想要建立憑證的目錄。

執行以下命令：

Windows
Linux

winpty openssl req -outform PEM -x509 -sha256 -newkey rsa:4096 -keyout device-key.pem -out device-cert.pem -days 30 -extensions usr_cert -addext extendedKeyUsage=clientAuth -subj "//CN=my-x509-device"

重要

僅需要為主體名稱（//CN=my-x509-device）提供的額外正斜線，才能在 Windows 平臺上使用 Git 逸出字串。

openssl req -outform PEM -x509 -sha256 -newkey rsa:4096 -keyout device-key.pem -out device-cert.pem -days 30 -extensions usr_cert -addext extendedKeyUsage=clientAuth -subj "/CN=my-x509-device"

當系統要求您 輸入 PEM 傳遞片語：時，請使用傳遞片語 1234。
當系統詢問 驗證 - 輸入 PEM 傳遞片語：時，請再次使用傳遞片語 1234 。

公鑰憑證檔案（device-cert.pem）和私鑰檔案（device-key.pem）現在應該會在您執行openssl命令的目錄中產生。

憑證檔案的主體通用名稱（CN）設定為 my-x509-device。針對以 X.509 為基礎的註冊，註冊標識符會設定為一般名稱。註冊標識碼是英數位元不區分大小寫的字串，加上特殊字元：'-'、、、'.'。'_'':' 最後一個字元必須是英數位元或虛線（'-'）。一般名稱必須遵循此格式。 DPS 支援最多 128 個字元的註冊標識符;不過，X.509 憑證中主體一般名稱的最大長度為 64 個字元。因此，使用 X.509 憑證時，註冊標識碼限制為 64 個字元。

憑證檔案是以Base 64編碼。若要檢視憑證檔案的主體通用名稱（CN）和其他屬性，請輸入下列命令：

Windows
Linux

winpty openssl x509 -in device-cert.pem -text -noout

openssl x509 -in device-cert.pem -text -noout

Certificate:
Data:
    Version: 3 (0x2)
    Serial Number:
        77:3e:1d:e4:7e:c8:40:14:08:c6:09:75:50:9c:1a:35:6e:19:52:e2
    Signature Algorithm: sha256WithRSAEncryption
    Issuer: CN = my-x509-device
    Validity
        Not Before: May  5 21:41:42 2022 GMT
        Not After : Jun  4 21:41:42 2022 GMT
    Subject: CN = my-x509-device
    Subject Public Key Info:
        Public Key Algorithm: rsaEncryption
            RSA Public-Key: (4096 bit)
            Modulus:
                00:d2:94:37:d6:1b:f7:43:b4:21:c6:08:1a:d6:d7:
                e6:40:44:4e:4d:24:41:6c:3e:8c:b2:2c:b0:23:29:
                ...
                23:6e:58:76:45:18:03:dc:2e:9d:3f:ac:a3:5c:1f:
                9f:66:b0:05:d5:1c:fe:69:de:a9:09:13:28:c6:85:
                0e:cd:53
            Exponent: 65537 (0x10001)
    X509v3 extensions:
        X509v3 Basic Constraints:
            CA:FALSE
        Netscape Comment:
            OpenSSL Generated Certificate
        X509v3 Subject Key Identifier:
            63:C0:B5:93:BF:29:F8:57:F8:F9:26:44:70:6F:9B:A4:C7:E3:75:18
        X509v3 Authority Key Identifier:
            keyid:63:C0:B5:93:BF:29:F8:57:F8:F9:26:44:70:6F:9B:A4:C7:E3:75:18

        X509v3 Extended Key Usage:
            TLS Web Client Authentication
Signature Algorithm: sha256WithRSAEncryption
     82:8a:98:f8:47:00:85:be:21:15:64:b9:22:b0:13:cc:9e:9a:
     ed:f5:93:b9:4b:57:0f:79:85:9d:89:47:69:95:65:5e:b3:b1:
     ...
     cc:b2:20:9a:b7:f2:5e:6b:81:a1:04:93:e9:2b:92:62:e0:1c:
     ac:d2:49:b9:36:d2:b0:21

範例程式代碼需要未加密的私鑰。執行下列命令以建立未加密的私密金鑰：

Windows
Linux

winpty openssl rsa -in device-key.pem -out unencrypted-device-key.pem

openssl rsa -in device-key.pem -out unencrypted-device-key.pem

當系統要求您輸入 device-key.pem：的傳遞片語時，請使用您先前執行的相同複雜片語。 1234

讓 Git Bash 提示保持開啟。您稍後在本快速入門中需要它。

C# 範例程式代碼已設定為使用 X.509 憑證，這些憑證會儲存在受密碼保護的 PKCS#12 格式檔案中（certificate.pfx）。您仍然需要您剛建立的 PEM 格式化公鑰憑證檔案（device-cert.pem），以在本快速入門稍後建立個別註冊專案。

若要產生範例預期的 PKCS12 格式檔案，請輸入下列命令：

Windows
Linux

winpty openssl pkcs12 -inkey device-key.pem -in device-cert.pem -export -out certificate.pfx

openssl pkcs12 -inkey device-key.pem -in device-cert.pem -export -out certificate.pfx

當系統要求您輸入 device-key.pem：的傳遞片語時，請使用您先前執行的相同複雜片語。 1234
當系統要求 輸入匯出密碼：時，請使用密碼 1234。
當系統詢問 驗證 - 輸入匯出密碼：時，請再次使用密碼 1234 。

PKCS12 格式化的憑證檔案（certificate.pfx）現在應該會在您執行 openssl 命令的目錄中產生。
將 PKCS12 格式化的憑證檔案複製到 X.509 裝置布建範例的項目目錄。提供的路徑相對於您下載範例存放庫的位置。
```
cp certificate.pfx ./azure-iot-sdk-csharp/provisioning/device/samples/"Getting Started"/X509Sample
```

您不需要 Git Bash 提示以取得本快速入門的其餘部分。不過，如果後續步驟發生問題，您可能想要保持開啟狀態來檢查憑證。

範例程式代碼需要未加密的私鑰。執行下列命令以建立未加密的私密金鑰：

Windows
Linux

winpty openssl rsa -in device-key.pem -out unencrypted-device-key.pem

openssl rsa -in device-key.pem -out unencrypted-device-key.pem

當系統要求您輸入 device-key.pem：的傳遞片語時，請使用您先前執行的相同複雜片語。 1234

將裝置憑證和未加密的私鑰複製到 X.509 裝置布建範例的項目目錄。提供的路徑相對於您下載 SDK 的位置。

cp device-cert.pem ./azure-iot-sdk-node/provisioning/device/samples
cp unencrypted-device-key.pem ./azure-iot-sdk-node/provisioning/device/samples

您不需要 Git Bash 提示以取得本快速入門的其餘部分。不過，如果後續步驟發生問題，您可能想要保持開啟狀態來檢查憑證。

將裝置憑證和私鑰複製到 X.509 裝置布建範例的項目目錄。提供的路徑相對於您下載 SDK 的位置。

cp device-cert.pem ./azure-iot-sdk-python/samples/async-hub-scenarios
cp device-key.pem ./azure-iot-sdk-python/samples/async-hub-scenarios

您不需要 Git Bash 提示以取得本快速入門的其餘部分。不過，如果後續步驟發生問題，您可能想要保持開啟狀態來檢查憑證。

Java 範例程式代碼需要未加密的私鑰。執行下列命令以建立未加密的私密金鑰：

Windows
Linux

winpty openssl pkey -in device-key.pem -out unencrypted-device-key.pem

openssl pkey -in device-key.pem -out unencrypted-device-key.pem

當系統要求您輸入 device-key.pem：的傳遞片語時，請使用您先前執行的相同複雜片語。 1234

讓 Git Bash 提示保持開啟。您稍後在本快速入門中需要它。

建立裝置註冊

Azure IoT 裝置布建服務支援兩種類型的註冊：

註冊群組：用來註冊多個相關裝置。
個別註冊：用來註冊單一裝置。

本文示範使用IoT中樞布建單一裝置的個別註冊。

登入 Azure 入口網站並流覽至您的裝置布建服務實例。
從導覽功能表的 [設定] 區段中選取 [管理註冊]。
選取 [ 個別註冊] 索引 標籤，然後選取 [ 新增個別註冊]。

在 [新增註冊] 頁面的 [註冊 + 布建] 上，提供下列信息來設定註冊詳細數據：

欄位	描述
認證	選取 [X.509 用戶端憑證 ] 作為證明機制。
X.509 憑證設定	上傳將用來驗證此註冊裝置的一或兩個憑證。
布建狀態	如果您想要讓此註冊可供布建其裝置，請核取 [ 啟用此註冊 ] 方塊。如果您想要停用註冊，請取消核取此方塊。您可以稍後變更此設定。
重新布建原則	選擇重新布建原則，以反映您希望 DPS 如何處理要求重新布建的裝置。如需詳細資訊，請參閱重新布建原則。

選取 [ 下一步：IoT 中樞]。

在 [新增註冊] 頁面的 [IoT 中樞] 索引卷標上，提供下列資訊來判斷註冊可以布建裝置的 IoT 中樞：

欄位	描述
目標IoT中樞	選取一或多個連結的IoT中樞，或將新連結新增至IoT中樞。若要深入瞭解如何將IoT中樞連結至 DPS 實例，請參閱如何連結和管理IoT中樞。
配置原則	如果您選取了多個連結的IoT中樞，請選取要將裝置指派給不同中樞的方式。若要深入瞭解配置原則，請參閱如何使用配置原則。如果您只選取一個連結的IoT中樞，建議您使用平均加權散發原則。

選取 [下一步：裝置設定]

在 [新增註冊] 頁面的 [裝置設定] 索引標籤上，提供下列資訊來定義新布建裝置的設定方式：

欄位	描述
裝置識別碼	提供將在 IoT 中樞中指派給布建裝置的裝置標識碼。如果您沒有提供裝置識別碼，將會使用註冊標識碼。
IoT Edge	如果布建的裝置將執行 Azure IoT Edge，請檢查布建裝置上的啟用 IoT Edge。如果此註冊適用於未啟用IoT Edge的裝置，請取消核取此方塊。
裝置標籤	使用此文字框提供您想要套用至所布建裝置裝置對應項的任何標籤。
所需的屬性	使用此文字框提供您想要套用至已布建裝置之裝置對應項的任何所需屬性。

如需詳細資訊，請參閱瞭解和使用 IoT 中樞中的裝置對應項。

完成時，選取 [下一步:檢閱 + 建立]。
在 [ 檢閱 + 建立] 索引標籤上，確認您的所有值，然後選取 [ 建立]。

準備並執行裝置佈建程序代碼

在本節中，您會更新範例程式代碼，以將裝置的開機順序傳送至您的裝置布建服務實例。此開機順序會讓裝置辨識並指派給連結至 DPS 實例的 IoT 中樞。

在本節中，您會使用 Git Bash 提示字元和 Visual Studio IDE。

設定布建裝置程序代碼

在本節中，您會使用裝置布建服務實例資訊來更新範例程序代碼。

在 Azure 入口網站中，選取裝置布建服務的 [概觀] 索引標籤。
複製 [ 標識符範圍] 值。
啟動 Visual Studio，然後開啟您在 azure-iot-sdk-c git 存放庫根目錄中建立 cmake 的新方案檔案。專案檔名為 azure_iot_sdks.sln。
在 Visual Studio 方案總管中，流覽至 [Provision_Samples > prov_dev_client_sample 原始程式檔]，>然後開啟 prov_dev_client_sample.c。
id_scope尋找常數，並將值取代為您在步驟 2 中複製的標識碼範圍值。
```
static const char* id_scope = "0ne00000A0A";
```

在相同的檔案中尋找函式的定義 main() 。請確定 hsm_type 變數已設定為 SECURE_DEVICE_TYPE_X509。

SECURE_DEVICE_TYPE hsm_type;
//hsm_type = SECURE_DEVICE_TYPE_TPM;
hsm_type = SECURE_DEVICE_TYPE_X509;
//hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;

儲存您的變更。
以 滑鼠右鍵按兩下prov_dev_client_sample 專案，然後選取 [ 設定為啟始專案]。

設定自訂 HSM 存根程式代碼

與實際安全硬體型記憶體互動的詳細數據會因硬體而異。因此，本快速入門中模擬裝置所使用的憑證和私鑰會在自定義硬體安全性模組（HSM）存根程式代碼中硬式編碼。

若要更新自定義 HSM 存根程式代碼，以模擬識別碼為 my-x509-device的裝置身分識別：

在visual Studio的方案總管中，流覽至 Provision_Samples custom_hsm_example >> Source Files，然後開啟 custom_hsm_example.c。
使用產生裝置憑證my-x509-device時所使用的一般名稱，更新字串常數的COMMON_NAME字串值。
```
static const char* const COMMON_NAME = "my-x509-device";
```
使用您先前產生的裝置憑證 device-cert.pem 更新常數位符串的字串值CERTIFICATE。

範例中的憑證文字語法必須遵循下列模式，Visual Studio 不會有額外的空格或剖析。
```
static const char* const CERTIFICATE = "-----BEGIN CERTIFICATE-----\n"
"MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n"
    ...
"MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n"
"-----END CERTIFICATE-----";        
```
手動更新此字串值可能會容易發生錯誤。若要產生適當的語法，您可以將下列命令複製並貼到 Git Bash 提示字元中，然後按 ENTER 鍵。此命令會產生字串常數值的 CERTIFICATE 語法，並將它寫入輸出。
```
sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' device-cert.pem
```
複製並貼上常數值的輸出憑證文字。
使用裝置憑證的未加密私鑰更新常數的 PRIVATE_KEY 字串值， unencrypted-device-key.pem。

私鑰文字的語法必須遵循下列模式，且 Visual Studio 不會有額外的空格或剖析。
```
static const char* const PRIVATE_KEY = "-----BEGIN RSA PRIVATE KEY-----\n"
"MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n"
    ...
"X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n"
"-----END RSA PRIVATE KEY-----";
```
手動更新此字串值可能會容易發生錯誤。若要產生適當的語法，您可以將下列命令複製並貼到 Git Bash 提示字元中，然後按 ENTER 鍵。此命令會產生字串常數值的 PRIVATE_KEY 語法，並將它寫入輸出。
```
sed -e 's/^/"/;$ !s/$/""\\n"/;$ s/$/"/' unencrypted-device-key.pem
```
複製並貼上常數值的輸出私鑰文字。
儲存您的變更。
以 滑鼠右鍵按兩下custom_hsm__example 專案，然後選取 [ 建置]。

重要

在下一節中建置其餘方案之前，您必須先建 置custom_hsm_example 專案。

執行範例

在 Visual Studio 選單上，選取 [偵錯>開始但不偵錯] 以執行解決方案。如果系統提示您重建專案，請在執行之前選取 [ 是 ] 以重建專案。

下列輸出是模擬裝置 my-x509-device 成功開機並連線到布建服務的範例。裝置會指派給IoT中樞並註冊：
```
Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-iot-hub-2.azure-devices.net, deviceId: my-x509-device
Press enter key to exit:
```

在本節中，您會使用 Windows 命令提示字元。

在 Azure 入口網站中，選取裝置布建服務的 [概觀] 索引標籤。
複製 [ 標識符範圍] 值。
在 Windows 命令提示字元中，變更為 X509Sample 目錄。此目錄位於 .\azure-iot-sdk-csharp\provisioning\device\samples\getting started\X509Sample 目錄，從您在計算機上複製範例的目錄。
輸入下列命令來建置並執行 X.509 裝置布建範例（將值取代 <IDScope> 為您在上一節中複製的標識符範圍。憑證檔案預設為 ./certificate.pfx，並提示輸入 .pfx 密碼。
```
dotnet run -- -s <IDScope>
```
如果您想要將憑證和密碼當做參數傳遞，您可以使用下列格式。

注意

執行應用程式以變更 TransportType （-t）和 GlobalDeviceEndpoint （-g）時，可以一起傳遞其他參數。
```
dotnet run -- -s 0ne00000A0A -c certificate.pfx -p 1234
```

裝置會連線到 DPS，並指派給 IoT 中樞。然後，裝置會將遙測訊息傳送至 IoT 中樞。

Loading the certificate...
Enter the PFX password for certificate.pfx:
****
Found certificate: A33DB11B8883DEE5B1690ACFEAAB69E8E928080B CN=my-x509-device; PrivateKey: True
Using certificate A33DB11B8883DEE5B1690ACFEAAB69E8E928080B CN=my-x509-device
Initializing the device provisioning client...
Initialized for registration Id my-x509-device.
Registering with the device provisioning service...
Registration status: Assigned.
Device my-x509-device registered to MyExampleHub.azure-devices.net.
Creating X509 authentication for IoT Hub...
Testing the provisioned device with IoT Hub...
Sending a telemetry message...
Finished.

在本節中，您會使用 Windows 命令提示字元。

在 Azure 入口網站中，選取裝置布建服務的 [概觀] 索引標籤。
複製 [ 標識符範圍] 值。

在 Windows 命令提示字元中，移至範例目錄，並安裝範例所需的套件。所顯示的路徑相對於您複製 SDK 的位置。

cd .\azure-iot-sdk-node\provisioning\device\samples
npm install

此範例會使用五個環境變數來驗證及布建使用 DPS 的 IoT 裝置。這些環境變數包括：

變數名稱	描述
`PROVISIONING_HOST`	用來連線到 DPS 實例的端點。在本快速入門中，請使用全域端點 `global.azure-devices-provisioning.net`。
`PROVISIONING_IDSCOPE`	DPS 實例的標識碼範圍。
`PROVISIONING_REGISTRATION_ID`	裝置的註冊標識碼。它必須符合裝置憑證中的主體通用名稱。
`CERTIFICATE_FILE`	裝置憑證檔案的路徑。
`KEY_FILE`	裝置私鑰檔案的路徑。

新增全域裝置端點和標識符範圍的環境變數。將取代 <id-scope> 為您在步驟 2 中複製的值。
```
set PROVISIONING_HOST=global.azure-devices-provisioning.net
set PROVISIONING_IDSCOPE=<id-scope>
```
設定裝置註冊標識碼的環境變數。 IoT 裝置的註冊標識碼必須符合其裝置憑證上的主體通用名稱。如果您遵循本快速入門中的步驟來產生自我簽署的測試憑證， my-x509-device 則為裝置的主體名稱和註冊標識符。
```
set PROVISIONING_REGISTRATION_ID=my-x509-device
```

設定裝置憑證和（未加密）裝置私鑰檔案的環境變數。

set CERTIFICATE_FILE=.\device-cert.pem
set KEY_FILE=.\unencrypted-device-key.pem

執行範例並確認已成功布建裝置。

node register_x509.js

您應該會看到類似下列範例的結果：

registration succeeded
assigned hub=contoso-hub-2.azure-devices.net
deviceId=my-x509-device
Client connected
send status: MessageEnqueued

在本節中，您會使用 Windows 命令提示字元。

在 Azure 入口網站中，選取裝置布建服務的 [概觀] 索引標籤。
複製標識元範圍和 全域裝置端點 值。

在 Windows 命令提示字元中，移至provision_x509.py範例的目錄。所顯示的路徑相對於您複製 SDK 的位置。

cd ./azure-iot-sdk-python/samples/async-hub-scenarios

此範例會使用六個環境變數來驗證及布建使用 DPS 的 IoT 裝置。這些環境變數包括：

變數名稱	描述
`PROVISIONING_HOST`	用來連線到 DPS 實例的全域端點。
`PROVISIONING_IDSCOPE`	DPS 實例的標識碼範圍。
`DPS_X509_REGISTRATION_ID`	裝置的註冊標識碼。它也必須符合裝置憑證上的主體名稱。
`X509_CERT_FILE`	裝置憑證檔案的路徑。
`X509_KEY_FILE`	裝置憑證私鑰檔案的路徑。
`PASS_PHRASE`	您用來加密憑證和私鑰檔案的傳遞片語（`1234`）。

新增全域裝置端點和標識符範圍的環境變數。

set PROVISIONING_HOST=global.azure-devices-provisioning.net
set PROVISIONING_IDSCOPE=<ID scope for your DPS resource>

設定註冊標識碼的環境變數。 IoT 裝置的註冊標識碼必須符合其裝置憑證上的主體名稱。如果您遵循本快速入門中的步驟來產生自我簽署的測試憑證， my-x509-device 則為裝置的主體名稱和註冊標識符。
```
set DPS_X509_REGISTRATION_ID=my-x509-device
```

設定憑證檔案、私鑰檔案和傳遞片語的環境變數。

set X509_CERT_FILE=./device-cert.pem
set X509_KEY_FILE=./device-key.pem
set PASS_PHRASE=1234

檢閱provision_x509.py的程序代碼。如果您未使用 Python 3.7 版或更新版本，請進行此處所述的程式代碼變更，以取代 asyncio.run(main()) 並儲存您的變更。

執行範例。此範例會連線到 DPS，其會將裝置布建至 IoT 中樞。布建裝置之後，此範例會將一些測試訊息傳送至IoT中樞。

$ python azure-iot-sdk-python/samples/async-hub-scenarios/provision_x509.py
RegistrationStage(RequestAndResponseOperation): Op will transition into polling after interval 2.  Setting timer.
The complete registration result is
my-x509-device
TestHub12345.azure-devices.net
initialAssignment
null
Will send telemetry from the provisioned device
sending message #4
sending message #7
sending message #2
sending message #8
sending message #5
sending message #9
sending message #1
sending message #6
sending message #10
sending message #3
done sending message #4
done sending message #7
done sending message #2
done sending message #8
done sending message #5
done sending message #9
done sending message #1
done sending message #6
done sending message #10
done sending message #3

在本節中，您會使用 Windows 命令提示字元和 Git Bash 提示字元。

在 Azure 入口網站中，選取裝置布建服務的 [概觀] 索引標籤。
複製標識元範圍和 全域裝置端點 值。
在您的 Windows 命令提示字元中，流覽至範例項目資料夾。顯示的路徑相對於您複製 SDK 的位置
```
cd .\azure-iot-sdk-java\provisioning\provisioning-device-client-samples\provisioning-X509-sample
```
在範例程式代碼中輸入布建服務和 X.509 身分識別資訊。這項資訊會在布建期間用於在裝置註冊之前證明模擬裝置。
1. 在慣用的編輯器中開啟檔案 .\src\main\java\samples\com\microsoft\azure\sdk\iot\ProvisioningX509Sample.java 。
2. 使用您先前複製的 識別碼範圍 和 布建服務全域端點 來更新下列值。
```
private static final String idScope = "[Your ID scope here]";
private static final String globalEndpoint = "[Your Provisioning Service Global Endpoint here]";
private static final ProvisioningDeviceClientTransportProtocol PROVISIONING_DEVICE_CLIENT_TRANSPORT_PROTOCOL = ProvisioningDeviceClientTransportProtocol.HTTPS;
```
3. 使用您的憑證 device-cert.pem 值更新常數位符串的值leafPublicPem。
  
  憑證文字的語法必須遵循下列模式，且沒有額外的空格或字元。
```
private static final String leafPublicPem = "-----BEGIN CERTIFICATE-----\n" +
"MIIFOjCCAyKgAwIBAgIJAPzMa6s7mj7+MA0GCSqGSIb3DQEBCwUAMCoxKDAmBgNV\n" +
    ...
"MDMwWhcNMjAxMTIyMjEzMDMwWjAqMSgwJgYDVQQDDB9BenVyZSBJb1QgSHViIENB\n" +
"-----END CERTIFICATE-----";        
```
  手動更新此字串值可能會容易發生錯誤。若要產生適當的語法，您可以將下列命令複製並貼到 Git Bash 提示字元中，然後按 ENTER 鍵。此命令會產生字串常數值的 leafPublicPem 語法，並將它寫入輸出。
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' device-cert.pem
```
  複製並貼上常數值的輸出憑證文字。
4. 使用裝置憑證的未加密私鑰更新常數的 leafPrivateKey 字串值， unencrypted-device-key.pem。
  
  私鑰文字的語法必須遵循下列模式，且沒有額外的空格或字元。
```
private static final String leafPrivateKey = "-----BEGIN PRIVATE KEY-----\n" +
"MIIJJwIBAAKCAgEAtjvKQjIhp0EE1PoADL1rfF/W6v4vlAzOSifKSQsaPeebqg8U\n" +
    ...
"X7fi9OZ26QpnkS5QjjPTYI/wwn0J9YAwNfKSlNeXTJDfJ+KpjXBcvaLxeBQbQhij\n" +
"-----END PRIVATE KEY-----";
```
  手動更新此字串值可能會容易發生錯誤。若要產生適當的語法，您可以將下列命令複製並貼到 Git Bash 提示字元中，然後按 ENTER 鍵。此命令會產生字串常數值的 leafPrivateKey 語法，並將它寫入輸出。
```
sed 's/^/"/;$ !s/$/\\n" +/;$ s/$/"/' unencrypted-device-key.pem
```
  複製並貼上常數值的輸出私鑰文字。
5. 儲存您的變更。
建置範例，然後移至 target 資料夾。
```
mvn clean install
cd target
```

組建會輸出資料夾中具有下列檔格式的.jar檔案 target ： provisioning-x509-sample-{version}-with-deps.jar;例如： provisioning-x509-sample-1.8.1-with-deps.jar。執行.jar檔案。您可能需要取代下列命令中的版本。

java -jar ./provisioning-x509-sample-1.8.1-with-deps.jar

此範例會連線到 DPS，其會將裝置布建至 IoT 中樞。布建裝置之後，此範例會將一些測試訊息傳送至IoT中樞。

Starting...
Beginning setup.
WARNING: sun.reflect.Reflection.getCallerClass is not supported. This will impact performance.
2022-05-11 09:42:05,025 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Initialized a ProvisioningDeviceClient instance using SDK version 2.0.0
2022-05-11 09:42:05,027 DEBUG (main) [com.microsoft.azure.sdk.iot.provisioning.device.ProvisioningDeviceClient] - Starting provisioning thread...
Waiting for Provisioning Service to register
2022-05-11 09:42:05,030 INFO (global.azure-devices-provisioning.net-6255a8ba-CxnPendingConnectionId-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Opening the connection to device provisioning service...
2022-05-11 09:42:05,252 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Connection to device provisioning service opened successfully, sending initial device registration message
2022-05-11 09:42:05,286 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-RegisterTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.RegisterTask] - Authenticating with device provisioning service using x509 certificates
2022-05-11 09:42:06,083 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Waiting for device provisioning service to provision this device...
2022-05-11 09:42:06,083 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Current provisioning status: ASSIGNING
Waiting for Provisioning Service to register
2022-05-11 09:42:15,685 INFO (global.azure-devices-provisioning.net-6255a8ba-Cxn6255a8ba-azure-iot-sdk-ProvisioningTask) [com.microsoft.azure.sdk.iot.provisioning.device.internal.task.ProvisioningTask] - Device provisioning service assigned the device successfully
IotHUb Uri : MyExampleHub.azure-devices.net
Device ID : java-device-01
2022-05-11 09:42:25,057 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-05-11 09:42:25,080 INFO (main) [com.microsoft.azure.sdk.iot.device.transport.ExponentialBackoffWithJitter] - NOTE: A new instance of ExponentialBackoffWithJitter has been created with the following properties. Retry Count: 2147483647, Min Backoff Interval: 100, Max Backoff Interval: 10000, Max Time Between Retries: 100, Fast Retry Enabled: true
2022-05-11 09:42:25,087 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Initialized a DeviceClient instance using SDK version 2.0.3
2022-05-11 09:42:25,129 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - Opening MQTT connection...
2022-05-11 09:42:25,150 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT CONNECT packet...
2022-05-11 09:42:25,982 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT CONNECT packet was acknowledged
2022-05-11 09:42:25,983 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sending MQTT SUBSCRIBE packet for topic devices/java-device-01/messages/devicebound/#
2022-05-11 09:42:26,068 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.Mqtt] - Sent MQTT SUBSCRIBE packet for topic devices/java-device-01/messages/devicebound/# was acknowledged
2022-05-11 09:42:26,068 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.mqtt.MqttIotHubConnection] - MQTT connection opened successfully
2022-05-11 09:42:26,070 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - The connection to the IoT Hub has been established
2022-05-11 09:42:26,071 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Updating transport status to new status CONNECTED with reason CONNECTION_OK
2022-05-11 09:42:26,071 DEBUG (main) [com.microsoft.azure.sdk.iot.device.DeviceIO] - Starting worker threads
2022-05-11 09:42:26,073 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking connection status callbacks with new status details
2022-05-11 09:42:26,074 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Client connection opened successfully
2022-05-11 09:42:26,075 INFO (main) [com.microsoft.azure.sdk.iot.device.DeviceClient] - Device client opened successfully
Sending message from device to IoT Hub...
2022-05-11 09:42:26,077 DEBUG (main) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Message was queued to be sent later ( Message details: Correlation Id [54d9c6b5-3da9-49fe-9343-caa6864f9a02] Message Id [28069a3d-f6be-4274-a48b-1ee539524eeb] )
Press any key to exit...
2022-05-11 09:42:26,079 DEBUG (MyExampleHub.azure-devices.net-java-device-01-ee6c362d-Cxn7a1fb819-e46d-4658-9b03-ca50c88c0440-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Sending message ( Message details: Correlation Id [54d9c6b5-3da9-49fe-9343-caa6864f9a02] Message Id [28069a3d-f6be-4274-a48b-1ee539524eeb] )
2022-05-11 09:42:26,422 DEBUG (MQTT Call: java-device-01) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - IotHub message was acknowledged. Checking if there is record of sending this message ( Message details: Correlation Id [54d9c6b5-3da9-49fe-9343-caa6864f9a02] Message Id [28069a3d-f6be-4274-a48b-1ee539524eeb] )
2022-05-11 09:42:26,425 DEBUG (MyExampleHub.azure-devices.net-java-device-01-ee6c362d-Cxn7a1fb819-e46d-4658-9b03-ca50c88c0440-azure-iot-sdk-IotHubSendTask) [com.microsoft.azure.sdk.iot.device.transport.IotHubTransport] - Invoking the callback function for sent message, IoT Hub responded to message ( Message details: Correlation Id [54d9c6b5-3da9-49fe-9343-caa6864f9a02] Message Id [28069a3d-f6be-4274-a48b-1ee539524eeb] ) with status OK
Message sent!

確認您的裝置布建註冊

若要查看裝置布建的IoT中樞，請檢查您先前建立之個別註冊的註冊詳細數據：

在 Azure 入口網站中，移至您的裝置布建服務。
在 [設定] 功能表中，選取 [管理註冊]。
選取 [個別註冊]。您先前 建立的 X.509 註冊專案 my-x509-device 應該會出現在清單中。
選取註冊專案。您裝置指派給的IoT中樞及其裝置識別碼會出現在 [註冊狀態] 之下。

若要確認IoT中樞內的裝置：

在 Azure 入口網站中，移至您裝置指派的 IoT 中樞。
在 [ 裝置管理] 功能表中，選取 [ 裝置]。
如果您的裝置已成功布建，其裝置標識碼 my-x509-device 應該會出現在清單中，且 [狀態 ] 已設定為 已啟用。如果您沒有看到您的裝置，請選取 [ 重新整理]。

重要

如果您從裝置註冊專案中的預設值變更 初始裝置對應項狀態 ，它可以從中樞提取所需的對應項狀態，並據以採取行動。如需詳細資訊，請參閱瞭解和使用 IoT 中樞中的裝置對應項

清除資源

如果您打算繼續處理和探索裝置用戶端範例，請勿清除本快速入門中建立的資源。如果您不打算繼續，請使用下列步驟來刪除本快速入門所建立的所有資源。

刪除您的裝置註冊

關閉您電腦上的裝置用戶端範例輸出視窗。
從 Azure 入口網站左側功能表中，選取 [所有資源]。
選取您的裝置布建服務。
在 [設定] 功能表中，選取 [管理註冊]。
選取 [ 個別註冊] 索引標籤 。
選取您在本快速入門中註冊之裝置註冊標識符旁的複選框。
在頁面頂端，選取 [刪除]。

從IoT 中樞刪除裝置註冊

從 Azure 入口網站左側功能表中，選取 [所有資源]。
選取您的IoT中樞。
在 [ 總管] 功能表中，選取 [IoT 裝置]。
選取您在本快速入門中註冊之裝置的裝置識別符旁的複選框。
在頁面頂端，選取 [刪除]。

下一步

在本快速入門中，您已使用個別註冊，將單一裝置布建至IoT中樞。接下來，瞭解如何跨多個中樞布建多個裝置。

教學課程：使用自定義配置原則管理IoT中樞指派

Share via

快速入門：布建 X.509 憑證模擬裝置

必要條件

準備您的開發環境

建立自我簽署 X.509 裝置憑證

建立裝置註冊

準備並執行裝置佈建程序代碼

設定布建裝置程序代碼

設定自訂 HSM 存根程式代碼

執行範例

確認您的裝置布建註冊

清除資源

刪除您的裝置註冊

從IoT 中樞刪除裝置註冊

下一步

其他資源

Share via

快速入門：布建 X.509 憑證模擬裝置

必要條件

準備您的開發環境

建立自我簽署 X.509 裝置憑證

建立裝置註冊

準備並執行裝置佈建程序代碼

設定布建裝置程序代碼

設定自訂 HSM 存根程式代碼

執行範例

確認您的裝置布建註冊

清除資源

刪除您的裝置註冊

從IoT 中樞 刪除裝置註冊

下一步

其他資源

從IoT 中樞刪除裝置註冊