Azure Sphere – HTTPS cURL Easy

02/25/2025

This sample demonstrates how to use the cURL Easy interface with Azure Sphere over a secure HTTPS connection. For details about using the libcurl library with Azure Sphere, see Connect to web services using cURL.

The sample periodically downloads the index web page at example.com, by using cURL over a secure HTTPS connection. It uses the cURL Easy interface, which is a synchronous (blocking) API. By default, this sample uses the proxy configured for the device.

The sample logs the downloaded content. If the size of the downloaded content exceeds 2 KiB, the sample pauses the download, prints the content that has been downloaded so far, and then resumes the download. Refer to cURL curl_easy_pause API for more information.

The sample uses the following Azure Sphere libraries.

Library	Purpose
curl	Configures the data transfer and downloads the web page over HTTP/HTTPS.
eventloop	Invokes handlers for timer events.
log	Displays messages in the Device Output window during debugging.
networking	Gets and sets network interface configuration.
storage	Gets the path to the certificate file that is used to authenticate the server.

File/folder	Description
`app_manifest.json`	Application manifest file, which describes the resources.
`CMakeLists.txt`	CMake configuration file, which Contains the project information and is required for all builds.
`CMakePresets.json`	CMake presets file, which contains the information to configure the CMake project.
`launch.vs.json`	JSON file that tells Visual Studio how to deploy and debug the application.
`LICENSE.txt`	The license for this sample application.
`main.c`	Main C source code file.
`README.md`	This README file.
`.vscode`	Folder containing the JSON files that configure Visual Studio Code for deploying and debugging the application.

Prerequisites

The sample requires the following hardware:

An Azure Sphere development board

Setup

Complete the following steps to set up this sample.

Ensure that your Azure Sphere device is connected to your computer, and your computer is connected to the internet.
Ensure that you have Azure Sphere SDK version 24.03 or above. At the command prompt, run az sphere show-sdk-version to check. Upgrade the Azure Sphere SDK for Windows or Linux as needed.
Ensure that the Azure CLI is installed. At a minimum, the Azure CLI version must be 2.45.0 or later.
Install the Azure Sphere extension.
Enable application development, if you have not already done so, by entering the az sphere device enable-development command in the command prompt.
Clone the Azure Sphere samples repository and find the HTTPS_Curl_Easy sample in the HTTPS folder or download the zip file from the Microsoft samples browser.
Note that the sample can connect only to websites listed in the AllowedConnections capability of the app_manifest.json file. The sample is set up to connect to the website example.com:
```
"Capabilities": {
    "AllowedConnections": [ "example.com" ],
  },
```
You can revise the sample to connect to a different website for downloading, as described in the Rebuild the sample to download from a different website section of this README.
By default, this sample configures the cURL handle to use the proxy. To bypass the proxy, add "--BypassProxy" in the CmdArgs field.

CmdArgs: [ "--BypassProxy" ],

For further details see connect through a proxy.
Configure networking on your device. You must either set up WiFi or set up Ethernet on your development board, depending on the type of network connection you are using.

Configure a static IP address

You can configure a static IP address on an Ethernet or a Wi-Fi interface. If you have configured a device with a static IP and require name resolution, your application must set a static DNS address. For more information, see the sections Static IP address and Static DNS address in Use network services.

Best practice when using libcurl

When using libcurl, as with other networking applications, the Azure Sphere OS will allocate socket buffers which are attributed to your application's RAM usage. You can tune the size of these buffers to reduce the RAM footprint of your application as appropriate. Refer to Manage RAM usage for further details.

Build and run the sample

To build and run this sample, follow the instructions in Build a sample application.

Rebuild the sample to download from a different website

To download data from a website other than the default website, you'll need to get the root CA certificate from the website, modify the sample to use the new website and its certificate, and build and run the modified sample.

Complete the steps described in the following sections.

Download the root CA certificate

If the website uses SSL, you may need to use a different root CA certificate. To download the certificate from the website, complete the following steps:

Open the browser and click the Secure icon, which is a padlock in the address bar.
If you're using Microsoft Edge, select Connection is secure; then click the certificate icon (highlighted yellow):
Select Certificate.
Open the Certification Path tab.
Select the top certificate in the hierarchy and then select View Certificate.
Open the Details tab and select Copy to File.
In the Certificate Export Wizard, click Next.
Select the Base-64 encoded X.509 (.CER) format and then click Next.
Type the file name to which to export the certificate and then click Next.
Click Finish to complete the wizard.
Rename the downloaded certificate file to have the .pem extension.

