Łączenie z usługami internetowymi

Artykuł
09/27/2024

Ważne

Jest to dokumentacja usługi Azure Sphere (starsza wersja). Usługa Azure Sphere (starsza wersja) zostanie wycofana 27 września 2027 r., a użytkownicy muszą przeprowadzić migrację do usługi Azure Sphere (zintegrowanej) do tej pory. Użyj selektora wersji znajdującego się powyżej spisu treści, aby wyświetlić dokumentację usługi Azure Sphere (zintegrowaną).

Zestaw SDK usługi Azure Sphere zawiera bibliotekę libcurl, której aplikacje wysokiego poziomu mogą używać do łączenia się i uwierzytelniania za pomocą usług internetowych HTTP i HTTPS. Obsługiwane są zarówno uwierzytelnianie serwera, jak i klienta, dzięki czemu aplikacje mogą sprawdzić, czy komunikują się z oczekiwanym serwerem i mogą udowodnić, że ich urządzenie i dzierżawa usługi Azure Sphere są uzasadnione. Wzajemne uwierzytelnianie łączy te dwa.

Repozytorium przykładów usługi Azure Sphere w witrynie GitHub zawiera następujące przykłady curl:

HTTPS_Curl_Easy używa synchronicznego (blokowania) interfejsu API na potrzeby uwierzytelniania serwera.
HTTPS_Curl_Multi przykład używa asynchronicznego (nieblokujących) interfejsu API na potrzeby uwierzytelniania serwera.

Mimo że podejście synchroniczne do uwierzytelniania serwera w HTTPS_Curl_Easy jest dość proste, aplikacje usługi Azure Sphere powinny zazwyczaj używać bardziej złożonej techniki asynchronicznej pokazanej w przykładzie HTTPS_Curl_Multi wraz z wzorcem opartym na zdarzeniach opartym na epokach.

Witryna internetowa libcurl zawiera szczegółową dokumentację interfejsu API języka C libcurl i wiele przykładów. Różnice między biblioteką cURL i biblioteką środowiska uruchomieniowego zestawu Azure Sphere SDK są następujące:

Nazwa stałej (definicja)	Limity zakresów cURL	Limity zakresu usługi Azure Sphere
CURLOPT_BUFFERSIZE (rozmiar buforu)	Ustawienie domyślne: 16 KB	Ustawienie domyślne: 1536 KB
CURLOPT_UPLOAD_BUFFERSIZE (rozmiar buforu przekazywania)	Ustawienie domyślne: 64 KB Maksymalna: 2 MB Minimum: 16 KB	Ustawienie domyślne: 1536 KB Maksymalna: 64 KB Minimum: 1536 KB
CURLOPT_HEADERFUNCTION (pełny nagłówek HTTP przekazany do tej funkcji)	Maksymalna: 100 KB	Maksymalna: 16 KB
CURLOPT_DNS_CACHE_TIMEOUT	Ustawienie domyślne: buforowanie wyników przez 60 sekund Maksymalna: buforowanie wyników na zawsze Minimum: 0 (nie buforuj wyników)	Wszystkie wartości są zastępowane do wartości 0, a wyniki nie są buforowane.

Wymagania dotyczące aplikacji korzystających z narzędzia curl

Aplikacje korzystające z biblioteki curl muszą zawierać odpowiednie pliki nagłówkowe oraz udostępniać informacje o dzierżawie i hoście internetowym w manifeście aplikacji.

Pliki nagłówkowe

Aby użyć narzędzia curl, uwzględnij następujące pliki nagłówkowe w aplikacji:

#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>
#include <applibs/networking_curl.h>  // required only if using proxy to connect to the internet

Plik nagłówkowy storage.h jest wymagany tylko w przypadku podania co najmniej jednego certyfikatu w pakiecie obrazu aplikacji. Nagłówek deviceauth_curl.h jest wymagany do przeprowadzania wzajemnego uwierzytelniania. Nagłówek networking_curl.h jest wymagany, jeśli aplikacja używa serwera proxy do łączenia się z Internetem.

Manifest aplikacji

Pole AllowedConnections manifestu aplikacji musi określać hosty, z którymi łączy się aplikacja. Musi również zawierać nazwę każdej domeny, którą połączenie może napotkać w przypadku przekierowania. Na przykład zarówno microsoft.com aplikacja, jak i www.microsoft.com jest wymagana dla aplikacji łączącej się ze stroną główną firmy Microsoft.

Jeśli aplikacja używa wzajemnego uwierzytelniania, pole DeviceAuthentication manifestu musi zawierać identyfikator dzierżawy usługi Azure Sphere. Certyfikaty uwierzytelniania urządzenia są wystawiane tylko wtedy, gdy identyfikator dzierżawy urządzenia jest zgodny z identyfikatorem dzierżawy w manifeście aplikacji. To ograniczenie zapewnia ochronę w głębi systemu: aplikacja działająca na urządzeniu w innej dzierżawie (np. inna jednostka lub nieautoryzna) nie może uwierzytelnić się na serwerze.

Jeśli aplikacja używa serwera proxy, pole ReadNetworkProxyConfig wskazuje, czy aplikacja ma uprawnienia do pobierania konfiguracji serwera proxy.

