Menggunakan wolfSSL untuk koneksi TLS

Artikel
08/09/2023

Azure Sphere SDK menyertakan subset pustaka wolfSSL untuk keamanan lapisan transportasi (TLS), yang dapat digunakan aplikasi tingkat tinggi untuk membuat koneksi TLS yang aman.

Referensi API wolfSSL menyediakan dokumentasi menyeluruh dari API wolfSSL, bersama dengan banyak contoh. Azure Sphere mendukung subset API yang memastikan kompatibilitas biner.

Persyaratan untuk aplikasi yang menggunakan pustaka wolfSSL

Aplikasi yang menggunakan pustaka wolfSSL harus menyertakan file header dan konfigurasi build yang diperlukan.

API TLS WolfSSL tidak memerlukan kemampuan dalam manifes aplikasi. Namun, jika aplikasi tersambung ke titik akhir internet, manifes aplikasi harus menyertakan informasi tentang koneksi. Lihat Menyambungkan ke layanan web untuk detail selengkapnya tentang mengaktifkan konektivitas.

File header

Aplikasi yang menggunakan API wolfSSL harus menyertakan ssl.h file header, dan mungkin memerlukan satu atau beberapa file header tambahan, tergantung pada fitur wolfSSL yang digunakan:

#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>

Lihat dokumentasi wolfSSL untuk menentukan file header mana yang diperlukan aplikasi Anda.

Konfigurasi build

Untuk membuat aplikasi dengan dukungan API TLS WolfSSL, edit file CMakePresets.json dan CMakeLists.txt untuk menentukan rangkaian API target dan untuk menautkan pustaka wolfSSL.

Atur TARGET_API_SET di CMakePresets.json ke 6 atau yang lebih besar.
```
"AZURE_SPHERE_TARGET_API_SET": "6"
```
Tambahkan wolfssl ke daftar target_link_libraries di CMakeLists.txt untuk menautkan pustaka wolfSSL ke dalam proyek:
```
target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c wolfssl)
```

Fitur yang didukung

Azure Sphere SDK mendukung TLS wolfSSL pihak klien menggunakan sertifikat klien yang disediakan Microsoft atau sertifikat atau pilihan Anda. Azure Sphere SDK mendukung TLS serigala sisi serverSSL hanya menggunakan sertifikat pilihan Anda. Skenario yang tidak didukung termasuk:

Hanya koneksi TLS pihak klien wolfSSL yang didukung dengan sertifikat klien yang disediakan Microsoft. Koneksi TLS sisi server tidak dapat menggunakan sertifikat klien yang disediakan Microsoft.
Aplikasi dapat menggunakan dukungan TLS WolfSSL bawaan atau menggunakan dan menautkan dalam implementasi pustaka wolfSSL lainnya. Namun, penggunaan campuran dukungan bawaan dengan pustaka wolfSSL lain tidak didukung.

Menggunakan wolfSSL di Azure Sphere

Aplikasi Azure Sphere tingkat tinggi dapat menggunakan WolfSSL untuk membuat dan berkomunikasi melalui koneksi TLS. Aplikasi biasanya harus menggunakan kombinasi teknik untuk membuat dan berkomunikasi melalui koneksi ini.

Catatan

Untuk keamanan yang ditingkatkan, aplikasi harus menggunakan wolfSSL_CTX_set_verify() untuk memvalidasi host. Lihat dokumentasi WolfSSL untuk informasi selengkapnya.

Menginisialisasi wolfSSL untuk koneksi TLS klien

Untuk membuat koneksi TLS dengan wolfSSL, aplikasi terlebih dahulu harus menginisialisasi pustaka dan konteks SSL (CTX), seperti dalam potongan kode berikut:

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

Memuat sertifikat

Setelah wolfSSL diinisialisasi, wolfSSL dapat memuat sertifikat untuk digunakan dengan koneksi TLS. Anda dapat menyertakan sertifikat dalam paket gambar aplikasi, seperti yang dijelaskan dalam Menambahkan sertifikat CA ke paket gambar.

Contoh berikut ini memperlihatkan bagaimana aplikasi dapat menggunakan Storage_GetAbsolutePathInImagePackage untuk mendapatkan jalur ke sertifikat klien yang merupakan bagian dari paket gambar aplikasi, lalu hubungi wolfSSL_CTX_load_verify_locations untuk memuat sertifikat ke wolfSSL. Perhatikan bahwa aplikasi harus menyertakan storage.h file header untuk menggunakan Storage_GetAbsolutePathInImagePackage.

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

Membuat koneksi pihak klien

Setelah memuat sertifikat, aplikasi dapat menetapkan koneksi TLS. Langkah ini melibatkan pembuatan objek SSL, mengasosiasikannya dengan deskriptor soket, lalu membuat koneksi, seperti dalam contoh ini:

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

Membaca dan menulis data dari koneksi

Untuk menulis dan membaca data dari koneksi, aplikasi dapat menggunakan masing-masing wolfSSL_write dan wolfSSL_read, seperti yang diperlihatkan contoh berikut ini. Dalam contoh ini, penulisan ke server berisi permintaan HTTP/1.1 standar untuk mengambil konten halaman. Dokumentasi di HTTP/1.1: Permintaan (w3.org) memberikan gambaran umum yang baik tentang struktur ini. Namun, perhatikan bahwa dokumen ini telah digantikan dan Anda bisa menemukan detail selengkapnya tentang struktur permintaan dalam penggantian RFC 9110: HTTP Semantics (rfc-editor.org).

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

Menginisialisasi wolfSSL untuk koneksi sisi server

Untuk membuat server TLS dengan wolfSSL, aplikasi harus terlebih dahulu menginisialisasi pustaka dan konteks SSL (CTX), seperti dalam potongan kode berikut:

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

Terima koneksi masuk menggunakan server TLS WolfSSL

Terima koneksi masuk dari klien ke server Azure Sphere.

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

Pembersihan

Ketika aplikasi selesai menggunakan koneksi, aplikasi harus membebaskan sumber daya terkait.

    free(certificatePath);

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

Sampel

Untuk contoh fungsionalitas WolfSSL pada platform Azure Sphere, lihat WolfSSL_HighLevelApp.

Bagikan melalui