Menggunakan wolfSSL untuk koneksi TLS

Artikel
11/05/2024

Penting

Ini adalah dokumentasi Azure Sphere (Warisan). Azure Sphere (Warisan) dihentikan pada 27 September 2027, dan pengguna harus bermigrasi ke Azure Sphere (Terintegrasi) saat ini. Gunakan pemilih Versi yang terletak di atas TOC untuk melihat dokumentasi Azure Sphere (Terintegrasi).

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 tentang 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 terhubung 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 membangun aplikasi dengan dukungan WolfSSL TLS API, edit file CMakePresets.json dan CMakeLists.txt untuk menentukan set API target dan untuk menautkan pustaka wolfSSL.

Atur TARGET_API_SET di CMakePresets.json ke 6 atau lebih tinggi.
```
"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 WolfSSL TLS sisi klien menggunakan sertifikat klien yang disediakan Microsoft atau sertifikat atau pilihan Anda. Azure Sphere SDK mendukung TLS wolfSSL sisi server hanya menggunakan sertifikat pilihan Anda. Skenario yang tidak didukung termasuk:

Hanya koneksi TLS sisi 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 cuplikan 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 menunjukkan bagaimana aplikasi dapat menggunakan Storage_GetAbsolutePathInImagePackage untuk mendapatkan jalur ke sertifikat klien yang merupakan bagian dari paket gambar aplikasi, lalu memanggil 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 sisi klien

Setelah memuat sertifikat, aplikasi dapat membuat koneksi TLS. Langkah ini melibatkan pembuatan objek SSL, mengaitkannya 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 wolfSSL_write dan wolfSSL_read, masing-masing, seperti yang ditunjukkan contoh berikut. Dalam contoh ini, tulis 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 dapat 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 cuplikan 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;
    }

Menerima 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 dilakukan 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 sampel fungsionalitas WolfSSL pada platform Azure Sphere, lihat WolfSSL_HighLevelApp.

Bagikan melalui