Podczas programowania można znaleźć identyfikator bieżącej dzierżawy usługi Azure Sphere przy użyciu polecenia azsphere tenant show-selected.

W poniższym przykładzie pole AllowedConnections określa, że aplikacja łączy się tylko www.example.comz usługą , pole DeviceAuthentication określa identyfikator dzierżawy usługi Azure Sphere, umożliwiając aplikacji używanie certyfikatu urządzenia do wzajemnego uwierzytelniania, a pole ReadNetworkProxyConfig określa, że aplikacja może ponownie pobrać informacje o konfiguracji serwera proxy.

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

Obsługiwane funkcje

Biblioteka Libcurl dla usługi Azure Sphere obsługuje tylko protokoły HTTP i HTTPS. Ponadto system operacyjny usługi Azure Sphere nie obsługuje niektórych funkcji, takich jak pliki z możliwością zapisu (pliki cookie) lub gniazda systemu UNIX. Funkcje, które nie będą obsługiwane w przyszłych wersjach libcurl, takich jak rodzina mprintf(), nie są dostępne.

Biblioteka Libcurl dla usługi Azure Sphere obsługuje protokoły TLS 1.2 i TLS 1.3 i wycofały protokoły TLS 1.0 i TLS 1.1 zgodnie z szerszą strategią zabezpieczeń protokołu TLS firmy Microsoft.

Poniżej przedstawiono obsługiwane zestawy szyfrowania:

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

Próby użycia nieobsługiwanej wersji protokołu TLS zwracają błąd CyaSSL does not support <version>.

Uwierzytelnianie serwera

Usługa Azure Sphere obsługuje uwierzytelnianie serwera za pośrednictwem biblioteki libcurl. Certyfikat serwera musi być podpisany przez urząd certyfikacji, któremu ufa urządzenie. Aby biblioteka libcurl uwierzytelniła serwer, aplikacja musi podać ścieżkę do pliku urzędu certyfikacji.

Dodawanie certyfikatów urzędu certyfikacji do pakietu obrazów

Aby użyć co najmniej jednego urzędu certyfikacji, należy dodać certyfikaty do pakietu obrazów. Każdy certyfikat musi być zakodowany w formacie base-64. Najprostszym podejściem jest utworzenie pojedynczego pliku zawierającego wszystkie dodatkowe certyfikaty. Plik musi mieć rozszerzenie nazwy pliku pem. Aby dodać certyfikaty:

Utwórz folder certs w folderze projektu dla aplikacji. Folder projektu zawiera plik CMakeLists dla aplikacji.
W folderze certs utwórz plik tekstowy z rozszerzeniem pem, skopiuj do niego każdy certyfikat i zapisz plik.
W pliku CMakeLists.txt dodaj plik certyfikatu do pakietu obrazów jako plik zasobu. Na przykład:

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

Plik certyfikatu powinien teraz zostać wyświetlony w folderze certs w pakiecie obrazów.

Ustawianie lokalizacji certyfikatów

W aplikacji użyj opcji CURLOPT_CAPATH i CURLOPT_CAINFO , aby ustawić lokalizacje certyfikatów. Wywołaj Storage_GetAbsolutePathInImagePackage , aby pobrać ścieżkę bezwzględną do certyfikatów w pakiecie obrazu, a następnie wywołaj curl_easy_setopt.

CURLOPT_CAPATH ustawia domyślny folder dla certyfikatów. Na przykład poniższy kod nakazuje programowi curl wyszukanie certyfikatów w folderze certs na obrazie:

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

CURLOPT_CAINFO ustawia ścieżkę do pliku zawierającego co najmniej jeden certyfikat. Program Curl wyszukuje ten plik oprócz domyślnego folderu ustawionego w CURLOPT_CAPATH. Na przykład:

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

Ten kod informuje program curl o zaufaniu wszystkim urzędom certyfikacji zdefiniowanym w pliku mycertificates.pem oprócz urzędów certyfikacji zdefiniowanych w katalogu ustawionym w CURLOPT_CAPATH.

Wzajemne uwierzytelnianie

Wzajemne uwierzytelnianie sprawdza, czy zarówno serwer, jak i urządzenie klienckie są wiarygodne. Jest to proces wieloetapowy:

Aplikacja uwierzytelnia serwer przy użyciu certyfikatu urzędu certyfikacji zgodnie z opisem w temacie Uwierzytelnianie serwera.
Aplikacja przedstawia certyfikat uwierzytelniania klienta x509 na serwerze, aby serwer mógł uwierzytelnić urządzenie.
Serwer używa łańcucha certyfikatów dzierżawy usługi Azure Sphere, aby sprawdzić, czy urządzenie należy do dzierżawy.

Aplikacja może skonfigurować stronę uwierzytelniania urządzenia wzajemnego uwierzytelniania na jeden z dwóch sposobów:

Skonfiguruj funkcję DeviceAuth_CurlSslFunc usługi Azure Sphere jako funkcję SSL, która wykonuje uwierzytelnianie.
Utwórz niestandardową funkcję SSL, która wywołuje funkcję DeviceAuth_SslCtxFunc usługi Azure Sphere na potrzeby uwierzytelniania.

