TLS 연결에 wolfSSL 사용

  • 아티클

Azure Sphere SDK에는 상위 수준 애플리케이션이 보안 TLS 연결을 만드는 데 사용할 수 있는 TLS(전송 계층 보안)를 위한 wolfSSL 라이브러리의 하위 집합이 포함되어 있습니다.

wolfSSL API 참조는 많은 예제와 함께 wolfSSL API에 대한 철저한 설명서를 제공합니다. Azure Sphere는 이진 호환성을 보장하는 API의 하위 집합 을 지원합니다.

wolfSSL 라이브러리를 사용하는 애플리케이션에 대한 요구 사항

wolfSSL 라이브러리를 사용하는 애플리케이션에는 필요한 헤더 파일과 빌드 구성이 포함되어야 합니다.

wolfSSL TLS API에는 애플리케이션 매니페스트의 기능이 필요하지 않습니다. 그러나 애플리케이션이 인터넷 엔드포인트에 연결하는 경우 애플리케이션 매니페스트에는 연결에 대한 정보가 포함되어야 합니다. 연결 사용에 대한 자세한 내용은 웹 서비스에 연결을 참조하세요.

헤더 파일

wolfSSL API를 사용하는 애플리케이션은 헤더 파일을 포함 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 설명서를 참조하세요.

빌드 구성

wolfSSL TLS API 지원을 사용하여 애플리케이션을 빌드하려면 CMakePresets.json 및 CMakeLists.txt 파일을 편집하여 대상 API 집합을 지정하고 wolfSSL 라이브러리를 각각 연결합니다.

  1. CMakePresets.json TARGET_API_SET 6 이상으로 설정합니다.

    "AZURE_SPHERE_TARGET_API_SET": "6"

  2. CMakeLists.txt target_link_libraries 목록에 를 추가하여 wolfssl wolfSSL 라이브러리를 프로젝트에 연결합니다.

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

지원되는 기능

Azure Sphere SDK는 Microsoft에서 제공한 클라이언트 인증서 또는 인증서 또는 선택한 클라이언트 쪽 wolfSSL TLS를 지원합니다. Azure Sphere SDK는 선택한 인증서만 사용하여 서버 쪽 wolfSSL TLS를 지원합니다. 지원되지 않는 주목할 만한 시나리오는 다음과 같습니다.

  • microsoft에서 제공하는 클라이언트 인증서에서는 wolfSSL 클라이언트 쪽 TLS 연결만 지원됩니다. 서버 쪽 TLS 연결은 Microsoft에서 제공하는 클라이언트 인증서를 사용할 수 없습니다.

  • 애플리케이션은 기본 제공 wolfSSL TLS 지원을 사용하거나 다른 wolfSSL 라이브러리 구현에서 및 링크를 사용할 수 있습니다. 그러나 다른 wolfSSL 라이브러리와 함께 기본 제공 지원의 혼합 사용은 지원되지 않습니다.

Azure Sphere에서 wolfSSL 사용

상위 수준 Azure Sphere 애플리케이션은 wolfSSL을 사용하여 TLS 연결을 통해 만들고 통신할 수 있습니다. 애플리케이션은 일반적으로 이러한 연결을 만들고 통신하기 위해 기술의 조합을 사용해야 합니다.

참고

보안 강화를 위해 애플리케이션은 wolfSSL_CTX_set_verify()를 사용하여 호스트의 유효성을 검사해야 합니다. 자세한 내용은 wolfSSL 설명서를 참조하세요.

클라이언트 TLS 연결에 대한 wolfSSL 초기화

wolfSSL을 사용하여 TLS 연결을 만들려면 애플리케이션은 먼저 다음 코드 조각과 같이 라이브러리 및 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 연결에 사용할 인증서를 로드할 수 있습니다. 이미지 패키지에 CA 인증서 추가에 설명된 대로 애플리케이션 이미지 패키지에 인증서를 포함할 수 있습니다.

다음 예제에서는 앱이 Storage_GetAbsolutePathInImagePackage 사용하여 애플리케이션 이미지 패키지의 일부인 클라이언트 인증서의 경로를 가져와 서 wolfSSL_CTX_load_verify_locations 호출하여 인증서를 wolfSSL에 로드하는 방법을 보여 줍니다. 앱은 Storage_GetAbsolutePathInImagePackage 사용할 헤더 파일을 포함 storage.h 해야 합니다.

   #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 초기화

wolfSSL을 사용하여 TLS 서버를 만들려면 애플리케이션은 먼저 다음 코드 조각과 같이 라이브러리 및 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;
    }

wolfSSL TLS 서버를 사용하여 들어오는 연결 허용

클라이언트에서 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();
    }

샘플

Azure Sphere 플랫폼의 WolfSSL 기능 샘플은 WolfSSL_HighLevelApp 참조하세요.