Megosztás a következőn keresztül:

Csatlakozás webszolgáltatásokhoz

  • Cikk

Az Azure Sphere SDK tartalmazza a libcurl kódtárat, amelyet a magas szintű alkalmazások a HTTP- és HTTPS-webszolgáltatásokkal való csatlakozáshoz és hitelesítéshez használhatnak. A kiszolgáló- és ügyfélhitelesítés is támogatott, így az alkalmazások ellenőrizhetik, hogy a várt kiszolgálóval kommunikálnak-e, és bizonyítani tudják a kiszolgálónak, hogy az eszközük és az Azure Sphere-katalógusuk megbízható. A kölcsönös hitelesítés egyesíti a kettőt.

A GitHubon található Azure Sphere-mintatár a következő curl-mintákat tartalmazza:

  • HTTPS_Curl_Easy szinkron (blokkoló) API-t használ a kiszolgálóhitelesítéshez.
  • HTTPS_Curl_Multi minta egy aszinkron (nem blokkoló) API-t használ a kiszolgálóhitelesítéshez.

Bár a kiszolgálóhitelesítés szinkron megközelítése a HTTPS_Curl_Easy-ben meglehetősen egyszerű, az Azure Sphere-alkalmazásoknak általában a HTTPS_Curl_Multi mintában bemutatott összetettebb aszinkron technikát kell használniuk, egy epoll-alapú, egyszálas eseményvezérelt mintával együtt.

A libcurl webhely részletes dokumentációt nyújt a libcurl C API-ról , és számos példát tartalmaz. A cURL-kódtár és az Azure Sphere SDK futtatókörnyezeti kódtár közötti különbségek a következők:

Állandó neve
(definíció)		 cURL-tartománykorlátok Az Azure Sphere tartománykorlátai
CURLOPT_BUFFERSIZE
(puffer mérete)		 Alapértelmezett: 16 KB Alapértelmezett: 1536 KB
CURLOPT_UPLOAD_BUFFERSIZE
(feltöltési puffer mérete)		 Alapértelmezett: 64 KB
Maximum: 2 MB
Minimum: 16 KB
 Alapértelmezett: 1536 KB
Maximum: 64 KB
Minimum: 1536 KB
CURLOPT_HEADERFUNCTION
(a függvénynek átadott TELJES HTTP-fejléc)		 Maximum: 100 KB Maximum: 16 KB
CURLOPT_DNS_CACHE_TIMEOUT Alapértelmezett: gyorsítótárazási eredmények 60 másodpercig
Maximális: a gyorsítótár mindig eredményeket ad
Minimum: 0 (ne gyorsítótárazza az eredményeket)		 Minden érték felül van bírálva 0-ra, és az eredmények nem lesznek gyorsítótárazva.

A curl-t használó alkalmazásokra vonatkozó követelmények

A curl-kódtárat használó alkalmazásoknak tartalmazniuk kell a megfelelő fejlécfájlokat, és meg kell adniuk az Azure Sphere (örökölt) bérlőI UUID azonosítóját és az internetes gazdagép adatait az alkalmazásjegyzékben.

Fejlécfájlok

A curl használatához foglalja bele ezeket a fejlécfájlokat az alkalmazásba:

#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

A storage.h fejlécfájl csak akkor szükséges, ha egy vagy több tanúsítványt ad meg az alkalmazás lemezképcsomagjában. A deviceauth_curl.h fejléc szükséges a kölcsönös hitelesítés végrehajtásához. A networking_curl.h fejlécre akkor van szükség, ha az alkalmazás proxyt használ az internethez való csatlakozáshoz.

Alkalmazásjegyzék

Az alkalmazásjegyzék AllowedConnections mezőjének meg kell adnia azokat a gazdagépeket, amelyekhez az alkalmazás csatlakozik. Tartalmaznia kell azon tartományok nevét is, amelyekkel a kapcsolat átirányításkor találkozhat. Például a microsoft.com és www.microsoft.com a is szükséges egy olyan alkalmazáshoz, amely a Microsoft kezdőlapjára csatlakozik.

Ha az alkalmazás kölcsönös hitelesítést használ, a jegyzékfájl DeviceAuthentication mezőjének tartalmaznia kell az Azure Sphere (örökölt) bérlőI UUID azonosítóját. Az eszközhitelesítési tanúsítványok csak akkor vannak kibocsátva, ha az eszköz katalógusa olyan Azure Sphere-bérlőI UUID-hoz van csatolva, amely megfelel az alkalmazásjegyzékben szereplő bérlőI UUID-nak. Ez a korlátozás mélységi védelmet biztosít: egy másik katalógusban (például egy másik ügyfél vagy egy rosszindulatú entitás) lévő eszközön futó alkalmazások nem tudnak hitelesítést végezni a kiszolgálón.

