Skip to content

Commit 01fe072

Browse files
AlexLanzanobigbrett
AlexLanzano
and
bigbrett
authored
Implement timeout capability. Apply timeout to crypto response (#278)
* Implement timeout capability. Apply timeout to crypto response --------- Co-authored-by: Brett Nicholas <7547222+bigbrett@users.noreply.github.com>
1 parent 2a334a3 commit 01fe072

File tree

14 files changed

+1336
-2
lines changed

14 files changed

+1336
-2
lines changed

‎docs/draft/timeout.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Timeout Functionality: Client Perspective
2+
3+
## Overview
4+
5+
The response timeout feature is primarily designed to prevent the client from blocking indefinitely when the server fails to respond to a request. This is most relevant for **blocking operations** such as wolfCrypt cryptographic calls, where the client sends a request and polls for a response in a tight loop. Without a timeout, a non-responsive server would cause the client to hang forever.
6+
7+
Since the timeout is checked inside `wh_CommClient_RecvResponse`, it **can** also apply to the split (async) API where the caller manually polls `RecvResponse`. However, in the async case the timeout is only evaluated each time the caller invokes `RecvResponse` -- it does not proactively notify the caller or fire asynchronously. If the caller is not actively polling, the timeout has no effect.
8+
9+
## 1. Configuration at Init Time
10+
11+
The timeout feature uses a callback-based abstraction (similar to the lock feature) that allows platform-specific timer implementations without introducing OS dependencies in core wolfHSM code. A platform port provides a callback table implementing the timer operations, and the core timeout module delegates to these callbacks.
12+
13+
The timeout lives in the comm layer. When creating a client, you provide a `whTimeoutConfig` in the `whCommClientConfig`:
14+
```c
15+
/* Platform-specific setup (e.g. POSIX) */
16+
posixTimeoutContext posixCtx = {0};
17+
posixTimeoutConfig posixCfg = {.timeoutUs = WH_SEC_TO_USEC(5)};
18+
whTimeoutCb timeoutCbTable = POSIX_TIMEOUT_CB;
19+
20+
/* NOTE: The callback table, platform context, and expiredCtx must remain valid
21+
* for the lifetime of the whCommClient/whTimeout instance. Do not use stack
22+
* locals that go out of scope while the client is still in use. */
23+
whTimeoutConfig timeoutCfg = {
24+
.cb = &timeoutCbTable, /* platform callback table */
25+
.context = &posixCtx, /* platform context */
26+
.config = &posixCfg, /* platform-specific config */
27+
.expiredCb = myTimeoutHandler, /* optional app callback on expiry */
28+
.expiredCtx = myAppContext, /* context passed to app callback */
29+
};
30+
whCommClientConfig commConfig = {
31+
.transport_cb = &transportCb,
32+
.transport_context = &transportCtx,
33+
.transport_config = &transportCfg,
34+
.client_id = 1,
35+
.respTimeoutConfig = &timeoutCfg, /* attach timeout config */
36+
};
37+
whClientConfig clientCfg = {
38+
.comm = &commConfig,
39+
};
40+
wh_Client_Init(&clientCtx, &clientCfg);
41+
```
42+
43+
During `wh_CommClient_Init`, the timeout is initialized via `wh_Timeout_Init()`. This calls the platform `init` callback to set up timer resources but doesn't start any timer yet.
44+
If `respTimeoutConfig` is NULL (or `cb` is NULL), the timeout enters no-op mode and never expires.
45+
46+
## 2. How the Timeout Works
47+
48+
The timeout is handled transparently in the comm layer:
49+
50+
1. **`wh_CommClient_SendRequest`**: After a successful send, starts the response timer via `wh_Timeout_Start()`.
51+
2. **`wh_CommClient_RecvResponse`**: When the transport returns `WH_ERROR_NOTREADY`, checks `wh_Timeout_Expired()`. If expired, returns `WH_ERROR_TIMEOUT`. On successful receive, stops the timer via `wh_Timeout_Stop()`.
52+
53+
For blocking (synchronous) client APIs, this means the internal `do { ... } while (ret == WH_ERROR_NOTREADY)` polling loop automatically gets timeout support -- the client will return `WH_ERROR_TIMEOUT` instead of spinning forever if the server does not respond within the configured deadline.
54+
55+
For split (async) APIs where the application calls `SendRequest` and `RecvResponse` separately, the timeout check occurs each time `RecvResponse` is called and returns `WH_ERROR_NOTREADY`. The timeout does **not** interrupt the caller or provide out-of-band notification -- it is purely poll-based.
56+
57+
```
58+
Client App CommClient whTimeout
59+
| | |
60+
|-- wh_Client_AesCbc() -------->| |
61+
| |-- SendRequest ------> cb->start()
62+
| | |
63+
| |-- RecvResponse (NOTREADY) |
64+
| |-- Expired? -------> cb->expired() -> no
65+
| |-- RecvResponse (NOTREADY) |
66+
| |-- Expired? -------> cb->expired() -> no
67+
| | ... |
68+
| |-- RecvResponse (NOTREADY) |
69+
| |-- Expired? -------> cb->expired() -> YES
70+
| | |-- expiredCb()
71+
|<-- WH_ERROR_TIMEOUT -----------| |
72+
```
73+
74+
## 3. What the Client Sees
75+
76+
From the application's perspective, any client API that waits for a server response can now return `WH_ERROR_TIMEOUT` (-2010) instead of hanging indefinitely. The application can then decide how to handle it -- retry, log, fail gracefully, etc.
77+
The `expiredCb` fires *before* the error is returned, so you can use it for logging or cleanup without needing to check the return code first.
78+
79+
## 4. Overriding Expiration via the Callback
80+
81+
The application expired callback receives a pointer to the `isExpired` flag and can override it by setting `*isExpired = 0`. This suppresses the expiration for the current check, allowing the polling loop to continue. A common use case is to extend the timeout deadline: clear the flag, then call `wh_Timeout_Start()` to restart the timer.
82+
83+
The callback can also return a non-zero error code to signal a failure. When it does, `wh_Timeout_Expired()` propagates that error directly to the caller instead of returning the expired flag.
84+
85+
```c
86+
static int myOverrideCb(whTimeout* timeout, int* isExpired)
87+
{
88+
int* retryCount = (int*)timeout->expiredCtx;
89+
if (retryCount == NULL) {
90+
return WH_ERROR_BADARGS;
91+
}
92+
93+
(*retryCount)++;
94+
95+
if (*retryCount <= 1) {
96+
/* First expiration: suppress and restart the timer */
97+
*isExpired = 0;
98+
wh_Timeout_Start(timeout);
99+
}
100+
/* Subsequent expirations: allow the timeout to fire */
101+
return WH_ERROR_OK;
102+
}
103+
104+
int retryCount = 0;
105+
posixTimeoutContext posixCtx = {0};
106+
posixTimeoutConfig posixCfg = {.timeoutUs = WH_SEC_TO_USEC(5)};
107+
whTimeoutCb timeoutCbTable = POSIX_TIMEOUT_CB;
108+
109+
whTimeoutConfig timeoutCfg = {
110+
.cb = &timeoutCbTable,
111+
.context = &posixCtx,
112+
.config = &posixCfg,
113+
.expiredCb = myOverrideCb,
114+
.expiredCtx = &retryCount,
115+
};
116+
```
117+
118+
## 5. Design Notes
119+
- **Primary use case: blocking wolfCrypt operations.** The timeout is designed to prevent indefinite hangs when the server fails to respond to blocking client API calls, which currently only exist when using the wolfCrypt API for crypto. These calls internally poll `RecvResponse` in a tight loop, and the timeout provides automatic protection against a non-responsive server.
120+
- **Async API compatibility.** The timeout mechanism also works with the split wolfHSM `SendRequest`/`RecvResponse` API, but only checks for expiration when `RecvResponse` is called by the application. It is purely poll-driven, and there is no callback, signal, or interrupt that fires independently. If the application stops calling `RecvResponse`, the timeout will not trigger.
121+
- **The timeout is per-comm-client, not per-call.** All operations for a given client share the same `respTimeout` context with the same duration. You can call `wh_Timeout_Set()` to change the duration between calls, but there's no per-operation override.
122+
- **Timer starts on send, checks on receive.** The timer window begins when a request is successfully sent, measuring the full round-trip wait.

‎port/posix/posix_timeout.c‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
/*
2+
* Copyright (C) 2026 wolfSSL Inc.
3+
*
4+
* This file is part of wolfHSM.
5+
*
6+
* wolfHSM is free software; you can redistribute it and/or modify
7+
* it under the terms of the GNU General Public License as published by
8+
* the Free Software Foundation; either version 3 of the License, or
9+
* (at your option) any later version.
10+
*
11+
* wolfHSM is distributed in the hope that it will be useful,
12+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14+
* GNU General Public License for more details.
15+
*
16+
* You should have received a copy of the GNU General Public License
17+
* along with wolfHSM. If not, see <http://www.gnu.org/licenses/>.
18+
*/
19+
/*
20+
* port/posix/posix_timeout.c
21+
*
22+
* POSIX implementation of the wolfHSM timeout abstraction.
23+
* Uses CLOCK_MONOTONIC for time measurement.
24+
*/
25+
26+
#include "wolfhsm/wh_settings.h"
27+
28+
#ifdef WOLFHSM_CFG_ENABLE_TIMEOUT
29+
30+
#include <stddef.h>
31+
#include <time.h>
32+
33+
#include "wolfhsm/wh_error.h"
34+
#include "wolfhsm/wh_timeout.h"
35+
36+
#include "port/posix/posix_timeout.h"
37+
38+
/* Use CLOCK_MONOTONIC for timeout measurement to avoid issues with wall-clock
39+
* adjustments (NTP, manual changes, etc.) that could cause spurious expirations
40+
* or overly long timeouts. */
41+
static uint64_t _getMonotonicTimeUs(void)
42+
{
43+
struct timespec ts;
44+
if (clock_gettime(CLOCK_MONOTONIC, &ts) != 0) {
45+
return 0;
46+
}
47+
return (uint64_t)ts.tv_sec * 1000000ULL + (uint64_t)(ts.tv_nsec / 1000);
48+
}
49+
50+
int posixTimeout_Init(void* context, const void* config)
51+
{
52+
posixTimeoutContext* ctx = (posixTimeoutContext*)context;
53+
const posixTimeoutConfig* cfg = (const posixTimeoutConfig*)config;
54+
55+
if (ctx == NULL) {
56+
return WH_ERROR_BADARGS;
57+
}
58+
59+
ctx->startUs = 0;
60+
ctx->timeoutUs = (cfg != NULL) ? cfg->timeoutUs : 0;
61+
ctx->running = 0;
62+
63+
ctx->initialized = 1;
64+
return WH_ERROR_OK;
65+
}
66+
67+
int posixTimeout_Cleanup(void* context)
68+
{
69+
posixTimeoutContext* ctx = (posixTimeoutContext*)context;
70+
71+
if (ctx == NULL) {
72+
return WH_ERROR_BADARGS;
73+
}
74+
75+
ctx->startUs = 0;
76+
ctx->timeoutUs = 0;
77+
ctx->running = 0;
78+
ctx->initialized = 0;
79+
80+
return WH_ERROR_OK;
81+
}
82+
83+
int posixTimeout_Set(void* context, uint64_t timeoutUs)
84+
{
85+
posixTimeoutContext* ctx = (posixTimeoutContext*)context;
86+
87+
if (ctx == NULL) {
88+
return WH_ERROR_BADARGS;
89+
}
90+
91+
if (!ctx->initialized) {
92+
return WH_ERROR_BADARGS;
93+
}
94+
95+
ctx->timeoutUs = timeoutUs;
96+
97+
return WH_ERROR_OK;
98+
}
99+
100+
int posixTimeout_Start(void* context)
101+
{
102+
posixTimeoutContext* ctx = (posixTimeoutContext*)context;
103+
104+
if (ctx == NULL) {
105+
return WH_ERROR_BADARGS;
106+
}
107+
108+
if (!ctx->initialized) {
109+
return WH_ERROR_BADARGS;
110+
}
111+
112+
ctx->startUs = _getMonotonicTimeUs();
113+
if (ctx->startUs == 0) {
114+
return WH_ERROR_ABORTED;
115+
}
116+
ctx->running = 1;
117+
118+
return WH_ERROR_OK;
119+
}
120+
121+
int posixTimeout_Stop(void* context)
122+
{
123+
posixTimeoutContext* ctx = (posixTimeoutContext*)context;
124+
125+
if (ctx == NULL) {
126+
return WH_ERROR_BADARGS;
127+
}
128+
129+
if (!ctx->initialized) {
130+
return WH_ERROR_BADARGS;
131+
}
132+
133+
ctx->startUs = 0;
134+
ctx->running = 0;
135+
136+
return WH_ERROR_OK;
137+
}
138+
139+
int posixTimeout_Expired(void* context, int* expired)
140+
{
141+
posixTimeoutContext* ctx = (posixTimeoutContext*)context;
142+
uint64_t nowUs;
143+
144+
if ((ctx == NULL) || (expired == NULL)) {
145+
return WH_ERROR_BADARGS;
146+
}
147+
148+
if (!ctx->initialized) {
149+
return WH_ERROR_BADARGS;
150+
}
151+
152+
/* Not started or no timeout configured = not expired */
153+
if (!ctx->running || (ctx->timeoutUs == 0)) {
154+
*expired = 0;
155+
return WH_ERROR_OK;
156+
}
157+
158+
nowUs = _getMonotonicTimeUs();
159+
if (nowUs == 0) {
160+
return WH_ERROR_ABORTED;
161+
}
162+
*expired = ((nowUs - ctx->startUs) >= ctx->timeoutUs) ? 1 : 0;
163+
164+
return WH_ERROR_OK;
165+
}
166+
167+
#endif /* WOLFHSM_CFG_ENABLE_TIMEOUT */

‎port/posix/posix_timeout.h‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
/*
2+
* Copyright (C) 2026 wolfSSL Inc.
3+
*
4+
* This file is part of wolfHSM.
5+
*
6+
* wolfHSM is free software; you can redistribute it and/or modify
7+
* it under the terms of the GNU General Public License as published by
8+
* the Free Software Foundation; either version 3 of the License, or
9+
* (at your option) any later version.
10+
*
11+
* wolfHSM is distributed in the hope that it will be useful,
12+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14+
* GNU General Public License for more details.
15+
*
16+
* You should have received a copy of the GNU General Public License
17+
* along with wolfHSM. If not, see <http://www.gnu.org/licenses/>.
18+
*/
19+
/*
20+
* port/posix/posix_timeout.h
21+
*
22+
* POSIX implementation of the wolfHSM timeout abstraction.
23+
* Uses CLOCK_MONOTONIC for time measurement.
24+
*/
25+
26+
#ifndef PORT_POSIX_POSIX_TIMEOUT_H_
27+
#define PORT_POSIX_POSIX_TIMEOUT_H_
28+
29+
#include "wolfhsm/wh_settings.h"
30+
31+
#ifdef WOLFHSM_CFG_ENABLE_TIMEOUT
32+
33+
#include <stdint.h>
34+
35+
#include "wolfhsm/wh_timeout.h"
36+
37+
/* Configuration for POSIX timeout backend */
38+
typedef struct posixTimeoutConfig_t {
39+
uint64_t timeoutUs; /* Timeout duration in microseconds; 0 = no timeout */
40+
} posixTimeoutConfig;
41+
42+
/* Context structure holding timer state */
43+
typedef struct posixTimeoutContext_t {
44+
uint64_t startUs; /* Snapshot of start time */
45+
uint64_t timeoutUs; /* Configured timeout duration */
46+
int running; /* 1 if timer is running, 0 otherwise */
47+
int initialized; /* 1 if initialized, 0 otherwise */
48+
} posixTimeoutContext;
49+
50+
/* Callback functions matching whTimeoutCb interface */
51+
int posixTimeout_Init(void* context, const void* config);
52+
int posixTimeout_Cleanup(void* context);
53+
int posixTimeout_Set(void* context, uint64_t timeoutUs);
54+
int posixTimeout_Start(void* context);
55+
int posixTimeout_Stop(void* context);
56+
int posixTimeout_Expired(void* context, int* expired);
57+
58+
/* Convenience macro for callback table initialization */
59+
/* clang-format off */
60+
#define POSIX_TIMEOUT_CB \
61+
{ \
62+
.init = posixTimeout_Init, \
63+
.cleanup = posixTimeout_Cleanup, \
64+
.set = posixTimeout_Set, \
65+
.start = posixTimeout_Start, \
66+
.stop = posixTimeout_Stop, \
67+
.expired = posixTimeout_Expired, \
68+
}
69+
/* clang-format on */
70+
71+
#endif /* WOLFHSM_CFG_ENABLE_TIMEOUT */
72+
73+
#endif /* !PORT_POSIX_POSIX_TIMEOUT_H_ */

0 commit comments

Comments
 (0)