wolfhsm/wh_server.h

Functions

	Name
int	wh_Server_Init(whServerContext * server, whServerConfig * config) Initializes the server context with the provided configuration.
int	wh_Server_SetConnected(whServerContext * server, whCommConnected connected) Sets the connection state of the server.
int	wh_Server_SetConnectedCb(void * s, whCommConnected connected) Sets a callback function that should be invoked by the underlying transport after it is initialized.
int	wh_Server_GetConnected(whServerContext * server, whCommConnected * out_connected) Gets the connection state of the server.
int	wh_Server_GetCanceledSequence(whServerContext * server, uint16_t * outSeq) Gets the canceled sequence number of the server.
int	wh_Server_SetCanceledSequence(whServerContext * server, uint16_t cancelSeq) Sets the canceled sequence number of the server.
int	wh_Server_HandleRequestMessage(whServerContext * server) Handles incoming request messages and dispatches them to the appropriate handlers.
int	wh_Server_Cleanup(whServerContext * server) Cleans up the server context and associated resources.
int	wh_Server_RegisterCustomCb(whServerContext * server, uint16_t actionId, whServerCustomCb cb) Registers a custom callback handler for a specific action.
int	wh_Server_HandleCustomCbRequest(whServerContext * server, uint16_t magic, uint16_t action, uint16_t seq, uint16_t req_size, const void * req_packet, uint16_t * out_resp_size, void * resp_packet) Handles incoming custom callback requests.
int	wh_Server_DmaRegisterCb(struct whServerContext_t * server, whServerDmaClientMemCb cb) Registers a custom client DMA callback.
int	wh_Server_DmaRegisterAllowList(struct whServerContext_t * server, const whServerDmaAddrAllowList * allowlist) Registers the allowable client read/write addresses for DMA.
int	wh_Server_DmaCheckMemOperAllowed(const struct whServerContext_t * server, whServerDmaOper oper, void * addr, size_t size) Checks if a DMA memory operation is allowed based on the server's allowlist.
int	wh_Server_DmaProcessClientAddress(struct whServerContext_t * server, uintptr_t clientAddr, void ** serverPtr, size_t len, whServerDmaOper oper, whServerDmaFlags flags) Processes a client address for DMA operations, using the native pointer size of the system.

Functions Documentation

function wh_Server_Init

int wh_Server_Init(
    whServerContext * server,
    whServerConfig * config
)

Initializes the server context with the provided configuration.

Parameters:

server Pointer to the server context.
config Pointer to the server configuration.

Return: int Returns 0 on success, WH_ERROR_BADARGS if the arguments are invalid, or WH_ERROR_ABORTED if initialization fails.

Public server context functions

This function must be called before any other server functions are used on the supplied context. Note that the NVM and Crypto components of the config structure MUST be initialized before calling this function.

function wh_Server_SetConnected

int wh_Server_SetConnected(
    whServerContext * server,
    whCommConnected connected
)

Sets the connection state of the server.

Parameters:

server Pointer to the server context.
connected The connection state to set.

Return: int Returns 0 on success, or WH_ERROR_BADARGS if the arguments are invalid.

The connection state indicates whether the server is ready to handle incoming requests. This function should be invoked when the underlying transport is ready for use.

function wh_Server_SetConnectedCb

int wh_Server_SetConnectedCb(
    void * s,
    whCommConnected connected
)

Sets a callback function that should be invoked by the underlying transport after it is initialized.

Parameters:

s Pointer to the server context.
connected The connection state to set.

Return: int Returns 0 on success.

The connection state indicates whether the server is ready to handle incoming requests. This function should be invoked when the underlying transport is ready for use.

function wh_Server_GetConnected

int wh_Server_GetConnected(
    whServerContext * server,
    whCommConnected * out_connected
)

Gets the connection state of the server.

Parameters:

server Pointer to the server context.
out_connected Pointer to store the connection state.

Return: int Returns 0 on success, or WH_ERROR_BADARGS if the arguments are invalid.