A fejlesztés során az örökölt bérlőI UUID az az sphere catalog show paranccsal és az MigratedCatalogIdtags objektumból való kinyerésével kereshető meg.

Ha az alkalmazás proxyt használ, a ReadNetworkProxyConfig mező azt jelzi, hogy az alkalmazás rendelkezik-e engedéllyel a proxykonfiguráció lekéréséhez.

A következő példában az AllowedConnections mező azt határozza meg, hogy az alkalmazás csak a -hez www.example.comcsatlakozik, a DeviceAuthentication mező az Azure Sphere (örökölt) bérlőI UUID azonosítóját adja meg, amely lehetővé teszi az alkalmazás számára, hogy az eszköztanúsítványt kölcsönös hitelesítéshez használja, a ReadNetworkProxyConfig mező pedig azt, hogy az alkalmazás újrapróbálkozhasson a proxy konfigurációs adataival.

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

Támogatott funkciók

Az Azure Sphere-hez készült Libcurl csak a HTTP- és HTTPS-protokollokat támogatja. Emellett az Azure Sphere operációs rendszer nem támogat bizonyos funkciókat, például írható fájlokat (cookie-kat) vagy UNIX-szoftvercsatornákat. A jövőbeli libcurl-kiadásokban, például az mprintf() családban nem támogatott funkciók nem érhetők el.

Az Azure Sphere-hez készült Libcurl támogatja a TLS 1.2-t és a TLS 1.3-at, és kivezette a TLS 1.0-t és a TLS 1.1-et a szélesebb körű Microsoft TLS biztonsági stratégiával összhangban.

A támogatott titkosítócsomagok a következők:

  • 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

A TLS nem támogatott verziójának használatára tett kísérletek a következő hibát CyaSSL does not support <version>eredményezik: .

Kiszolgálóhitelesítés

Az Azure Sphere támogatja a kiszolgálói hitelesítést a libcurl használatával. A kiszolgáló tanúsítványát az eszköz által megbízhatónak minősítő hitelesítésszolgáltatónak (CA) kell aláírnia. Ahhoz, hogy a libcurl hitelesíthesse a kiszolgálót, az alkalmazásnak meg kell adnia a CA-fájl elérési útját.

Ca-tanúsítványok hozzáadása a rendszerképcsomaghoz

Egy vagy több hitelesítésszolgáltató használatához hozzá kell adnia a tanúsítványokat a rendszerképcsomaghoz. Minden tanúsítványnak base-64 kódolásúnak kell lennie. A legegyszerűbb módszer egyetlen fájl létrehozása, amely az összes további tanúsítványt tartalmazza. A fájlnak .pem fájlnévkiterjesztéssel kell rendelkeznie. Tanúsítványok hozzáadása:

  1. Hozzon létre egy certs mappát az alkalmazás projektmappájában. A projektmappa tartalmazza az alkalmazás CMakeLists fájlját.
  2. A certs mappában hozzon létre egy .pem kiterjesztésű szövegfájlt, másolja bele az egyes tanúsítványokat, és mentse a fájlt.
  3. A CMakeLists.txt fájlban adja hozzá a tanúsítványfájlt a lemezképcsomaghoz erőforrásfájlként. Például:
azsphere_target_add_image_package(${PROJECT_NAME} RESOURCE_FILES "certs/DigiCertGlobalRootCA.pem")

A tanúsítványfájlnak ekkor meg kell jelennie a lemezképcsomag certs mappájában.

Tanúsítványhelyek beállítása

Az alkalmazásban a CURLOPT_CAPATH és a CURLOPT_CAINFO beállításával adja meg a tanúsítványok helyét. Hívja meg a Storage_GetAbsolutePathInImagePackage , hogy lekérje a lemezképcsomagban lévő tanúsítványok abszolút elérési útját, majd hívja meg a curl_easy_setopt.

CURLOPT_CAPATH beállítja a tanúsítványok alapértelmezett mappáit. A következő kód például arra utasítja a curl-t, hogy keresse meg a tanúsítványokat a rendszerkép Tanúsítványok mappájában:

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

CURLOPT_CAINFO egy vagy több tanúsítványt tartalmazó fájl elérési útját állítja be. A Curl a fájlban a CURLOPT_CAPATH alapértelmezett mappája mellett keres. Például:

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

Ez a kód arra utasítja a Curl-t, hogy bízzon meg a mycertificates.pem fájlban definiált hitelesítésszolgáltatókban, valamint az CURLOPT_CAPATH könyvtárában definiált hitelesítésszolgáltatókban.

Kölcsönös hitelesítés

