DTLS server example making use of wolfHSM by JacobBarthelmeh · Pull Request #561 · wolfSSL/wolfssl-examples

JacobBarthelmeh · 2026-02-27T23:08:04Z

No description provided.

Copilot

Pull request overview

Adds a DTLS server demo that offloads wolfSSL cryptography to a wolfHSM server (POSIX shared-memory transport, optional DMA).

Changes:

Introduces a DTLS server implementation (server.c, server_io.c) and a small protocol-agnostic server API (server.h).
Adds demo-specific wolfSSL/wolfHSM build configuration headers under config/.
Adds build/run automation (Makefile) and usage documentation (README).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
hsm/dtls_server/server_io.c	Implements DTLS socket + wolfSSL context/handshake + read/write helpers using wolfHSM device ID.
hsm/dtls_server/server.h	Declares a small server API and configuration struct for the demo.
hsm/dtls_server/server.c	Demo main program: connects to wolfHSM server, registers crypto callbacks, runs DTLS echo server.
hsm/dtls_server/config/wolfhsm_cfg.h	wolfHSM client configuration for the demo (POSIX time, client enablement, etc.).
hsm/dtls_server/config/user_settings.h	wolfSSL feature configuration for DTLS 1.3 + crypto callback operation.
hsm/dtls_server/README.md	Build/run instructions and architecture overview for the demo.
hsm/dtls_server/Makefile	One-command build of wolfSSL, wolfHSM server, and the DTLS server demo; run helpers.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-27T23:14:15Z

hsm/dtls_server/Makefile

+FILENAMES_C = $(notdir $(SRC_C))
+OBJS_C = $(addprefix $(BUILD_DIR)/, $(FILENAMES_C:.c=.o))
+vpath %.c $(dir $(SRC_C))


Building objects into a single directory using only $(notdir ...) risks object-name collisions (same basename from different directories), which can silently overwrite .o files and produce incorrect binaries. Use unique object paths (e.g., mirror source directories under Build/, or encode the source path into the object filename) so every source compiles to a distinct object file.

Copilot · 2026-02-27T23:14:15Z

hsm/dtls_server/server_io.c

+        fprintf(stderr, "wolfSSL_accept failed: error = %d, %s\n", err,
+                wolfSSL_ERR_reason_error_string(err));


wolfSSL_get_error() returns a wolfSSL I/O/error category (e.g., WOLFSSL_ERROR_WANT_READ, WOLFSSL_ERROR_SSL), but wolfSSL_ERR_reason_error_string() expects an entry from the wolfSSL error queue (from wolfSSL_ERR_get_error()), so the printed reason will be wrong or NULL. Consider printing the wolfSSL_get_error() code as-is, and separately drain/print the error queue via wolfSSL_ERR_get_error() (or use the appropriate wolfSSL error-string API for the returned code).

Suggested change

fprintf(stderr, "wolfSSL_accept failed: error = %d, %s\n", err,

wolfSSL_ERR_reason_error_string(err));

fprintf(stderr, "wolfSSL_accept failed: error = %d\n", err);

/* Drain and print wolfSSL error queue for more detailed info */

for (;;) {

unsigned long queueErr = wolfSSL_ERR_get_error();

if (queueErr == 0) {

break;

}

{

const char* reason = wolfSSL_ERR_reason_error_string(queueErr);

fprintf(stderr, " wolfSSL error queue: code = %lu, reason = %s\n",

queueErr, (reason != NULL) ? reason : "unknown");

}

}

Copilot · 2026-02-27T23:14:15Z

hsm/dtls_server/server_io.c

+    ret = wolfSSL_read(ctx->ssl, data, (int)length);
+    if (ret < 0) {
+        int err = wolfSSL_get_error(ctx->ssl, ret);
+        if (err != WOLFSSL_ERROR_WANT_READ) {
+            fprintf(stderr, "wolfSSL_read failed: error = %d, %s\n", err,
+                    wolfSSL_ERR_reason_error_string(err));
+        }
+        return -1;
+    }


For DTLS/TLS, wolfSSL_read() can legitimately return WOLFSSL_ERROR_WANT_READ (and wolfSSL_write() can return WANT_WRITE) without indicating a fatal error. Returning -1 here will cause the caller to treat a retryable condition as a hard failure/disconnect. Propagate retryable errors distinctly (e.g., return 0, or map WANT_READ/WANT_WRITE to a specific non-fatal return code) and only return -1 for non-retryable errors.

Copilot · 2026-02-27T23:14:16Z

hsm/dtls_server/server.c

+    /* Initialize transport context */
+    memset(&g_shm_client_ctx, 0, sizeof(g_shm_client_ctx));
+    memset(&g_comm_config, 0, sizeof(g_comm_config));
+    memset(&g_client_config, 0, sizeof(g_client_config));
+
+    /* Configure shared memory transport with DMA */
+    g_shm_config.name = WH_POSIX_SHARED_MEMORY_NAME;
+    g_shm_config.req_size = WH_POSIX_REQ_SIZE;
+    g_shm_config.resp_size = WH_POSIX_RESP_SIZE;
+    g_shm_config.dma_size = WH_POSIX_DMA_SIZE;


g_shm_config is written without being zero-initialized. If posixTransportShmConfig contains additional fields beyond those explicitly assigned here, they may contain indeterminate values and break transport initialization. Add memset(&g_shm_config, 0, sizeof(g_shm_config)); before populating its fields.

Copilot · 2026-02-27T23:14:16Z

hsm/dtls_server/server_io.c

+    /* Enable debug output */
+    wolfSSL_Debugging_ON();


Enabling wolfSSL debugging unconditionally can leak sensitive operational details into logs and is risky outside local dev. Gate this behind a build-time flag (e.g., DEBUG/WOLFHSM_CFG_DEBUG) or a runtime option, and keep debugging disabled by default.