function wh_Server_GetCanceledSequence

int wh_Server_GetCanceledSequence(
    whServerContext * server,
    uint16_t * outSeq
)

Gets the canceled sequence number of the server.

Parameters:

server Pointer to the server context.
outSeq Pointer to store the canceled sequence number.

Return: int Returns 0 on success, or WH_ERROR_BADARGS if the arguments are invalid

The canceled sequence number is the comms layer sequence number of the last canceled request. This number is set by the server port in response to an out-of-band signal from the client when the client wishes to cancel a request.

function wh_Server_SetCanceledSequence

int wh_Server_SetCanceledSequence(
    whServerContext * server,
    uint16_t cancelSeq
)

Sets the canceled sequence number of the server.

The canceled sequence number is the comms layer sequence number of the last canceled request. This function should be used by the server port to set the canceled sequence number in response to an out-of-band signal from the client.

function wh_Server_HandleRequestMessage

int wh_Server_HandleRequestMessage(
    whServerContext * server
)

Handles incoming request messages and dispatches them to the appropriate handlers.

Parameters:

server Pointer to the server context.

Return: int Returns 0 on success, WH_ERROR_BADARGS if the arguments are invalid, WH_ERROR_NOTREADY if the server is not connected or no data is available, or a negative error code on failure.

This function processes incoming request messages from the communication server in a non-blocking fashion. It determines the message group and action, and dispatches the request to the appropriate handler. The function also sends a response back to the client.

function wh_Server_Cleanup

int wh_Server_Cleanup(
    whServerContext * server
)

Cleans up the server context and associated resources.

Parameters:

server Pointer to the server context.

Return: int Returns WH_ERROR_OK on success, or WH_ERROR_BADARGS if the arguments are invalid.

This function releases any resources associated with the server context, including communication server resources. It resets the server context to its initial state.

function wh_Server_RegisterCustomCb

int wh_Server_RegisterCustomCb(
    whServerContext * server,
    uint16_t actionId,
    whServerCustomCb cb
)

Registers a custom callback handler for a specific action.

Parameters:

server Pointer to the server context.
actionId The action ID for which the callback is being registered.
cb The custom callback handler to register.

Return: int Returns WH_ERROR_OK on success, or WH_ERROR_BADARGS if the arguments are invalid.

Server custom callback functions

This function allows the server to register a custom callback handler for a specific action ID. The callback will be invoked when a request with the corresponding action ID is received.

function wh_Server_HandleCustomCbRequest

int wh_Server_HandleCustomCbRequest(
    whServerContext * server,
    uint16_t magic,
    uint16_t action,
    uint16_t seq,
    uint16_t req_size,
    const void * req_packet,
    uint16_t * out_resp_size,
    void * resp_packet
)

Handles incoming custom callback requests.

Parameters:

server Pointer to the server context.
magic The magic number for the request.
action The action ID of the request.
seq The sequence number of the request.
req_size The size of the request packet.
req_packet Pointer to the request packet data.
out_resp_size Pointer to store the size of the response packet.
resp_packet Pointer to store the response packet data.

Return: int Returns WH_ERROR_OK on success, WH_ERROR_BADARGS if the arguments are invalid, WH_ERROR_ABORTED if the request is malformed, or a negative error code on failure.

This function processes incoming custom callback requests by invoking the registered custom callback handler for the specified action. It translates the request and response messages and sends the appropriate response back to the client.

function wh_Server_DmaRegisterCb

int wh_Server_DmaRegisterCb(
    struct whServerContext_t * server,
    whServerDmaClientMemCb cb
)

Registers a custom client DMA callback.

Parameters:

server Pointer to the server context.
cb The custom DMA callback handler to register.

Return: int Returns WH_ERROR_OK on success, or WH_ERROR_BADARGS if the arguments are invalid.

Server DMA functions

This function allows the server to register a custom callback handler for processing client memory operations. The callback will be invoked during DMA operations to transform client addresses, manipulate caches, etc.

