Поделиться через

Использование wolfSSL для подключений TLS

  • Статья

Пакет SDK для Azure Sphere включает подмножество библиотеки wolfSSL для обеспечения безопасности на уровне транспорта (TLS), которую высокоуровневые приложения могут использовать для создания безопасных подключений TLS.

Справочник по API wolfSSL содержит подробную документацию по API wolfSSL, а также множество примеров. Azure Sphere поддерживает подмножество API , которое обеспечивает двоичную совместимость.

Требования для приложений, использующих библиотеку wolfSSL

Приложения, использующие библиотеку wolfSSL, должны содержать необходимые файлы заголовков и конфигурацию сборки.

ДЛЯ API TLS wolfSSL не требуются возможности манифеста приложения. Однако если приложение подключается к конечной точке Интернета, манифест приложения должен содержать сведения о подключении. Дополнительные сведения о включении подключения см. в разделе Подключение к веб-службам .

Файлы заголовков

Приложения, использующие API wolfSSL, должны содержать ssl.h файл заголовка и могут требовать один или несколько дополнительных файлов заголовков в зависимости от используемых функций wolfSSL:

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

Сведения о том, какие файлы заголовков требуются приложению, см. в документации по wolfSSL.

Конфигурация сборки

Чтобы создать приложение с поддержкой API TLS wolfSSL, измените файлы CMakePresets.json и CMakeLists.txt, чтобы указать целевой набор API и связать библиотеку wolfSSL соответственно.

  1. Задайте для TARGET_API_SET в CMakePresets.json значение 6 или более.

    "AZURE_SPHERE_TARGET_API_SET": "6"

  2. Добавьте wolfssl в список target_link_libraries в CMakeLists.txt, чтобы связать библиотеку wolfSSL с проектом:

    target_link_libraries(${PROJECT_NAME} applibs pthread gcc_s c wolfssl)

Поддерживаемые функции

Пакет SDK для Azure Sphere поддерживает протокол TLS wolfSSL на стороне клиента, используя предоставленный корпорацией Майкрософт сертификат клиента или сертификат или ваш выбор. Пакет SDK для Azure Sphere поддерживает протокол TLS wolfSSL на стороне сервера, используя только сертификат на ваш выбор. Ниже приведены следующие неподдерживаемые сценарии:

  • Сертификат клиента, предоставленный Корпорацией Майкрософт, поддерживает только клиентские подключения TLS на стороне клиента wolfSSL. Подключения TLS на стороне сервера не могут использовать предоставленный корпорацией Майкрософт сертификат клиента.

  • Приложение может либо использовать встроенную поддержку TLS wolfSSL, либо использовать и связать в другой реализации библиотеки wolfSSL. Однако смешанное использование встроенной поддержки с другой библиотекой wolfSSL не поддерживается.

Использование wolfSSL в Azure Sphere

Высокоуровневые приложения Azure Sphere могут использовать wolfSSL для создания и обмена данными по протоколу TLS. Приложения обычно должны использовать сочетание методов для создания этих подключений и обмена данными по ним.

Примечание

Для повышения безопасности приложения должны использовать wolfSSL_CTX_set_verify() для проверки узла. Дополнительные сведения см. в документации по wolfSSL .

Инициализация wolfSSL для клиентских подключений TLS

Чтобы создать TLS-подключение с wolfSSL, приложение сначала должно инициализировать библиотеку и контекст SSL (CTX), как показано в следующем фрагменте кода:

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

Загрузка сертификата

После инициализации wolfSSL можно загрузить сертификат для использования с подключением TLS. Сертификат можно включить в пакет образа приложения, как описано в разделе Добавление сертификатов ЦС в пакет образа.

В следующем примере показано, как приложение может использовать Storage_GetAbsolutePathInImagePackage , чтобы получить путь к сертификату клиента, который входит в пакет образа приложения, а затем вызвать wolfSSL_CTX_load_verify_locations для загрузки сертификата в wolfSSL. Обратите внимание, что приложение должно содержать файл заголовка storage.h для использования 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;
    }

Создание подключения на стороне клиента

После загрузки сертификата приложение может установить ПОДКЛЮЧЕНИЕ TLS. Этот шаг включает создание объекта SSL, связывание его с дескриптором сокета, а затем создание соединения, как показано в следующем примере:

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

Чтение и запись данных из подключения

Для записи и чтения данных из подключения приложение может использовать wolfSSL_write и wolfSSL_read соответственно, как показано в следующем примере. В этом примере запись на сервер содержит стандартный запрос HTTP/1.1 для получения содержимого страницы. В документации по http/1.1: Request (w3.org) приведены подробные сведения об этой структуре. Однако обратите внимание, что этот документ заменен, и дополнительные сведения о структуре запроса можно найти в документе RFC 9110: семантика HTTP (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);

Инициализация wolfSSL для подключений на стороне сервера

Чтобы создать TLS-сервер с wolfSSL, приложение должно сначала инициализировать библиотеку и контекст SSL (CTX), как показано в следующем фрагменте кода:

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

Прием входящих подключений с помощью сервера TLS wolfSSL

Примите входящие подключения от клиента к серверу Azure Sphere.

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

Очистки

Когда приложение использует подключение, оно должно освободить связанные ресурсы.

    free(certificatePath);

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

Образец

Пример функций WolfSSL на платформе Azure Sphere см. в разделе WolfSSL_HighLevelApp.