|
| 1 | +--- |
| 2 | +# Required metadata |
| 3 | +# For more information, see https://review.learn.microsoft.com/en-us/help/platform/learn-editor-add-metadata?branch=main |
| 4 | +# For valid values of ms.service, ms.prod, and ms.topic, see https://review.learn.microsoft.com/en-us/help/platform/metadata-taxonomies?branch=main |
| 5 | + |
| 6 | +title: Understand Device Update for Azure IoT Hub TLS download capabilities |
| 7 | +description: Key concepts to understand for TLS download of update content from Device Update for IoT Hub. |
| 8 | +author: andrewbrownmsft # GitHub alias |
| 9 | +ms.author: andbrown |
| 10 | +ms.service: iot-hub-device-update |
| 11 | +ms.topic: how-to |
| 12 | +ms.date: 06/07/2024 |
| 13 | +--- |
| 14 | + |
| 15 | +# How to understand and use the Transport Layer Security (TLS) download feature in Device Update for IoT Hub (Preview) |
| 16 | + |
| 17 | +When a device downloads an update from the Device Update service, the connection between the Device Update service and the device is HTTP-based. If a TLS connection (HTTPS) between the Device Update service and the device is preferred, this capability can be enabled upon request. |
| 18 | + |
| 19 | +>[!NOTE] |
| 20 | +>The TLS download feature is currently in [public preview](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). |
| 21 | +
|
| 22 | +## How to enable the TLS download feature |
| 23 | + |
| 24 | +Obtain your Azure Subscription ID and your Device Update for IoT Hub *account*, *instance*, and *Azure region* information. Here's how to find that information: |
| 25 | + |
| 26 | +- Azure Subscription ID: |
| 27 | + - See this article: [https://aka.ms/get-subscription-id](https://aka.ms/get-subscription-id) |
| 28 | + |
| 29 | +- Device Update for IoT Hub information: |
| 30 | + - Go to the [Azure portal](https://portal.azure.com/). |
| 31 | + - Search for "Device Update for IoT Hubs" and select the **Device Update for IoT Hubs** option. |
| 32 | + - Select your Device Update account. The *account name* is at the top of the screen. |
| 33 | + - Select the **Overview** view from the left-hand navigation pane. Look for the "Location" field (such as "West US 2"). This field is your *Azure region*. |
| 34 | + - Under the **Instance Management** heading in the left-hand navigation bar, select **Instances**. You'll see your *instance name*. |
| 35 | + - Use [this link](https://nam.dcv.ms/dBgKOpqIL7) to submit the information. You'll receive a reply when your Device Update instance is enabled for the preview TLS download feature. |
| 36 | + |
| 37 | +## Additional changes if using FreeRTOS |
| 38 | + |
| 39 | +If you're using FreeRTOS, the [Azure IoT Middleware for FreeRTOS](https://github.com/Azure/azure-iot-middleware-freertos) and [FreeRTOS samples](https://github.com/Azure-Samples/iot-middleware-freertos-samples) available from Microsoft currently support HTTP URLs and need to be modified for TLS (HTTPS) URLs: |
| 40 | + |
| 41 | +The Device Update for IoT Hub implementation in the Azure IoT Middleware for FreeRTOS SDK and samples use the below libraries for downloading the binaries: |
| 42 | +[Azure_iot_http.h](https://github.com/Azure/azure-iot-middleware-freertos/blob/7759a42a1eab12818ea2a8f3f940847743968021/source/interface/azure_iot_http.h#L13), which depends on: |
| 43 | + |
| 44 | +- [azure_iot_http_port.h](https://github.com/Azure/azure-iot-middleware-freertos/blob/7759a42a1eab12818ea2a8f3f940847743968021/ports/coreHTTP/azure_iot_http_port.h#L11) |
| 45 | + |
| 46 | +- [azure_iot_transport_interface.h](https://github.com/Azure/azure-iot-middleware-freertos/blob/7759a42a1eab12818ea2a8f3f940847743968021/source/interface/azure_iot_transport_interface.h#L5) |
| 47 | + |
| 48 | +The azure_iot_http_port.h can be modified to use the core http library for TLS - HTTPS support using the FreeRTOS example - [HTTP Demo (with TLS - Mutual Authentication) - FreeRTOS](https://www.freertos.org/http/http-demo-with-tls-mutual-authentication.html) |
| 49 | + |
| 50 | +The Device Update for IoT Hub samples also have functions to parse the URL that need to be revised: [iot-middleware-freertos-samples/demos/sample_azure_iot_adu/sample_azure_iot_adu.c at main - Azure-Samples/iot-middleware-freertos-samples (github.com)](https://github.com/Azure-Samples/iot-middleware-freertos-samples/blob/main/demos/sample_azure_iot_adu/sample_azure_iot_adu.c#L396). |
| 51 | + |
| 52 | +Finally, you may also need to make changes to your own implementation, such as changing the HTTPS header buffer to manage the update URL format that your device will receive from Device Update. |
| 53 | + |
| 54 | +## Next steps |
| 55 | + |
| 56 | +[Troubleshoot common issues](troubleshoot-device-update.md) |
| 57 | + |
0 commit comments