function wh_Server_DmaRegisterAllowList

int wh_Server_DmaRegisterAllowList(
    struct whServerContext_t * server,
    const whServerDmaAddrAllowList * allowlist
)

Registers the allowable client read/write addresses for DMA.

Parameters:

server Pointer to the server context.
allowlist Pointer to the list of allowable client addresses.

Return: int Returns WH_ERROR_OK on success, or WH_ERROR_BADARGS if the arguments are invalid.

This function allows the server to register a list of allowable client addresses for DMA read and write operations. The server will check these addresses during DMA operations to ensure they are within the allowed range for the client

function wh_Server_DmaCheckMemOperAllowed

int wh_Server_DmaCheckMemOperAllowed(
    const struct whServerContext_t * server,
    whServerDmaOper oper,
    void * addr,
    size_t size
)

Checks if a DMA memory operation is allowed based on the server's allowlist.

Parameters:

server Pointer to the server context.
oper The DMA operation type (e.g., read or write).
addr The address to be checked.
size The size of the memory operation.

Return: int Returns WH_ERROR_OK if the operation is allowed, WH_ERROR_BADARGS if the arguments are invalid, or WH_ERROR_ACCESS if the operation is not allowed.

This function verifies whether a specified DMA memory operation is permitted by checking the operation type and the address range against the server's registered allowlist. If no allowlist is registered, the operation is allowed.

function wh_Server_DmaProcessClientAddress

int wh_Server_DmaProcessClientAddress(
    struct whServerContext_t * server,
    uintptr_t clientAddr,
    void ** serverPtr,
    size_t len,
    whServerDmaOper oper,
    whServerDmaFlags flags
)

Processes a client address for DMA operations, using the native pointer size of the system.

Parameters:

server Pointer to the server context.
clientAddr The client address to be processed.
serverPtr Pointer to store the transformed server address.
len The length of the memory operation.
oper The DMA operation type (e.g., read or write).
flags Flags for the DMA operation.

Return: int Returns WH_ERROR_OK on success, WH_ERROR_BADARGS if the arguments are invalid, or a negative error code on failure.

This function transforms a client address for DMA operations. It performs user-supplied address transformations, cache manipulations, and checks the transformed address against the server's allowlist if registered.

Source code

/*
 * Copyright (C) 2024 wolfSSL Inc.
 *
 * This file is part of wolfHSM.
 *
 * wolfHSM is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * wolfHSM is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with wolfHSM.  If not, see <http://www.gnu.org/licenses/>.
 */
/*
 * wolfhsm/wh_server.h
 *
*
 */

#ifndef WOLFHSM_WH_SERVER_H_
#define WOLFHSM_WH_SERVER_H_

/* Pick up compile-time configuration */
#include "wolfhsm/wh_settings.h"

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

/* Forward declaration of the server structure so its elements can reference
 * itself  (e.g. server argument to custom callback) */
typedef struct whServerContext_t whServerContext;

#include "wolfhsm/wh_common.h"
#include "wolfhsm/wh_comm.h"
#include "wolfhsm/wh_nvm.h"
#include "wolfhsm/wh_message_customcb.h"

#ifndef WOLFHSM_CFG_NO_CRYPTO
#include "wolfssl/wolfcrypt/settings.h"
#include "wolfssl/wolfcrypt/types.h"
#include "wolfssl/wolfcrypt/random.h"
#include "wolfssl/wolfcrypt/rsa.h"
#include "wolfssl/wolfcrypt/ecc.h"
#include "wolfssl/wolfcrypt/curve25519.h"
#include "wolfssl/wolfcrypt/cryptocb.h"
#include "wolfssl/wolfcrypt/sha256.h"
#endif /* !WOLFHSM_CFG_NO_CRYPTO */

#ifdef WOLFHSM_CFG_SHE_EXTENSION
#include "wolfhsm/wh_she_common.h"
#include "wolfhsm/wh_server_she.h"
#endif


