Merge pull request #290905 from kgremban/nov11-baltimore

Baltimore root cert migration has ended

Author: v-shils

articles/iot-dps/concepts-x509-attestation.md

@@ -49,7 +49,23 @@ Imagine that Contoso is a large corporation with its own Public Key Infrastructu
 
 A *leaf certificate*, or *end-entity certificate*, identifies a certificate holder. It has the root certificate in its certificate chain and zero or more intermediate certificates. A leaf certificate is not used to sign any other certificates. It uniquely identifies a device to the provisioning service and is sometimes referred to as a *device certificate*. During authentication, a device uses the private key associated with its certificate to respond to a proof of possession challenge from the service.
 
-## Use X.509 certificates with DPS
+## Prepare certificates
+
+Devices use two different types of certificates when they connect to IoT Hub through DPS. When preparing your device, make sure you have all the proper certificates created and added to the device before connecting.
+
+* Public root certificates: All devices need a copy of the public root certificates that IoT Hub, IoT Central, and Device Provisioning Service use to authorize connections.
+* Authentication certificates: X.509 certificates are the recommended method for authenticating a device identity.
+
+### Required public root certificates
+
+Azure IoT devices use TLS to verify the authenticity of the IoT hub or DPS endpoint they're connecting to. Each device needs a copy of the root certificate that IoT Hub and DPS use. We recommend that all devices include the following root CAs in their trusted certificate store:
+
+* DigiCert Global G2 root CA
+* Microsoft RSA root CA 2017
+
+For more information about recommended certificate practices, see [TLS support](./tls-support.md).
+
+## Authentication using X.509 certificates
 
 The provisioning service exposes two enrollment types that you can use to control device access with the X.509 attestation mechanism:  
 

articles/iot-dps/quick-enroll-device-x509.md

@@ -16,7 +16,7 @@ ms.subservice: azure-iot-hub-dps
 
 # Programmatically create a Device Provisioning Service enrollment group for X.509 certificate attestation
 
