Connettersi a servizi WebConnect to web services

Azure Sphere SDK include la libreria libcurl, utilizzabile dalle applicazioni di alto livello per connettersi ed eseguire l'autenticazione ai servizi Web HTTP e HTTPS.The Azure Sphere SDK includes the libcurl library, which high-level applications can use to connect and authenticate with HTTP and HTTPS web services. Sono supportate sia l'autenticazione server che l'autenticazione client, in modo che le applicazioni possano verificare di comunicare con il server previsto e provare al server la legittimità del loro dispositivo e del loro tenant di Azure Sphere.Both server and client authentication are supported, so that applications can verify that they are communicating with the expected server and can prove to the server that their device and Azure Sphere tenant are legitimate. Le due funzionalità sono combinate nell'autenticazione reciproca.Mutual authentication combines the two.

Il repository di esempi per Azure Sphere in GitHub include gli esempi curl seguenti:The Azure Sphere samples repo on GitHub includes the following curl samples:

Anche se l'approccio sincrono all'autenticazione server in HTTPS_Curl_Easy è piuttosto semplice, le applicazioni di Azure Sphere in genere dovrebbero usare la tecnica asincrona più complessa mostrata nell'esempio HTTPS_Curl_Multi, insieme a un modello guidato dagli eventi a thread singolo basato su epoll.Although the synchronous approach to server authentication in HTTPS_Curl_Easy is quite simple, Azure Sphere applications should generally use the more complex asynchronous technique shown in the HTTPS_Curl_Multi sample, along with an epoll-based, single-threaded event-driven pattern.

Il sito Web di libcurl fornisce una documentazione completa dell'API C di libcurl e molti esempi.The libcurl website provides thorough documentation of the libcurl C API and many examples. Differenze tra la libreria cURL e la libreria di runtime di Azure Sphere SDK come indicato di seguito:Differences between the cURL Library and the Azure Sphere SDK runtime libary as follows:

Nome costanteConstant Name
definizione(definition)
limiti delle dimensioni cURLcURL size limits Limiti di dimensioni Azure SphereAzure Sphere size limits
CURLOPT_BUFFERSIZECURLOPT_BUFFERSIZE
(dimensione buffer)(buffer size)
impostazione predefinita: 16 KBdefault: 16 KB valore predefinito: 1536 KBdefault: 1536 KB
CURLOPT_UPLOAD_BUFFERSIZECURLOPT_UPLOAD_BUFFERSIZE
(caricare le dimensioni del buffer)(upload buffer size)
valore predefinito: 64 KBdefault: 64 KB
massimo: 2MBmaximum: 2MB
minimo: 16 KBminimum: 16 KB
valore predefinito: 1536 KBdefault: 1536 KB
massimo: 64 KBmaximum: 64 KB
minimo: 1536 KBminimum: 1536 KB
CURLOPT_HEADERFUNCTIONCURLOPT_HEADERFUNCTION
(intestazione HTTP completa passata a questa funzione)(complete HTTP header passed to this function)
massimo: 100 KBmaximum: 100 KB massimo: 16 KBmaximum: 16 KB

Requisiti per le applicazioni che usano curlRequirements for applications that use curl

Le applicazioni che usano la libreria curl devono includere i file di intestazione appropriati e fornire le informazioni su tenant e host Internet nel manifesto dell'applicazione.Applications that use the curl library must include the appropriate header files, and provide tenant and internet host information in the application manifest.

File di intestazioneHeader files

Per usare curl, includere questi file di intestazione all'interno dell'applicazione:To use curl, include these header files in your application:

#include <applibs/storage.h>  // required only if you supply a certificate in the image package
#include <tlsutils/deviceauth_curl.h> // required only for mutual authentication
#include <curl/curl.h>

Il file di intestazione storage.h è necessario solo se si specificano uno o più certificati nel pacchetto immagine dell'applicazione.The storage.h header file is required only if you supply one or more certificates in the application image package. L'intestazione deviceauth_curl.h è necessaria per eseguire l'autenticazione reciproca.The deviceauth_curl.h header is required for performing mutual authentication.

Manifesto dell'applicazioneApplication manifest

Il campo AllowedConnections del manifesto dell'applicazione deve specificare gli host a cui si connette l'applicazione.The AllowedConnections field of the application manifest must specify the hosts to which the application connects. Deve contenere anche il nome di ogni dominio che la connessione può incontrare se reindirizzata.It must also contain the name of each domain that the connection may encounter if redirected. Ad esempio, sia microsoft.com che www.microsoft.com sono necessari per un'applicazione che si connette alla home page di Microsoft.For example, both microsoft.com and www.microsoft.com are required for an application that connects to the Microsoft home page.

