Skip to content

Commit 7f9ed6e

Browse files
JacobBarthelmehJacobBarthelmeh
committed
add demo for DTLS server that offloads all crypto to wolfHSM server
1 parent 4e1a7d4 commit 7f9ed6e

7 files changed

Lines changed: 1332 additions & 0 deletions

File tree

‎examples/demo/dtls_server/Makefile‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
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+
54+
# Platform-specific linker flags for dead code stripping
55+
OS_NAME := $(shell uname -s | tr A-Z a-z)
56+
ifeq ($(OS_NAME),darwin)
57+
LDFLAGS += -Wl,-dead_strip
58+
else
59+
LDFLAGS += -Wl,--gc-sections
60+
endif
61+
62+
## Makefile options
63+
64+
# Set to @ to suppress command echo
65+
CMD_ECHO ?=
66+
67+
# Debug build
68+
ifeq ($(DEBUG),1)
69+
DBGFLAGS = -ggdb -g3 -O0
70+
CFLAGS += $(DBGFLAGS)
71+
LDFLAGS += $(DBGFLAGS)
72+
DEF += -DWOLFHSM_CFG_DEBUG
73+
endif
74+
75+
# Verbose debug output
76+
ifeq ($(DEBUG_VERBOSE),1)
77+
DBGFLAGS = -ggdb -g3 -O0
78+
CFLAGS += $(DBGFLAGS)
79+
LDFLAGS += $(DBGFLAGS)
80+
DEF += -DWOLFHSM_CFG_DEBUG -DWOLFHSM_CFG_DEBUG_VERBOSE
81+
endif
82+
83+
# Address sanitizer
84+
ifeq ($(ASAN),1)
85+
CFLAGS += -fsanitize=address
86+
LDFLAGS += -fsanitize=address
87+
endif
88+
89+
## Source files
90+
91+
# wolfCrypt source files
92+
SRC_C += $(wildcard $(WOLFSSL_DIR)/wolfcrypt/src/*.c)
93+
94+
# wolfSSL TLS source files
95+
SRC_C += $(wildcard $(WOLFSSL_DIR)/src/*.c)
96+
97+
# wolfHSM source files
98+
SRC_C += $(wildcard $(WOLFHSM_DIR)/src/*.c)
99+
100+
# wolfHSM POSIX port/HAL code
101+
SRC_C += $(wildcard $(WOLFHSM_PORT_DIR)/*.c)
102+
103+
# Project source files
104+
SRC_C += $(PROJECT_DIR)/server.c
105+
SRC_C += $(PROJECT_DIR)/server_io.c
106+
107+
## Automated processing
108+
109+
FILENAMES_C = $(notdir $(SRC_C))
110+
OBJS_C = $(addprefix $(BUILD_DIR)/, $(FILENAMES_C:.c=.o))
111+
vpath %.c $(dir $(SRC_C))
112+
113+
## Makefile Targets
114+
115+
.PHONY: all build clean help
116+
117+
all: build
118+
119+
build: $(BUILD_DIR) $(BUILD_DIR)/$(BIN).elf
120+
121+
$(BUILD_DIR):
122+
$(CMD_ECHO) mkdir -p $(BUILD_DIR)
123+
124+
$(BUILD_DIR)/%.o: %.c
125+
@echo "Compiling: $(notdir $<)"
126+
$(CMD_ECHO) $(CC) $(CFLAGS) $(DEF) $(INC) -c -o $@ $<
127+
128+
$(BUILD_DIR)/$(BIN).elf: $(OBJS_C)
129+
@echo "Linking: $(notdir $@)"
130+
$(CMD_ECHO) $(CC) $(LDFLAGS) -o $@ $^ $(LIBS)
131+
132+
clean:
133+
@echo "Cleaning build files..."
134+
@rm -rf $(BUILD_DIR)
135+
136+
help:
137+
@echo "TLS/DTLS Server with wolfHSM Crypto Offload"
138+
@echo ""
139+
@echo "Options:"
140+
@echo " DEBUG=1 - Enable debug build with symbols"
141+
@echo " DEBUG_VERBOSE=1 - Enable verbose debug output"
142+
@echo " ASAN=1 - Enable address sanitizer"
143+
@echo ""
144+
@echo "Example:"
145+
@echo " make DEBUG=1"

‎examples/demo/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 choosen 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 `wolfDTLSv1_3_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)