Compartir vía

Usar wolfSSL para conexiones TLS

  • Artículo

El SDK de Azure Sphere incluye un subconjunto de la biblioteca wolfSSL para la seguridad de la capa de transporte (TLS), que las aplicaciones de alto nivel pueden usar para crear conexiones TLS seguras.

La referencia de la API wolfSSL proporciona documentación exhaustiva de la API wolfSSL, junto con muchos ejemplos. Azure Sphere admite un subconjunto de la API que garantiza la compatibilidad binaria.

Requisitos para las aplicaciones que usan la biblioteca wolfSSL

Las aplicaciones que usan la biblioteca wolfSSL deben incluir los archivos de encabezado necesarios y la configuración de compilación.

La API de TLS wolfSSL no requiere funcionalidades en el manifiesto de la aplicación. Sin embargo, si la aplicación se conecta a un punto de conexión de Internet, el manifiesto de la aplicación debe incluir información sobre la conexión. Consulte Conectarse a servicios web para obtener más información sobre cómo habilitar la conectividad.

Archivos de encabezado

Las aplicaciones que usan la API wolfSSL deben incluir el archivo de ssl.h encabezado y pueden requerir uno o más archivos de encabezado adicionales, dependiendo de las características de wolfSSL en uso:

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

Consulte la documentación de wolfSSL para determinar qué archivos de encabezado requiere su aplicación.

Configuración de compilación

Para crear una aplicación con compatibilidad con la API DE TLS wolfSSL, edite los archivos de CMakePresets.json y CMakeLists.txt para especificar el conjunto de API de destino y vincular la biblioteca wolfSSL, respectivamente.

  1. Establezca la TARGET_API_SET en CMakePresets.json en 6 o superior.

    "AZURE_SPHERE_TARGET_API_SET": "6"

  2. Agregue wolfssl a la lista de target_link_libraries en CMakeLists.txt para vincular la biblioteca wolfSSL al proyecto:

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

Características compatibles

El SDK de Azure Sphere admite wolfSSL TLS del lado cliente con un certificado de cliente proporcionado por Microsoft, un certificado o su elección. El SDK de Azure Sphere admite wolfSSL TLS del lado servidor usando solo un certificado de su elección. Entre los escenarios no compatibles notables se incluyen:

  • Solo las conexiones TLS del lado cliente wolfSSL son compatibles con el certificado de cliente proporcionado por Microsoft. Las conexiones TLS del lado del servidor no pueden usar el certificado de cliente proporcionado por Microsoft.

  • Una aplicación puede usar la compatibilidad integrada con WOLFSSL TLS o usar y vincular en otra implementación de la biblioteca wolfSSL. Sin embargo, no se admite el uso mixto de la compatibilidad integrada con otra biblioteca wolfSSL.

Usar wolfSSL en Azure Sphere

Las aplicaciones de Azure Sphere de alto nivel pueden usar wolfSSL para crear y comunicarse a través de una conexión TLS. Las aplicaciones normalmente deben usar una combinación de las técnicas para crear y comunicarse a través de estas conexiones.

Nota

Para una mayor seguridad, las aplicaciones deben usar wolfSSL_CTX_set_verify() para validar el host. Consulta la documentación de wolfSSL para obtener más información.

Inicializa wolfSSL para conexiones de client TLS

Para crear una conexión TLS con wolfSSL, la aplicación primero debe inicializar la biblioteca y el contexto SSL (CTX), como en el siguiente fragmento de código:

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

Cargar el certificado

Después de inicializar wolfSSL, puede cargar un certificado para su uso con la conexión TLS. Puede incluir el certificado en el paquete de imagen de la aplicación, como se describe en Agregar certificados de entidad de certificación al paquete de imagen.

En el ejemplo siguiente se muestra cómo una aplicación puede usar Storage_GetAbsolutePathInImagePackage para obtener la ruta de acceso a un certificado de cliente que forma parte del paquete de imagen de la aplicación y, a continuación, llama a wolfSSL_CTX_load_verify_locations para cargar el certificado en wolfSSL. Tenga en cuenta que la aplicación debe incluir el archivo de storage.h encabezado para usar 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;
    }

Crear una conexión de cliente

Después de cargar el certificado, la aplicación puede establecer la conexión TLS. Este paso implica la creación de un objeto SSL, su asociación con un descriptor de socket y la creación de la conexión, como en este ejemplo:

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

Leer y escribir datos de la conexión

Para escribir y leer datos de la conexión, la aplicación puede usar wolfSSL_write y wolfSSL_read, respectivamente, como se muestra en el ejemplo siguiente. En este ejemplo, la escritura en el servidor contiene una solicitud HTTP/1.1 estándar para recuperar el contenido de la página. La documentación de HTTP/1.1: Request (w3.org) proporciona un buen resumen de esta estructura. Sin embargo, tenga en cuenta que este documento se ha reemplazado y puede encontrar más detalles sobre la estructura de solicitudes en su RFC 9110 de reemplazo: semántica 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);

Inicializar wolfSSL para conexiones del lado servidor

Para crear un servidor TLS con wolfSSL, la aplicación primero debe inicializar la biblioteca y el contexto SSL (CTX), como en el siguiente fragmento de código:

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

Aceptar conexiones entrantes con el servidor wolfSSL TLS

Acepte las conexiones entrantes desde un cliente al servidor Azure Sphere.

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

Limpieza

Cuando la aplicación termine de usar la conexión, debería liberar los recursos relacionados.

    free(certificatePath);

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

Muestra

Para obtener un ejemplo de la funcionalidad de WolfSSL en la plataforma Azure Sphere, consulte WolfSSL_HighLevelApp.