#ifndef WOLFHSM_CFG_NO_CRYPTO
typedef struct whServerCacheSlot {
    uint8_t        commited;
    whNvmMetadata   meta[1];
    uint8_t         buffer[WOLFHSM_CFG_SERVER_KEYCACHE_BUFSIZE];
} whServerCacheSlot;

typedef struct whServerBigCacheSlot {
    uint8_t       commited;
    whNvmMetadata meta[1];
    uint8_t       buffer[WOLFHSM_CFG_SERVER_KEYCACHE_BIG_BUFSIZE];
} whServerBigCacheSlot;

typedef struct whServerCryptoContext {
    int devId;
#ifndef WC_NO_RNG
    WC_RNG rng[1];
#endif
    union {
#if 0
#ifndef NO_AES
        Aes aes[1];
#endif
#ifndef NO_RSA
        RsaKey rsa[1];
#endif
#ifdef HAVE_CURVE25519
        curve25519_key curve25519Private[1];
#endif
#endif /* 0 */
#ifdef WOLFSSL_CMAC
        Cmac cmac[1];
#endif
#ifndef NO_SHA256
        wc_Sha256 sha256[1];
#endif
    } algoCtx;
} whServerCryptoContext;


#endif /* !WOLFHSM_CFG_NO_CRYPTO */

/* Type definition for a custom server callback  */
typedef int (*whServerCustomCb)(
    whServerContext* server,              /* points to dispatching server ctx */
    const whMessageCustomCb_Request* req, /* request from client to callback */
    whMessageCustomCb_Response*      resp /* response from callback to client */
);


/* Indicates to a DMA callback the type of memory operation the callback must
 * act on. Common use cases are remapping client addresses into server address
 * space (map in READ_PRE/WRITE_PRE, unmap in READ_POST/WRITE_POST), or
 * invalidating a cache block before reading from or after writing to client
 * memory */
typedef enum {
    /* Indicates server is about to read from client memory */
    WH_DMA_OPER_CLIENT_READ_PRE = 0,
    /* Indicates server has just read from client memory */
    WH_DMA_OPER_CLIENT_READ_POST = 1,
    /* Indicates server is about to write to client memory */
    WH_DMA_OPER_CLIENT_WRITE_PRE = 2,
    /* Indicates server has just written from client memory */
    WH_DMA_OPER_CLIENT_WRITE_POST = 3,
} whServerDmaOper;

/* Flags embedded in request/response structs provided by client */
typedef struct {
    uint8_t cacheForceInvalidate : 1;
    uint8_t : 7;
} whServerDmaFlags;

/* DMA callbacks invoked internally by wolfHSM before and after every client
 * memory operation. */
typedef int (*whServerDmaClientMemCb)(struct whServerContext_t* server,
                                      uintptr_t clientAddr, void** serverPtr,
                                      size_t len, whServerDmaOper oper,
                                      whServerDmaFlags flags);

/* DMA address entry within the allowed tables. */
/* Note: These are translated addresses from the Server's perspective*/
typedef struct {
    void*  addr;
    size_t size;
} whServerDmaAddr;

typedef whServerDmaAddr whServerDmaAddrList[WOLFHSM_CFG_SERVER_DMAADDR_COUNT];

/* Holds allowable client read/write addresses */
typedef struct {
    whServerDmaAddrList readList;  /* Allowed client read addresses */
    whServerDmaAddrList writeList; /* Allowed client write addresses */
} whServerDmaAddrAllowList;

/* Server DMA configuration struct for initializing a server */
typedef struct {
    whServerDmaClientMemCb          cb;               /* DMA callback */
    const whServerDmaAddrAllowList* dmaAddrAllowList; /* allowed addresses */
} whServerDmaConfig;

typedef struct {
    whServerDmaClientMemCb          cb;               /* DMA callback */
    const whServerDmaAddrAllowList* dmaAddrAllowList; /* allowed addresses */
} whServerDmaContext;