A kölcsönös hitelesítés ellenőrzi, hogy a kiszolgáló és az ügyféleszköz is megbízható-e. Ez egy többlépéses folyamat:

  1. Az alkalmazás hitelesítése hitelesítésszolgáltatói tanúsítvánnyal történik, a Kiszolgálóhitelesítés című szakaszban leírtak szerint.
  2. Az alkalmazás egy x509-ügyfél-hitelesítési tanúsítványt mutat be a kiszolgálónak, hogy a kiszolgáló hitelesíteni tudja az eszközt.
  3. A kiszolgáló az Azure Sphere-katalógus tanúsítványláncával ellenőrzi, hogy az eszköz a katalógushoz tartozik-e.

Az alkalmazások kétféleképpen állíthatják be a kölcsönös hitelesítés eszközhitelesítési oldalát:

  • Konfigurálja az Azure Sphere DeviceAuth_CurlSslFunc függvényt a hitelesítést végző SSL-függvényként.
  • Hozzon létre egy egyéni SSL-függvényt, amely meghívja az Azure Sphere DeviceAuth_SslCtxFunc függvényt a hitelesítéshez.

Megjegyzés

Az Azure Sphere nem támogatja az SSL-/TLS-újratárgyalást.

A függvények használata előtt frissítenie kell az alkalmazás CMakeLists.txt fájlját, hogy curl- és tlsutils-t adjon hozzá TARGET_LINK_LIBRARIES:

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

A DeviceAuth_CurlSslFunc használata

Az eszközhitelesítés legegyszerűbb módja a DeviceAuth_CurlSslFunc konfigurálása a curl SSL-hitelesítés visszahívási függvényeként:

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

A DeviceAuth_CurlSslFunc függvény lekéri az aktuális Azure Sphere-katalógus tanúsítványláncát, és beállítja a curl-kapcsolatot a kölcsönös hitelesítés végrehajtásához. Ha a hitelesítés sikertelen, a függvény CURLE_SSL_CERTPROBLEM ad vissza.

A DeviceAuth_SslCtxFunc használata

Az alkalmazások egyéni SSL-visszahívási függvényt is használhatnak, amely meghívja az Azure Sphere DeviceAuth_SslCtxFunc függvényt a hitelesítéshez.

Az egyéni SSL-függvénynek DeviceAuth_SslCtxFunc kell meghívnia a hitelesítés végrehajtásához, de a hitelesítéssel kapcsolatos egyéb feladatokat is elvégezhet. DeviceAuth_SslCtxFunc az DeviceAuthSslResult enumerálás értékét adja vissza, amely részletes információkat nyújt a hibáról. Például:

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

A katalógustanúsítvány-lánc használata a kiszolgálón

A kölcsönös hitelesítés végrehajtásához a kiszolgálónak képesnek kell lennie ellenőrizni, hogy az eszköz az Azure Sphere-katalógushoz tartozik-e, és hogy maga a katalógus jogszerű-e. A hitelesítés végrehajtásához a kiszolgálónak szüksége van az Azure Sphere-katalógus tanúsítványláncára, amely aláírja az összes Azure Sphere-eszközt:

A katalógus tanúsítványláncának lekéréséhez töltse le egy .p7b fájlba, ahogyan az alábbi példában látható:

az sphere ca-certificate download-chain --destination CA-cert-chain.p7b

Ezután használhatja a .p7b fájlt a kiszolgálón.

További tippek a curl használatához

Íme néhány további tipp a curl Azure Sphere-alkalmazásokban való használatához.

  • Ha a lap tartalmát RAM-ban vagy flash formátumban szeretné tárolni, vegye figyelembe, hogy az Azure Sphere-eszközön korlátozott a tárterület.

  • Annak érdekében, hogy a curl kövesse az átirányításokat, adja hozzá a következőt a kódhoz:

    curl_easy_setopt(curl_handle, CURLOPT_FOLLOWLOCATION, 1L);

  • Részletes információk hozzáadása a curl-műveletekkel kapcsolatban, amelyek hasznosak lehetnek a hibakeresés során:

    curl_easy_setopt(curl_handle, CURLOPT_VERBOSE, 1L);

  • Egyes kiszolgálók hibát adnak vissza, ha egy kérelem nem tartalmaz felhasználói ügynököt. Felhasználói ügynök beállítása:

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

  • Curl_multi időzítő visszahívások kezelésekor kerülje a rekurzív hívásokat, ha a jelentett időtúllépés 0 ezredmagas, mivel ez kiszámíthatatlan viselkedéshez vezethet. Ehelyett kezelje a 0ms-et 1ms-ként egy EventLoopTimer aktiválásával (a 0ms EventLoopTimers is rekurzív, ezért el kell kerülni).

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