Skip to content

Commit a9b1186

Browse files
xujing-msxujing-ms
authored
Update iot-hub-tls-support.md
1 parent 5f3b38f commit a9b1186

File tree

1 file changed

+94
-63
lines changed

1 file changed

+94
-63
lines changed

‎articles/iot-hub/iot-hub-tls-support.md

Lines changed: 94 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,23 @@
1414
IoT Hub uses Transport Layer Security (TLS) to secure connections from IoT devices and services.
1515

1616
> [!NOTE]
17-
> Azure IoT Hub will end support for TLS 1.0 and 1.1 on July 1st, 2025. Only TLS 1.2 and later will be supported after this date.
18-
> To find out the version of TLS your IoT Hub devices are running, please refer to [TLS 1.0 and 1.1 end of support guide](iot-hub-tls-ending-support-for-1-0-and-1-1.md).
19-
> It is therefore essential that you properly test and validate that *all* your IoT devices and services are compatible with TLS 1.2 and the [recommended ciphers](#cipher-suites) in advance.
17+
> Azure IoT Hub will end support for TLS 1.0 and 1.1 in alignment with the Azure wide service announcement for [TLS 1.0 and 1.1 retirement](https://azure.microsoft.com/en-us/updates?id=update-retirement-tls1-0-tls1-1-versions-azure-services).
18+
>
19+
> It is therefore essential that you properly test and validate that *all* your IoT devices and services are compatible with TLS 1.2 and the [recommended ciphers](#cipher-suites) in advance. It is highly recommend to use the [mininum TLS enforcement feature](#enforce-iot-hub-to-use-tls-1.2-and-strong-cipher-suites) as the mechanism for testing and compliance
20+
>
21+
> To find out the version of TLS your IoT Hub devices are running, please refer to [TLS 1.0 and 1.1 end of support guide](#Checking-TLS-versions-for-IoT-Hub-devices).
2022
21-
## IoT Hub's server TLS certificate
23+
## Mutual TLS support
24+
25+
Mutual TLS authentication ensures that the client _authenticates_ the server (IoT Hub) certificate and the server (IoT Hub) _authenticates_ the [X.509 client certificate or X.509 thumbprint](tutorial-x509-test-certs.md#create-a-client-certificate-for-a-device). _Authorization_ is performed by IoT Hub after _authentication_ is complete.
26+
27+
For AMQP and MQTT protocols, IoT Hub requests a client certificate in the initial TLS handshake. If one is provided, IoT Hub _authenticates_ the client certificate and the client _authenticates_ the IoT Hub certificate. This process is called mutual TLS authentication. When IoT Hub receives an MQTT connect packet or an AMQP link opens, IoT Hub performs _authorization_ for the requesting client and determines if the client requires X.509 authentication. If mutual TLS authentication was completed and the client is authorized to connect as the device, it is allowed. However, if the client requires X.509 authentication and client authentication was not completed during the TLS handshake, then IoT Hub rejects the connection.
28+
29+
For HTTP protocol, when the client makes its first request, IoT Hub checks if the client requires X.509 authentication and if client authentication was complete then IoT Hub performs authorization. If client authentication was not complete, then IoT Hub rejects the connection
30+
31+
After a successful TLS handshake, IoT Hub can authenticate a device using a symmetric key or an X.509 certificate. For certificate-based authentication, this can be any X.509 certificate, including ECC. IoT Hub validates the certificate against the thumbprint or certificate authority (CA) you provide. To learn more, see [Supported X.509 certificates](iot-hub-dev-guide-sas.md#supported-x509-certificates).
32+
33+
### IoT Hub's server TLS certificate
2234

2335
During a TLS handshake, IoT Hub presents RSA-keyed server certificates to connecting clients.In the past, the certificates were all rooted from the Baltimore Cybertrust Root CA. Because the Baltimore root is at end-of-life, we are in the process of migrating to a new root called DigiCert Global G2. This migration impacts all devices currently connecting to IoT Hub. For more information, see [IoT TLS certificate update](https://aka.ms/iot-ca-updates).
2436

@@ -30,43 +42,63 @@ Although root CA migrations are rare, for resilience in the modern security land
3042

3143
For links to download these certificates, see [Azure Certificate Authority details](../security/fundamentals/azure-CA-details.md).
3244

33-
#### Elliptic Curve Cryptography (ECC) server TLS certificate (preview)
45+
## Cipher suites supported by IoT Hub
3446

35-
IoT Hub ECC server TLS certificate is available for public preview. While offering similar security to RSA certificates, ECC certificate validation (with ECC-only cipher suites) uses up to 40% less compute, memory, and bandwidth. These savings are important for IoT devices because of their smaller profiles and memory, and to support use cases in network bandwidth limited environments.
47+
To comply with Azure security policy for a secure connection, these are the cipher suites that IoT Hub will support in on-going basis:
3648

37-
We strongly recommend that all devices using ECC trust the following two root CAs:
49+
| Cipher Suites | TLS Version |
50+
|-------------------------------------------|------------------------------|
51+
| `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` | TLS 1.2 Strong Cipher Suites |
52+
| `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` | TLS 1.2 Strong Cipher Suites |
53+
| `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` | TLS 1.2 Strong Cipher Suites |
54+
| `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384` | TLS 1.2 Strong Cipher Suites |
55+
| `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` | ECC-only Cipher Suites |
56+
| `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` | ECC-only Cipher Suite |
57+
| `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256` | ECC-only Cipher Suite |
58+
| `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384` | ECC-only Cipher Suite |
3859

39-
* DigiCert Global G3 root CA
40-
* Microsoft RSA root CA 2017
60+
The following cipher suites are currently supported by IoT Hub, however IoT Hub will end support for these cipher suites in accordance with the Azure TLS end of support.
4161

42-
For links to download these certificates, see [Azure Certificate Authority details](../security/fundamentals/azure-CA-details.md).
62+
| Cipher Suites | TLS Version |
63+
|---------------------------------------|------------------------------------|
64+
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | TLS 1.2 Weak Cipher Suites |
65+
| TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 | TLS 1.2 Weak Cipher Suites |
66+
| TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 | TLS 1.2 Weak Cipher Suites |
67+
| TLS_RSA_WITH_AES_256_GCM_SHA384 | TLS 1.2 Weak Cipher Suites |
68+
| TLS_RSA_WITH_AES_128_GCM_SHA256 | TLS 1.2 Weak Cipher Suites |
69+
| TLS_RSA_WITH_AES_256_CBC_SHA256 | TLS 1.2 Weak Cipher Suites |
70+
| TLS_RSA_WITH_AES_128_CBC_SHA256 | TLS 1.2 Weak Cipher Suites |
71+
| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | TLS 1.0/1.1/1.2 Weak Cipher Suites |
72+
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | TLS 1.0/1.1/1.2 Weak Cipher Suites |
73+
| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | TLS 1.0/1.1/1.2 Weak Cipher Suites |
74+
| TLS_RSA_WITH_3DES_EDE_CBC_SHA | TLS 1.0/1.1/1.2 Weak Cipher Suites |
75+
| TLS_RSA_WITH_3DES_EDE_CBC_SHA | TLS 1.0/1.1/1.2 Weak Cipher Suites |
76+
| TLS_RSA_WITH_AES_128_CBC_SHA | TLS 1.0/1.1/1.2 Weak Cipher Suites |
77+
| TLS_RSA_WITH_AES_256_CBC_SHA | TLS 1.0/1.1/1.2 Weak Cipher Suites |
4378

44-
To preview IoT Hub's ECC server certificate:
79+
A client can suggest a list of higher cipher suites to use during `ClientHello`. However, some of them might not be supported by IoT Hub (for example, `ECDHE-ECDSA-AES256-GCM-SHA384`). In this case, IoT Hub will try to follow the preference of the client, but eventually negotiate down the cipher suite with `ServerHello`.
4580

46-
1. [Create a new IoT hub with preview mode on](iot-hub-preview-mode.md).
47-
2. [Configure your client](#tls-configuration-for-sdk-and-iot-edge) to include *only* ECDSA cipher suites and *exclude* any RSA ones. These are the supported cipher suites for the ECC certificate public preview:
48-
* `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
49-
* `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
50-
* `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`
51-
* `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`
52-
3. Connect your client to the preview IoT hub.
81+
## Enforce IoT Hub to use TLS 1.2 and strong cipher suites
5382

54-
## Enforce IoT Hub to use TLS 1.2 in select regions
83+
To ensure your IoT devices are TLS 1.2 and [strong cipher suites](#cipher-suites) compliance, you can enforce compliance using mininum TLS enforcement feature in Azure IoT Hub.
5584

56-
For added security, configure your IoT Hubs to *only* allow client connections that use TLS version 1.2 and to enforce the use of [cipher suites](#cipher-suites). This feature is only supported in these regions:
85+
Currently this feature is only available in the following regions and during IoT Hub creation (other Azure regions will be supported in 2025):
5786

5887
* East US
5988
* South Central US
6089
* West US 2
6190
* US Gov Arizona
6291
* US Gov Virginia (TLS 1.0/1.1 support isn't available in this region - TLS 1.2 enforcement must be enabled or IoT hub creation fails)
6392

64-
To enable TLS 1.2 enforcement, follow the steps in [Create an IoT hub in Azure portal](create-hub.md), except
93+
To enable TLS 1.2 and strong cipher suites enforcement in Azure Portal:
6594

66-
- Choose a **Region** from one in the list above.
67-
- Under **Management -> Advanced -> Transport Layer Security (TLS) -> Minimum TLS version**, select **1.2**. This setting only appears for IoT hub created in supported region.
95+
1. Staring with the IoT Hub create wizard in Azure Portal
96+
2. Choose a **Region** from one in the list above.
97+
3. Under **Management -> Advanced -> Transport Layer Security (TLS) -> Minimum TLS version**, select **1.2**. This setting only appears for IoT hub created in supported region.
6898

6999
:::image type="content" source="media/iot-hub-tls-12-enforcement.png" alt-text="Screenshot showing how to turn on TLS 1.2 enforcement during IoT hub creation":::
100+
4. Click **Create**
101+
5. Connect your IoT devices to this IoT Hub
70102

71103
To use ARM template for creation, provision a new IoT Hub in any of the supported regions and set the `minTlsVersion` property to `1.2` in the resource specification:
72104

@@ -100,31 +132,26 @@ The created IoT Hub resource using this configuration will refuse device and ser
100132
>
101133
> Upon failovers, the `minTlsVersion` property of your IoT Hub will remain effective in the geo-paired region post-failover.
102134
103-
## Cipher suites
104-
105-
IoT Hubs that are configured to accept only TLS 1.2 will also enforce the use of the following recommended cipher suites:
106-
107-
* `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
108-
* `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
109-
* `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`
110-
* `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`
111-
112-
For IoT Hubs not configured for TLS 1.2 enforcement, TLS 1.2 still works with the following cipher suites, however support for these cipher will end by July 1st, 2025.
113-
114-
* `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`
115-
* `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384`
116-
* `TLS_DHE_RSA_WITH_AES_128_GCM_SHA256`
117-
* `TLS_RSA_WITH_AES_256_GCM_SHA384`
118-
* `TLS_RSA_WITH_AES_128_GCM_SHA256`
119-
* `TLS_RSA_WITH_AES_256_CBC_SHA256`
120-
* `TLS_RSA_WITH_AES_128_CBC_SHA256`
121-
* `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`
122-
* `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`
123-
* `TLS_RSA_WITH_AES_256_CBC_SHA`
124-
* `TLS_RSA_WITH_AES_128_CBC_SHA`
125-
* `TLS_RSA_WITH_3DES_EDE_CBC_SHA` **(This cipher will be deprecated on 10/01/2022 and will no longer be used for TLS handshakes)**
135+
## Checking TLS versions for IoT Hub devices
136+
Azure IoT Hub can provide diagnostic logs for several categories that can be analyzed using Azure Monitor Logs. In the connections log you can find the TLS Version for your IoT Hub devices.
137+
138+
To view these logs, follow these steps:
139+
1. In the [Azure portal](https://portal.azure.com), go to your IoT hub.
140+
2. In the resource menu under **Monitoring**, select **Diagnostic settings**. Ensure diagnostic settings have "Connections" checkmarked.
141+
3. In the resource menu under **Monitoring**, select **Logs**.
142+
4. Enter the following query:
143+
```azurecli
144+
AzureDiagnostics
145+
| where ResourceProvider == "MICROSOFT.DEVICES" and ResourceType == "IOTHUBS"
146+
| where Category == "Connections"
147+
| where OperationName == "deviceConnect"
148+
| extend props_json = parse_json(properties_s)
149+
| project DeviceId = props_json.deviceId, TLSVersion = props_json.tlsVersion
150+
```
151+
5. An example of the query results will look like:
152+
:::image type="content" source="./media/iot-hub-tls-ending-support-for-1-0-and-1-1/queryresult.png" alt-text="Diagram showing the query for device TLS version.":::
153+
6. Note: Devices using HTTPS connections won't generate an event in Azure Monitor logs.
126154

127-
A client can suggest a list of higher cipher suites to use during `ClientHello`. However, some of them might not be supported by IoT Hub (for example, `ECDHE-ECDSA-AES256-GCM-SHA384`). In this case, IoT Hub will try to follow the preference of the client, but eventually negotiate down the cipher suite with `ServerHello`.
128155

129156
## TLS configuration for SDK and IoT Edge
130157

@@ -140,34 +167,38 @@ Use the links below to configure TLS 1.2 and allowed ciphers in IoT Hub client S
140167

141168
IoT Edge devices can be configured to use TLS 1.2 when communicating with IoT Hub. For this purpose, use the [IoT Edge documentation page](https://github.com/Azure/iotedge/blob/master/edge-modules/edgehub-proxy/README.md).
142169

143-
## Device authentication
144170

145-
After a successful TLS handshake, IoT Hub can authenticate a device using a symmetric key or an X.509 certificate. For certificate-based authentication, this can be any X.509 certificate, including ECC. IoT Hub validates the certificate against the thumbprint or certificate authority (CA) you provide. To learn more, see [Supported X.509 certificates](iot-hub-dev-guide-sas.md#supported-x509-certificates).
146-
147-
## Mutual TLS support
171+
## Elliptic Curve Cryptography (ECC) server TLS certificate
148172

149-
Mutual TLS authentication ensures that the client _authenticates_ the server (IoT Hub) certificate and the server (IoT Hub) _authenticates_ the [X.509 client certificate or X.509 thumbprint](tutorial-x509-test-certs.md#create-a-client-certificate-for-a-device). _Authorization_ is performed by IoT Hub after _authentication_ is complete.
150-
151-
For AMQP and MQTT protocols, IoT Hub requests a client certificate in the initial TLS handshake. If one is provided, IoT Hub _authenticates_ the client certificate and the client _authenticates_ the IoT Hub certificate. This process is called mutual TLS authentication. When IoT Hub receives an MQTT connect packet or an AMQP link opens, IoT Hub performs _authorization_ for the requesting client and determines if the client requires X.509 authentication. If mutual TLS authentication was completed and the client is authorized to connect as the device, it is allowed. However, if the client requires X.509 authentication and client authentication was not completed during the TLS handshake, then IoT Hub rejects the connection.
152-
153-
For HTTP protocol, when the client makes its first request, IoT Hub checks if the client requires X.509 authentication and if client authentication was complete then IoT Hub performs authorization. If client authentication was not complete, then IoT Hub rejects the connection
154-
155-
156-
## Certificate pinning
173+
While offering similar security to RSA certificates, ECC certificate validation (with ECC-only cipher suites) uses up to 40% less compute, memory, and bandwidth. These savings are important for IoT devices because of their smaller profiles and memory, and to support use cases in network bandwidth limited environments.
157174

158-
[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 IoT Hub 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).
175+
To use IoT Hub's ECC server certificate:
176+
1. Ensure all devices trust the following root CAs:
177+
* DigiCert Global G2 root CA
178+
* Microsoft RSA root CA 2017
179+
3. [Configure your client](#tls-configuration-for-sdk-and-iot-edge) to include *only* ECDSA cipher suites and *exclude* any RSA ones. These are the supported cipher suites for the ECC certificate:
180+
* `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
181+
* `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
182+
* `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`
183+
* `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`
184+
4. Connect your client to the IoT hub.
159185

160-
## TLS maximum fragment length negotiation (preview)
186+
## TLS maximum fragment length negotiation
161187

162188
IoT Hub also supports TLS maximum fragment length negotiation, which is sometimes known as TLS frame size negotiation. This feature is in public preview.
163189

164190
Use this feature to specify the maximum plaintext fragment length to a value smaller than the default 2^14 bytes. Once negotiated, IoT Hub and the client begin fragmenting messages to ensure all fragments are smaller than the negotiated length. This behavior is helpful to compute or memory constrained devices. To learn more, see the [official TLS extension spec](https://tools.ietf.org/html/rfc6066#section-4).
165191

166192
Official SDK support for this public preview feature isn't yet available. To get started
167193

168-
1. [Create a new IoT hub with preview mode on](iot-hub-preview-mode.md).
194+
1. Create an IoT Hub.
169195
1. When using OpenSSL, call [SSL_CTX_set_tlsext_max_fragment_length](https://manpages.debian.org/testing/libssl-doc/SSL_CTX_set_max_send_fragment.3ssl.en.html) to specify the fragment size.
170-
1. Connect your client to the preview IoT Hub.
196+
1. Connect your client to the IoT Hub.
197+
198+
## Certificate pinning
199+
200+
[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 IoT Hub 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).
201+
171202

172203
## Next steps
173204

0 commit comments

Comments
 (0)