Update config; verify ca certs

Author: kgremban

.openpublishing.redirection.json

@@ -3261,7 +3261,7 @@
     {
       "source_path": "articles/iot-edge/how-to-install-production-certificates.md",
       "redirect_url": "/azure/iot-edge/how-to-manage-device-certificates",
-      "redirect_document_id": false
+      "redirect_document_id": true
     },
     {
       "source_path": "articles/cognitive-services/cognitive-services-recommendations-quick-start.md",

articles/iot-edge/how-to-auto-provision-symmetric-keys.md

@@ -170,14 +170,14 @@ The section in the configuration file for symmetric key provisioning looks like
 provisioning:
    source: "dps"
    global_endpoint: "https://global.azure-devices-provisioning.net"
-   scope_id: "{scope_id}"
+   scope_id: "<SCOPE_ID>"
    attestation:
       method: "symmetric_key"
-      registration_id: "{registration_id}"
-      symmetric_key: "{symmetric_key}"
+      registration_id: "<REGISTRATION_ID>"
+      symmetric_key: "<SYMMETRIC_KEY>"
 ```
 
-Replace the placeholder values for `{scope_id}`, `{registration_id}`, and `{symmetric_key}` with the data you collected earlier. Make sure the **provisioning:** line has no preceding whitespace and that nested items are indented by two spaces.
+Replace the placeholder values for `<SCOPE_ID>`, `<REGISTRATION_ID>`, and `<SYMMETRIC_KEY>` with the data you collected earlier. Make sure the **provisioning:** line has no preceding whitespace and that nested items are indented by two spaces.
 
 ### Windows device
 

articles/iot-edge/how-to-auto-provision-x509-certs.md

@@ -21,7 +21,7 @@ This article shows you how to create a Device Provisioning Service enrollment us
 * Create either an individual enrollment for a device, or a group enrollment for a set of devices.
 * Install the IoT Edge runtime and register the device with IoT Hub.
 
-Using X.509 certificates as an attestation mechanism is an excellent way to scale production and simplify device provisioning. X.509 certificates are typically arranged in a certificate chain of trust in which each certificate in the chain is signed by the private key of the next higher certificate, and so on, terminating in a self-signed root certificate or a trusted root certificate. This arrangement establishes a delegated chain of trust from the root certificate generated by a trusted root certificate authority (CA) down through each intermediate CA to the end-entity "leaf" certificate installed on a device.
+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.
 
 ## Prerequisites
 
@@ -35,9 +35,9 @@ Using X.509 certificates as an attestation mechanism is an excellent way to scal
 
 ## Generate device identity certificates
 
-The device identity certificate is a leaf certificate that connects through a certificate chain of trust to the top X.509 CA certificate. The device identity certificate must have it common name (CN) set to the device ID that you want the device to have in your IoT hub.
+The device identity certificate is a leaf certificate that connects through a certificate chain of trust to the top X.509 certificate authority (CA) certificate. The device identity certificate must have it common name (CN) set to the device ID that you want the device to have in your IoT hub.
 
-Device identity certificates are only used for provisioning the IoT Edge device and authenticating the device with Azure IoT Hub. They are not signing certificates, unlike the CA certificates that the IoT Edge device presents to modules or leaf devices for verification. For more information, see [Azure IoT Edge certificate usage detail](iot-edge-certs.md).
+Device identity certificates are only used for provisioning the IoT Edge device and authenticating the device with Azure IoT Hub. They aren't signing certificates, unlike the CA certificates that the IoT Edge device presents to modules or leaf devices for verification. For more information, see [Azure IoT Edge certificate usage detail](iot-edge-certs.md).
 
 After you create the device identity certificate, you should have two files: a .cer or .pem file that contains the public portion of the certificate, and a .cer or .pem file with the private key of the certificate. If you plan to use group enrollment in DPS, you also need the public portion of an intermediate or root CA certificate in the same certificate chain of trust.
 
@@ -57,7 +57,7 @@ Windows:
 * `<WRKDIR>\certs\iot-edge-device-identity-<name>-full-chain.cert.pem`
 * `<WRKDIR>\private\iot-edge-device-identity-<name>.key.pem`
 
-You need both these certificates on the IoT Edge device. If you're going to use individual enrollment in DPS, then you will upload the .cert.pem file. If you're going to use group enrollment in DPS, then you also need an intermediate or root CA certificate in the same certificate chain of trust to upload. In the case of the test certs, you can use the `<WRKDIR>\certs\azure-iot-test-only.root.ca.cert.pem` certificate for group enrollment.
+You need both these certificates on the IoT Edge device. If you're going to use individual enrollment in DPS, then you will upload the .cert.pem file. If you're going to use group enrollment in DPS, then you also need an intermediate or root CA certificate in the same certificate chain of trust to upload. If you're using demo certs, use the `<WRKDIR>\certs\azure-iot-test-only.root.ca.cert.pem` certificate for group enrollment.
 
 ## Create a DPS individual enrollment
 
@@ -67,6 +67,8 @@ If you're looking to provision multiple IoT Edge devices, follow the steps in th
 
 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).
 
+For more information about enrollments in the Device Provisioning Service, see [How to manage device enrollments](../iot-dps/how-to-manage-enrollments.md).
+
 1. In the [Azure portal](https://portal.azure.com), navigate to your instance of IoT Hub Device Provisioning Service.
 
 1. Under **Settings**, select **Manage enrollments**.
@@ -83,12 +85,8 @@ When you create an enrollment in DPS, you have the opportunity to declare an **I
 
    * **IoT Edge device**: Select **True** to declare that the enrollment is for an IoT Edge device.
 
-   * **Select how you want to assign devices to hubs**: Accept the default value, evenly weighted distribution. Or choose a different value that is specific to this enrollment.
-
    * **Select the IoT hubs this device can be assigned to**: 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.
 
-   * **Select how you want device data to be handled on re-provisioning**: Accept the default value, re-provision and migrate data. Or choose a different value to determine how to handle when devices request provisioning after the first time.
-
    * **Initial Device Twin State**: Add a tag value to be added to the device twin if you'd like. You can use tags to target groups of devices for automatic deployment. For example:
 
       ```json
@@ -102,8 +100,6 @@ When you create an enrollment in DPS, you have the opportunity to declare an **I
       }
       ```
 
-   * **Enable entry**: Select **Enable**.
-
 1. Select **Save**.
 
 Now that an enrollment exists for this device, the IoT Edge runtime can automatically provision the device during installation. Continue to the [Install the IoT Edge runtime](#install-the-iot-edge-runtime) section to set up your IoT Edge device.
@@ -113,12 +109,54 @@ Now that an enrollment exists for this device, the IoT Edge runtime can automati
 Use your generated certificates and keys to create a group enrollment in DPS for multiple IoT Edge devices. Group enrollments use an intermediate or root CA certificate from the certificate chain of trust used to generate the individual device identity certificates.
 
 >[!NOTE]
->Currently, group enrollment is only supported for IoT Edge on Linux devices. 
+>Currently, group enrollment is only supported for IoT Edge on Linux devices.
 
 If you're looking to provision a single IoT Edge device instead, follow the steps in the previous section, [Create a DPS individual enrollment](#create-a-dps-individual-enrollment).
 
 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).
 
+### Verify your root certificate
+
+When you create an enrollment group, you have the option of using a verified certificate. You can verify a certificate with DPS by proving that you have ownership of the root certificate. For more information, see [How to do proof-of-possession for X.509 CA certificates](../iot-dps/how-to-verify-certificates.md).
+
+1. In the [Azure portal](https://portal.azure.com), navigate to your instance of IoT Hub Device Provisioning Service.
+
+1. Select **Certificates** from the left-hand menu.
+
+1. Select **Add** to add a new certificate.
+
+1. Enter a friendly name for your certificate, then browse to the .cer or .pem file that represents the public part of your X.509 certificate.
+
+   If you're using the demo certificates, upload the `<wrkdir>/certs/azure-iot-test-only.root.ca.cert.pem` certificate.
+
+1. Select **Save**.
+
+1. Your certificate should now be listed on the **Certificates** page. Select it to open the certificate details.
+
+1. Select **Generate Verification Code** then copy the generated code.
+
+1. Whether you brought your own CA certificate or are using the demo certificates, you can use the verification tool provided in the IoT Edge repository to verify proof of possession. The verification tool uses your CA certificate to sign a new certificate that has the provided verification code as the subject name.
+
+   * Windows:
+
+     ```powershell
+     New-CACertsVerificationCert "<verification code>"
+     ```
+
+   * Linux:
+
+     ```bash
+     ./certGen.sh create_verification_certificate <verification code>
+     ```
+
+1. In the same certificate details page in the Azure portal, upload the newly generated verification certificate.
+
+1. Select **Verify**.
+
+### Create enrollment group
+
+For more information about enrollments in the Device Provisioning Service, see [How to manage device enrollments](../iot-dps/how-to-manage-enrollments.md).
+
 1. In the [Azure portal](https://portal.azure.com), navigate to your instance of IoT Hub Device Provisioning Service.
 
 1. Under **Settings**, select **Manage enrollments**.
@@ -131,16 +169,12 @@ When you create an enrollment in DPS, you have the opportunity to declare an **I
 
    * **IoT Edge device**: Select **True**. For a group enrollment, all devices must be IoT Edge devices or none of them can be.
 
-   * **Certificate Type**: Select **CA Certificate** if you have a certificate stored with DPS already, or **Intermediate Certificate** if you want to upload a new file for just this enrollment.
+   * **Certificate Type**: Select **CA Certificate** if you have a verified CA certificate stored with DPS, or **Intermediate Certificate** if you want to upload a new file for just this enrollment.
 
-   * **Primary certificate**: If you chose CA certificate in the last section, choose your certificate from the dropdown list. If you chose intermediate certificate, upload the public file from an intermediate CA certificate in the certificate chain of trust that was used to generate the device identity certificates.
-
-   * **Select how you want to assign devices to hubs**: Accept the default value, evenly weighted distribution. Or choose a different value that is specific to this enrollment.
+   * **Primary certificate**: If you chose CA certificate in the last section, choose your certificate from the dropdown list. If you chose intermediate certificate, upload the public file from a CA certificate in the certificate chain of trust that was used to generate the device identity certificates.
 
    * **Select the IoT hubs this device can be assigned to**: 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.
 
-   * **Select how you want device data to be handled on re-provisioning**: Accept the default value, re-provision and migrate data. Or choose a different value to determine how to handle when devices request provisioning after the first time.
-
    * **Initial Device Twin State**: Add a tag value to be added to the device twin if you'd like. You can use tags to target groups of devices for automatic deployment. For example:
 
       ```json