Suggested change

/* Enable debug output */

wolfSSL_Debugging_ON();

/* Enable debug output (only when explicitly enabled at build time) */

#ifdef WOLFHSM_CFG_DEBUG

wolfSSL_Debugging_ON();

#endif

Copilot · 2026-02-27T23:14:17Z

hsm/dtls_server/README.md

+
+```bash
+# Build the server
+cd examples/demo/dtls_server


The README paths don’t match this PR’s directory layout (hsm/dtls_server/...), which will cause copy/paste build/run steps to fail. Update the cd ... instructions to the correct location for this demo, and fix the double-space typo in 'using wolfssl'.

Suggested change

cd examples/demo/dtls_server

cd hsm/dtls_server

Copilot · 2026-02-27T23:14:17Z

hsm/dtls_server/README.md

+make
+
+# Build the wolfHSM POSIX server (if not already built)
+cd ../../posix/wh_posix_server


The README paths don’t match this PR’s directory layout (hsm/dtls_server/...), which will cause copy/paste build/run steps to fail. Update the cd ... instructions to the correct location for this demo, and fix the double-space typo in 'using wolfssl'.

Copilot · 2026-02-27T23:14:17Z

hsm/dtls_server/README.md

+In a new terminal:
+
+```bash
+cd examples/demo/dtls_server


The README paths don’t match this PR’s directory layout (hsm/dtls_server/...), which will cause copy/paste build/run steps to fail. Update the cd ... instructions to the correct location for this demo, and fix the double-space typo in 'using wolfssl'.

Copilot · 2026-02-27T23:14:17Z

hsm/dtls_server/README.md

+In a third terminal:
+
+```bash
+# For DTLS (default mode) - using  wolfssl with DTLS 1.3


The README paths don’t match this PR’s directory layout (hsm/dtls_server/...), which will cause copy/paste build/run steps to fail. Update the cd ... instructions to the correct location for this demo, and fix the double-space typo in 'using wolfssl'.

Suggested change

# For DTLS (default mode) - using wolfssl with DTLS 1.3

# For DTLS (default mode) - using wolfssl with DTLS 1.3

Copilot · 2026-02-27T23:14:18Z

hsm/dtls_server/server_io.c

+    printf("Received initial packet from %s:%d\n",
+           inet_ntoa(ctx->cliaddr.sin_addr),


inet_ntoa() uses a static internal buffer and is not thread-safe. Even if this is a demo, using inet_ntop() avoids that pitfall and is a safer pattern to copy into production code.

Suggested change

printf("Received initial packet from %s:%d\n",

inet_ntoa(ctx->cliaddr.sin_addr),

/* Convert client IP address to string in a thread-safe manner */

char addrStr[INET_ADDRSTRLEN];

const char* addrPrint = inet_ntop(AF_INET, &ctx->cliaddr.sin_addr,

addrStr, sizeof(addrStr));

if (addrPrint == NULL) {

addrPrint = "unknown";

}

printf("Received initial packet from %s:%d\n",

addrPrint,

JacobBarthelmeh added 2 commits February 27, 2026 15:14

add wolfHSM DTLS server demo

8b3c7be

Adjust Makefile to match more with DTLS client example

c4659fb

JacobBarthelmeh self-assigned this Feb 27, 2026

Copilot AI review requested due to automatic review settings February 27, 2026 23:08

JacobBarthelmeh mentioned this pull request Feb 27, 2026

add demo for DTLS server that offloads all crypto to wolfHSM server wolfSSL/wolfHSM#283

Closed

Copilot AI reviewed Feb 27, 2026

View reviewed changes

Copilot started reviewing on behalf of JacobBarthelmeh February 28, 2026 00:13 View session

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DTLS server example making use of wolfHSM#561

DTLS server example making use of wolfHSM#561
JacobBarthelmeh wants to merge 2 commits intowolfSSL:masterfrom
JacobBarthelmeh:hsm

JacobBarthelmeh commented Feb 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Copilot AI Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		fprintf(stderr, "wolfSSL_accept failed: error = %d, %s\n", err,
		wolfSSL_ERR_reason_error_string(err));

-        fprintf(stderr, "wolfSSL_accept failed: error = %d, %s\n", err,
-                wolfSSL_ERR_reason_error_string(err));
+        fprintf(stderr, "wolfSSL_accept failed: error = %d\n", err);
+        /* Drain and print wolfSSL error queue for more detailed info */
+        for (;;) {
+            unsigned long queueErr = wolfSSL_ERR_get_error();
+            if (queueErr == 0) {
+                break;
+            }
+            {
+                const char* reason = wolfSSL_ERR_reason_error_string(queueErr);
+                fprintf(stderr, "  wolfSSL error queue: code = %lu, reason = %s\n",
+                        queueErr, (reason != NULL) ? reason : "unknown");
+            }
+        }

	# For DTLS (default mode) - using wolfssl with DTLS 1.3
	# For DTLS (default mode) - using wolfssl with DTLS 1.3

		printf("Received initial packet from %s:%d\n",
		inet_ntoa(ctx->cliaddr.sin_addr),

-    printf("Received initial packet from %s:%d\n",
-           inet_ntoa(ctx->cliaddr.sin_addr),
+    /* Convert client IP address to string in a thread-safe manner */
+    char addrStr[INET_ADDRSTRLEN];
+    const char* addrPrint = inet_ntop(AF_INET, &ctx->cliaddr.sin_addr,
+                                      addrStr, sizeof(addrStr));
+    if (addrPrint == NULL) {
+        addrPrint = "unknown";
+    }
+    printf("Received initial packet from %s:%d\n",
+           addrPrint,

Conversation

JacobBarthelmeh commented Feb 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants