WolfSSL használata TLS-kapcsolatokhoz

Cikk
08/09/2023

Az Azure Sphere SDK tartalmazza a wolfSSL könyvtár egy részét a transport layer security (TLS) számára, amelyet a magas szintű alkalmazások biztonságos TLS-kapcsolatok létrehozásához használhatnak.

A wolfSSL API-referencia részletes dokumentációt nyújt a wolfSSL API-ról, számos példával együtt. Az Azure Sphere támogatja az API egy részét , amely biztosítja a bináris kompatibilitást.

A wolfSSL kódtárat használó alkalmazásokra vonatkozó követelmények

A wolfSSL kódtárat használó alkalmazásoknak tartalmazniuk kell a szükséges fejlécfájlokat és a buildkonfigurációt.

A wolfSSL TLS API nem igényel képességeket az alkalmazásjegyzékben. Ha azonban az alkalmazás egy internetes végponthoz csatlakozik, az alkalmazásjegyzéknek tartalmaznia kell a kapcsolattal kapcsolatos információkat. A kapcsolat engedélyezésével kapcsolatos további részletekért lásd: Csatlakozás webszolgáltatásokhoz .

Fejlécfájlok

A wolfSSL API-t használó alkalmazásoknak tartalmazniuk kell a ssl.h fejlécfájlt, és a használatban lévő wolfSSL-funkcióktól függően egy vagy több további fejlécfájlra lehet szükség:

#include <wolfssl/wolfcrypt/ecc.h>
#include <wolfssl/wolfcrypt/error-crypt.h>
#include <wolfssl/wolfcrypt/random.h>
#include <wolfssl/wolfcrypt/types.h>
#include <wolfssl/ssl.h>

Az alkalmazáshoz szükséges fejlécfájlok meghatározásához tekintse meg a wolfSSL dokumentációját.

Buildkonfiguráció

Ha wolfSSL TLS API-támogatással szeretne létrehozni egy alkalmazást, szerkessze a CMakePresets.json és CMakeLists.txt fájlokat a cél API-készlet meghatározásához, illetve a wolfSSL-kódtár csatolásához.

Állítsa a CMakePresets.json TARGET_API_SET 6 vagy nagyobb értékre.
```
"AZURE_SPHERE_TARGET_API_SET": "6"
```
Adja hozzá wolfssl a CMakeLists.txt target_link_libraries listájához a wolfSSL kódtár projekthez való csatolásához:
```
target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c wolfssl)
```

Támogatott funkciók

Az Azure Sphere SDK támogatja az ügyféloldali wolfSSL TLS-t egy Microsoft által biztosított ügyféltanúsítvány vagy egy ön által választott tanúsítvány használatával. Az Azure Sphere SDK támogatja a kiszolgálóoldali wolfSSL TLS-t, ha csak egy ön által választott tanúsítványt használ. A nem támogatott forgatókönyvek közé tartoznak a következők:

A Microsoft által biztosított ügyféltanúsítvány csak a wolfSSL ügyféloldali TLS-kapcsolatokat támogatja. A kiszolgálóoldali TLS-kapcsolatok nem használhatják a Microsoft által biztosított ügyféltanúsítványt.
Az alkalmazások használhatják a beépített wolfSSL TLS-támogatást, vagy használhatják és csatolhatják egy másik wolfSSL-kódtár implementációjában. A beépített támogatás más wolfSSL-kódtárakkal való vegyes használata azonban nem támogatott.

WolfSSL használata az Azure Sphere-ben

A magas szintű Azure Sphere-alkalmazások a wolfSSL használatával hozhatnak létre és kommunikálhatnak TLS-kapcsolaton keresztül. Az alkalmazásoknak általában a technikák kombinációjával kell létrehozniuk és kommunikálniuk ezeken a kapcsolatokon keresztül.

Megjegyzés

A fokozott biztonság érdekében az alkalmazásoknak a wolfSSL_CTX_set_verify() használatával kell ellenőriznie a gazdagépet. További információért tekintse meg a wolfSSL dokumentációját .

WolfSSL inicializálása ügyféloldali TLS-kapcsolatokhoz

A wolfSSL-lel való TLS-kapcsolat létrehozásához az alkalmazásnak először inicializálnia kell a kódtárat és az SSL-környezetet (CTX), ahogyan az alábbi kódrészletben látható:

    // Configure the wolfSSL library

    if (wolfSSL_Init() != WOLFSSL_SUCCESS) {
        Log_Debug("Error initializing wolfSSL library.\n");
        goto cleanupLabel;
    }

    // Configure wolfSSL CTX functionality

    WOLFSSL_METHOD *wolfSslMethod = wolfTLSv1_3_client_method();
    if (wolfSslMethod == NULL) {
        Log_Debug("Unable to allocate TLS v1.3 method.\n");
        goto cleanupLabel;
    }

    WOLFSSL_CTX *wolfSslCtx = wolfSSL_CTX_new(wolfSslMethod);
    if (wolfSslCtx == NULL) {
        Log_Debug("Unable get create SSL context.\n");
        goto cleanupLabel;
    }

A tanúsítvány betöltése

A wolfSSL inicializálása után betölthet egy tanúsítványt a TLS-kapcsolattal való használathoz. A tanúsítványt belefoglalhatja az alkalmazás rendszerképcsomagjához a Ca-tanúsítványok hozzáadása a lemezképcsomaghoz című cikkben leírtak szerint.

Az alábbi példa bemutatja, hogyan használhatja egy alkalmazás a Storage_GetAbsolutePathInImagePackage az alkalmazásképcsomag részét képező ügyféltanúsítvány elérési útját, majd meghívhatja wolfSSL_CTX_load_verify_locations , hogy betöltse a tanúsítványt a wolfSSL-be. Vegye figyelembe, hogy az alkalmazásnak tartalmaznia kell a storage.hStorage_GetAbsolutePathInImagePackage használni kívánt fejlécfájlt.

   #include <applibs/storage.h>
   ...

    // Get the full path to the certificate file used to authenticate the HTTPS server identity.
    // The .pem file is the certificate that is used to verify the
    // server identity.

    certificatePath = Storage_GetAbsolutePathInImagePackage("certs/YourDesiredCert.pem");
    if (certificatePath == NULL) {
        Log_Debug("The certificate path could not be resolved: errno=%d (%s)\n", errno,
                  strerror(errno));
        goto cleanupLabel;
    }

    // Load the client certificate into wolfSSL
    if (wolfSSL_CTX_load_verify_locations(ctx, certificatePath, NULL) != WOLFSSL_SUCCESS) {
        Log_Debug("Error loading certificate.\n");
        goto cleanupLabel;
    }

Ügyféloldali kapcsolat létrehozása

A tanúsítvány betöltése után az alkalmazás létrehozhatja a TLS-kapcsolatot. Ebben a lépésben létre kell hoznia egy SSL-objektumot, társítania kell azt egy szoftvercsatorna-leíróval, majd létre kell hoznia a kapcsolatot, ahogy az alábbi példában látható:

    // Create the SSL object
    if ((ssl = wolfSSL_new(ctx)) == NULL) {
        Log_Debug("Error creating final SSL object.\n");
        goto cleanupLabel;
    }

    // Attach the socket file descriptor to wolfSSL
    if (wolfSSL_set_fd(ssl, sockfd) != WOLFSSL_SUCCESS) {
        Log_Debug("Error attaching socket fd to wolfSSL.\n");
        goto cleanupLabel;
    }

    // Call Connect for incoming connections
    if (wolfSSL_connect(ssl) != WOLFSSL_SUCCESS) {
        Log_Debug("Error establishing TLS connection to host.\n");
        goto cleanupLabel;
    }

Adatok olvasása és írása a kapcsolatból

A kapcsolat adatainak írásához és olvasásához az alkalmazás használhatja a wolfSSL_write és a wolfSSL_read, ahogy az alábbi példa mutatja. Ebben a példában a kiszolgálóra való írás egy szabványos HTTP/1.1 kérést tartalmaz a lap tartalmának lekéréséhez. A HTTP/1.1: Request (w3.org) dokumentációja jó áttekintést nyújt erről a struktúráról. Vegye figyelembe azonban, hogy ezt a dokumentumot felülírták, és további részleteket a kérésszerkezetről a helyettesítő RFC 9110: HTTP Szemantikában (rfc-editor.org) talál.

    sprintf(buffer, "GET / HTTP/1.1\r\nHost: example.com\r\nAccept: */*\r\n\r\n");
    ret = wolfSSL_write(ssl, buffer, (int)strlen(buffer));
    if (ret != strlen(buffer)) {
        Log_Debug("Error writing GET command to server.\n");
        goto cleanupLabel;
    }

    // Read the data back
    ret = wolfSSL_read(ssl, buffer, BUFFER_SIZE);
    if (ret == -1) {
        Log_Debug("Error reading from host.\n");
        goto cleanupLabel;
    }

    Log_Debug("Received %d bytes from host.\n", ret);
    Log_Debug("%s\n", buffer);

WolfSSL inicializálása kiszolgálóoldali kapcsolatokhoz

A wolfSSL protokollal rendelkező TLS-kiszolgáló létrehozásához az alkalmazásnak először inicializálnia kell a kódtárat és az SSL-környezetet (CTX), ahogyan az alábbi kódrészletben látható:

// Configure wolfSSL CTX functionality
    WOLFSSL_METHOD *wolfSslMethod = wolfTLSv1_3_server_method();
    if (wolfSslMethod) == NULL) {
        Log_Debug("Unable to allocate TLS v1.3 method\n");
        goto cleanupLabel;
    }

    WOLFSSL_CTX *wolfSslCtx = wolfSSL_CTX_new(wolfSslMethod);
    if (wolfSslCtx == NULL) {
        Log_Debug("Unable to create SSL context.\n");
        goto cleanupLabel;
    }

Bejövő kapcsolatok elfogadása wolfSSL TLS-kiszolgálóval

Fogadja el az ügyfél és az Azure Sphere-kiszolgáló bejövő kapcsolatait.

    // Call Accept for incoming connections
    if (wolfSSL_accept(ssl) != WOLFSSL_SUCCESS) {
        Log_Debug("Error establishing TLS connection to host.\n");
        goto cleanupLabel;
    }

Razzia

Amikor az alkalmazás elkészült a kapcsolat használatával, felszabadítja a kapcsolódó erőforrásokat.

    free(certificatePath);

    if (ssl) {
        wolfSSL_free(ssl);
    }
    if (ctx) {
        wolfSSL_CTX_free(ctx);
        wolfSSL_Cleanup();
    }

Minta

Az Azure Sphere platform WolfSSL-funkcióinak mintáját lásd: WolfSSL_HighLevelApp.

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