@@ -154,8 +188,6 @@ When you create an enrollment in DPS, you have the opportunity to declare an **I
       }
       ```
 
-   * **Enable entry**: Select **Enable**.
-
 1. Select **Save**.
 
 Now that an enrollment exists for this device, the IoT Edge runtime can automatically provision the device during installation. Continue to the next section to set up your IoT Edge device.
@@ -191,10 +223,10 @@ The section in the configuration file for X.509 automatic provisioning looks lik
 provisioning:
   source: "dps"
   global_endpoint: "https://global.azure-devices-provisioning.net"
-  scope_id: "{scope_id}"
+  scope_id: "<SCOPE_ID>"
   attestation:
     method: "x509"
-#   registration_id: "<OPTIONAL REGISTRATION ID. IF UNSPECIFIED CAN BE OBTAINED FROM CN OF identity_cert"
+#   registration_id: "<OPTIONAL REGISTRATION ID. LEAVE COMMENTED OUT TO REGISTER WITH CN OF identity_cert>"
     identity_cert: "<REQUIRED URI TO DEVICE IDENTITY CERTIFICATE>"
     identity_pk: "<REQUIRED URI TO DEVICE IDENTITY PRIVATE KEY>"
 ```

articles/iot-edge/how-to-install-iot-edge-linux.md