Modify the sample to use the new website

Complete the following steps to modify the sample to use the new website.

In the app_manifest.json file, add the hostname of the new website to the AllowedConnections capability. For example, the following adds Contoso.com to the list of allowed websites.
```
"Capabilities": {
    "AllowedConnections": [ "example.com", "Contoso.com"],
  },
```

Open main.c, go to the following statement, and change example.com to the URL of the website you want to connect to.

if ((res = curl_easy_setopt(curlHandle, CURLOPT_URL, "https://example.com")) != CURLE_OK) {
    LogCurlError("curl_easy_setopt CURLOPT_URL", res);
    goto cleanupLabel;
}

Update the sample to use a different root CA certificate, if necessary:
1. Put the trusted root CA certificate in the certs/ folder (and optionally remove the existing DigiCert Global Root CA certificate).
2. Update line 14 of CMakeLists.txt to include the new trusted root CA certificate in the image package, instead of the DigiCert Global Root CA certificate.
3. Update line 185 of main.c to point to the new trusted root CA certificate.

Build and run the sample modified to use the new website

To build and run the modified sample, follow the instructions in the Build and run the sample section of this README.

Rebuild the sample to use mutual authentication

You can modify the sample to use mutual authentication if your website is configured to do so. The instructions in this section require that you already have a website and certificates configured for mutual authentication. See Connect to web services - mutual authentication for information about configuring mutual authentication on Azure Sphere. For information about configuring a website with mutual authentication for testing purposes, you can use Configure certificate authentication in ASP.NET Core.

Note: These instructions are for testing purposes only and should not be used in a production environment.

Complete the steps described in the following sections to rebuild the sample to use mutual authentication on a website that is configured for mutual authentication.

Update the application manifest

Add the following to the app_manifest.json file.

Add the DeviceAuthentication capability, and use it to specify your catalog ID.
In the AllowedConnections capability, add the HTTPS endpoint of the website that has mutual authentication configured.

The following code snippet is an example entry.
```
"Capabilities": {
    "AllowedConnections" : [ "example.com" ],
    "DeviceAuthentication": "77304f1f-9530-4157-8598-30bc1f3d66f0"
  },
```

Add the TLS utilities library

Add tlsutils to target_link_libraries in the CMakeLists.txt file, as shown in the following line of code:
```
target_link_libraries(${PROJECT_NAME} applibs gcc_s c curl tlsutils)
```
For information about this library, see TLS utilities library in the Azure Sphere documentation.

Open main.c and add the deviceauth_curl.h header file after curl.h:

#include <curl/curl.h>
#include <tlsutils/deviceauth_curl.h>

Add TLS utilities functions

Use the DeviceAuth_CurlSslFunc function or create a custom authentication function that calls DeviceAuth_SslCtxFunc to perform the authentication. See Connect to web services - mutual authentication for more information about these functions.

To use DeviceAuth_CurlSslFunc, revise main.c by adding the following code to the PerformWebPageDownload function after the if statement that sets CURLOPT_VERBOSE.

    // Configure SSL to use device authentication-provided client certificates
    if ((res = curl_easy_setopt(curlHandle, CURLOPT_SSL_CTX_FUNCTION, DeviceAuth_CurlSslFunc)) !=
        CURLE_OK) {
        LogCurlError("curl_easy_setopt CURLOPT_SSL_CTX_FUNCTION", res);
        goto cleanupLabel;
    }

To create a custom authentication function that calls DeviceAuth_SslCtxFunc, complete the following steps.

Create your custom callback function. The following code is an example:

    static CURLcode UserSslCtxFunction(CURL* curlHandle, void* sslCtx, void* userCtx)
    {
        DeviceAuthSslResult result = DeviceAuth_SslCtxFunc(sslCtx);

        if (result != DeviceAuthSslResult_Success) {
            Log_Debug("Failed to set up device auth client certificates: %d\n", result);
            return CURLE_SSL_CERTPROBLEM;
        }

        return CURLE_OK;
    }

In main.c, add your custom function above the PerformWebPageDownload function.

Add the following code to the PerformWebPageDownload function after the if statement that sets CURLOPT_VERBOSE.

    // Configure SSL to use device authentication-provided client certificates
    if ((res = curl_easy_setopt(curlHandle, CURLOPT_SSL_CTX_FUNCTION, UserSslCtxFunction)) !=
        CURLE_OK) {
        LogCurlError("curl_easy_setopt CURLOPT_SSL_CTX_FUNCTION", res);
        goto cleanupLabel;
    }

Build and run the sample modified to use mutual authentication