wolfHSM: add DTLS client example that uses HSM as cryptographic back end

README.md

@@ -379,6 +379,16 @@ Please see the [utasker/README.md](utasker/README.md) for further usage and
 details.
 
 
+<br />
+
+#### HSM (Hardware Security Module)
+
+This directory contains examples demonstrating wolfSSL integration with wolfHSM,
+a portable Hardware Security Module framework.
+
+Please see the [wolfhsm/README.md](wolfhsm/README.md) for further details.
+
+
 <br />
 
 #### UEFI (wolfCrypt UEFI application Example)

hsm/README.md

@@ -0,0 +1,23 @@
+# wolfHSM Examples
+
+Examples demonstrating wolfSSL integration with [wolfHSM](https://github.com/wolfssl/wolfhsm),
+a portable Hardware Security Module (HSM) framework.
+
+## Examples
+
+### DTLS Client (`dtls_client/`)
+
+DTLS client with HSM-backed cryptography. Private keys stay on the HSM.
+
+Quick start:
+```bash
+cd dtls_client
+make download_repos all
+# Then run each component in separate terminals (see README)
+```
+
+See [dtls_client/README.md](dtls_client/README.md) for details.
+
+## Support
+
+For questions please email [email protected]

hsm/dtls_client/Makefile

@@ -0,0 +1,166 @@
+# wolfHSM DTLS Client Example
+#
+# Usage:
+#   make download_repos    # Clone wolfSSL and wolfHSM repos
+#   make all               # Build everything (wolfSSL server, wolfHSM server, client)
+#   make run_hsm_server    # Start wolfHSM server
+#   make run_dtls_server   # Start wolfSSL DTLS server
+#   make run_client        # Run the DTLS client
+#   make clean             # Clean build artifacts
+#   make clean_repos       # Remove cloned repositories
+
+BIN = wh_dtls_client
+
+WOLFSSL_DIR ?= ./wolfssl
+WOLFHSM_DIR ?= ./wolfhsm
+WOLFHSM_PORT_DIR = $(WOLFHSM_DIR)/port/posix
+WOLFHSM_SERVER_DIR = $(WOLFHSM_DIR)/examples/posix/wh_posix_server
+
+PROJECT_DIR = .
+BUILD_DIR = $(PROJECT_DIR)/Build
+
+# Compiler settings
+CC = gcc
+CSTD = -std=c99
+CFLAGS_EXTRA = -Werror -Wall -Wextra -ffunction-sections -fdata-sections
+CFLAGS = $(CSTD) $(CFLAGS_EXTRA)
+DEF = -D_POSIX_C_SOURCE=200809L -DWOLFSSL_USER_SETTINGS -DWOLFHSM_CFG
+DEF += -DWC_USE_DEVID=0x5748534D
+
+INC = -I$(PROJECT_DIR) -I$(WOLFSSL_DIR) -I$(WOLFHSM_DIR) -I$(WOLFHSM_PORT_DIR)
+
+# Linker settings
+LDFLAGS = -Wl,--gc-sections
+LIBS = -lc -lm
+
+# Source files (wolfCrypt, wolfSSL, wolfHSM, port, project)
+WOLFCRYPT_SRC := $(wildcard $(WOLFSSL_DIR)/wolfcrypt/src/*.c)
+SRC_C = $(filter-out %/evp.c %/misc.c,$(WOLFCRYPT_SRC))
+WOLFSSL_SRC := $(wildcard $(WOLFSSL_DIR)/src/*.c)
+SRC_C += $(filter-out %/bio.c %/conf.c %/pk.c %/ssl_asn1.c %/ssl_bn.c %/ssl_certman.c %/ssl_crypto.c %/ssl_load.c %/ssl_misc.c %/ssl_p7p12.c %/ssl_sess.c %/ssl_sk.c %/x509.c %/x509_str.c,$(WOLFSSL_SRC))
+SRC_C += $(wildcard $(WOLFHSM_DIR)/src/*.c)
+SRC_C += $(wildcard $(WOLFHSM_PORT_DIR)/*.c)
+SRC_C += $(wildcard $(PROJECT_DIR)/*.c)
+
+# Debug support
+ifeq ($(DEBUG),1)
+    CFLAGS += -ggdb -g3
+    LDFLAGS += -ggdb -g3
+    DEF += -DWOLFHSM_CFG_DEBUG
+endif
+
+# Object files
+FILENAMES_C = $(notdir $(SRC_C))
+OBJS_C = $(addprefix $(BUILD_DIR)/, $(FILENAMES_C:.c=.o))
+vpath %.c $(dir $(SRC_C))
+
+# Phony targets
+.PHONY: all download_repos build_wolfssl build_wolfhsm_server build_app run_hsm_server run_dtls_server run_client clean clean_repos
+
+# Default target
+all: check_repos build_wolfssl build_wolfhsm_server build_app
+	@echo "Build complete. Run 'make help' for usage instructions."
+
+# Clone repositories
+download_repos:
+	@echo "=== Cloning repositories ==="
+	@if [ ! -d "$(WOLFSSL_DIR)" ]; then \
+		git clone --depth 1 https://github.com/wolfssl/wolfssl.git $(WOLFSSL_DIR); \
+	else \
+		echo "wolfssl already exists, skipping clone"; \
+	fi
+	@if [ ! -d "$(WOLFHSM_DIR)" ]; then \
+		git clone --depth 1 https://github.com/wolfssl/wolfhsm.git $(WOLFHSM_DIR); \
+	else \
+		echo "wolfhsm already exists, skipping clone"; \
+	fi
+
+# Check that repos exist
+check_repos:
+	@if [ ! -d "$(WOLFSSL_DIR)" ] || [ ! -d "$(WOLFHSM_DIR)" ]; then \
+		echo "Error: Repositories not found. Run 'make download_repos' first."; \
+		exit 1; \
+	fi
+
+# Build wolfSSL
+# Note: The DTLS client uses its own user_settings.h to build wolfSSL statically,
+# so this configure is only for the wolfSSL example server/client binaries.
+build_wolfssl: check_repos
+	@echo "=== Building wolfSSL ==="
+	@if [ ! -f "$(WOLFSSL_DIR)/examples/server/server" ]; then \
+		cd $(WOLFSSL_DIR) && \
+		./autogen.sh && \
+		./configure --enable-dtls --enable-dtls13 --enable-ecc && \
+		make -j; \
+	else \
+		echo "wolfSSL already built, skipping"; \
+	fi
+
+# Build wolfHSM POSIX server
+# Note: The wolfHSM server Makefile expects WOLFSSL_DIR relative to its location
+# Server is at ./wolfhsm/examples/posix/wh_posix_server/
+# wolfssl is at ./wolfssl/
+# So from server: ../../../../wolfssl
+build_wolfhsm_server: check_repos
+	@echo "=== Building wolfHSM server ==="
+	@if [ ! -f "$(WOLFHSM_SERVER_DIR)/Build/wh_posix_server.elf" ]; then \
+		$(MAKE) -C $(WOLFHSM_SERVER_DIR) clean || true; \
+		$(MAKE) -C $(WOLFHSM_SERVER_DIR) WOLFSSL_DIR=../../../../wolfssl -j; \
+	else \
+		echo "wolfHSM server already built, skipping"; \
+	fi
+
+# Build DTLS client
+build_app: $(BUILD_DIR) $(BUILD_DIR)/$(BIN).elf
+	@echo "DTLS client built: $(BUILD_DIR)/$(BIN).elf"
+
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+$(BUILD_DIR)/%.o: %.c
+	@echo "Compiling: $(notdir $<)"
+	$(CC) $(CFLAGS) $(DEF) $(INC) -c -o $@ $<
+
+$(BUILD_DIR)/$(BIN).elf: $(OBJS_C)
+	@echo "Linking: $(notdir $@)"
+	$(CC) $(LDFLAGS) -o $@ $^ $(LIBS)
+
+# Convenience targets for running each component in separate terminals
+
+run_hsm_server: all
+	@echo "Starting wolfHSM server..."
+	@echo "Press Ctrl+C to stop"
+	@echo ""
+	$(WOLFHSM_SERVER_DIR)/Build/wh_posix_server.elf --type tcp \
+		--key $(WOLFSSL_DIR)/certs/ecc-client-key.der \
+		--id 1 --client 12
+
+run_dtls_server: all
+	@echo "Starting wolfSSL DTLS server..."
+	@echo "Press Ctrl+C to stop"
+	@echo ""
+	cd $(WOLFSSL_DIR) && ./examples/server/server -u -v 4 \
+		-c ./certs/server-ecc.pem \
+		-k ./certs/ecc-key.pem \
+		-A ./certs/client-ecc-cert.pem \
+		-p 11111 -i
+
+run_client: all
+	$(BUILD_DIR)/$(BIN).elf 127.0.0.1
+
+# Clean build artifacts
+clean:
+	@echo "Cleaning build files"
+	rm -rf $(BUILD_DIR)
+	@# Clean wolfHSM server build
+	@if [ -d "$(WOLFHSM_SERVER_DIR)" ]; then \
+		$(MAKE) -C $(WOLFHSM_SERVER_DIR) clean 2>/dev/null || true; \
+	fi
+	@# Clean wolfSSL build
+	@if [ -f "$(WOLFSSL_DIR)/Makefile" ]; then \
+		$(MAKE) -C $(WOLFSSL_DIR) clean 2>/dev/null || true; \
+	fi
+
+clean_repos: clean
+	@echo "Removing cloned repositories"
+	rm -rf $(WOLFSSL_DIR) $(WOLFHSM_DIR)

hsm/dtls_client/README.md

@@ -0,0 +1,73 @@
+# wolfHSM DTLS Client Example
+
+Demonstrates a DTLS client using wolfHSM for cryptographic operations.
+All private key operations are performed on the HSM - keys never leave
+the secure environment.
+The example uses wolfHSM posix server for HSM communication/simulation.
+
+
+## Quick Start
+
+### Build
+```bash
+make download_repos   # Clone repos (first time only)
+make all              # Build everything
+```
+
+### Run (3 separate terminals)
+
+**Terminal 1** - Start wolfHSM posix server:
+```bash
+make run_hsm_server
+```
+
+**Terminal 2** - Start DTLS server:
+```bash
+make run_dtls_server
+```
+
+**Terminal 3** - Run client:
+```bash
+make run_client
+```
+
+## Using Existing Repositories
+
+```bash
+make WOLFSSL_DIR=/path/to/wolfssl WOLFHSM_DIR=/path/to/wolfhsm all
+```
+
+## Architecture
+
+```
++------------------+     TCP      +------------------+
+|  DTLS Client     |<------------>|  wolfHSM Server  |
+|                  |              |  (crypto ops)    |
++--------+---------+              +------------------+
+         | UDP/DTLS
+         v
++------------------+
+|  DTLS Server     |
+|  (application)   |
++------------------+
+```
+
+## Makefile Targets
+
+| Target | Description |
+|--------|-------------|
+| `download_repos` | Clone wolfSSL and wolfHSM |
+| `all` | Build everything (default) |
+| `run_hsm_server` | Start wolfHSM server (Terminal 1) |
+| `run_dtls_server` | Start wolfSSL DTLS server (Terminal 2) |
+| `run_client` | Run the DTLS client (Terminal 3) |
+| `clean` | Clean build artifacts |
+| `clean_repos` | Remove cloned repositories |
+| `help` | Show help |
+
+## Debug Build
+
+```bash
+make clean
+make DEBUG=1
+```

hsm/dtls_client/user_settings.h

@@ -0,0 +1,52 @@
+#ifndef USER_SETTINGS_H_
+#define USER_SETTINGS_H_
+
+
+/* POSIX system headers */
+#define HAVE_SYS_TIME_H
+
+/** wolfHSM Client required settings */
+/* CryptoCB support - required for offloading crypto to HSM */
+#define WOLF_CRYPTO_CB
+#define HAVE_ANONYMOUS_INLINE_AGGREGATES 1
+
+/* PK callbacks - required for TLS-level HSM key operations */
+#define HAVE_PK_CALLBACKS
+
+/* Enable DTLS support */
+#define WOLFSSL_DTLS
+#define WOLFSSL_DTLS13
+#define WOLFSSL_TLS13
+#define HAVE_TLS_EXTENSIONS
+#define WOLFSSL_SEND_HRR_COOKIE
+
+/* Remove old TLS versions */
+#define NO_OLD_TLS
+
+/** Crypto Algorithm Options */
+
+/* ECC for ECDHE key exchange and ECDSA authentication */
+#define HAVE_ECC
+#define HAVE_SUPPORTED_CURVES
+
+/* AES-GCM for symmetric encryption */
+#define HAVE_AESGCM
+
+/* HKDF for key derivation */
+#define HAVE_HKDF
+
+/* Timing resistance / side-channel attack protection */
+#define TFM_TIMING_RESISTANT
+#define ECC_TIMING_RESISTANT
+#define WC_RSA_BLINDING
+
+/* Use wolfSSL's internal string comparison instead of system strcasecmp */
+#define USE_WOLF_STRCASECMP
+
+/* Remove unneeded features */
+#define NO_MAIN_DRIVER
+#define NO_DO178
+#define NO_RSA
+#define NO_DH
+
+#endif /* USER_SETTINGS_H_ */