@@ -174,13 +174,12 @@ sudo nano /etc/iotedge/config.yaml
 
 Find the provisioning configurations of the file and uncomment the **Manual provisioning configuration** section. Update the value of **device_connection_string** with the connection string from your IoT Edge device. Make sure any other provisioning sections are commented out. Make sure the **provisioning:** line has no preceding whitespace and that nested items are indented by two spaces.
 
-   ```yml
-   # Manual provisioning configuration
-   provisioning:
-     source: "manual"
-     device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
-     dyname_reprovisioning: false
-   ```
+```yml
+# Manual provisioning configuration
+provisioning:
+  source: "manual"
+  device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
+```
 
 To paste clipboard contents into Nano `Shift+Right Click` or press `Shift+Insert`.
 
@@ -196,7 +195,7 @@ sudo systemctl restart iotedge
 
 ### Option 2: Automatic provisioning
 
-IoT Edge devices can be automatically provisioned using the [Azure IoT Hub Device Provisioning Service (DPS)](../iot-dps/index.yml). Currently, IoT Edge supports two attestation mechanisms when using automatic provisioning, but your hardware requirements may impact your choices. For example, Raspberry Pi devices do not come with a Trusted Platform Module (TPM) chip by default. For more information, refer to the following articles:
+IoT Edge devices can be automatically provisioned using the [Azure IoT Hub Device Provisioning Service (DPS)](../iot-dps/index.yml). Currently, IoT Edge supports two attestation mechanisms when using automatic provisioning, but your hardware requirements may impact your choices. For example, Raspberry Pi devices do not come with a Trusted Platform Module (TPM) chip by default. For more information, see the following articles:
 
 * [Create and provision an IoT Edge device with a virtual TPM on a Linux VM](how-to-auto-provision-simulated-device-linux.md)
 * [Create and provision an IoT Edge device using X.509 certificates](how-to-auto-provision-x509-certs.md)
