Merge pull request #86034 from v-stadam/x509_deploy_dps_0816

Use X.509 with DPS enrollments

Author: garycentric

articles/iot-edge/TOC.yml

@@ -135,14 +135,14 @@
       href: how-to-update-iot-edge.md
   - name: Auto-provision with DPS
     items:
-    - name: Symmetric key attestation
-      href: how-to-auto-provision-symmetric-keys.md
     - name: TPM attestation
       items:
       - name: Linux
         href: how-to-auto-provision-simulated-device-linux.md
       - name: Windows
-        href: how-to-auto-provision-simulated-device-windows.md  
+        href: how-to-auto-provision-simulated-device-windows.md
+    - name: Symmetric key attestation
+      href: how-to-auto-provision-symmetric-keys.md
   - name: Develop and debug custom modules
     items:
     - name: Visual Studio 2019

articles/iot-edge/how-to-auto-provision-simulated-device-linux.md

@@ -13,21 +13,28 @@ ms.custom: seodec18
 
 # Create and provision an IoT Edge device with a virtual TPM on a Linux virtual machine
 
-Azure IoT Edge devices can be automatically provisioned using the [Device Provisioning Service](../iot-dps/index.yml). If you're unfamiliar with the process of autoprovisioning, review the [autoprovisioning concepts](../iot-dps/concepts-auto-provisioning.md) before continuing. 
+Azure IoT Edge devices can be automatically provisioned using the [Device Provisioning Service](../iot-dps/index.yml). If you're unfamiliar with the process of auto-provisioning, review the [auto-provisioning concepts](../iot-dps/concepts-auto-provisioning.md) before continuing.
 
-This article shows you how to test autoprovisioning on a simulated IoT Edge device with the following steps: 
+This article shows you how to test auto-provisioning on a simulated IoT Edge device with the following steps:
 
 * Create a Linux virtual machine (VM) in Hyper-V with a simulated Trusted Platform Module (TPM) for hardware security.
 * Create an instance of IoT Hub Device Provisioning Service (DPS).
 * Create an individual enrollment for the device
 * Install the IoT Edge runtime and connect the device to IoT Hub
 