-This article shows you how to programmatically create an [enrollment group](concepts-service.md#enrollment-group) that uses intermediate or root CA X.509 certificates. The enrollment group is created by using the [Azure IoT Hub DPS service SDK](libraries-sdks.md#service-sdks) and a sample application. An enrollment group controls access to the provisioning service for devices that share a common signing certificate in their certificate chain. To learn more, see [Use X.509 certificates with DPS](./concepts-x509-attestation.md#use-x509-certificates-with-dps). For more information about using X.509 certificate-based Public Key Infrastructure (PKI) with Azure IoT Hub and Device Provisioning Service, see [X.509 CA certificate security overview](../iot-hub/iot-hub-x509ca-overview.md).
+This article shows you how to programmatically create an [enrollment group](concepts-service.md#enrollment-group) that uses intermediate or root CA X.509 certificates. The enrollment group is created by using the [Azure IoT Hub DPS service SDK](libraries-sdks.md#service-sdks) and a sample application. An enrollment group controls access to the provisioning service for devices that share a common signing certificate in their certificate chain. To learn more, see [Use X.509 certificates with DPS](./concepts-x509-attestation.md#authentication-using-x509-certificates). For more information about using X.509 certificate-based Public Key Infrastructure (PKI) with Azure IoT Hub and Device Provisioning Service, see [X.509 CA certificate security overview](../iot-hub/iot-hub-x509ca-overview.md).
 
 ## Prerequisites
 

articles/iot-dps/tls-support.md

@@ -7,7 +7,7 @@ author: kgremban
 ms.author: kgremban
 ms.service: azure-iot-hub
 ms.topic: concept-article
-ms.date: 09/15/2022
+ms.date: 11/27/2024
 ms.subservice: azure-iot-hub-dps
 ---
 
@@ -59,7 +59,7 @@ az deployment group create -g <your resource group name> --template-file templat
 
 For more information on creating DPS resources with Resource Manager templates, see, [Set up DPS with an Azure Resource Manager template](quick-setup-auto-provision-rm.md).
 
-The DPS resource created using this configuration will refuse devices that attempt to connect using TLS versions 1.0 and 1.1.
+The DPS resource created using this configuration refuses devices that attempt to connect using TLS versions 1.0 and 1.1.
 
 > [!NOTE]
 > The `minTlsVersion` property is read-only and cannot be changed once your DPS resource is created. It is therefore essential that you properly test and validate that *all* your IoT devices are compatible with TLS 1.2 and the [recommended ciphers](#recommended-ciphers) in advance.
@@ -77,7 +77,7 @@ DPS instances enforce the use of the following recommended and legacy cipher sui
 
 ### Legacy cipher suites
 
-These cipher suites are currently still supported by DPS but will be depreciated. Use the recommended cipher suites above if possible.
+These cipher suites are still supported by DPS but will be depreciated. Use the recommended cipher suites if possible.
 
 | Option #1 (better security) |
 | :--- |
@@ -91,9 +91,36 @@ These cipher suites are currently still supported by DPS but will be depreciated
 
 When DPS enrollments are configured for X.509 authentication, mutual TLS (mTLS) is supported by DPS.
 
-## Certificate pinning
+## Server TLS certificate
 
-[Certificate pinning](https://www.digicert.com/blog/certificate-pinning-what-is-certificate-pinning) and filtering of the TLS server certificates (aka leaf certificates) and intermediate certificates associated with DPS endpoints is strongly discouraged as Microsoft frequently rolls these certificates with little or no notice. If you must, only pin the root certificates as described in this [Azure IoT blog post](https://techcommunity.microsoft.com/t5/internet-of-things-blog/azure-iot-tls-critical-changes-are-almost-here-and-why-you/ba-p/2393169).
+During a TLS handshake, DPS presents RSA-keyed server certificates to connecting clients. All DPS instances in the global Azure cloud use the TLS certificate issued by the DigiCert Global Root G2 certificate. 
+
+We also recommend adding the Microsoft RSA Root Certificate Authority 2017 certificates to your devices to prevent disruptions in case the DigiCert Global Root G2 is retired unexpectedly. Although root CA migrations are rare, for resilience in the modern security landscape you should prepare your IoT scenario for the unlikely event that a root CA is compromised or an emergency root CA migration is necessary.
+
+We strongly recommend that all devices trust the following root CAs:
+
+* DigiCert Global G2 root CA
+* Microsoft RSA root CA 2017
+
+For links to download these certificates, see [Azure Certificate Authority details](../security/fundamentals/azure-CA-details.md).
+
+### Certificate trust in the SDKs
+
+The [Azure IoT device SDKs](../iot-hub/iot-hub-devguide-sdks.md) connect and authenticate devices to Azure IoT services. The different SDKs manage certificates in different ways depending on the language and version, but most rely on the device's trusted certificate store rather than pinning certificates directly in the codebase. This approach provides flexibility and resilience to handle future changes in root certificates. 
+
+The following table summarizes which SDK versions support the trusted certificate store:
+
+| Azure IoT device SDK | Supported versions |
+| -------------------- | ------------------ |
+| C | All currently supported versions |
+| C# | All currently supported versions |
+| Java | Version 2.x.x and higher |
+| Node.js | All currently supported versions |
+| Python | All currently supported versions |
+
+### Certificate pinning
+
+[Certificate pinning](https://www.digicert.com/blog/certificate-pinning-what-is-certificate-pinning) and filtering of the TLS server certificates (also known as leaf certificates) and intermediate certificates associated with DPS endpoints is discouraged as Microsoft frequently rolls these certificates with little or no notice. If you must, only pin the root certificates.
 
 ## Use TLS 1.2 in the IoT SDKs
 

articles/iot-hub/create-connect-device.md

@@ -22,6 +22,34 @@ Create a device identity for your device to connect to Azure IoT Hub. This artic
 
 * If your IoT hub is managed with role-based access control (RBAC), then you need **Read/Write/Delete Device/Module** permissions for the steps in this article. Those permissions are included in [IoT Hub Registry Contributor](../role-based-access-control/built-in-roles/internet-of-things.md#iot-hub-registry-contributor) role.
 
+## Prepare certificates
+
+Devices use two different types of certificates to connect to IoT Hub. When preparing your device, make sure you have all the proper certificates created and added to the device before connecting.
+
+* Public root certificates: All devices need a copy of the public root certificates that IoT Hub, IoT Central, and Device Provisioning Service use to authorize connections.
+* Authentication certificates: X.509 certificates are the recommended method for authenticating a device identity.
+
+### Required public root certificates
+
+Azure IoT devices use TLS to verify the authenticity of the IoT hub or DPS endpoint they're connecting to. Each device needs a copy of the root certificate that IoT Hub and DPS use. We recommend that all devices include the following root CAs in their trusted certificate store:
+
+* DigiCert Global G2 root CA
+* Microsoft RSA root CA 2017
+
+For more information about IoT Hub's recommended certificate practices, see [TLS support](./iot-hub-tls-support.md).
+
+### Authentication certificates
+
+If you use X.509 certificate authentication for your devices, make sure your certificates are ready before registering a device:
+
+* For CA-signed certificates, the tutorial [Create and upload certificates for testing](./tutorial-x509-test-certs.md) provides a good introduction for how to create CA-signed certificates and upload them to IoT Hub. After completing that tutorial, you're ready to register a device with **X.509 CA signed** authentication.
+
+* For self-signed certificates, you need two device certificates (a primary and a secondary certificate) on the device and thumbprints for both to upload to IoT Hub. One way to retrieve the thumbprint from a certificate is with the following OpenSSL command:
+
+  ```bash
+  openssl x509 -in <certificate filename>.pem -text -fingerprint
+  ```
+
 ## Register a device
 
 In this section, you create a device identity in the [identity registry in your IoT hub](./iot-hub-devguide-identity-registry.md). A device can't connect to a hub unless it has a device identity.
@@ -42,18 +70,6 @@ When you register a device, you choose its authentication method. IoT Hub suppor
 
   If your device has a CA-signed X.509 certificate, then you upload a root or intermediate certificate authority (CA) certificate in the signing chain to IoT Hub before you register the device. The device has an X.509 certificate with the verified X.509 CA in its certificate chain of trust. When the device connects, it presents its full certificate chain and the IoT hub can validate it because it knows the X.509 CA. Multiple devices can authenticate against the same verified X.509 CA. For more information, see [Authenticate identities with X.509 certificates](./authenticate-authorize-x509.md).
 
-### Prepare certificates
-
-If you're using either of the X.509 certificate authentication methods, make sure your certificates are ready before registering a device:
-
-* For CA-signed certificates, the tutorial [Create and upload certificates for testing](./tutorial-x509-test-certs.md) provides a good introduction for how to create CA-signed certificates and upload them to IoT Hub. After completing that tutorial, you're ready to register a device with **X.509 CA signed** authentication.
-
-* For self-signed certificates, you need two device certificates (a primary and a secondary certificate) on the device and thumbprints for both to upload to IoT Hub. One way to retrieve the thumbprint from a certificate is with the following OpenSSL command:
-
-  ```bash
-  openssl x509 -in <certificate filename>.pem -text -fingerprint
-  ```
-
 ### Add a device
 
 Create a device identity in your IoT hub.