@@ -219,10 +218,10 @@ TPM attestation:
 provisioning:
   source: "dps"
   global_endpoint: "https://global.azure-devices-provisioning.net"
-  scope_id: "{scope_id}"
+  scope_id: "<SCOPE_ID>"
   attestation:
     method: "tpm"
-    registration_id: "{registration_id}"
+    registration_id: "<REGISTRATION_ID>"
 ```
 
 X.509 attestation:
@@ -232,10 +231,10 @@ X.509 attestation:
 provisioning:
   source: "dps"
   global_endpoint: "https://global.azure-devices-provisioning.net"
-  scope_id: "{scope_id}"
+  scope_id: "<SCOPE_ID>"
   attestation:
     method: "x509"
-#   registration_id: "<OPTIONAL REGISTRATION ID. IF UNSPECIFIED CAN BE OBTAINED FROM CN OF identity_cert"
+#   registration_id: "<OPTIONAL REGISTRATION ID. LEAVE COMMENTED OUT TO REGISTER WITH CN OF identity_cert>"
     identity_cert: "<REQUIRED URI TO DEVICE IDENTITY CERTIFICATE>"
     identity_pk: "<REQUIRED URI TO DEVICE IDENTITY PRIVATE KEY>"
 ```
@@ -247,11 +246,11 @@ Symmetric key attestation:
 provisioning:
   source: "dps"
   global_endpoint: "https://global.azure-devices-provisioning.net"
-  scope_id: "{scope_id}"
+  scope_id: "<SCOPE_ID>"
   attestation:
     method: "symmetric_key"
-    registration_id: "{registration_id}"
-    symmetric_key: "{symmetric_key}"
+    registration_id: "<REGISTRATION_ID>"
+    symmetric_key: "<SYMMETRIC_KEY>"
 ```
 
 To paste clipboard contents into Nano `Shift+Right Click` or press `Shift+Insert`.
@@ -314,7 +313,7 @@ Many embedded device manufacturers ship device images that contain custom Linux
    ./check-config.sh
    ```
 
-This command provides a detailed output that contains the status of kernel features that are used by the Moby runtime. You will want to ensure that all items under `Generally Necessary` and  `Network Drivers` are enabled to ensure that your kernel is fully compatible with the Moby runtime.  If you have identified any missing features, enable them by rebuilding your kernel from source and selecting the associated modules for inclusion in the appropriate kernel .config.  Similarly, if you are using a kernel configuration generator like defconfig or menuconfig, find and enable the respective features and rebuild your kernel accordingly.  Once you have deployed your newly modified kernel, run the check-config script again to verify that all the required features were successfully enabled.
+This command provides a detailed output that contains the status of kernel features that are used by the Moby runtime. You will want to ensure that all items under `Generally Necessary` and  `Network Drivers` are enabled to ensure that your kernel is fully compatible with the Moby runtime.  If you have identified any missing features, enable them by rebuilding your kernel from source and selecting the associated modules for inclusion in the appropriate kernel .config.  Similarly, if you are using a kernel configuration generator like `defconfig` or `menuconfig`, find and enable the respective features and rebuild your kernel accordingly.  Once you have deployed your newly modified kernel, run the check-config script again to verify that all the required features were successfully enabled.
 
 ## Uninstall IoT Edge
 

articles/iot-edge/how-to-install-iot-edge-windows.md

@@ -42,7 +42,7 @@ IoT Core devices must include the IoT Core- Windows Containers optional feature
 Get-Service vmcompute
 ```
 
-If the service is present, you should get a successful response with the service status listed as **running**. If the vmcompute service is not found, then your device does not meet the requirements for IoT Edge. Contact your hardware provider to ask about support for this feature.
+If the service is present, you should get a successful response with the service status listed as **running**. If the `vmcompute` service is not found, then your device does not meet the requirements for IoT Edge. Contact your hardware provider to ask about support for this feature.
 
 ### Prepare for a container engine