-The steps in this article are meant for testing purposes.
+> [!NOTE]
+> TPM 2.0 is required when using TPM attestation with DPS and can only be used to create individual, not group, enrollments.
+
+> [!TIP]
+> This article describes how to test DPS provisioning using a TPM simulator, but much of it applies to physical TPM hardware such as the [Infineon OPTIGA™ TPM](https://catalog.azureiotsolutions.com/details?title=OPTIGA-TPM-SLB-9670-Iridium-Board), an Azure Certified for IoT device.
+>
+> If you're using a physical device, you can skip ahead to the [Retrieve provisioning information from a physical device](#retrieve-provisioning-information-from-a-physical-device) section in this article.
 
 ## Prerequisites
 
-* A Windows development machine with [Hyper-V enabled](https://docs.microsoft.com/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). This article uses Windows 10 running an Ubuntu Server VM. 
-* An active IoT Hub. 
+* A Windows development machine with [Hyper-V enabled](https://docs.microsoft.com/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). This article uses Windows 10 running an Ubuntu Server VM.
+* An active IoT Hub.
+* If using a simulated TPM, [Visual Studio](https://visualstudio.microsoft.com/vs/) 2015 or later with the ['Desktop development with C++'](https://www.visualstudio.com/vs/support/selecting-workloads-visual-studio-2017/) workload enabled.
 
 ## Create a Linux virtual machine with a virtual TPM
 
@@ -67,7 +74,7 @@ It may take a few minutes to create the new VM.
 
 ### Enable virtual TPM
 
-Once your VM is created, open its settings to enable the virtual trusted platform module (TPM) that lets you autoprovision the device. 
+Once your VM is created, open its settings to enable the virtual trusted platform module (TPM) that lets you auto-provision the device.
 
 1. Select the virtual machine, then open its **Settings**.
 
@@ -81,18 +88,48 @@ Once your VM is created, open its settings to enable the virtual trusted platfor
 
 ### Start the virtual machine and collect TPM data
 
-In the virtual machine, build a C SDK tool that you can use to retrieve the device's **Registration ID** and **Endorsement Key**. 
+In the virtual machine, build a tool that you can use to retrieve the device's **Registration ID** and **Endorsement key**.
 
 1. Start your virtual machine and connect to it.
 
-2. Follow the prompts within the virtual machine to finish the installation process and reboot the machine. 
+1. Follow the prompts within the virtual machine to finish the installation process and reboot the machine.
 
-3. Sign in to your VM, then follow the steps in [Set up a Linux development environment](https://github.com/Azure/azure-iot-sdk-c/blob/master/doc/devbox_setup.md#linux) to install and build the Azure IoT device SDK for C. 
+1. Sign in to your VM, then follow the steps in [Set up a Linux development environment](https://github.com/Azure/azure-iot-sdk-c/blob/master/doc/devbox_setup.md#linux) to install and build the Azure IoT device SDK for C.
 
    >[!TIP]
-   >In the course of this article, you'll copy to and paste from the virtual machine, which is not easy through the Hyper-V Manager connection application. You may want to connect to virtual machine through Hyper-V Manager once to retrieve its IP address: `ifconfig`. Then, you can use the IP address to connect through SSH: `ssh <username>@<ipaddress>`.
+   >In the course of this article, you'll copy to and paste from the virtual machine, which is not easy through the Hyper-V Manager connection application. You may want to connect to the virtual machine through Hyper-V Manager once to retrieve its IP address: `ifconfig`. Then, you can use the IP address to connect through SSH: `ssh <username>@<ipaddress>`.
 
-4. Run the following commands to build an C SDK tool that retrieves your device provisioning information. 
+1. Run the following commands to build the SDK tool that retrieves your device provisioning information from the TPM simulator.
+
+   ```bash
+   cd azure-iot-sdk-c/cmake
+   cmake -Duse_prov_client:BOOL=ON -Duse_tpm_simulator:BOOL=ON ..
+   cd provisioning_client/tools/tpm_device_provision
+   make
+   sudo ./tpm_device_provision
+   ```
+
+1. From a command window, navigate to the `azure-iot-sdk-c` directory and run the TPM simulator. It listens over a socket on ports 2321 and 2322. Do not close this command window; you will need to keep this simulator running.
+
+   From the `azure-iot-sdk-c` directory, run the following command to start the simulator:
+
+   ```bash
+   ./provisioning_client/deps/utpm/tools/tpm_simulator/Simulator.exe
+   ```
+
+1. Using Visual Studio, open the solution generated in the `cmake` directory named `azure_iot_sdks.sln`, and build it using the **Build solution** command on the **Build** menu.
+
+1. In the **Solution Explorer** pane in Visual Studio, navigate to the folder **Provision\_Tools**. Right-click the **tpm_device_provision** project and select **Set as Startup Project**.
+
+1. Run the solution using either of the **Start** commands on the **Debug** menu. The output window displays the TPM simulator's **Registration ID** and the **Endorsement key**, which you should copy for use later when you create an individual enrollment for your device in You can close this window (with Registration ID and Endorsement key), but leave the TPM simulator window running.
+
+## Retrieve provisioning information from a physical device
+
+On your device, build a tool that you can use to retrieve the device's provisioning information.
+
+1. Follow the steps in [Set up a Linux development environment](https://github.com/Azure/azure-iot-sdk-c/blob/master/doc/devbox_setup.md#linux) to install and build the Azure IoT device SDK for C.
+
+1. Run the following commands to build the SDK tool that retrieves your device provisioning information from the TPM device.
 
    ```bash
    cd azure-iot-sdk-c/cmake
@@ -101,10 +138,8 @@ In the virtual machine, build a C SDK tool that you can use to retrieve the devi
    make
    sudo ./tpm_device_provision
    ```
-   >[!TIP]
-   >If you are testing with TPM simulator, you'll need to put an extra parameter `-Duse_tpm_simulator:BOOL=ON` to enable it. The full command will be `cmake -Duse_prov_client:BOOL=ON -Duse_tpm_simulator:BOOL=ON ..`.
 
-5. Copy the values for **Registration ID** and **Endorsement Key**. You use these values to create an individual enrollment for your device in DPS. 
+1. Copy the values for **Registration ID** and **Endorsement key**. You use these values to create an individual enrollment for your device in DPS.
 
 ## Set up the IoT Hub Device Provisioning Service
 
@@ -125,15 +160,18 @@ When you create an enrollment in DPS, you have the opportunity to declare an **I
 3. Select **Add individual enrollment** then complete the following steps to configure the enrollment:  
 
    1. For **Mechanism**, select **TPM**. 
-   
+
    2. Provide the **Endorsement key** and **Registration ID** that you copied from your virtual machine.
-   
+
+      > [!TIP]
+      > If you're using a physical TPM device, you need to determine the **Endorsement key**, which is unique to each TPM chip and is obtained from the TPM chip manufacturer associated with it. You can derive a unique **Registration ID** for your TPM device by, for example, creating an SHA-256 hash of the endorsement key.
+
    3. Select **True** to declare that this virtual machine is an IoT Edge device. 
-   
+
    4. Choose the linked **IoT Hub** that you want to connect your device to. You can choose multiple hubs, and the device will be assigned to one of them according to the selected allocation policy. 
-   
+
    5. Provide an ID for your device if you'd like. You can use device IDs to target an individual device for module deployment. If you don't provide a device ID, the registration ID is used.
-   
+
    6. Add a tag value to the **Initial Device Twin State** if you'd like. You can use tags to target groups of devices for module deployment. For example: 
 
       ```json
@@ -212,35 +250,6 @@ You can give TPM access to the IoT Edge runtime by overriding the systemd settin
 
    If you don't see that the correct permissions have been applied, try rebooting your machine to refresh udev. 
 
-8. Open the IoT Edge runtime overrides file. 
-
-   ```bash
-   sudo systemctl edit iotedge.service
-   ```
-
-9. Add the following code to establish a TPM environment variable.
-
-   ```input
-   [Service]
-   Environment=IOTEDGE_USE_TPM_DEVICE=ON
-   ```
-
-10. Save and exit the file.
-
-11. Verify that the override was successful.
-
-    ```bash
-    sudo systemctl cat iotedge.service
-    ```
-
-    Successful output displays the **iotedge** default service variables, and then shows the environment variable that you set in **override.conf**. 
-
-12. Reload the settings.
-
-    ```bash
-    sudo systemctl daemon-reload
-    ```
-
 ## Restart the IoT Edge runtime
 
 Restart the IoT Edge runtime so that it picks up all the configuration changes that you made on the device. 

articles/iot-edge/how-to-auto-provision-simulated-device-windows.md

@@ -1,5 +1,5 @@
 ---
-title: Auto-provision Windows devices with DPS - Azure IoT Edge | Microsoft Docs 
+title: Automatically provision Windows devices with DPS - Azure IoT Edge | Microsoft Docs 
 description: Use a simulated device on your Windows machine to test automatic device provisioning for Azure IoT Edge with Device Provisioning Service
 author: kgremban
 manager: philmea
@@ -11,17 +11,23 @@ services: iot-edge
 ms.custom: seodec18
 ---
 
-# Create and provision a simulated TPM Edge device on Windows
+# Create and provision a simulated IoT Edge device with a virtual TPM on Windows
 
 Azure IoT Edge devices can be auto-provisioned using the [Device Provisioning Service](../iot-dps/index.yml) just like devices that are not edge-enabled. If you're unfamiliar with the process of auto-provisioning, review the [auto-provisioning concepts](../iot-dps/concepts-auto-provisioning.md) before continuing.
 
-This article shows you how to test auto-provisioning on a simulated Edge device with the following steps:
+This article shows you how to test auto-provisioning on a simulated IoT Edge device with the following steps:
 
 * Create an instance of IoT Hub Device Provisioning Service (DPS).
 * Create a simulated device on your Windows machine with a simulated Trusted Platform Module (TPM) for hardware security.
 * Create an individual enrollment for the device.
 * Install the IoT Edge runtime and connect the device to IoT Hub.
 
+> [!NOTE]
+> TPM 2.0 is required when using TPM attestation with DPS and can only be used to create individual, not group, enrollments.
+
+> [!TIP]
+> This article describes testing auto-provisioning by using TPM attestation on virtual devices, but much of it applies when using physical TPM hardware as well.
+
 ## Prerequisites
 
 * A Windows development machine. This article uses Windows 10.
@@ -33,9 +39,14 @@ Create a new instance of the IoT Hub Device Provisioning Service in Azure, and l
 
 After you have the Device Provisioning Service running, copy the value of **ID Scope** from the overview page. You use this value when you configure the IoT Edge runtime.
 
+> [!TIP]
+> If you're using a physical TPM device, you need to determine the **Endorsement key**, which is unique to each TPM chip and is obtained from the TPM chip manufacturer associated with it. You can derive a unique **Registration ID** for your TPM device by, for example, creating an SHA-256 hash of the endorsement key.
+>
+> Follow the instructions in the article [How to manage device enrollments with Azure Portal](../iot-dps/how-to-manage-enrollments.md) to create your enrollment in DPS and then proceed with the [Install the IoT Edge runtime](#install-the-iot-edge-runtime) section in this article to continue.
+
 ## Simulate a TPM device
 
-Create a simulated TPM device on your Windows development machine. Retrieve the **Registration ID** and **Endorsement Key** for your device, and use them to create an individual enrollment entry in DPS.
+Create a simulated TPM device on your Windows development machine. Retrieve the **Registration ID** and **Endorsement key** for your device, and use them to create an individual enrollment entry in DPS.
 
 When you create an enrollment in DPS, you have the opportunity to declare an **Initial Device Twin State**. In the device twin you can set tags to group devices by any metric you need in your solution, like region, environment, location, or device type. These tags are used to create [automatic deployments](how-to-deploy-monitor.md).
 
@@ -55,15 +66,39 @@ After creating the individual enrollment, save the value of the **Registration I
 
 ## Install the IoT Edge runtime
 
-After completing the previous section, you should see your new device listed as an IoT Edge device in your IoT Hub. Now, you need to install the IoT Edge runtime on your device.
+The IoT Edge runtime is deployed on all IoT Edge devices. Its components run in containers, and allow you to deploy additional containers to the device so that you can run code at the edge.
+
+You'll need the following information when provisioning your device:
+
+* The DPS **ID Scope** value
+* The device **Registration ID** you created
+
+Install the IoT Edge runtime on the device that is running the simulated TPM. You'll configure the IoT Edge runtime for automatic, not manual, provisioning.
 
-The IoT Edge runtime is deployed on all IoT Edge devices. Its components run in containers, and allow you to deploy additional containers to the device so that you can run code at the edge.  
+> [!TIP]
+> Keep the window that's running the TPM simulator open during your installation and testing.
 
-Follow the instructions to install the IoT Edge runtime on the device that is running the simulated TPM from the previous section. Make sure to configure the IoT Edge runtime for automatic, not manual, provisioning.
+For more detailed information about installing IoT Edge on Windows, including prerequisites and instructions for tasks like managing containers and updating IoT Edge, see [Install the Azure IoT Edge runtime on Windows](how-to-install-iot-edge-windows.md).
 
-Know your DPS **ID Scope** and device **Registration ID** before installing IoT Edge on your device.
+1. Open a PowerShell window in administrator mode. Be sure to use an AMD64 session of PowerShell when installing IoT Edge, not PowerShell (x86).
 
-[Install and automatically provision IoT Edge](how-to-install-iot-edge-windows.md#option-2-install-and-automatically-provision)
+1. The **Deploy-IoTEdge** command checks that your Windows machine is on a supported version, turns on the containers feature, and then downloads the moby runtime and the IoT Edge runtime. The command defaults to using Windows containers.
+
+   ```powershell
+   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
+   Deploy-IoTEdge
+   ```
+
+1. At this point, IoT Core devices may restart automatically. Other Windows 10 or Windows Server devices may prompt you to restart. If so, restart your device now. Once your device is ready, run PowerShell as an administrator again.
+
+1. The **Initialize-IoTEdge** command configures the IoT Edge runtime on your machine. The command defaults to manual provisioning with Windows containers. Use the `-Dps` flag to use the Device Provisioning Service instead of manual provisioning.
+
+   Replace the placeholder values for `{scope_id}` and `{registration_id}` with the data you collected earlier.
+
+   ```powershell
+   . {Invoke-WebRequest -useb https://aka.ms/iotedge-win} | Invoke-Expression; `
+   Initialize-IoTEdge -Dps -ScopeId {scope ID} -RegistrationId {registration ID}
+   ```
 
 ## Verify successful installation
 
@@ -77,7 +112,6 @@ Get-Service iotedge
 
 Examine service logs from the last 5 minutes.
 
-
 ```powershell
 . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog
 ```