Skip to content

Commit 8b3c7be

Browse files
JacobBarthelmehJacobBarthelmeh
committed
add wolfHSM DTLS server demo
1 parent f2dec15 commit 8b3c7be

7 files changed

Lines changed: 1332 additions & 0 deletions

File tree

‎hsm/dtls_server/Makefile‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
## Makefile for TLS/DTLS Server using wolfHSM for crypto operations
2+
##
3+
## This example demonstrates a server that offloads all cryptographic
4+
## operations to a wolfHSM server running on the POSIX transport with
5+
## DMA support. By default, DTLS (UDP) mode is used.
6+
##
7+
## Usage:
8+
## 1. Build: make DEBUG=1
9+
## 2. Start the wolfHSM server: cd ../../posix/wh_posix_server && ./Build/wh_posix_server.elf --type dma
10+
## 3. Run this server: ./Build/wh_server.elf
11+
## 4. Connect with a client
12+
13+
## Project name - sets output filename
14+
BIN = wh_server
15+
16+
## Important directories
17+
PROJECT_DIR ?= .
18+
CONFIG_DIR ?= $(PROJECT_DIR)/config
19+
20+
# wolfSSL and wolfHSM directories (relative to this Makefile)
21+
WOLFSSL_DIR ?= ../../../../wolfssl
22+
WOLFHSM_DIR ?= ../../..
23+
WOLFHSM_PORT_DIR ?= $(WOLFHSM_DIR)/port/posix
24+
25+
# Output directory for build files
26+
BUILD_DIR ?= $(PROJECT_DIR)/Build
27+
28+
## Includes
29+
INC = -I$(PROJECT_DIR) \
30+
-I$(CONFIG_DIR) \
31+
-I$(WOLFSSL_DIR) \
32+
-I$(WOLFHSM_DIR) \
33+
-I$(WOLFHSM_PORT_DIR)
34+
35+
## Defines
36+
# POSIX requires C source be defined before any header
37+
DEF += -D_POSIX_C_SOURCE=200809L
38+
39+
# Library configuration defines for user-supplied settings
40+
DEF += -DWOLFSSL_USER_SETTINGS -DWOLFHSM_CFG
41+
42+
# Enable DMA transport by default (matches server --type dma)
43+
DEF += -DWOLFHSM_CFG_DMA
44+
45+
## Architecture flags
46+
ARCHFLAGS ?=
47+
48+
## Compiler and linker flags
49+
ASFLAGS ?= $(ARCHFLAGS)
50+
CFLAGS_EXTRA ?= -Wextra
51+
CFLAGS ?= $(ARCHFLAGS) -Wno-cpp -std=c99 -Wall -Werror $(CFLAGS_EXTRA)
52+
LDFLAGS ?= $(ARCHFLAGS)
53+
LIBS = -lc -lm
54+
55+
# Platform-specific linker flags for dead code stripping
56+
OS_NAME := $(shell uname -s | tr A-Z a-z)
57+
ifeq ($(OS_NAME),darwin)
58+
LDFLAGS += -Wl,-dead_strip
59+
else
60+
LDFLAGS += -Wl,--gc-sections
61+
endif
62+
63+
## Makefile options
64+
65+
# Set to @ to suppress command echo
66+
CMD_ECHO ?=
67+
68+
# Debug build
69+
ifeq ($(DEBUG),1)
70+
DBGFLAGS = -ggdb -g3 -O0
71+
CFLAGS += $(DBGFLAGS)
72+
LDFLAGS += $(DBGFLAGS)
73+
DEF += -DWOLFHSM_CFG_DEBUG
74+
endif
75+
76+
# Verbose debug output
77+
ifeq ($(DEBUG_VERBOSE),1)
78+
DBGFLAGS = -ggdb -g3 -O0
79+
CFLAGS += $(DBGFLAGS)
80+
LDFLAGS += $(DBGFLAGS)
81+
DEF += -DWOLFHSM_CFG_DEBUG -DWOLFHSM_CFG_DEBUG_VERBOSE
82+
endif
83+
84+
# Address sanitizer
85+
ifeq ($(ASAN),1)
86+
CFLAGS += -fsanitize=address
87+
LDFLAGS += -fsanitize=address
88+
endif
89+
90+
## Source files
91+
92+
# wolfCrypt source files
93+
SRC_C += $(wildcard $(WOLFSSL_DIR)/wolfcrypt/src/*.c)
94+
95+
# wolfSSL TLS source files
96+
SRC_C += $(wildcard $(WOLFSSL_DIR)/src/*.c)
97+
98+
# wolfHSM source files
99+
SRC_C += $(wildcard $(WOLFHSM_DIR)/src/*.c)
100+
101+
# wolfHSM POSIX port/HAL code
102+
SRC_C += $(wildcard $(WOLFHSM_PORT_DIR)/*.c)
103+
104+
# Project source files
105+
SRC_C += $(PROJECT_DIR)/server.c
106+
SRC_C += $(PROJECT_DIR)/server_io.c
107+
108+
## Automated processing
109+
110+
FILENAMES_C = $(notdir $(SRC_C))
111+
OBJS_C = $(addprefix $(BUILD_DIR)/, $(FILENAMES_C:.c=.o))
112+
vpath %.c $(dir $(SRC_C))
113+
114+
## Makefile Targets
115+
116+
.PHONY: all build clean help
117+
118+
all: build
119+
120+
build: $(BUILD_DIR) $(BUILD_DIR)/$(BIN).elf
121+
122+
$(BUILD_DIR):
123+
$(CMD_ECHO) mkdir -p $(BUILD_DIR)
124+
125+
$(BUILD_DIR)/%.o: %.c
126+
@echo "Compiling: $(notdir $<)"
127+
$(CMD_ECHO) $(CC) $(CFLAGS) $(DEF) $(INC) -c -o $@ $<
128+
129+
$(BUILD_DIR)/$(BIN).elf: $(OBJS_C)
130+
@echo "Linking: $(notdir $@)"
131+
$(CMD_ECHO) $(CC) $(LDFLAGS) -o $@ $^ $(LIBS)
132+
133+
clean:
134+
@echo "Cleaning build files..."
135+
@rm -rf $(BUILD_DIR)
136+
137+
help:
138+
@echo "TLS/DTLS Server with wolfHSM Crypto Offload"
139+
@echo ""
140+
@echo "Options:"
141+
@echo " DEBUG=1 - Enable debug build with symbols"
142+
@echo " DEBUG_VERBOSE=1 - Enable verbose debug output"
143+
@echo " ASAN=1 - Enable address sanitizer"
144+
@echo ""
145+
@echo "Example:"
146+
@echo " make DEBUG=1"

‎hsm/dtls_server/README.md‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# TLS/DTLS Server with wolfHSM Crypto Offload
2+
3+
This example demonstrates a TLS/DTLS server that offloads cryptographic
4+
operations to a wolfHSM server. By default, DTLS (UDP-based) is used, but
5+
the code can be adapted for TLS (TCP-based) connections.
6+
7+
The wolfHSM server runs separately and communicates via the chosen transport.
8+
9+
## Architecture
10+
11+
```
12+
+-------------------+ Shared Memory (DMA) +-------------------+
13+
| | <-----------------------------> | |
14+
| TLS/DTLS Server | Crypto Operations Request | wolfHSM Server |
15+
| (This Example) | <-----------------------------> | (wh_posix_server)|
16+
| | Crypto Operations Response | |
17+
+-------------------+ +-------------------+
18+
| |
19+
| TLS/DTLS | Performs all
20+
| | crypto ops:
21+
v | - Key Exchange
22+
+-------------------+ | - Signing
23+
| TLS/DTLS Client | | - Encryption
24+
| | | - Hashing
25+
+-------------------+ +
26+
```
27+
28+
## How It Works
29+
30+
1. **wolfHSM Server**: The `wh_posix_server` runs with `--type dma` to provide
31+
crypto services over shared memory with DMA support.
32+
33+
2. **TLS/DTLS Server**: This example connects to the wolfHSM server as a client
34+
and registers a crypto callback. All wolfSSL/wolfCrypt operations are
35+
forwarded to the HSM.
36+
37+
3. **Crypto Offload**: When `wolfSSL_CTX_SetDevId()` is called with `WH_DEV_ID`,
38+
wolfSSL routes crypto operations through the registered callback to the
39+
wolfHSM server.
40+
41+
## Building
42+
43+
### Prerequisites
44+
45+
1. wolfSSL library built with crypto callback support
46+
2. wolfHSM library with POSIX port
47+
48+
### Build Steps
49+
50+
```bash
51+
# Build the server
52+
cd examples/demo/dtls_server
53+
make
54+
55+
# Build the wolfHSM POSIX server (if not already built)
56+
cd ../../posix/wh_posix_server
57+
make DMA=1
58+
```
59+
60+
## Running
61+
62+
### Step 1: Start the wolfHSM Server
63+
64+
```bash
65+
cd examples/posix/wh_posix_server
66+
./Build/wh_posix_server.elf --type dma
67+
```
68+
69+
You should see:
70+
```
71+
Example wolfHSM POSIX server built with wolfSSL version X.X.X
72+
Using DMA with shared memory transport
73+
Waiting for connection...
74+
```
75+
76+
### Step 2: Start the Server
77+
78+
In a new terminal:
79+
80+
```bash
81+
cd examples/demo/dtls_server
82+
./Build/wh_server.elf
83+
```
84+
85+
#### Command-Line Options
86+
87+
```
88+
Usage: ./Build/wh_server.elf [options]
89+
90+
Options:
91+
-A <file> CA certificate file (PEM or DER format)
92+
If not specified, uses built-in test certificate
93+
-c <file> Server certificate file (PEM or DER format)
94+
-k <file> Server private key file (PEM or DER format)
95+
-p <port> Port to listen on (default: 11111)
96+
-h Show this help message
97+
```
98+
99+
#### Examples
100+
101+
```bash
102+
# Use default built-in certificates
103+
./Build/wh_server.elf
104+
105+
# Use client-cert.pem from wolfssl bundle for example client to connect
106+
./Build/wh_server.elf -A /path/to/wolfssl/certs/client-cert.pem
107+
108+
# Use custom certificates and port
109+
./Build/wh_server.elf -A ca.pem -c server.pem -k server-key.pem -p 4433
110+
```
111+
112+
You should see:
113+
```
114+
DTLS server starting on port 11111...
115+
Connected to wolfHSM server successfully
116+
Waiting for client on port 11111...
117+
```
118+
119+
### Step 3: Connect a Client
120+
121+
In a third terminal:
122+
123+
```bash
124+
# For DTLS (default mode) - using wolfssl with DTLS 1.3
125+
./examples/examples/client -u -v 4
126+
```
127+
128+
## Key Integration Points
129+
130+
### 1. Registering Crypto Callbacks
131+
132+
In `server.c`, we register the wolfHSM crypto callbacks:
133+
134+
```c
135+
/* Register crypto callback for non-DMA operations */
136+
wc_CryptoCb_RegisterDevice(WH_DEV_ID, wh_Client_CryptoCb, (void*)g_client);
137+
138+
/* Register crypto callback for DMA operations (larger data) */
139+
wc_CryptoCb_RegisterDevice(WH_DEV_ID_DMA, wh_Client_CryptoCbDma, (void*)g_client);
140+
```
141+
142+
### 2. Setting Device ID on wolfSSL Object
143+
144+
In `server_io.c`, we configure wolfSSL to use the HSM on the WOLFSSL_CTX object:
145+
146+
```c
147+
wolfSSL_CTX_SetDevId(ctx, WH_DEV_ID);
148+
```
149+
150+
### 3. DMA vs Non-DMA
151+
152+
- **WH_DEV_ID**: Uses standard message-based crypto operations. Suitable for
153+
smaller data sizes.
154+
155+
- **WH_DEV_ID_DMA**: Uses DMA (Direct Memory Access) for data transfer.
156+
More efficient for larger data like TLS record encryption.
157+
158+
## Configuration
159+
160+
### wolfSSL Configuration (`config/user_settings.h`)
161+
162+
Key settings for TLS/DTLS with wolfHSM:
163+
164+
```c
165+
/* Enable DTLS 1.3 (for UDP mode) */
166+
#define WOLFSSL_DTLS
167+
#define WOLFSSL_DTLS13
168+
#define WOLFSSL_TLS13
169+
170+
/* Enable crypto callbacks for wolfHSM */
171+
#define WOLF_CRYPTO_CB
172+
173+
/* Hash DRBG for RNG */
174+
#define HAVE_HASHDRBG
175+
```
176+
177+
### wolfHSM Configuration (`config/wolfhsm_cfg.h`)
178+
179+
Key settings for wolfHSM client:
180+
181+
```c
182+
/* Enable wolfHSM client */
183+
#define WOLFHSM_CFG_ENABLE_CLIENT
184+
185+
/* Enable DMA transport */
186+
#define WOLFHSM_CFG_DMA
187+
```
188+
189+
## Troubleshooting
190+
191+
### "Failed to connect to wolfHSM server"
192+
193+
Make sure the `wh_posix_server` is running with `--type dma` before starting
194+
the DTLS server.
195+
196+
### Handshake Failures
197+
198+
1. Check that both the wolfHSM server and DTLS server are built with the same
199+
wolfSSL version.
200+
201+
2. Verify the shared memory name matches between client and server
202+
(default: "wh_example_shm").
203+
204+
3. Enable verbose debugging:
205+
```bash
206+
make DEBUG_VERBOSE=1
207+
```
208+
209+
## Adapting for TLS
210+
211+
To use TLS instead of DTLS:
212+
213+
1. In `server_io.c`, change the method from `wolfDTLS_server_method()` to
214+
`wolfTLSv1_3_server_method()` or another TLS method.
215+
216+
2. Change the socket initialization from UDP to TCP (replace
217+
`initialize_udp_socket()` with a TCP equivalent).
218+
219+
3. Remove the DTLS-specific peer address setup in `setup_ssl_accept()`.

0 commit comments

Comments
 (0)