Se l'applicazione usa l'autenticazione reciproca, il campo DeviceAuthentication del manifesto deve includere l'ID tenant di Azure Sphere.If the application uses mutual authentication, the DeviceAuthentication field of the manifest must include the Azure Sphere tenant ID. I certificati di autenticazione del dispositivo vengono emessi solo se l'ID tenant del dispositivo corrisponde all'ID tenant nel manifesto dell'applicazione.Device authentication certificates are issued only if the device's tenant ID matches the tenant ID in the application manifest. Questa limitazione offre un meccanismo di difesa avanzato: un'applicazione in esecuzione su un dispositivo in un tenant diverso (ad esempio, quello di un altro cliente o di un'entità non autorizzata) non può eseguire l'autenticazione al server.This restriction provides defense in depth: an application running on a device in a different tenant (say, that of a different customer or a rogue entity) cannot authenticate to the server.

In fase di sviluppo è possibile trovare l'ID del tenant corrente di Azure Sphere usando il comando azsphere tenant show-selected.During development, you can find the ID of the current Azure Sphere tenant by using the azsphere tenant show-selected command.

Nell'esempio seguente il campo AllowedConnections specifica che l'applicazione si connette solo a www.example.com e il campo DeviceAuthentication specifica l'ID tenant Azure Sphere e quindi consente all'applicazione di usare il certificato del dispositivo per l'autenticazione reciproca.In the following example, the AllowedConnections field specifies that the application connects only to www.example.com, and the DeviceAuthentication field specifies the Azure Sphere tenant ID and thus enables the application to use the device certificate for mutual authentication.

  "Capabilities": {
    "AllowedConnections": [ "www.example.com" ],
    "Gpio": [],
    "Uart": [],
    "WifiConfig": false,
    "DeviceAuthentication": "00000000-0000-0000-0000-000000000000"
  }

Funzionalità supportateSupported functionality

Libcurl per Azure Sphere supporta solo i protocolli HTTP e HTTPS.Libcurl for Azure Sphere supports only the HTTP and HTTPS protocols. Inoltre, il sistema operativo Azure Sphere non supporta alcune funzionalità, come i file scrivibili (cookie) o i socket UNIX.In addition, the Azure Sphere OS does not support some functionality, such as writable files (cookies) or UNIX sockets. Le funzionalità che non saranno supportate nelle versioni future di libcurl, ad esempio la famiglia mprintf() , non sono disponibili.Features that will not be supported in future libcurl releases, such as the mprintf() family, are not available.

Libcurl per Azure Sphere supporta TLS 1,2 e TLS 1,3 e ha deprecato TLS 1,0 e TLS 1,1 in linea con la strategia di sicurezza Microsoft TLSpiù ampia.Libcurl for Azure Sphere supports TLS 1.2 and TLS 1.3, and has deprecated TLS 1.0 and TLS 1.1 in alignment with the broader Microsoft TLS security strategy.

Di seguito sono riportati i pacchetti di crittografia supportati:The following are the supported cipher suites:

  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

I tentativi di usare una versione non supportata di TLS restituiscono l'errore CyaSSL does not support <version>.Attempts to use an unsupported version of TLS return the error CyaSSL does not support <version>.

Autenticazione del serverServer authentication

Azure Sphere supporta l'autenticazione server tramite libcurl.Azure Sphere supports server authentication through libcurl. Il certificato del server deve essere firmato da un'autorità di certificazione (CA) considerata attendibile dal dispositivo.The server’s certificate must be signed by a Certificate Authority (CA) that the device trusts. Per permettere l'autenticazione di un server da parte di libcurl, l'applicazione deve fornire il percorso del file dell'autorità di certificazione.For libcurl to authenticate a server, the application must provide the path to the CA file.

Aggiungere certificati della CA al pacchetto immagineAdd CA certificates to the image package

Per usare una o più CA, è necessario aggiungere i certificati al pacchetto immagine.To use one or more CAs, you must add the certificates to your image package. Ogni certificato deve essere con codifica Base64.Each certificate must be base-64 encoded. L'approccio più semplice consiste nel creare un singolo file contenente tutti i certificati aggiuntivi.The simplest approach is to create a single file that contains all the additional certificates. Il file deve avere .pem come estensione del file.The file must have the .pem filename extension. Per aggiungere i certificati:To add certificates:

  1. Creare una cartella certs nella cartella del progetto per l'applicazione.Create a certs folder in the project folder for your application. La cartella del progetto contiene il file CMakeLists per l'applicazione.The project folder contains the CMakeLists file for your application.
  2. Nella cartella certs creare un file di testo con l'estensione pem, quindi copiare tutti i certificati nel file e salvarlo.In the certs folder, create a text file with the .pem extension, copy each certificate into it, and save the file.
  3. Nel file CMakeLists.txt aggiungere il file del certificato al pacchetto immagine come file di risorse.In the CMakeLists.txt file, add the certificate file to the image package as a resource file. Ad esempio:For example:

azsphere_target_add_image_package(${PROJECT_NAME} RESOURCE_FILES "certs/DigiCertGlobalRootCA.pem")

A questo punto, il file del certificato dovrebbe essere visibile nella cartella certs nel pacchetto immagine.The certificate file should now appear in the certs folder in the image package.

Impostare le posizioni dei certificatiSet certificate locations

Nell'applicazione usare le opzioni CURLOPT_CAPATH e CURLOPT_CAINFO per impostare le posizioni dei certificati.In your application, use the CURLOPT_CAPATH and CURLOPT_CAINFO options to set the locations of the certificates. Chiamare Storage_GetAbsolutePathInImagePackage per recuperare il percorso assoluto dei certificati nel pacchetto immagine e quindi chiamare curl_easy_setopt.Call Storage_GetAbsolutePathInImagePackage to retrieve the absolute path to the certificates in the image package and then call curl_easy_setopt.

CURLOPT_CAPATH imposta una cartella predefinita per i certificati.CURLOPT_CAPATH sets a default folder for the certificates. Il codice seguente, ad esempio, indica a curl di cercare i certificati solo nella cartella certs nell'immagine:For example, the following code tells curl to look for certificates in the certs folder in the image:

char *path = Storage_GetAbsolutePathInImagePackage("certs");
curl_easy_setopt(curl_handle, CURLOPT_CAPATH, path);

CURLOPT_CAINFO imposta il percorso di un file che contiene uno o più certificati.CURLOPT_CAINFO sets a path to a file that contains one or more certificates. Curl cerca in questo file oltre che nel set di cartelle predefinito in CURLOPT_CAPATH. Ad esempio:Curl searches this file in addition to the default folder set in CURLOPT_CAPATH.For example:

char *path = Storage_GetAbsolutePathInImagePackage("CAs/mycertificates.pem");
curl_easy_setopt(curl_handle, CURLOPT_CAINFO, path);

Questo codice indica a curl di considerare attendibile tutte le autorità di certificazione definite nel file mycertificates.pem, oltre a quelle definite nella directory impostata in CURLOPT_CAPATH.This code tells curl to trust any CAs that are defined in the mycertificates.pem file, in addition to CAs that are defined in the directory set in CURLOPT_CAPATH.

Autenticazione reciprocaMutual authentication

L'autenticazione reciproca verifica che il server e il dispositivo client siano entrambi legittimi.Mutual authentication verifies that both the server and the client device are legitimate. Il processo si articola in più passaggi:It's a multi-step process:

  1. L'applicazione autentica il server usando un certificato dell'autorità di certificazione, come descritto in Autenticazione del server.The application authenticates the server using a CA certificate, as described in Server authentication.
  2. L'applicazione presenta un certificato di autenticazione client x509 al server in modo che quest'ultimo possa autenticare il dispositivo.The application presents an x509 client authentication certificate to the server so that the server can authenticate the device.
  3. Il server usa la catena di certificati del tenant di Azure Sphere per verificare che il dispositivo appartenga al tenant.The server uses the Azure Sphere tenant's certificate chain to verify that the device belongs to the tenant.

Un'applicazione può configurare il lato autenticazione dispositivo dell'autenticazione reciproca in uno dei due modi seguenti.An application can set up the device-authentication side of mutual authentication in either of two ways:

  • Configurare la funzione DeviceAuth_CurlSslFunc di Azure Sphere come funzione SSL che esegue l'autenticazione.Configure the Azure Sphere DeviceAuth_CurlSslFunc function as the SSL function that performs authentication.
  • Creare una funzione SSL personalizzata che chiama la funzione DeviceAuth_SslCtxFunc di Azure Sphere per l'autenticazione.Create a custom SSL function that calls the Azure Sphere DeviceAuth_SslCtxFunc function for authentication.

Nota

Azure Sphere non supporta la rinegoziazione SSL/TLS.Azure Sphere does not support SSL/TLS renegotiation.

Prima di usare una delle due funzioni, è necessario aggiornare il file CMakeLists.txt per l'applicazione per aggiungere curl e tlsutils a TARGET_LINK_LIBRARIES:Before you use either function, you must update the CMakeLists.txt file for your application to add curl and tlsutils to TARGET_LINK_LIBRARIES:

TARGET_LINK_LIBRARIES(${PROJECT_NAME} applibs pthread gcc_s c curl tlsutils)

Usare DeviceAuth_CurlSslFuncUse DeviceAuth_CurlSslFunc

Il modo più semplice per eseguire l'autenticazione del dispositivo consiste nel configurare DeviceAuth_CurlSslFunc come funzione di callback per l'autenticazione SSL di curl:The simplest way to perform device authentication is to configure DeviceAuth_CurlSslFunc as the callback function for curl SSL authentication:

// Set DeviceAuth_CurlSslFunc to perform authentication
CURLcode err = curl_easy_setopt(_curl, CURLOPT_SSL_CTX_FUNCTION, DeviceAuth_CurlSslFunc);
if (err) {
    // Set ssl function failed
    return err;
}

La funzione DeviceAuth_CurlSslFunc recupera la catena di certificati per il tenant corrente di Azure Sphere e imposta la connessione curl per l'esecuzione dell'autenticazione reciproca.The DeviceAuth_CurlSslFunc function retrieves the certificate chain for the current Azure Sphere tenant and sets up the curl connection to perform mutual authentication. Se l'autenticazione non riesce, la funzione restituisce CURLE_CERTPROBLEM.If authentication fails, the function returns CURLE_SSL_CERTPROBLEM.

Usare DeviceAuth_SslCtxFuncUse DeviceAuth_SslCtxFunc

Un'applicazione può anche usare una funzione di callback SSL che chiama la funzione DeviceAuth_SslCtxFunc di Azure Sphere per l'autenticazione.An application can also use a custom SSL callback function that calls the Azure Sphere DeviceAuth_SslCtxFunc function for authentication.

La funzione SSL personalizzata deve chiamare DeviceAuth_SslCtxFunc per eseguire l'autenticazione, ma può anche eseguire altre attività correlate.Your custom SSL function must call DeviceAuth_SslCtxFunc to perform the authentication, but may also do other tasks related to authentication. DeviceAuth_SslCtxFunc restituisce un valore dell'enumerazione DeviceAuthSslResult, che fornisce informazioni dettagliate sull'errore.DeviceAuth_SslCtxFunc returns a value of the DeviceAuthSslResult enumeration, which provides detailed information about the failure. Ad esempio:For example:

static CURLcode MyCallback(CURL *curl, void *sslctx, void *userCtx)
{
    int err = DeviceAuth_SslCtxFunc(sslctx);
    Log_Debug("ssl func callback error %d\n", err);
    if (err) {
        // detailed error handling code goes here
    }
    return CURLE_OK;
}
...

err = curl_easy_setopt(curl, CURLOPT_SSL_CTX_FUNCTION, MyCallback);
    if (err) {
        goto cleanupLabel;
    }

Usare la catena di certificati del tenant sul serverUse the tenant certificate chain on your server

Per eseguire l'autenticazione reciproca, il server deve essere in grado di verificare che il dispositivo appartenga al tenant di Azure Sphere e che il tenant stesso sia legittimo.To perform mutual authentication, the server must be able to verify that the device belongs to your Azure Sphere tenant and that the tenant itself is legitimate. Per eseguire questa autenticazione, il server richiede la catena di certificati del tenant di Azure Sphere, che firma tutti i dispositivi di Azure Sphere:To perform this authentication, the server requires the Azure Sphere tenant's certificate chain, which signs all your Azure Sphere devices:

Per ottenere la catena di certificati per il tenant, scaricarla in un file con estensione p7b, come nell'esempio seguente:To get the certificate chain for your tenant, download it to a .p7b file, as in the following example:

azsphere ca-certificate download-chain --output CA-cert-chain.p7b

È quindi possibile usare il file con estensione p7b nel server.You can then use the .p7b file on your server.

Ulteriori suggerimenti per l'uso di curlAdditional tips for using curl

Di seguito sono riportati alcuni suggerimenti aggiuntivi per l'uso di curl in un'applicazione di Azure Sphere.Here are some additional tips for using curl in an Azure Sphere application.

  • Se si prevede di archiviare il contenuto della pagina nella RAM o nella memoria flash, tenere presente che l'archiviazione nel dispositivo Azure Sphere è limitata.If you plan to store page content in RAM or flash, keep in mind that storage on the Azure Sphere device is limited.

  • Per assicurarsi che curl segua i reindirizzamenti, aggiungere quanto segue al codice:To ensure that curl follows redirects, add the following to your code:

    curl_easy_setopt(curl_handle, CURLOPT_FOLLOWLOCATION, 1L);
    
  • Per aggiungere informazioni dettagliate sulle operazioni di curl che possono risultare utili durante il debug:To add verbose information about curl operations that might be helpful during debugging:

    curl_easy_setopt(curl_handle, CURLOPT_VERBOSE, 1L);
    
  • Alcuni server restituiscono errori se una richiesta non contiene un agente utente.Some servers return errors if a request does not contain a user agent. Per impostare un agente utente:To set a user agent:

    curl_easy_setopt(curl_handle, CURLOPT_USERAGENT, "libcurl-agent/1.0");