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

Статья
11/05/2024

Внимание

Это документация по Azure Sphere (устаревшая версия). Служба Azure Sphere (устаревшая версия) выходит на пенсию 27 сентября 2027 г., и к этому времени пользователи должны перейти в Azure Sphere (интегрированная). Используйте селектор версий, расположенный над toC, чтобы просмотреть документацию по Azure Sphere (интегрированная).

Пакет 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 соответственно.

Задайте TARGET_API_SET в CMakePresets.json значение 6 или больше.
```
"AZURE_SPHERE_TARGET_API_SET": "6"
```
Добавьте 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, используя только сертификат вашего выбора. К заметным неподдерживаемым сценариям относятся:

Только клиентские подключения на стороне клиента 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. Запрос (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.

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