Uso de wolfSSL para conexiones TLS

Artículo
09/27/2024

Importante

Esta es la documentación de Azure Sphere (heredado). Azure Sphere (heredado) se retira el 27 de septiembre de 2027 y los usuarios deben migrar a Azure Sphere (integrado) en este momento. Use el selector de versiones situado encima de la TOC para ver la documentación de Azure Sphere (integrado).

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 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 aplicación. Sin embargo, si la aplicación se conecta a un punto de conexión de Internet, el manifiesto de aplicación debe incluir información sobre la conexión. Consulte Conexión 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 varios archivos de encabezado adicionales, en función de las características 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 la aplicación.

Configuración de compilación

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

Establezca el TARGET_API_SET en CMakePresets.json en 6 o superior.
```
"AZURE_SPHERE_TARGET_API_SET": "6"
```
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 admitidas

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

Solo se admiten conexiones TLS del lado cliente wolfSSL con el certificado de cliente proporcionado por Microsoft. Las conexiones TLS del lado servidor no pueden usar el certificado de cliente proporcionado por Microsoft.
Una aplicación puede usar la compatibilidad integrada con TLS wolfSSL o usar y vincular en otra implementación de biblioteca wolfSSL. Sin embargo, no se admite el uso mixto de la compatibilidad integrada con otra biblioteca wolfSSL.

Uso de 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. Normalmente, las aplicaciones deben usar una combinación de las técnicas para crear y comunicarse a través de estas conexiones.

Nota:

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

Inicialización de wolfSSL para conexiones TLS de cliente

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

Carga del certificado

Después de inicializar wolfSSL, puede cargar un certificado para usarlo con la conexión TLS. Puede incluir el certificado en el paquete de imágenes de aplicación, como se describe en Agregar certificados de CA al paquete de imágenes.

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 imágenes de aplicación y, a continuación, llamar 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;
    }

Creación de una conexión del lado cliente

Después de cargar el certificado, la aplicación puede establecer la conexión TLS. Este paso implica crear un objeto SSL, asociarlo con un descriptor de socket y, a continuación, crear 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 desde 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: Solicitud (w3.org) proporciona una buena introducción a 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 reemplazo RFC 9110: 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);

Inicialización de wolfSSL para conexiones del lado servidor

Para crear un servidor TLS con wolfSSL, la aplicación debe inicializar primero 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 mediante el servidor TLS wolfSSL

Acepte conexiones entrantes de un cliente al servidor de 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 haya terminado de usar la conexión, debe liberar los recursos relacionados.

    free(certificatePath);

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

Ejemplo

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

Compartir a través de