Uwaga

Usługa Azure Sphere nie obsługuje ponownego negocjowania protokołu SSL/TLS.

Przed użyciem jednej z funkcji należy zaktualizować plik CMakeLists.txt dla aplikacji, aby dodać narzędzia curl i tlsutils do TARGET_LINK_LIBRARIES:

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

Korzystanie z DeviceAuth_CurlSslFunc

Najprostszym sposobem przeprowadzenia uwierzytelniania urządzenia jest skonfigurowanie DeviceAuth_CurlSslFunc jako funkcji wywołania zwrotnego na potrzeby uwierzytelniania ssl curl:

// 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;
}

Funkcja DeviceAuth_CurlSslFunc pobiera łańcuch certyfikatów dla bieżącej dzierżawy usługi Azure Sphere i konfiguruje połączenie curl w celu przeprowadzenia wzajemnego uwierzytelniania. Jeśli uwierzytelnianie zakończy się niepowodzeniem, funkcja zwróci CURLE_SSL_CERTPROBLEM.

Korzystanie z DeviceAuth_SslCtxFunc

Aplikacja może również użyć niestandardowej funkcji wywołania zwrotnego SSL, która wywołuje funkcję DeviceAuth_SslCtxFunc usługi Azure Sphere na potrzeby uwierzytelniania.

Niestandardowa funkcja SSL musi wywoływać DeviceAuth_SslCtxFunc w celu przeprowadzenia uwierzytelniania, ale może również wykonywać inne zadania związane z uwierzytelnianiem. DeviceAuth_SslCtxFunc zwraca wartość DeviceAuthSslResult wyliczenia, która zawiera szczegółowe informacje o awarii. Na przykład:

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;
    }

Używanie łańcucha certyfikatów dzierżawy na serwerze

Aby przeprowadzić wzajemne uwierzytelnianie, serwer musi mieć możliwość sprawdzenia, czy urządzenie należy do dzierżawy usługi Azure Sphere i czy sama dzierżawa jest legalna. Aby przeprowadzić to uwierzytelnianie, serwer wymaga łańcucha certyfikatów dzierżawy usługi Azure Sphere, który podpisuje wszystkie urządzenia usługi Azure Sphere:

Aby uzyskać łańcuch certyfikatów dla dzierżawy, pobierz go do pliku p7b, jak w poniższym przykładzie:

Interfejs wiersza polecenia usługi Azure Sphere
Klasyczny interfejs wiersza polecenia usługi Azure Sphere

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

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

Uwaga

Klasyczny interfejs wiersza polecenia usługi Azure Sphere zostaje wycofany. Zalecamy korzystanie z usługi Azure Sphere (zintegrowanej).

Następnie możesz użyć pliku p7b na serwerze.

Dodatkowe porady dotyczące korzystania z narzędzia curl

Poniżej przedstawiono kilka dodatkowych wskazówek dotyczących korzystania z narzędzia curl w aplikacji usługi Azure Sphere.

Jeśli planujesz przechowywanie zawartości strony w pamięci RAM lub flash, pamiętaj, że magazyn na urządzeniu usługi Azure Sphere jest ograniczony.
Aby upewnić się, że program curl jest zgodny z przekierowaniami, dodaj następujący kod:
```
curl_easy_setopt(curl_handle, CURLOPT_FOLLOWLOCATION, 1L);
```
Aby dodać pełne informacje o operacjach curl, które mogą być przydatne podczas debugowania:
```
curl_easy_setopt(curl_handle, CURLOPT_VERBOSE, 1L);
```
Niektóre serwery zwracają błędy, jeśli żądanie nie zawiera agenta użytkownika. Aby ustawić agenta użytkownika:
```
curl_easy_setopt(curl_handle, CURLOPT_USERAGENT, "libcurl-agent/1.0");
```

Podczas obsługi curl_multi wywołań zwrotnych czasomierza należy unikać cyklicznych wywołań, gdy zgłoszony limit czasu wynosi 0 ms, ponieważ może to prowadzić do nieprzewidywalnego zachowania. Zamiast tego należy traktować 0 ms jako 1ms, wyzwalając EventLoopTimer (0ms EventLoopTimers są również rekursywne i należy unikać).

static int CurlTimerCallback(CURLM *multi, long timeoutMillis, void *unused)
{
     // A value of -1 means the timer does not need to be started.
     if (timeoutMillis != -1) {

         if (timeoutMillis == 0) {
             // We cannot queue an event for 0ms in the future (the timer never fires)
             // So defer it very slightly (see https://curl.se/libcurl/c/multi-event.html)
             timeoutMillis = 1;
         }

         // Start a single shot timer with the period as provided by cURL.
         // The timer handler will invoke cURL to process the web transfers.
         const struct timespec timeout = {.tv_sec = timeoutMillis / 1000,
                                          .tv_nsec = (timeoutMillis % 1000) * 1000000};
         SetEventLoopTimerOneShot(curlTimer, &timeout);
     }

     return 0;
}

Udostępnij za pośrednictwem