typedef struct whServerConfig_t {
    whCommServerConfig* comm_config;
    whNvmContext*       nvm;

#ifndef WOLFHSM_CFG_NO_CRYPTO
    whServerCryptoContext* crypto;
#ifdef WOLFHSM_CFG_SHE_EXTENSION
    whServerSheContext* she;
#endif /* WOLFHSM_CFG_SHE_EXTENSION */
#if defined WOLF_CRYPTO_CB
    int devId;
#endif /* WOLF_CRYPTO_CB */
#endif /* !WOLFHSM_CFG_NO_CRYPTO */
    whServerDmaConfig* dmaConfig;
} whServerConfig;


/* Context structure to maintain the state of an HSM server */
struct whServerContext_t {
    whNvmContext* nvm;
    whCommServer  comm[1];
#ifndef WOLFHSM_CFG_NO_CRYPTO
    whServerCryptoContext*  crypto;
    whServerCacheSlot       cache[WOLFHSM_CFG_SERVER_KEYCACHE_COUNT];
    whServerBigCacheSlot    bigCache[WOLFHSM_CFG_SERVER_KEYCACHE_BIG_COUNT];
#ifdef WOLFHSM_CFG_SHE_EXTENSION
    whServerSheContext* she;
#endif
#endif /* !WOLFHSM_CFG_NO_CRYPTO */
    whServerCustomCb   customHandlerTable[WOLFHSM_CFG_SERVER_CUSTOMCB_COUNT];
    whServerDmaContext dma;
    int                connected;
    uint16_t cancelSeq;
    uint8_t WH_PAD[2];
};


/* Initialize the comms and crypto cache components.
 * Note: NVM and Crypto components must be initialized prior to Server Init
 */

int wh_Server_Init(whServerContext* server, whServerConfig* config);

int wh_Server_SetConnected(whServerContext* server, whCommConnected connected);

int wh_Server_SetConnectedCb(void* s, whCommConnected connected);

int wh_Server_GetConnected(whServerContext* server,
                           whCommConnected* out_connected);

int wh_Server_GetCanceledSequence(whServerContext* server, uint16_t* outSeq);


int wh_Server_SetCanceledSequence(whServerContext* server, uint16_t cancelSeq);

int wh_Server_HandleRequestMessage(whServerContext* server);

int wh_Server_Cleanup(whServerContext* server);

int wh_Server_RegisterCustomCb(whServerContext* server, uint16_t actionId,
                               whServerCustomCb cb);

int wh_Server_HandleCustomCbRequest(whServerContext* server, uint16_t magic,
                                    uint16_t action, uint16_t seq,
                                    uint16_t req_size, const void* req_packet,
                                    uint16_t* out_resp_size, void* resp_packet);

#ifdef WOLFHSM_CFG_DMA

int wh_Server_DmaRegisterCb(struct whServerContext_t* server,
                            whServerDmaClientMemCb    cb);

int wh_Server_DmaRegisterAllowList(struct whServerContext_t*       server,
                                   const whServerDmaAddrAllowList* allowlist);

int wh_Server_DmaCheckMemOperAllowed(const struct whServerContext_t* server,
                                     whServerDmaOper oper, void* addr,
                                     size_t size);

int wh_Server_DmaProcessClientAddress(struct whServerContext_t* server,
                                      uintptr_t clientAddr, void** serverPtr,
                                      size_t len, whServerDmaOper oper,
                                      whServerDmaFlags flags);

int whServerDma_CopyFromClient(struct whServerContext_t* server,
                               void* serverPtr, uintptr_t clientAddr,
                               size_t len, whServerDmaFlags flags);

int whServerDma_CopyToClient(struct whServerContext_t* server,
                             uintptr_t clientAddr, void* serverPtr, size_t len,
                             whServerDmaFlags flags);
#endif /* WOLFHSM_CFG_DMA */

#endif /* !WOLFHSM_WH_SERVER_H_ */

Updated on 2025-07-01 at 01:47:15 +0000