Merge pull request #211429 from micahl/update-tpm-tool

Recommend use of tpm2-tools

Author: prmerger-automator[bot]

articles/iot-edge/how-to-create-iot-edge-device.md

@@ -138,32 +138,32 @@ To see more of the features of DPS, see the [Features section of the overview pa
 
 ## Choose an authentication method
 
-### Symmetric keys attestation
-
-Symmetric key attestation is a simple approach to authenticating a device. This attestation method represents a "Hello world" experience for developers who are new to device provisioning, or don't have strict security requirements.
-
-When you create a new device identity in IoT Hub, the service creates two keys. You place one of the keys on the device, and it presents the key to IoT Hub when authenticating.
-
-This authentication method is faster to get started but not as secure. Device provisioning using a TPM or X.509 certificates is more secure and should be used for solutions with more stringent security requirements.
-
 ### X.509 certificate attestation
 
-Using X.509 certificates as an attestation mechanism is an excellent way to scale production and simplify device provisioning. Typically, X.509 certificates are arranged in a certificate chain of trust. Starting with a self-signed or trusted root certificate, each certificate in the chain signs the next lower certificate. This pattern creates a delegated chain of trust from the root certificate down through each intermediate certificate to the final "leaf" certificate installed on a device.
+Using X.509 certificates as an attestation mechanism is the recommended way to scale production and simplify device provisioning. Typically, X.509 certificates are arranged in a certificate chain of trust. Starting with a self-signed or trusted root certificate, each certificate in the chain signs the next lower certificate. This pattern creates a delegated chain of trust from the root certificate down through each intermediate certificate to the final "leaf" certificate installed on a device. 
 
-You create two X.509 identity certificates and place them on the device. When you create a new device identity in IoT Hub, you provide thumbprints from both certificates. When the device authenticates to IoT Hub, it presents one certificate and IoT Hub verifies that the certificate matches its thumbprint.
+You create two X.509 identity certificates and place them on the device. When you create a new device identity in IoT Hub, you provide thumbprints from both certificates. When the device authenticates to IoT Hub, it presents one certificate and IoT Hub verifies that the certificate matches its thumbprint. The X.509 keys on the device should be stored in a Hardware Security Module (HSM). For example, PKCS#11 modules, ATECC, dTPM, etc.
 
-This authentication method is more secure than symmetric keys and is recommended for production scenarios.
+This authentication method is more secure than symmetric keys and supports group enrollments which provides a simplified management experience for a high number of devices. This authentication method is recommended for production scenarios.
 
 ### Trusted platform module (TPM) attestation
 
-Using TPM attestation is the most secure method for device provisioning, as it provides authentication features in both software and hardware. Each TPM chip uses a unique endorsement key to verify its authenticity.
+Using TPM attestation is a method for device provisioning that uses authentication features in both software and hardware. Each TPM chip uses a unique endorsement key to verify its authenticity.
 
 TPM attestation is only available for provisioning at-scale with DPS, and only supports individual enrollments not group enrollments. Group enrollments aren't available because of the device-specific nature of TPM.
 
 TPM 2.0 is required when you use TPM attestation with the device provisioning service.
 
 This authentication method is more secure than symmetric keys and is recommended for production scenarios.
 
+### Symmetric keys attestation
+
+Symmetric key attestation is a simple approach to authenticating a device. This attestation method represents a "Hello world" experience for developers who are new to device provisioning, or don't have strict security requirements.
+
+When you create a new device identity in IoT Hub, the service creates two keys. You place one of the keys on the device, and it presents the key to IoT Hub when authenticating.
+
+This authentication method is faster to get started but not as secure. Device provisioning using a TPM or X.509 certificates is more secure and should be used for solutions with more stringent security requirements.
+
 ## Next steps
 
 You can use the table of contents to navigate to the appropriate end-to-end guide for creating an IoT Edge device for your IoT Edge solution's platform, provisioning, and authentication requirements.

articles/iot-edge/how-to-provision-devices-at-scale-linux-tpm.md

@@ -52,6 +52,8 @@ The tasks are as follows:
 
 A physical Linux device to be the IoT Edge device.
 
+If you are a device manufacturer then refer to guidance on [integrating a TPM into the manufacturing process](../iot-dps/concepts-device-oem-security-practices.md#integrating-a-tpm-into-the-manufacturing-process).
+
 # [Virtual machine](#tab/virtual-machine)
 
 A Windows development machine with [Hyper-V enabled](/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). This article uses Windows 10 running an Ubuntu Server VM.
@@ -141,6 +143,8 @@ After the installation is finished and you've signed back in to your VM, you're
 
 ## Retrieve provisioning information for your TPM
 
+<!-- 1.1 -->
+:::moniker range="<iotedge-1.4"
 In this section, you build a tool that you can use to retrieve the registration ID and endorsement key for your TPM.
 
 1. Sign in to your device, and 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.
@@ -157,11 +161,74 @@ In this section, you build a tool that you can use to retrieve the registration
 
 1. The output window displays the device's **Registration ID** and the **Endorsement key**. Copy these values for use later when you create an individual enrollment for your device in the device provisioning service.
 
-> [!TIP]
-> If you don't want to use the SDK tool to retrieve the information, you need to find another way to obtain the provisioning information. The endorsement key, which is unique to each TPM chip, is obtained from the TPM chip manufacturer associated with it. You can derive a unique registration ID for your TPM device. For example, you can create an SHA-256 hash of the endorsement key.
+:::moniker-end
+<!-- end 1.1 -->
+
+<!-- iotedge-1.4 -->
+:::moniker range=">=iotedge-1.4"
+
+> [!NOTE]
+> This article previously used the `tpm_device_provision` tool from the IoT C SDK to generate provisioning info. If you relied on that tool previously, then be aware the steps below generate a different registration ID for the same public endorsement key. If you need to recreate the registration ID as before then refer to how the C SDK's [tpm_device_provision tool](https://github.com/Azure/azure-iot-sdk-c/tree/main/provisioning_client/tools/tpm_device_provision) generates it. Be sure the registration ID for the individual enrollment in DPS matches the regisration ID the IoT Edge device is configured to use.
+
+In this section, you use the TPM2 software tools to retrieve the endorsement key for your TPM and then generate a unique registration ID. This section corresponds with [Step 3: Device has firmware and software installed](../iot-dps/concepts-device-oem-security-practices.md#step-3-device-has-firmware-and-software-installed) in the process for [integrating a TPM into the manufacturing process](../iot-dps/concepts-device-oem-security-practices.md#integrating-a-tpm-into-the-manufacturing-process).
+
+### Install the TPM2 Tools
+Sign in to your device, and install the `tpm2-tools` package.
+
+# [Ubuntu / Debian / Raspberry Pi OS](#tab/ubuntu+debian+rpios)
+
+
+   ```bash
+   sudo apt-get install tpm2-tools
+   ```
+
+# [Red Hat Enterprise Linux](#tab/rhel)
+
+
+   ```bash
+   sudo yum install tpm2-tools
+   ```
+
+---
+
+Run the following script to read the endorsement key, creating one if it does not already exist.
+
+   ```bash
+   #!/bin/sh
+   if [ "$USER" != "root" ]; then
+     SUDO="sudo "
+   fi
+
+   $SUDO tpm2_readpublic -Q -c 0x81010001 -o ek.pub 2> /dev/null
+   if [ $? -gt 0 ]; then
+     # Create the endorsement key (EK)
+     $SUDO tpm2_createek -c 0x81010001 -G rsa -u ek.pub
+
+     # Create the storage root key (SRK)
+     $SUDO tpm2_createprimary -Q -C o -c srk.ctx > /dev/null
+
+     # make the SRK persistent
+     $SUDO tpm2_evictcontrol -c srk.ctx 0x81000001 > /dev/null
+
+     # open transient handle space for the TPM
+     $SUDO tpm2_flushcontext -t > /dev/null
+   fi
+
+   printf "Gathering the registration information...\n\nRegistration Id:\n%s\n\nEndorsement Key:\n%s\n" $(sha256sum -b ek.pub | cut -d' ' -f1 | sed -e 's/[^[:alnum:]]//g') $(base64 -w0 ek.pub)
+   $SUDO rm ek.pub srk.ctx 2> /dev/null
+
+   ```
+
+The output window displays the device's **Endorsement key** and a unique **Registration ID**. Copy these values for use later when you create an individual enrollment for your device in the device provisioning service.
+
+:::moniker-end
+<!-- end iotedge-1.4 -->
 
 After you have your registration ID and endorsement key, you're ready to continue.
 
+> [!TIP]
+> If you don't want to use the TPM2 software tools to retrieve the information, you need to find another way to obtain the provisioning information. The endorsement key, which is unique to each TPM chip, is obtained from the TPM chip manufacturer associated with it. You can derive a unique registration ID for your TPM device. For example, as shown above you can create an SHA-256 hash of the endorsement key.
+
 <!-- Create an enrollment for your device using TPM provisioning information H2 and content -->
 [!INCLUDE [tpm-create-a-device-provision-service-enrollment.md](../../includes/tpm-create-a-device-provision-service-enrollment.md)]
 

articles/iot-edge/how-to-provision-devices-at-scale-linux-x509.md

@@ -24,6 +24,9 @@ The tasks are as follows:
 
 Using X.509 certificates as an attestation mechanism is an excellent way to scale production and simplify device provisioning. Typically, X.509 certificates are arranged in a certificate chain of trust. Starting with a self-signed or trusted root certificate, each certificate in the chain signs the next lower certificate. This pattern creates a delegated chain of trust from the root certificate down through each intermediate certificate to the final "leaf" certificate installed on a device.
 
+> [!TIP]
+> If your device has a Hardware Security Module (HSM) such as a TPM 2.0, then we recommend storing the X.509 keys securely in the HSM. Learn more about how to implement the zero-touch provisioning at scale described in [this blueprint](https://azure.microsoft.com/blog/the-blueprint-to-securely-solve-the-elusive-zerotouch-provisioning-of-iot-devices-at-scale) with the [iotedge-tpm2cloud](https://aka.ms/iotedge-tpm2cloud) sample.
+
 ## Prerequisites
 
 <!-- Cloud resources prerequisites H3 and content -->