wolfhsm/wh_client.h

Functions

	Name
int	wh_Client_Init(whClientContext * c, const whClientConfig * config)
int	wh_Client_Cleanup(whClientContext * c) Disconnects from the server and releases client context resources.
int	wh_Client_SendRequest(whClientContext * c, uint16_t group, uint16_t action, uint16_t data_size, const void * data)
int	wh_Client_RecvResponse(whClientContext * c, uint16_t * out_group, uint16_t * out_action, uint16_t * out_size, void * data)
int	wh_Client_CommInitRequest(whClientContext * c) Sends a communication initialization request to the server.
int	wh_Client_CommInitResponse(whClientContext * c, uint32_t * out_clientid, uint32_t * out_serverid) Receives a communication initialization response from the server.
int	wh_Client_CommInit(whClientContext * c, uint32_t * out_clientid, uint32_t * out_serverid) Initializes communication with the server with a blocking call.
int	wh_Client_CommInfoRequest(whClientContext * c) Sends a communications information request to the server.
int	wh_Client_CommInfoResponse(whClientContext * c, uint8_t * out_version, uint8_t * out_build, uint32_t * out_cfg_comm_data_len, uint32_t * out_cfg_nvm_object_count, uint32_t * out_cfg_keycache_count, uint32_t * out_cfg_keycache_bufsize, uint32_t * out_cfg_keycache_bigcount, uint32_t * out_cfg_keycache_bigbufsize, uint32_t * out_cfg_customcb_count, uint32_t * out_cfg_dmaaddr_count, uint32_t * out_debug_state, uint32_t * out_boot_state, uint32_t * out_lifecycle_state, uint32_t * out_nvm_state) Receives a communication information response from the server.
int	wh_Client_CommInfo(whClientContext * c, uint8_t * out_version, uint8_t * out_build, uint32_t * out_cfg_comm_data_len, uint32_t * out_cfg_nvm_object_count, uint32_t * out_cfg_keycache_count, uint32_t * out_cfg_keycache_bufsize, uint32_t * out_cfg_keycache_bigcount, uint32_t * out_cfg_keycache_bigbufsize, uint32_t * out_cfg_customcb_count, uint32_t * out_cfg_dmaaddr_count, uint32_t * out_debug_state, uint32_t * out_boot_state, uint32_t * out_lifecycle_state, uint32_t * out_nvm_state) Retrieves server configuration and state with a blocking call.
int	wh_Client_CommCloseRequest(whClientContext * c) Sends a communication close request to the server.
int	wh_Client_EnableCancel(whClientContext * c) Enables request cancellation.
int	wh_Client_DisableCancel(whClientContext * c) Disables request cancellation.
int	wh_Client_CancelRequest(whClientContext * c) Cancels the previous request, currently only supports CMAC. Async Request.
int	wh_Client_CancelResponse(whClientContext * c) Handles the response for a cancellation the previous request, currently only supports CMAC. Async response handler.
int	wh_Client_Cancel(whClientContext * c) Cancels the previous request, currently only supports CMAC.
int	wh_Client_CommCloseResponse(whClientContext * c) Receives a communication close response from the server.
int	wh_Client_CommClose(whClientContext * c) Closes communication with the server.
int	wh_Client_EchoRequest(whClientContext * c, uint16_t size, const void * data) Sends an echo request to the server.
int	wh_Client_EchoResponse(whClientContext * c, uint16_t * out_size, void * data) Receives an echo response from the server.
int	wh_Client_Echo(whClientContext * c, uint16_t snd_len, const void * snd_data, uint16_t * out_rcv_len, void * rcv_data) Sends an echo request to the server and receives the response.
int	wh_Client_KeyCacheRequest_ex(whClientContext * c, uint32_t flags, uint8_t * label, uint16_t labelSz, uint8_t * in, uint16_t inSz, uint16_t keyId) Sends a key cache request to the server.
int	wh_Client_KeyCacheRequest(whClientContext * c, uint32_t flags, uint8_t * label, uint16_t labelSz, uint8_t * in, uint16_t inSz) Sends a key cache request to the server.
int	wh_Client_KeyCacheResponse(whClientContext * c, uint16_t * keyId) Receives a key cache response from the server.
int	wh_Client_KeyCache(whClientContext * c, uint32_t flags, uint8_t * label, uint16_t labelSz, uint8_t * in, uint16_t inSz, uint16_t * keyId) Sends a key cache request to the server and receives the response.
int	wh_Client_KeyEvictRequest(whClientContext * c, uint16_t keyId) Sends a key eviction request to the server.
int	wh_Client_KeyEvictResponse(whClientContext * c) Receives a key eviction response from the server.
int	wh_Client_KeyEvict(whClientContext * c, uint16_t keyId) Sends a key eviction request to the server and receives the response.
int	wh_Client_KeyExportRequest(whClientContext * c, uint16_t keyId) Sends a key export request to the server.
int	wh_Client_KeyExportResponse(whClientContext * c, uint8_t * label, uint16_t labelSz, uint8_t * out, uint16_t * outSz) Receives a key export response from the server.
int	wh_Client_KeyExport(whClientContext * c, uint16_t keyId, uint8_t * label, uint16_t labelSz, uint8_t * out, uint16_t * outSz) Sends a key export request to the server and receives the response.
int	wh_Client_KeyCommitRequest(whClientContext * c, whNvmId keyId) Sends a key commit request to the server.
int	wh_Client_KeyCommitResponse(whClientContext * c) Receives a key commit response from the server.
int	wh_Client_KeyCommit(whClientContext * c, whNvmId keyId) Sends a key commit request to the server and receives the response.
int	wh_Client_KeyEraseRequest(whClientContext * c, whNvmId keyId) Sends a key erase request to the server.
int	wh_Client_KeyEraseResponse(whClientContext * c) Receives a key erase response from the server.
int	wh_Client_KeyErase(whClientContext * c, whNvmId keyId) Sends a key erase request to the server and receives the response.
int	wh_Client_KeyCacheDmaRequest(whClientContext * c, uint32_t flags, uint8_t * label, uint16_t labelSz, const void * keyAddr, uint16_t keySz, uint16_t keyId) Sends a key cache request using DMA to the server.
int	wh_Client_KeyCacheDmaResponse(whClientContext * c, uint16_t * keyId) Receives a key cache response for DMA from the server.
int	wh_Client_KeyCacheDma(whClientContext * c, uint32_t flags, uint8_t * label, uint16_t labelSz, const void * keyAddr, uint16_t keySz, uint16_t * keyId) Performs a complete key cache operation using DMA.
int	wh_Client_KeyExportDmaRequest(whClientContext * c, uint16_t keyId, const void * keyAddr, uint16_t keySz) Sends a key export request using DMA to the server.
int	wh_Client_KeyExportDmaResponse(whClientContext * c, uint8_t * label, uint16_t labelSz, uint16_t * outSz) Receives a key export response for DMA from the server.
int	wh_Client_KeyExportDma(whClientContext * c, uint16_t keyId, const void * keyAddr, uint16_t keySz, uint8_t * label, uint16_t labelSz, uint16_t * outSz) Performs a complete key export operation using DMA.
int	wh_Client_CounterInitRequest(whClientContext * c, whNvmId counterId, uint32_t counter)
int	wh_Client_CounterInitResponse(whClientContext * c, uint32_t * counter)
int	wh_Client_CounterInit(whClientContext * c, whNvmId counterId, uint32_t * counter) Creates and initializes a counter with the value set in counter.
int	wh_Client_CounterResetRequest(whClientContext * c, whNvmId counterId)
int	wh_Client_CounterResetResponse(whClientContext * c, uint32_t * counter)
int	wh_Client_CounterReset(whClientContext * c, whNvmId counterId, uint32_t * counter) Creates and initializes a counter with to 0.
int	wh_Client_CounterIncrementRequest(whClientContext * c, whNvmId counterId)
int	wh_Client_CounterIncrementResponse(whClientContext * c, uint32_t * counter)
int	wh_Client_CounterIncrement(whClientContext * c, whNvmId counterId, uint32_t * counter) Increments a counter.
int	wh_Client_CounterReadRequest(whClientContext * c, whNvmId counterId)
int	wh_Client_CounterReadResponse(whClientContext * c, uint32_t * counter)
int	wh_Client_CounterRead(whClientContext * c, whNvmId counterId, uint32_t * counter) Read a counter.
int	wh_Client_CounterDestroyRequest(whClientContext * c, whNvmId counterId)
int	wh_Client_CounterDestroyResponse(whClientContext * c)
int	wh_Client_CounterDestroy(whClientContext * c, whNvmId counterId) Destroy a counter.
int	wh_Client_NvmInitRequest(whClientContext * c) Sends a non-volatile memory (NVM) initialization request to the server.
int	wh_Client_NvmInitResponse(whClientContext * c, int32_t * out_rc, uint32_t * out_clientnvm_id, uint32_t * out_servernvm_id) Receives a non-volatile memory (NVM) initialization response from the server.
int	wh_Client_NvmInit(whClientContext * c, int32_t * out_rc, uint32_t * out_clientnvm_id, uint32_t * out_servernvm_id) Sends a non-volatile memory (NVM) initialization request to the server and receives the response.
int	wh_Client_NvmCleanupRequest(whClientContext * c) Sends a non-volatile memory (NVM) cleanup request to the server.
int	wh_Client_NvmCleanupResponse(whClientContext * c, int32_t * out_rc) Receives a non-volatile memory (NVM) cleanup response from the server.
int	wh_Client_NvmCleanup(whClientContext * c, int32_t * out_rc) Sends a non-volatile memory (NVM) cleanup request to the server and receives the response.
int	wh_Client_NvmGetAvailableRequest(whClientContext * c) Sends a request to the server to get available non-volatile memory (NVM) information.
int	wh_Client_NvmGetAvailableResponse(whClientContext * c, int32_t * out_rc, uint32_t * out_avail_size, whNvmId * out_avail_objects, uint32_t * out_reclaim_size, whNvmId * out_reclaim_objects) Receives a response from the server with available non-volatile memory (NVM) information.
int	wh_Client_NvmGetAvailable(whClientContext * c, int32_t * out_rc, uint32_t * out_avail_size, whNvmId * out_avail_objects, uint32_t * out_reclaim_size, whNvmId * out_reclaim_objects) Sends a request to the server and receives a response with available non-volatile memory (NVM) information.
int	wh_Client_NvmAddObjectRequest(whClientContext * c, whNvmId id, whNvmAccess access, whNvmFlags flags, whNvmSize label_len, uint8_t * label, whNvmSize len, const uint8_t * data) Sends a request to the server to add an object to non-volatile memory (NVM).
int	wh_Client_NvmAddObjectResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after attempting to add an object to non-volatile memory (NVM).
int	wh_Client_NvmAddObject(whClientContext * c, whNvmId id, whNvmAccess access, whNvmFlags flags, whNvmSize label_len, uint8_t * label, whNvmSize len, const uint8_t * data, int32_t * out_rc) Sends a request to the server and receives a response to add an object to non-volatile memory (NVM).
int	wh_Client_NvmListRequest(whClientContext * c, whNvmAccess access, whNvmFlags flags, whNvmId start_id) Sends a request to the server to list non-volatile memory (NVM) objects.
int	wh_Client_NvmListResponse(whClientContext * c, int32_t * out_rc, whNvmId * out_count, whNvmId * out_id) Receives a response from the server with a list of non-volatile memory (NVM) objects.
int	wh_Client_NvmList(whClientContext * c, whNvmAccess access, whNvmFlags flags, whNvmId start_id, int32_t * out_rc, whNvmId * out_count, whNvmId * out_id) Sends a request to the server and receives a response to list non-volatile memory (NVM) objects.
int	wh_Client_NvmGetMetadataRequest(whClientContext * c, whNvmId id) Sends a request to the server to get metadata of a non-volatile memory (NVM) object.
int	wh_Client_NvmGetMetadataResponse(whClientContext * c, int32_t * out_rc, whNvmId * out_id, whNvmAccess * out_access, whNvmFlags * out_flags, whNvmSize * out_len, whNvmSize label_len, uint8_t * label) Receives a response from the server with metadata of a non-volatile memory (NVM) object.
int	wh_Client_NvmGetMetadata(whClientContext * c, whNvmId id, int32_t * out_rc, whNvmId * out_id, whNvmAccess * out_access, whNvmFlags * out_flags, whNvmSize * out_len, whNvmSize label_len, uint8_t * label) Sends a request to the server and receives a response to get metadata of a non-volatile memory (NVM) object.
int	wh_Client_NvmDestroyObjectsRequest(whClientContext * c, whNvmId list_count, const whNvmId * id_list) Sends a request to the server to destroy non-volatile memory (NVM) objects.
int	wh_Client_NvmDestroyObjectsResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after attempting to destroy non-volatile memory (NVM) objects.
int	wh_Client_NvmDestroyObjects(whClientContext * c, whNvmId list_count, const whNvmId * id_list, int32_t * out_rc) Sends a request to the server and receives a response to destroy non-volatile memory (NVM) objects.
int	wh_Client_NvmReadRequest(whClientContext * c, whNvmId id, whNvmSize offset, whNvmSize data_len) Sends a request to the server to read data from a non-volatile memory (NVM) object.
int	wh_Client_NvmReadResponse(whClientContext * c, int32_t * out_rc, whNvmSize * out_len, uint8_t * data) Receives a response from the server with NVM object data.
int	wh_Client_NvmRead(whClientContext * c, whNvmId id, whNvmSize offset, whNvmSize data_len, int32_t * out_rc, whNvmSize * out_len, uint8_t * data) Sends a request to the server and receives a response to read data from a non-volatile memory (NVM) object.
int	wh_Client_NvmAddObjectDmaRequest(whClientContext * c, whNvmMetadata * metadata, whNvmSize data_len, const uint8_t * data) Sends a request to the server to add an object to non-volatile memory (NVM) using DMA.
int	wh_Client_NvmAddObjectDmaResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after attempting to add an object to non-volatile memory (NVM) using DMA.
int	wh_Client_NvmAddObjectDma(whClientContext * c, whNvmMetadata * metadata, whNvmSize data_len, const uint8_t * data, int32_t * out_rc) Sends a request to the server and receives a response to add an object to non-volatile memory (NVM) using DMA.
int	wh_Client_NvmReadDmaRequest(whClientContext * c, whNvmId id, whNvmSize offset, whNvmSize data_len, uint8_t * data)
int	wh_Client_NvmReadDmaResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after attempting to read data from non-volatile memory (NVM) using DMA, with automatic detection of client address width (32-bit or 64-bit).
int	wh_Client_NvmReadDma(whClientContext * c, whNvmId id, whNvmSize offset, whNvmSize data_len, uint8_t * data, int32_t * out_rc) Sends a request to the server and receives a response to read data from non-volatile memory (NVM) using DMA, with automatic detection of client address width (32-bit or 64-bit).
int	wh_Client_CustomCbRequest(whClientContext * c, const whMessageCustomCb_Request * req) Sends a custom callback request to the server.
int	wh_Client_CustomCbResponse(whClientContext * c, whMessageCustomCb_Response * resp) Receives a response from the server after sending a custom callback request.
int	wh_Client_CustomCheckRegisteredRequest(whClientContext * c, uint32_t id) Sends a request to the server to check if a custom callback is registered.
int	wh_Client_CustomCbCheckRegisteredResponse(whClientContext * c, uint16_t * outId, int * responseError) Receives a response from the server after checking if a custom callback is registered.
int	wh_Client_CustomCbCheckRegistered(whClientContext * c, uint16_t id, int * responseError) Sends a request to the server and receives a response to check if a custom callback is registered.
int	wh_Client_CertInitRequest(whClientContext * c) Sends a request to initialize the certificate manager on the server.
int	wh_Client_CertInitResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after initializing the certificate manager.
int	wh_Client_CertInit(whClientContext * c, int32_t * out_rc) Sends a request and receives a response to initialize the certificate manager.
int	wh_Client_CertAddTrustedRequest(whClientContext * c, whNvmId id, const uint8_t * cert, uint32_t cert_len) Sends a request to add a trusted certificate to NVM storage.
int	wh_Client_CertAddTrustedResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after adding a trusted certificate.
int	wh_Client_CertAddTrusted(whClientContext * c, whNvmId id, const uint8_t * cert, uint32_t cert_len, int32_t * out_rc) Sends a request and receives a response to add a trusted certificate.
int	wh_Client_CertEraseTrustedRequest(whClientContext * c, whNvmId id) Sends a request to erase a trusted certificate from NVM storage.
int	wh_Client_CertEraseTrustedResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after erasing a trusted certificate.
int	wh_Client_CertEraseTrusted(whClientContext * c, whNvmId id, int32_t * out_rc) Sends a request and receives a response to erase a trusted certificate.
int	wh_Client_CertReadTrustedRequest(whClientContext * c, whNvmId id, uint32_t cert_len) Sends a request to read a trusted certificate from NVM storage.
int	wh_Client_CertReadTrustedResponse(whClientContext * c, uint8_t * cert, uint32_t * cert_len, int32_t * out_rc) Receives a response from the server after getting a trusted certificate.
int	wh_Client_CertReadTrusted(whClientContext * c, whNvmId id, uint8_t * cert, uint32_t * cert_len, int32_t * out_rc) Sends a request and receives a response to read a trusted certificate.
int	wh_Client_CertVerifyRequest(whClientContext * c, const uint8_t * cert, uint32_t cert_len, whNvmId trustedRootNvmId) Sends a request to verify a certificate against trusted certificates.
int	wh_Client_CertVerifyResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after verifying a certificate.
int	wh_Client_CertVerify(whClientContext * c, const uint8_t * cert, uint32_t cert_len, whNvmId trustedRootNvmId, int32_t * out_rc) Sends a request and receives a response to verify a certificate.
int	wh_Client_CertVerifyAndCacheLeafPubKeyRequest(whClientContext * c, const uint8_t * cert, uint32_t cert_len, whNvmId trustedRootNvmId, whKeyId keyId) Sends a request to verify a certificate and cache the leaf public key.
int	wh_Client_CertVerifyAndCacheLeafPubKeyResponse(whClientContext * c, whKeyId * out_keyId, int32_t * out_rc) Receives a response from the server after verifying a certificate and caching the leaf public key.
int	wh_Client_CertVerifyAndCacheLeafPubKey(whClientContext * c, const uint8_t * cert, uint32_t cert_len, whNvmId trustedRootNvmId, whKeyId * inout_keyId, int32_t * out_rc) Sends a request and receives a response to verify a certificate, while also instructing the server to cache the public key of the leaf certificate.
int	wh_Client_CertAddTrustedDmaRequest(whClientContext * c, whNvmId id, const void * cert, uint32_t cert_len) Sends a request to add a trusted certificate to NVM storage using DMA.
int	wh_Client_CertAddTrustedDmaResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after adding a trusted certificate using DMA.
int	wh_Client_CertAddTrustedDma(whClientContext * c, whNvmId id, const void * cert, uint32_t cert_len, int32_t * out_rc) Sends a request and receives a response to add a trusted certificate using DMA.
int	wh_Client_CertReadTrustedDmaRequest(whClientContext * c, whNvmId id, void * cert, uint32_t cert_len) Sends a request to read a trusted certificate from NVM storage using DMA.
int	wh_Client_CertReadTrustedDmaResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after reading a trusted certificate using DMA.
int	wh_Client_CertReadTrustedDma(whClientContext * c, whNvmId id, void * cert, uint32_t cert_len, int32_t * out_rc) Sends a request and receives a response to read trusted certificate using DMA.
int	wh_Client_CertVerifyDmaRequest(whClientContext * c, const void * cert, uint32_t cert_len, whNvmId trustedRootNvmId) Sends a request to verify a certificate using DMA.
int	wh_Client_CertVerifyDmaResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after verifying a certificate using DMA.
int	wh_Client_CertVerifyDma(whClientContext * c, const void * cert, uint32_t cert_len, whNvmId trustedRootNvmId, int32_t * out_rc) Sends a request and receives a response to verify a certificate using DMA.
int	wh_Client_CertVerifyDmaAndCacheLeafPubKeyRequest(whClientContext * c, const void * cert, uint32_t cert_len, whNvmId trustedRootNvmId, whKeyId keyId) Sends a request to verify a certificate using DMA and cache the leaf certificate public key.
int	wh_Client_CertVerifyDmaAndCacheLeafPubKeyResponse(whClientContext * c, whKeyId * out_keyId, int32_t * out_rc) Receives a response from the server after verifying a certificate using DMA and caching the leaf public key.
int	wh_Client_CertVerifyDmaAndCacheLeafPubKey(whClientContext * c, const void * cert, uint32_t cert_len, whNvmId trustedRootNvmId, whKeyId * inout_keyId, int32_t * out_rc) Sends a request and receives a response to verify a certificate using DMA and cache the leaf certificate public key.
int	wh_Client_CertVerifyAcertRequest(whClientContext * c, const void * cert, uint32_t cert_len, whNvmId trustedRootNvmId) Sends a request to verify an attribute certificate.
int	wh_Client_CertVerifyAcertResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after verifying an attribute certificate.
int	wh_Client_CertVerifyAcert(whClientContext * c, const void * cert, uint32_t cert_len, whNvmId trustedRootNvmId, int32_t * out_rc) Sends a request and receives a response to verify an attribute certificate.
int	wh_Client_CertVerifyAcertDmaRequest(whClientContext * c, const void * cert, uint32_t cert_len, whNvmId trustedRootNvmId) Prepares and sends a DMA request to verify an attribute certificate.
int	wh_Client_CertVerifyAcertDmaResponse(whClientContext * c, int32_t * out_rc) Receives a response from the server after verifying an attribute certificate using DMA.
int	wh_Client_CertVerifyAcertDma(whClientContext * c, const void * cert, uint32_t cert_len, whNvmId trustedRootNvmId, int32_t * out_rc) Sends a DMA request and receives a response to verify an attribute certificate.

Attributes

	Name
const int[WH_NUM_DEVIDS]	WH_DEV_IDS_ARRAY

Functions Documentation

function wh_Client_Init

int wh_Client_Init(
    whClientContext * c,
    const whClientConfig * config
)

Parameters:

c The pointer to the whClientContext object to be initialized.
config The pointer to the whClientConfig object containing the configuration settings.

Return: Returns 0 on success, or a negative value indicating an error.

Context initialization and shutdown functions Initializes a whClientContext object with the provided configuration.

function wh_Client_Cleanup

int wh_Client_Cleanup(
    whClientContext * c
)

Disconnects from the server and releases client context resources.

Parameters:

c A pointer to the whClientContext structure to be cleaned up.

Return: Returns 0 on success, or a negative value on failure.

This function frees any resources allocated during the initialization of the whClientContext. It should be called when the client is no longer needed

function wh_Client_SendRequest

int wh_Client_SendRequest(
    whClientContext * c,
    uint16_t group,
    uint16_t action,
    uint16_t data_size,
    const void * data
)

Parameters:

c The client context.
group The group identifier.
action The action identifier.
data_size The size of the data to be sent. Zero is allowed in the case of NULL data.
data A pointer to the data to be sent. NULL is allowed in the case of zero-sized data.

Return: Returns 0 on success, or a negative value on failure.

Generic request/response functions Sends a request to the server using the specified client context.

function wh_Client_RecvResponse

int wh_Client_RecvResponse(
    whClientContext * c,
    uint16_t * out_group,
    uint16_t * out_action,
    uint16_t * out_size,
    void * data
)

Parameters:

c The client context.
out_group Pointer to store the received group value.
out_action Pointer to store the received action value.
out_size Pointer to store the received size value.
data Pointer to store the received data.

Return: 0 if successful, a negative value if an error occurred.

Receives a response from the server and extracts the group, action, size, and data.

function wh_Client_CommInitRequest

int wh_Client_CommInitRequest(
    whClientContext * c
)

Sends a communication initialization request to the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

Comm component functions

This function prepares and sends a communication initialization request message to the server. It populates the message with the client's ID (initialized from the config struct at client initialization) and sends it using the communication context.

function wh_Client_CommInitResponse

int wh_Client_CommInitResponse(
    whClientContext * c,
    uint32_t * out_clientid,
    uint32_t * out_serverid
)

Receives a communication initialization response from the server.

Parameters:

c Pointer to the client context.
out_clientid Pointer to store the client ID from the response.
out_serverid Pointer to store the server ID from the response.

Return: int Returns 0 on success, or a negative error code on failure.

This function waits for and processes a communication initialization response message from the server. It validates the response and extracts the client and server IDs from the message.

function wh_Client_CommInit

int wh_Client_CommInit(
    whClientContext * c,
    uint32_t * out_clientid,
    uint32_t * out_serverid
)

Initializes communication with the server with a blocking call.

Parameters:

c Pointer to the client context.
out_clientid Pointer to store the client ID from the response.
out_serverid Pointer to store the server ID from the response.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of initializing communication with the server. It sends an initialization request and waits for a valid response, extracting the client and server IDs from the response.

function wh_Client_CommInfoRequest

int wh_Client_CommInfoRequest(
    whClientContext * c
)

Sends a communications information request to the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a communication information request message to the server.

function wh_Client_CommInfoResponse

int wh_Client_CommInfoResponse(
    whClientContext * c,
    uint8_t * out_version,
    uint8_t * out_build,
    uint32_t * out_cfg_comm_data_len,
    uint32_t * out_cfg_nvm_object_count,
    uint32_t * out_cfg_keycache_count,
    uint32_t * out_cfg_keycache_bufsize,
    uint32_t * out_cfg_keycache_bigcount,
    uint32_t * out_cfg_keycache_bigbufsize,
    uint32_t * out_cfg_customcb_count,
    uint32_t * out_cfg_dmaaddr_count,
    uint32_t * out_debug_state,
    uint32_t * out_boot_state,
    uint32_t * out_lifecycle_state,
    uint32_t * out_nvm_state
)

Receives a communication information response from the server.

Parameters:

c Pointer to the client context.
out_version Pointer to store the server version string (8 bytes)
out_build Pointer to store the server build string (8 bytes)
out_cfg_comm_data_len Pointer to store the server's maximum data len for any request or response
out_cfg_nvm_object_count Pointer to store the server's maximum number of NVM objects
out_cfg_keycache_count Pointer to store the server's number of keys in the server RAM
out_cfg_keycache_bufsize Pointer to store the server's maximum size of each key in server RAM
out_cfg_keycache_bigcount Pointer to store the server's number of big keys in the server RAM
out_cfg_keycache_bigbufsize bufsize Pointer to store the server's maximum size of each big key in server RAM
out_cfg_customcb_count Pointer to store the server's number of custom callbacks
out_cfg_dmaaddr_count Pointer to store the server's number of dmaaddr regions Growth:
out_debug_state Pointer to store the server's current debug state
out_boot_state Pointer to store the server's current boot state
out_lifecycle_state Pointer to store the server's lifecyle state
out_nvm_state Pointer to store the server's current nvm state

Return: int Returns 0 on success, or a negative error code on failure.

This function waits for and processes a communication information response message from the server. It validates the response and extracts the server configuration data from the message.

function wh_Client_CommInfo

int wh_Client_CommInfo(
    whClientContext * c,
    uint8_t * out_version,
    uint8_t * out_build,
    uint32_t * out_cfg_comm_data_len,
    uint32_t * out_cfg_nvm_object_count,
    uint32_t * out_cfg_keycache_count,
    uint32_t * out_cfg_keycache_bufsize,
    uint32_t * out_cfg_keycache_bigcount,
    uint32_t * out_cfg_keycache_bigbufsize,
    uint32_t * out_cfg_customcb_count,
    uint32_t * out_cfg_dmaaddr_count,
    uint32_t * out_debug_state,
    uint32_t * out_boot_state,
    uint32_t * out_lifecycle_state,
    uint32_t * out_nvm_state
)

Retrieves server configuration and state with a blocking call.

Parameters:

c Pointer to the client context.
out_version Pointer to store the server version string (8 bytes)
out_build Pointer to store the server build string (8 bytes)
out_cfg_comm_data_len Pointer to store the server's maximum data len for any request or response
out_cfg_nvm_object_count Pointer to store the server's maximum number of NVM objects
out_cfg_keycache_count Pointer to store the server's number of keys in the server RAM
out_cfg_keycache_bufsize Pointer to store the server's maximum size of each key in server RAM
out_cfg_keycache_bigcount Pointer to store the server's number of keys in the server RAM
out_cfg_keycache_bigbufsize Pointer to store the server's maximum size of each key in server RAM
out_cfg_customcb_count Pointer to store the server's number of custom callbacks
out_cfg_dmaaddr_count Pointer to store the server's number of dmaaddr regions Growth:
out_debug_state Pointer to store the server's current debug state
out_boot_state Pointer to store the server's current boot state
out_lifecycle_state Pointer to store the server's lifecyle state
out_nvm_state Pointer to store the server's current nvm state

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending communication info request and parsting the response from the server by busy polling for a valid response.

function wh_Client_CommCloseRequest

int wh_Client_CommCloseRequest(
    whClientContext * c
)

Sends a communication close request to the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a communication close request message to the server. It signals the server to close the communication channel with the client.

function wh_Client_EnableCancel

int wh_Client_EnableCancel(
    whClientContext * c
)

Enables request cancellation.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function allows subsequent requests to be canceled, the responses that are normally handled by automatically by wolfCrypt must be handled with a wolfHSM specific function call.

function wh_Client_DisableCancel

int wh_Client_DisableCancel(
    whClientContext * c
)

Disables request cancellation.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function disables request cancellation, making wolfCrypt automatically handle responses again.

function wh_Client_CancelRequest

int wh_Client_CancelRequest(
    whClientContext * c
)

Cancels the previous request, currently only supports CMAC. Async Request.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function sends a cancellation request to the server to cancel the previous request made. Does not wait for the response which must be handled seperately

function wh_Client_CancelResponse

int wh_Client_CancelResponse(
    whClientContext * c
)

Handles the response for a cancellation the previous request, currently only supports CMAC. Async response handler.

Parameters:

c Pointer to the client context.

Return: int Returns 0 or WH_ERROR_CANCEL_LATE on success, or a negative error code on failure.

This function handles the response for a request cancellation previously sent to the server. Blocks to wait for the response.

function wh_Client_Cancel

int wh_Client_Cancel(
    whClientContext * c
)

Cancels the previous request, currently only supports CMAC.

Parameters:

c Pointer to the client context.

Return: int Returns 0 or WH_ERROR_CANCEL_LATE on success, or a negative error code on failure.

This function sends a cancellation request to the server and waits for the response to cancel the previous request made.

function wh_Client_CommCloseResponse

int wh_Client_CommCloseResponse(
    whClientContext * c
)

Receives a communication close response from the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function checks for and processes a communication close response message from the server.

function wh_Client_CommClose

int wh_Client_CommClose(
    whClientContext * c
)

Closes communication with the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of closing communication with the server. It sends a close request and waits for a valid response to confirm that the communication channel has been closed.

function wh_Client_EchoRequest

int wh_Client_EchoRequest(
    whClientContext * c,
    uint16_t size,
    const void * data
)

Sends an echo request to the server.

Parameters:

c Pointer to the client context.
size Size of the data payload.
data Pointer to the data payload.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends an echo request message to the server. The message contains a data payload of the specified size. This function does not block; it returns immediately after sending the request.

function wh_Client_EchoResponse

int wh_Client_EchoResponse(
    whClientContext * c,
    uint16_t * out_size,
    void * data
)

Receives an echo response from the server.

Parameters:

c Pointer to the client context.
out_size Pointer to store the size of the received data payload.
data Pointer to store the received data payload.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process an echo response message from the server. It validates the response and extracts the data payload. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_Echo

int wh_Client_Echo(
    whClientContext * c,
    uint16_t snd_len,
    const void * snd_data,
    uint16_t * out_rcv_len,
    void * rcv_data
)

Sends an echo request to the server and receives the response.

Parameters:

c Pointer to the client context.
snd_len Size of the data payload to send.
snd_data Pointer to the data payload to send.
out_rcv_len Pointer to store the size of the received data payload.
rcv_data Pointer to store the received data payload.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending an echo request to the server and receiving the response. It sends the request and repeatedly attempts to receive a valid response, extracting the data payload from the response once received. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_KeyCacheRequest_ex

int wh_Client_KeyCacheRequest_ex(
    whClientContext * c,
    uint32_t flags,
    uint8_t * label,
    uint16_t labelSz,
    uint8_t * in,
    uint16_t inSz,
    uint16_t keyId
)

Sends a key cache request to the server.

Parameters:

c Pointer to the client context.
flags Flags for the key cache request.
label Pointer to the label associated with the key.
labelSz Size of the label.
in Pointer to the key data to be cached.
inSz Size of the key data.
keyId Key ID to be used for caching. If set to WH_KEYID_ERASED, a new ID will be generated.

Return: int Returns 0 on success, or a negative error code on failure.

Key functions

For client-side key data to be used, it must first be brought into the key cache (RAM) of the HSM server. Key cache requests instruct the server to transfer key data from client memory and allocate space in the HSM server RAM to hold this key. Key eviction requests instruct the HSM server to remove the key from the cache so that the RAM may be reused. Key export requests instruct the server to send back the cached key data to client RAM. Key commit requests instruct the HSM server to write the cached key into the HSM NVM. Key erase requests instruct the HSM server to remove a previously committed key from NVM.

This function prepares and sends a key cache request message to the server. The message contains the specified flags, label, and input data. This function does not block; it returns immediately after sending the request.

function wh_Client_KeyCacheRequest

int wh_Client_KeyCacheRequest(
    whClientContext * c,
    uint32_t flags,
    uint8_t * label,
    uint16_t labelSz,
    uint8_t * in,
    uint16_t inSz
)

Sends a key cache request to the server.

Parameters:

c Pointer to the client context.
flags Flags for the key cache request.
label Pointer to the label associated with the key.
labelSz Size of the label.
in Pointer to the key data to be cached.
inSz Size of the key data.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a key cache request message to the server. The message contains the specified flags, label, and input data. This function does not block; it returns immediately after sending the request.

function wh_Client_KeyCacheResponse

int wh_Client_KeyCacheResponse(
    whClientContext * c,
    uint16_t * keyId
)

Receives a key cache response from the server.

Parameters:

c Pointer to the client context.
keyId Pointer to store the key ID assigned by the server.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a key cache response message from the server. It validates the response and extracts the key ID. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_KeyCache

int wh_Client_KeyCache(
    whClientContext * c,
    uint32_t flags,
    uint8_t * label,
    uint16_t labelSz,
    uint8_t * in,
    uint16_t inSz,
    uint16_t * keyId
)

Sends a key cache request to the server and receives the response.

Parameters:

c Pointer to the client context.
flags Flags for the key cache request.
label Pointer to the label associated with the key.
labelSz Size of the label.
in Pointer to the key data to be cached.
inSz Size of the key data.
keyId Pointer to store the key ID assigned by the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a key cache request to the server and receiving the response. It sends the request and repeatedly attempts to receive a valid response, extracting the key ID from the response once received. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_KeyEvictRequest

int wh_Client_KeyEvictRequest(
    whClientContext * c,
    uint16_t keyId
)

Sends a key eviction request to the server.

Parameters:

c Pointer to the client context.
keyId Key ID to be evicted.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a key eviction request message to the server. The message contains the specified key ID. This function does not block; it returns immediately after sending the request.

function wh_Client_KeyEvictResponse

int wh_Client_KeyEvictResponse(
    whClientContext * c
)

Receives a key eviction response from the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a key eviction response message from the server. It validates the response. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_KeyEvict

int wh_Client_KeyEvict(
    whClientContext * c,
    uint16_t keyId
)

Sends a key eviction request to the server and receives the response.

Parameters:

c Pointer to the client context.
keyId Key ID to be evicted.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a key eviction request to the server and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_KeyExportRequest

int wh_Client_KeyExportRequest(
    whClientContext * c,
    uint16_t keyId
)

Sends a key export request to the server.

Parameters:

c Pointer to the client context.
keyId Key ID to be exported.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a key export request message to the server. The message contains the specified key ID. This function does not block; it returns immediately after sending the request.

function wh_Client_KeyExportResponse

int wh_Client_KeyExportResponse(
    whClientContext * c,
    uint8_t * label,
    uint16_t labelSz,
    uint8_t * out,
    uint16_t * outSz
)

Receives a key export response from the server.

Parameters:

c Pointer to the client context.
label Pointer to store the label associated with the key.
labelSz Size of the label buffer.
out Pointer to store the exported key data.
outSz Pointer to store the size of the exported key data.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a key export response message from the server. It validates the response and extracts the label and key data. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_KeyExport

int wh_Client_KeyExport(
    whClientContext * c,
    uint16_t keyId,
    uint8_t * label,
    uint16_t labelSz,
    uint8_t * out,
    uint16_t * outSz
)

Sends a key export request to the server and receives the response.

Parameters:

c Pointer to the client context.
keyId Key ID to be exported.
label Pointer to store the label associated with the key.
labelSz Size of the label buffer.
out Pointer to store the exported key data.
outSz Pointer to store the size of the exported key data.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a key export request to the server and receiving the response. It sends the request and repeatedly attempts to receive a valid response, extracting the label and key data from the response once received. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_KeyCommitRequest

int wh_Client_KeyCommitRequest(
    whClientContext * c,
    whNvmId keyId
)

Sends a key commit request to the server.

Parameters:

c Pointer to the client context.
keyId Key ID to be committed. Committing a key means making it persistent in non-volatile memory.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a key commit request message to the server. The message contains the specified key ID. This function does not block; it returns immediately after sending the request.

function wh_Client_KeyCommitResponse

int wh_Client_KeyCommitResponse(
    whClientContext * c
)

Receives a key commit response from the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a key commit response message from the server. It validates the response. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_KeyCommit

int wh_Client_KeyCommit(
    whClientContext * c,
    whNvmId keyId
)

Sends a key commit request to the server and receives the response.

Parameters:

c Pointer to the client context.
keyId Key ID to be committed. Committing a key means making it persistent in non-volatile memory.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a key commit request to the server and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_KeyEraseRequest

int wh_Client_KeyEraseRequest(
    whClientContext * c,
    whNvmId keyId
)

Sends a key erase request to the server.

Parameters:

c Pointer to the client context.
keyId Key ID to be erased.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a key erase request message to the server. The message contains the specified key ID. This function does not block; it returns immediately after sending the request.

function wh_Client_KeyEraseResponse

int wh_Client_KeyEraseResponse(
    whClientContext * c
)

Receives a key erase response from the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a key erase response message from the server. It validates the response. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_KeyErase

int wh_Client_KeyErase(
    whClientContext * c,
    whNvmId keyId
)

Sends a key erase request to the server and receives the response.

Parameters:

c Pointer to the client context.
keyId Key ID to be erased.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a key erase request to the server and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_KeyCacheDmaRequest

int wh_Client_KeyCacheDmaRequest(
    whClientContext * c,
    uint32_t flags,
    uint8_t * label,
    uint16_t labelSz,
    const void * keyAddr,
    uint16_t keySz,
    uint16_t keyId
)

Sends a key cache request using DMA to the server.

Parameters:

c Pointer to the client context.
flags Key flags.
label Optional label for the key.
labelSz Size of the label in bytes.
keyAddr DMA address of the key data.
keySz Size of the key in bytes.
keyId Key ID to be associated with the cached key.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a key cache request message using DMA addressing to the server. The message contains the key data and metadata. This function does not block; it returns immediately after sending the request.

function wh_Client_KeyCacheDmaResponse

int wh_Client_KeyCacheDmaResponse(
    whClientContext * c,
    uint16_t * keyId
)

Receives a key cache response for DMA from the server.

Parameters:

c Pointer to the client context.
keyId Pointer to store the assigned key ID.

Return: int Returns 0 on success, or a negative error code on failure.

This function processes a key cache response message for a DMA operation from the server. It validates the response and returns the assigned key ID.

function wh_Client_KeyCacheDma

int wh_Client_KeyCacheDma(
    whClientContext * c,
    uint32_t flags,
    uint8_t * label,
    uint16_t labelSz,
    const void * keyAddr,
    uint16_t keySz,
    uint16_t * keyId
)

Performs a complete key cache operation using DMA.

Parameters:

c Pointer to the client context.
flags Key flags.
label Optional label for the key.
labelSz Size of the label in bytes.
keyAddr DMA address of the key data.
keySz Size of the key in bytes.
keyId Pointer to store the assigned key ID.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of caching a key using DMA, including sending the request and receiving the response.

function wh_Client_KeyExportDmaRequest

int wh_Client_KeyExportDmaRequest(
    whClientContext * c,
    uint16_t keyId,
    const void * keyAddr,
    uint16_t keySz
)

Sends a key export request using DMA to the server.

Parameters:

c Pointer to the client context.
keyId Key ID to export.
keyAddr DMA address where the key should be exported.
keySz Size of the key buffer in bytes.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a key export request message using DMA addressing to the server.

function wh_Client_KeyExportDmaResponse

int wh_Client_KeyExportDmaResponse(
    whClientContext * c,
    uint8_t * label,
    uint16_t labelSz,
    uint16_t * outSz
)

Receives a key export response for DMA from the server.

Parameters:

c Pointer to the client context.
label Buffer to store the key's label.
labelSz Size of the label buffer.
outSz Pointer to store the actual size of the exported key.

Return: int Returns 0 on success, or a negative error code on failure.

This function processes a key export response message for a DMA operation from the server.

function wh_Client_KeyExportDma

int wh_Client_KeyExportDma(
    whClientContext * c,
    uint16_t keyId,
    const void * keyAddr,
    uint16_t keySz,
    uint8_t * label,
    uint16_t labelSz,
    uint16_t * outSz
)

Performs a complete key export operation using DMA.

Parameters:

c Pointer to the client context.
keyId Key ID to export.
keyAddr DMA address where the key should be exported.
keySz Size of the key buffer in bytes.
label Buffer to store the key's label.
labelSz Size of the label buffer.
outSz Pointer to store the actual size of the exported key.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of exporting a key using DMA, including sending the request and receiving the response.

function wh_Client_CounterInitRequest

int wh_Client_CounterInitRequest(
    whClientContext * c,
    whNvmId counterId,
    uint32_t counter
)

function wh_Client_CounterInitResponse

int wh_Client_CounterInitResponse(
    whClientContext * c,
    uint32_t * counter
)

function wh_Client_CounterInit

int wh_Client_CounterInit(
    whClientContext * c,
    whNvmId counterId,
    uint32_t * counter
)

Creates and initializes a counter with the value set in counter.

Parameters:

c Pointer to the whClientContext structure.
counterId counter ID to be associated with the counter.
counter Value to initialize the counter with, returns with the value set by the HSM for confirmation.

Return: int Returns 0 on success or a negative error code on failure.

This function creates/resets a counter with the supplied counterId and gives it the value stored in counter at the start of the call.

function wh_Client_CounterResetRequest

int wh_Client_CounterResetRequest(
    whClientContext * c,
    whNvmId counterId
)

function wh_Client_CounterResetResponse

int wh_Client_CounterResetResponse(
    whClientContext * c,
    uint32_t * counter
)

function wh_Client_CounterReset

int wh_Client_CounterReset(
    whClientContext * c,
    whNvmId counterId,
    uint32_t * counter
)

Creates and initializes a counter with to 0.

Parameters:

c Pointer to the whClientContext structure.
counterId Counter ID to be associated with the counter.
counter Value set by the HSM for confirmation.

Return: int Returns 0 on success or a negative error code on failure.

This function creates/resets a counter with the supplied counterId and gives it the value of 0.

function wh_Client_CounterIncrementRequest

int wh_Client_CounterIncrementRequest(
    whClientContext * c,
    whNvmId counterId
)

function wh_Client_CounterIncrementResponse

int wh_Client_CounterIncrementResponse(
    whClientContext * c,
    uint32_t * counter
)

function wh_Client_CounterIncrement

int wh_Client_CounterIncrement(
    whClientContext * c,
    whNvmId counterId,
    uint32_t * counter
)

Increments a counter.

Parameters:

c Pointer to the whClientContext structure.
counterId Counter ID to be associated with the counter.
counter Value set by the HSM for confirmation.

Return: int Returns 0 on success or a negative error code on failure.

This function increments a counter created previously. If the counter would roll over the HSM will saturate the value, keeping it at the uint32_t max.

function wh_Client_CounterReadRequest

int wh_Client_CounterReadRequest(
    whClientContext * c,
    whNvmId counterId
)

function wh_Client_CounterReadResponse

int wh_Client_CounterReadResponse(
    whClientContext * c,
    uint32_t * counter
)

function wh_Client_CounterRead

int wh_Client_CounterRead(
    whClientContext * c,
    whNvmId counterId,
    uint32_t * counter
)

Read a counter.

Parameters:

c Pointer to the whClientContext structure.
counterId Counter ID to be associated with the counter.
counter Value set by the HSM.

Return: int Returns 0 on success or a negative error code on failure.

This function read a counter created previously.

function wh_Client_CounterDestroyRequest

int wh_Client_CounterDestroyRequest(
    whClientContext * c,
    whNvmId counterId
)

function wh_Client_CounterDestroyResponse

int wh_Client_CounterDestroyResponse(
    whClientContext * c
)

function wh_Client_CounterDestroy

int wh_Client_CounterDestroy(
    whClientContext * c,
    whNvmId counterId
)

Destroy a counter.

Parameters:

c Pointer to the whClientContext structure.
counterId Counter ID to be associated with the counter.

Return: int Returns 0 on success or a negative error code on failure.

This function destroys an NVM counter created previously.

function wh_Client_NvmInitRequest

int wh_Client_NvmInitRequest(
    whClientContext * c
)

Sends a non-volatile memory (NVM) initialization request to the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

NVM functions

This function prepares and sends an NVM initialization request message to the server. The message contains the client NVM ID. This function does not block; it returns immediately after sending the request.

function wh_Client_NvmInitResponse

int wh_Client_NvmInitResponse(
    whClientContext * c,
    int32_t * out_rc,
    uint32_t * out_clientnvm_id,
    uint32_t * out_servernvm_id
)

Receives a non-volatile memory (NVM) initialization response from the server.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.
out_clientnvm_id Pointer to store the client NVM ID assigned by the server.
out_servernvm_id Pointer to store the server NVM ID assigned by the server.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process an NVM initialization response message from the server. It validates the response and extracts the client and server NVM IDs. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmInit

int wh_Client_NvmInit(
    whClientContext * c,
    int32_t * out_rc,
    uint32_t * out_clientnvm_id,
    uint32_t * out_servernvm_id
)

Sends a non-volatile memory (NVM) initialization request to the server and receives the response.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.
out_clientnvm_id Pointer to store the client NVM ID assigned by the server.
out_servernvm_id Pointer to store the server NVM ID assigned by the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending an NVM initialization request to the server and receiving the response. It sends the request and repeatedly attempts to receive a valid response, extracting the client and server NVM IDs from the response once received. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_NvmCleanupRequest

int wh_Client_NvmCleanupRequest(
    whClientContext * c
)

Sends a non-volatile memory (NVM) cleanup request to the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends an NVM cleanup request message to the server. This function does not block; it returns immediately after sending the request.

function wh_Client_NvmCleanupResponse

int wh_Client_NvmCleanupResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a non-volatile memory (NVM) cleanup response from the server.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process an NVM cleanup response message from the server. It validates the response. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmCleanup

int wh_Client_NvmCleanup(
    whClientContext * c,
    int32_t * out_rc
)

Sends a non-volatile memory (NVM) cleanup request to the server and receives the response.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending an NVM cleanup request to the server and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_NvmGetAvailableRequest

int wh_Client_NvmGetAvailableRequest(
    whClientContext * c
)

Sends a request to the server to get available non-volatile memory (NVM) information.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to the server to retrieve information about the available and reclaimable NVM space and objects. This function does not block; it returns immediately after sending the request.

function wh_Client_NvmGetAvailableResponse

int wh_Client_NvmGetAvailableResponse(
    whClientContext * c,
    int32_t * out_rc,
    uint32_t * out_avail_size,
    whNvmId * out_avail_objects,
    uint32_t * out_reclaim_size,
    whNvmId * out_reclaim_objects
)

Receives a response from the server with available non-volatile memory (NVM) information.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.
out_avail_size Pointer to store the available NVM size.
out_avail_objects Pointer to store the available NVM objects.
out_reclaim_size Pointer to store the reclaimable NVM size.
out_reclaim_objects Pointer to store the reclaimable NVM objects.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a response message from the server containing information about the available and reclaimable NVM space and objects. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmGetAvailable

int wh_Client_NvmGetAvailable(
    whClientContext * c,
    int32_t * out_rc,
    uint32_t * out_avail_size,
    whNvmId * out_avail_objects,
    uint32_t * out_reclaim_size,
    whNvmId * out_reclaim_objects
)

Sends a request to the server and receives a response with available non-volatile memory (NVM) information.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.
out_avail_size Pointer to store the available NVM size.
out_avail_objects Pointer to store the available NVM objects.
out_reclaim_size Pointer to store the reclaimable NVM size.
out_reclaim_objects Pointer to store the reclaimable NVM objects.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to the server to retrieve information about the available and reclaimable NVM space and objects, and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_NvmAddObjectRequest

int wh_Client_NvmAddObjectRequest(
    whClientContext * c,
    whNvmId id,
    whNvmAccess access,
    whNvmFlags flags,
    whNvmSize label_len,
    uint8_t * label,
    whNvmSize len,
    const uint8_t * data
)

Sends a request to the server to add an object to non-volatile memory (NVM).

Parameters:

c Pointer to the client context.
id The ID of the NVM object to add.
access The access permissions for the NVM object.
flags Flags associated with the NVM object.
label_len The length of the label.
label Pointer to the label data.
len The length of the data.
data Pointer to the data to be added.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to the server to add an object to the NVM. The request includes the object ID, access permissions, flags, label, and data. This function does not block; it returns immediately after sending the request.

function wh_Client_NvmAddObjectResponse

int wh_Client_NvmAddObjectResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after attempting to add an object to non-volatile memory (NVM).

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a response message from the server after an add object request. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmAddObject

int wh_Client_NvmAddObject(
    whClientContext * c,
    whNvmId id,
    whNvmAccess access,
    whNvmFlags flags,
    whNvmSize label_len,
    uint8_t * label,
    whNvmSize len,
    const uint8_t * data,
    int32_t * out_rc
)

Sends a request to the server and receives a response to add an object to non-volatile memory (NVM).

Parameters:

c Pointer to the client context.
id The ID of the NVM object to add.
access The access permissions for the NVM object.
flags Flags associated with the NVM object.
label_len The length of the label.
label Pointer to the label data.
len The length of the data.
data Pointer to the data to be added.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to the server to add an object to the NVM and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_NvmListRequest

int wh_Client_NvmListRequest(
    whClientContext * c,
    whNvmAccess access,
    whNvmFlags flags,
    whNvmId start_id
)

Sends a request to the server to list non-volatile memory (NVM) objects.

Parameters:

c Pointer to the client context.
access The access permissions for the NVM objects to list.
flags Flags associated with the NVM objects to list.
start_id The starting ID of the NVM objects to list.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to the server to list NVM objects. The request includes the access permissions, flags, and the starting object ID. This function does not block; it returns immediately after sending the request.

function wh_Client_NvmListResponse

int wh_Client_NvmListResponse(
    whClientContext * c,
    int32_t * out_rc,
    whNvmId * out_count,
    whNvmId * out_id
)

Receives a response from the server with a list of non-volatile memory (NVM) objects.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.
out_count Pointer to store the count of NVM objects that match the criteria.
out_id Pointer to store the ID of the first matching NVM object.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a response message from the server containing a list of NVM objects. It validates the response and extracts the return code, count of objects, and the object IDs. The count is the number of objects that match the flags/access pattern starting at start_id. The out_id is the first matching object ID. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmList

int wh_Client_NvmList(
    whClientContext * c,
    whNvmAccess access,
    whNvmFlags flags,
    whNvmId start_id,
    int32_t * out_rc,
    whNvmId * out_count,
    whNvmId * out_id
)

Sends a request to the server and receives a response to list non-volatile memory (NVM) objects.

Parameters:

c Pointer to the client context.
access The access permissions for the NVM objects to list.
flags Flags associated with the NVM objects to list.
start_id The starting ID of the NVM objects to list.
out_rc Pointer to store the return code from the server.
out_count Pointer to store the count of NVM objects that match the criteria.
out_id Pointer to store the ID of the first matching NVM object.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to the server to list NVM objects and receiving the response. It sends the request and repeatedly attempts to receive a valid response. The count is the number of objects that match the flags/access pattern starting at start_id. The out_id is the first matching object ID. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_NvmGetMetadataRequest

int wh_Client_NvmGetMetadataRequest(
    whClientContext * c,
    whNvmId id
)

Sends a request to the server to get metadata of a non-volatile memory (NVM) object.

Parameters:

c Pointer to the client context.
id The ID of the NVM object for which metadata is requested.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to the server to retrieve metadata for a specific NVM object. The request includes the object ID. This function does not block; it returns immediately after sending the request.

function wh_Client_NvmGetMetadataResponse

int wh_Client_NvmGetMetadataResponse(
    whClientContext * c,
    int32_t * out_rc,
    whNvmId * out_id,
    whNvmAccess * out_access,
    whNvmFlags * out_flags,
    whNvmSize * out_len,
    whNvmSize label_len,
    uint8_t * label
)

Receives a response from the server with metadata of a non-volatile memory (NVM) object.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.
out_id Pointer to store the ID of the NVM object.
out_access Pointer to store the access permissions of the NVM object.
out_flags Pointer to store the flags of the NVM object.
out_len Pointer to store the length of the data.
label_len The length of the label buffer.
label Pointer to store the label data.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a response message from the server containing metadata of an NVM object. It validates the response and extracts the return code, object ID, access permissions, flags, data length, and label. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmGetMetadata

int wh_Client_NvmGetMetadata(
    whClientContext * c,
    whNvmId id,
    int32_t * out_rc,
    whNvmId * out_id,
    whNvmAccess * out_access,
    whNvmFlags * out_flags,
    whNvmSize * out_len,
    whNvmSize label_len,
    uint8_t * label
)

Sends a request to the server and receives a response to get metadata of a non-volatile memory (NVM) object.

Parameters:

c Pointer to the client context.
id The ID of the NVM object for which metadata is requested.
out_rc Pointer to store the return code from the server.
out_id Pointer to store the ID of the NVM object.
out_access Pointer to store the access permissions of the NVM object.
out_flags Pointer to store the flags of the NVM object.
out_len Pointer to store the length of the data.
label_len The length of the label buffer.
label Pointer to store the label data.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to the server to get metadata of an NVM object and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_NvmDestroyObjectsRequest

int wh_Client_NvmDestroyObjectsRequest(
    whClientContext * c,
    whNvmId list_count,
    const whNvmId * id_list
)

Sends a request to the server to destroy non-volatile memory (NVM) objects.

Parameters:

c Pointer to the client context.
list_count The number of NVM objects to destroy.
id_list Pointer to an array of IDs of the NVM objects to destroy.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to the server to destroy a list of NVM objects. The request includes the count of objects and their IDs. This function does not block; it returns immediately after sending the request.

function wh_Client_NvmDestroyObjectsResponse

int wh_Client_NvmDestroyObjectsResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after attempting to destroy non-volatile memory (NVM) objects.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a response message from the server after attempting to destroy NVM objects. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmDestroyObjects

int wh_Client_NvmDestroyObjects(
    whClientContext * c,
    whNvmId list_count,
    const whNvmId * id_list,
    int32_t * out_rc
)

Sends a request to the server and receives a response to destroy non-volatile memory (NVM) objects.

Parameters:

c Pointer to the client context.
list_count The number of NVM objects to destroy.
id_list Pointer to an array of IDs of the NVM objects to destroy.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to the server to destroy NVM objects and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_NvmReadRequest

int wh_Client_NvmReadRequest(
    whClientContext * c,
    whNvmId id,
    whNvmSize offset,
    whNvmSize data_len
)

Sends a request to the server to read data from a non-volatile memory (NVM) object.

Parameters:

c Pointer to the client context.
id The ID of the NVM object to read from.
offset The offset within the NVM object data to start reading from.
data_len The length of data to read.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to the server to read data from a specific NVM object. The request includes the object ID, the offset within the NVM object data to start reading from, and the length of data to read. This function does not block; it returns immediately after sending the request.

function wh_Client_NvmReadResponse

int wh_Client_NvmReadResponse(
    whClientContext * c,
    int32_t * out_rc,
    whNvmSize * out_len,
    uint8_t * data
)

Receives a response from the server with NVM object data.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.
out_len Pointer to store the length of the data read.
data Pointer to store the NVM object data.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a response message from the server containing NVM object data. It validates the response and extracts the return code, the length of the data read, and the data itself. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmRead

int wh_Client_NvmRead(
    whClientContext * c,
    whNvmId id,
    whNvmSize offset,
    whNvmSize data_len,
    int32_t * out_rc,
    whNvmSize * out_len,
    uint8_t * data
)

Sends a request to the server and receives a response to read data from a non-volatile memory (NVM) object.

Parameters:

c Pointer to the client context.
id The ID of the NVM object to read from.
offset The offset within the NVM object data to start reading from.
data_len The length of data to read.
out_rc Pointer to store the return code from the server.
out_len Pointer to store the length of the data read.
data Pointer to store the NVM object data.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to the server to read data from an NVM object and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_NvmAddObjectDmaRequest

int wh_Client_NvmAddObjectDmaRequest(
    whClientContext * c,
    whNvmMetadata * metadata,
    whNvmSize data_len,
    const uint8_t * data
)

Sends a request to the server to add an object to non-volatile memory (NVM) using DMA.

Parameters:

c Pointer to the client context.
metadata Pointer to the metadata.
data_len The length of the data to be added.
data Pointer to the data to be added.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to the server to add an object to NVM using DMA. The request includes the metadata client address, the length of the data, and the data client address. This function does not block; it returns immediately after sending the request.

function wh_Client_NvmAddObjectDmaResponse

int wh_Client_NvmAddObjectDmaResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after attempting to add an object to non-volatile memory (NVM) using DMA.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a response message from the server after attempting to add an object to NVM using DMA. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmAddObjectDma

int wh_Client_NvmAddObjectDma(
    whClientContext * c,
    whNvmMetadata * metadata,
    whNvmSize data_len,
    const uint8_t * data,
    int32_t * out_rc
)

Sends a request to the server and receives a response to add an object to non-volatile memory (NVM) using DMA.

Parameters:

c Pointer to the client context.
metadata Pointer to the metadata.
data_len The length of the data to be added.
data Pointer to the data to be added.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to the server to add an object to NVM using DMA and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_NvmReadDmaRequest

int wh_Client_NvmReadDmaRequest(
    whClientContext * c,
    whNvmId id,
    whNvmSize offset,
    whNvmSize data_len,
    uint8_t * data
)

function wh_Client_NvmReadDmaResponse

int wh_Client_NvmReadDmaResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after attempting to read data from non-volatile memory (NVM) using DMA, with automatic detection of client address width (32-bit or 64-bit).

Parameters:

c Pointer to the client context.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a response message from the server after attempting to read data from NVM using DMA. The client address width (32-bit or 64-bit) is automatically detected. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_NvmReadDma

int wh_Client_NvmReadDma(
    whClientContext * c,
    whNvmId id,
    whNvmSize offset,
    whNvmSize data_len,
    uint8_t * data,
    int32_t * out_rc
)

Sends a request to the server and receives a response to read data from non-volatile memory (NVM) using DMA, with automatic detection of client address width (32-bit or 64-bit).

Parameters:

c Pointer to the client context.
id The NVM ID of the object to read.
offset The offset within the object to start reading from.
data_len The length of the data to be read.
data Pointer to the data buffer where the data will be read into.
out_rc Pointer to store the return code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to the server to read data from NVM using DMA and receiving the response. The client address width (32-bit or 64-bit) is automatically detected. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_CustomCbRequest

int wh_Client_CustomCbRequest(
    whClientContext * c,
    const whMessageCustomCb_Request * req
)

Sends a custom callback request to the server.

Parameters:

c Pointer to the client context.
req Pointer to the custom callback request structure.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a custom callback request to the server. The request includes the custom callback request structure. This function does not block; it returns immediately after sending the request.

function wh_Client_CustomCbResponse

int wh_Client_CustomCbResponse(
    whClientContext * c,
    whMessageCustomCb_Response * resp
)

Receives a response from the server after sending a custom callback request.

Parameters:

c Pointer to the client context.
resp Pointer to store the custom callback response from the server.

Return: int Returns 0 on success, WH_ERROR_NOTREADY if no response is available, or a negative error code on failure.

This function attempts to process a response message from the server after sending a custom callback request. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CustomCheckRegisteredRequest

int wh_Client_CustomCheckRegisteredRequest(
    whClientContext * c,
    uint32_t id
)

Sends a request to the server to check if a custom callback is registered.

Parameters:

c Pointer to the client context.
id The ID of the custom callback to check.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to the server to check if a custom callback is registered. The request includes the callback ID. This function does not block; it returns immediately after sending the request.

function wh_Client_CustomCbCheckRegisteredResponse

int wh_Client_CustomCbCheckRegisteredResponse(
    whClientContext * c,
    uint16_t * outId,
    int * responseError
)

Receives a response from the server after checking if a custom callback is registered.

Parameters:

c Pointer to the client context.
outId Pointer to store the callback ID from the server.
responseError Pointer to store the response error code from the server.

Return: int Returns 0 if the callback is registered, WH_ERROR_NOHANDLER if it is not registered, or a negative error code on failure.

This function attempts to process a response message from the server after checking if a custom callback is registered. It validates the response and extracts the return code and callback ID. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CustomCbCheckRegistered

int wh_Client_CustomCbCheckRegistered(
    whClientContext * c,
    uint16_t id,
    int * responseError
)

Sends a request to the server and receives a response to check if a custom callback is registered.

Parameters:

c Pointer to the client context.
id The ID of the custom callback to check.
responseError Pointer to store the response error code from the server.

Return: int Returns 0 if the callback is registered, WH_ERROR_NOHANDLER if it is not registered, or a negative error code on failure.

This function handles the complete process of sending a request to the server to check if a custom callback is registered and receiving the response. It sends the request and repeatedly attempts to receive a valid response. This function blocks until the entire operation is complete or an error occurs.

function wh_Client_CertInitRequest

int wh_Client_CertInitRequest(
    whClientContext * c
)

Sends a request to initialize the certificate manager on the server.

Parameters:

c Pointer to the client context.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to initialize the certificate manager on the server. This function does not block; it returns immediately after sending the request.

function wh_Client_CertInitResponse

int wh_Client_CertInitResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after initializing the certificate manager.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after initializing the certificate manager. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertInit

int wh_Client_CertInit(
    whClientContext * c,
    int32_t * out_rc
)

Sends a request and receives a response to initialize the certificate manager.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to initialize the certificate manager and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertAddTrustedRequest

int wh_Client_CertAddTrustedRequest(
    whClientContext * c,
    whNvmId id,
    const uint8_t * cert,
    uint32_t cert_len
)

Sends a request to add a trusted certificate to NVM storage.

Parameters:

c Pointer to the client context.
id The NVM ID to store the certificate.
cert Pointer to the certificate data.
cert_len Length of the certificate data.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to add a trusted certificate to NVM storage. This function does not block; it returns immediately after sending the request.

function wh_Client_CertAddTrustedResponse

int wh_Client_CertAddTrustedResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after adding a trusted certificate.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after adding a trusted certificate. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertAddTrusted

int wh_Client_CertAddTrusted(
    whClientContext * c,
    whNvmId id,
    const uint8_t * cert,
    uint32_t cert_len,
    int32_t * out_rc
)

Sends a request and receives a response to add a trusted certificate.

Parameters:

c Pointer to the client context.
id The NVM ID to store the certificate.
cert Pointer to the certificate data.
cert_len Length of the certificate data.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to add a trusted certificate and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertEraseTrustedRequest

int wh_Client_CertEraseTrustedRequest(
    whClientContext * c,
    whNvmId id
)

Sends a request to erase a trusted certificate from NVM storage.

Parameters:

c Pointer to the client context.
id The NVM ID of the certificate to delete.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to erase a trusted certificate from NVM storage. This function does not block; it returns immediately after sending the request.

function wh_Client_CertEraseTrustedResponse

int wh_Client_CertEraseTrustedResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after erasing a trusted certificate.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after erasing a trusted certificate. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertEraseTrusted

int wh_Client_CertEraseTrusted(
    whClientContext * c,
    whNvmId id,
    int32_t * out_rc
)

Sends a request and receives a response to erase a trusted certificate.

Parameters:

c Pointer to the client context.
id The NVM ID of the certificate to delete.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to erase a trusted certificate and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertReadTrustedRequest

int wh_Client_CertReadTrustedRequest(
    whClientContext * c,
    whNvmId id,
    uint32_t cert_len
)

Sends a request to read a trusted certificate from NVM storage.

Parameters:

c Pointer to the client context.
id The NVM ID of the certificate to retrieve.
cert_len Maximum length of the certificate buffer.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to read a trusted certificate from NVM storage. This function does not block; it returns immediately after sending the request.

function wh_Client_CertReadTrustedResponse

int wh_Client_CertReadTrustedResponse(
    whClientContext * c,
    uint8_t * cert,
    uint32_t * cert_len,
    int32_t * out_rc
)

Receives a response from the server after getting a trusted certificate.

Parameters:

c Pointer to the client context.
cert Pointer to store the certificate data.
cert_len Pointer to the maximum length of the certificate buffer. On output, contains the actual length of the certificate.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after getting a trusted certificate. It validates the response, extracts the certificate data, and updates the certificate length. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertReadTrusted

int wh_Client_CertReadTrusted(
    whClientContext * c,
    whNvmId id,
    uint8_t * cert,
    uint32_t * cert_len,
    int32_t * out_rc
)

Sends a request and receives a response to read a trusted certificate.

Parameters:

c Pointer to the client context.
id The NVM ID of the certificate to retrieve.
cert Pointer to store the certificate data.
cert_len Pointer to the maximum length of the certificate buffer. On output, contains the actual length of the certificate.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to read a trusted certificate and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertVerifyRequest

int wh_Client_CertVerifyRequest(
    whClientContext * c,
    const uint8_t * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId
)

Sends a request to verify a certificate against trusted certificates.

Parameters:

c Pointer to the client context.
cert Pointer to the certificate data to verify.
cert_len Length of the certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to verify a certificate against trusted certificates. This function does not block; it returns immediately after sending the request.

function wh_Client_CertVerifyResponse

int wh_Client_CertVerifyResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after verifying a certificate.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after verifying a certificate. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertVerify

int wh_Client_CertVerify(
    whClientContext * c,
    const uint8_t * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId,
    int32_t * out_rc
)

Sends a request and receives a response to verify a certificate.

Parameters:

c Pointer to the client context.
cert Pointer to the certificate data to verify.
cert_len Length of the certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to verify a certificate and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertVerifyAndCacheLeafPubKeyRequest

int wh_Client_CertVerifyAndCacheLeafPubKeyRequest(
    whClientContext * c,
    const uint8_t * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId,
    whKeyId keyId
)

Sends a request to verify a certificate and cache the leaf public key.

Parameters:

c Pointer to the client context.
cert Pointer to the certificate data to verify.
cert_len Length of the certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.
keyId The keyId to cache the leaf public key in. If set to WH_KEYID_ERASED, the server will pick a keyId.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to verify a certificate and also instructs the server to cache the public key of the leaf certificate. This function does not block; it returns immediately after sending the request.

function wh_Client_CertVerifyAndCacheLeafPubKeyResponse

int wh_Client_CertVerifyAndCacheLeafPubKeyResponse(
    whClientContext * c,
    whKeyId * out_keyId,
    int32_t * out_rc
)

Receives a response from the server after verifying a certificate and caching the leaf public key.

Parameters:

c Pointer to the client context.
out_keyId Pointer to store the key ID of the cached leaf public key.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after verifying a certificate and caching the leaf public key. It validates the response and extracts the return code and key ID. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertVerifyAndCacheLeafPubKey

int wh_Client_CertVerifyAndCacheLeafPubKey(
    whClientContext * c,
    const uint8_t * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId,
    whKeyId * inout_keyId,
    int32_t * out_rc
)

Sends a request and receives a response to verify a certificate, while also instructing the server to cache the public key of the leaf certificate.

Parameters:

c Pointer to the client context.
cert Pointer to the certificate data to verify.
cert_len Length of the certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.
inout_keyId Pointer to the desired key ID of the cached leaf public key. If set to WH_KEYID_ERASED, the server will pick a keyId. On output, contains the keyId of the cached leaf public key.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to verify a certificate and cache the leaf public key, and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertAddTrustedDmaRequest

int wh_Client_CertAddTrustedDmaRequest(
    whClientContext * c,
    whNvmId id,
    const void * cert,
    uint32_t cert_len
)

Sends a request to add a trusted certificate to NVM storage using DMA.

Parameters:

c Pointer to the client context.
id NVM ID to store the trusted certificate.
cert Pointer to the certificate data to add.
cert_len Length of the certificate data.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to add a trusted certificate to NVM storage using DMA. This function does not block; it returns immediately after sending the request.

function wh_Client_CertAddTrustedDmaResponse

int wh_Client_CertAddTrustedDmaResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after adding a trusted certificate using DMA.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after adding a trusted certificate using DMA. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertAddTrustedDma

int wh_Client_CertAddTrustedDma(
    whClientContext * c,
    whNvmId id,
    const void * cert,
    uint32_t cert_len,
    int32_t * out_rc
)

Sends a request and receives a response to add a trusted certificate using DMA.

Parameters:

c Pointer to the client context.
id NVM ID to store the trusted certificate.
cert Pointer to the certificate data to add.
cert_len Length of the certificate data.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to add a trusted certificate using DMA and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertReadTrustedDmaRequest

int wh_Client_CertReadTrustedDmaRequest(
    whClientContext * c,
    whNvmId id,
    void * cert,
    uint32_t cert_len
)

Sends a request to read a trusted certificate from NVM storage using DMA.

Parameters:

c Pointer to the client context.
id NVM ID of the trusted certificate to get.
cert Pointer to buffer to store the certificate data.
cert_len Length of the certificate buffer.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to read a trusted certificate from NVM storage using DMA. This function does not block; it returns immediately after sending the request.

function wh_Client_CertReadTrustedDmaResponse

int wh_Client_CertReadTrustedDmaResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after reading a trusted certificate using DMA.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after reading a trusted certificate using DMA. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertReadTrustedDma

int wh_Client_CertReadTrustedDma(
    whClientContext * c,
    whNvmId id,
    void * cert,
    uint32_t cert_len,
    int32_t * out_rc
)

Sends a request and receives a response to read trusted certificate using DMA.

Parameters:

c Pointer to the client context.
id NVM ID of the trusted certificate to get.
cert Pointer to buffer to store the certificate data.
cert_len Length of the certificate buffer.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to read a trusted certificate using DMA and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertVerifyDmaRequest

int wh_Client_CertVerifyDmaRequest(
    whClientContext * c,
    const void * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId
)

Sends a request to verify a certificate using DMA.

Parameters:

c Pointer to the client context.
cert Pointer to the certificate data to verify.
cert_len Length of the certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to verify a certificate using DMA. This function does not block; it returns immediately after sending the request.

function wh_Client_CertVerifyDmaResponse

int wh_Client_CertVerifyDmaResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after verifying a certificate using DMA.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after verifying a certificate using DMA. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertVerifyDma

int wh_Client_CertVerifyDma(
    whClientContext * c,
    const void * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId,
    int32_t * out_rc
)

Sends a request and receives a response to verify a certificate using DMA.

Parameters:

c Pointer to the client context.
cert Pointer to the certificate data to verify.
cert_len Length of the certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to verify a certificate using DMA and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertVerifyDmaAndCacheLeafPubKeyRequest

int wh_Client_CertVerifyDmaAndCacheLeafPubKeyRequest(
    whClientContext * c,
    const void * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId,
    whKeyId keyId
)

Sends a request to verify a certificate using DMA and cache the leaf certificate public key.

Parameters:

c Pointer to the client context.
cert Pointer to the certificate data to verify.
cert_len Length of the certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.
keyId The keyId to cache the leaf public key in. If set to WH_KEYID_ERASED, the server will pick a keyId.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to verify a certificate using DMA and also instructs the server to cache the public key of the leaf certificate. This function does not block; it returns immediately after sending the request.

function wh_Client_CertVerifyDmaAndCacheLeafPubKeyResponse

int wh_Client_CertVerifyDmaAndCacheLeafPubKeyResponse(
    whClientContext * c,
    whKeyId * out_keyId,
    int32_t * out_rc
)

Receives a response from the server after verifying a certificate using DMA and caching the leaf public key.

Parameters:

c Pointer to the client context.
out_keyId Pointer to store the key ID of the cached leaf public key.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after verifying a certificate using DMA and caching the leaf public key. It validates the response and extracts the return code and key ID. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertVerifyDmaAndCacheLeafPubKey

int wh_Client_CertVerifyDmaAndCacheLeafPubKey(
    whClientContext * c,
    const void * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId,
    whKeyId * inout_keyId,
    int32_t * out_rc
)

Sends a request and receives a response to verify a certificate using DMA and cache the leaf certificate public key.

Parameters:

c Pointer to the client context.
cert Pointer to the certificate data to verify.
cert_len Length of the certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.
inout_keyId Pointer to the desired key ID of the cached leaf public key. If set to WH_KEYID_ERASED, the server will pick a keyId. On output, contains the keyId of the cached leaf public key.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to verify a certificate using DMA and cache the leaf certificate public key, and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertVerifyAcertRequest

int wh_Client_CertVerifyAcertRequest(
    whClientContext * c,
    const void * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId
)

Sends a request to verify an attribute certificate.

Parameters:

c Pointer to the client context.
cert Pointer to the attribute certificate data to verify.
cert_len Length of the attribute certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a request to verify an attribute certificate against a trusted root certificate. This function does not block; it returns immediately after sending the request.

function wh_Client_CertVerifyAcertResponse

int wh_Client_CertVerifyAcertResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after verifying an attribute certificate.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after verifying an attribute certificate. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertVerifyAcert

int wh_Client_CertVerifyAcert(
    whClientContext * c,
    const void * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId,
    int32_t * out_rc
)

Sends a request and receives a response to verify an attribute certificate.

Parameters:

c Pointer to the client context.
cert Pointer to the attribute certificate data to verify.
cert_len Length of the attribute certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a request to verify an attribute certificate and receiving the response. It blocks until the entire operation is complete or an error occurs.

function wh_Client_CertVerifyAcertDmaRequest

int wh_Client_CertVerifyAcertDmaRequest(
    whClientContext * c,
    const void * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId
)

Prepares and sends a DMA request to verify an attribute certificate.

Parameters:

c Pointer to the client context.
cert Pointer to the attribute certificate data to verify.
cert_len Length of the attribute certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.

Return: int Returns 0 on success, or a negative error code on failure.

This function prepares and sends a DMA request to verify an attribute certificate against a trusted root certificate. This function does not block; it returns immediately after sending the request.

function wh_Client_CertVerifyAcertDmaResponse

int wh_Client_CertVerifyAcertDmaResponse(
    whClientContext * c,
    int32_t * out_rc
)

Receives a response from the server after verifying an attribute certificate using DMA.

Parameters:

c Pointer to the client context.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function attempts to process a response message from the server after verifying an attribute certificate using DMA. It validates the response and extracts the return code. This function does not block; it returns WH_ERROR_NOTREADY if a response has not been received.

function wh_Client_CertVerifyAcertDma

int wh_Client_CertVerifyAcertDma(
    whClientContext * c,
    const void * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId,
    int32_t * out_rc
)

Sends a DMA request and receives a response to verify an attribute certificate.

Parameters:

c Pointer to the client context.
cert Pointer to the attribute certificate data to verify.
cert_len Length of the attribute certificate data.
trustedRootNvmId NVM ID of the trusted root certificate to verify against.
out_rc Pointer to store the response code from the server.

Return: int Returns 0 on success, or a negative error code on failure.

This function handles the complete process of sending a DMA request to verify an attribute certificate and receiving the response. It blocks until the entire operation is complete or an error occurs.

Attributes Documentation

variable WH_DEV_IDS_ARRAY

const int[WH_NUM_DEVIDS] WH_DEV_IDS_ARRAY;

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_client.h
 *
 * Base WolfHSM Client Library API
 *
 * The WolfHSM Client provides a single context and connection to a
 * WolfHSM Server.  All communications and state are internally managed by
 * registering a crypto callback function to be invoked synchronously when
 * wolfCrypt functions are called.  In order to specify to use the WolfHSM
 * Server for cryptographic operations, the device id WH_DEV_ID should be
 * passed into any of the wolfCrypt init functions.
 *
 * In addition to the offload of cryptographic functions, the WolfHSM Client
 * also exposes WolfHSM Server key management, non-volatile memory, and protocol
 * functions.
 *
 */

#ifndef WOLFHSM_WH_CLIENT_H_
#define WOLFHSM_WH_CLIENT_H_

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

/* System libraries */
#include <stdint.h>

/* Common WolfHSM types and defines shared with the server */
#include "wolfhsm/wh_common.h"

/* Component includes */
#include "wolfhsm/wh_comm.h"
#include "wolfhsm/wh_message_customcb.h"


#ifndef WOLFHSM_CFG_NO_CRYPTO

/* Device Id to be registered and passed to wolfCrypt functions */
enum WH_CLIENT_DEVID_ENUM {
    WH_DEV_ID = 0x5748534D, /* "WHSM" */
#ifdef WOLFHSM_CFG_DMA
    WH_DEV_ID_DMA = 0x57444D41, /* "WDMA" */
    WH_NUM_DEVIDS = 2
#else
    WH_NUM_DEVIDS = 1
#endif
};
extern const int WH_DEV_IDS_ARRAY[WH_NUM_DEVIDS];
#endif

typedef int (*whClientCancelCb)(uint16_t cancelSeq);

/* Client context */
struct whClientContext_t {
    uint16_t     last_req_id;
    uint16_t     last_req_kind;
    uint8_t      cancelable;
    whCommClient comm[1];
    whClientCancelCb cancelCb;
};
typedef struct whClientContext_t whClientContext;

struct whClientConfig_t {
    whCommClientConfig* comm;
    whClientCancelCb cancelCb;
};
typedef struct whClientConfig_t whClientConfig;


int wh_Client_Init(whClientContext* c, const whClientConfig* config);

int wh_Client_Cleanup(whClientContext* c);


int wh_Client_SendRequest(whClientContext* c, uint16_t group, uint16_t action,
                          uint16_t data_size, const void* data);
int wh_Client_RecvResponse(whClientContext* c, uint16_t* out_group,
                           uint16_t* out_action, uint16_t* out_size,
                           void* data);


int wh_Client_CommInitRequest(whClientContext* c);

int wh_Client_CommInitResponse(whClientContext* c, uint32_t* out_clientid,
                               uint32_t* out_serverid);

int wh_Client_CommInit(whClientContext* c, uint32_t* out_clientid,
                       uint32_t* out_serverid);


int wh_Client_CommInfoRequest(whClientContext* c);

int wh_Client_CommInfoResponse(whClientContext* c,
        uint8_t* out_version,
        uint8_t* out_build,
        uint32_t *out_cfg_comm_data_len,
        uint32_t *out_cfg_nvm_object_count,
        uint32_t *out_cfg_keycache_count,
        uint32_t *out_cfg_keycache_bufsize,
        uint32_t *out_cfg_keycache_bigcount,
        uint32_t *out_cfg_keycache_bigbufsize,
        uint32_t *out_cfg_customcb_count,
        uint32_t *out_cfg_dmaaddr_count,
        uint32_t *out_debug_state,
        uint32_t *out_boot_state,
        uint32_t *out_lifecycle_state,
        uint32_t *out_nvm_state);

int wh_Client_CommInfo(whClientContext* c,
        uint8_t* out_version,
        uint8_t* out_build,
        uint32_t *out_cfg_comm_data_len,
        uint32_t *out_cfg_nvm_object_count,
        uint32_t *out_cfg_keycache_count,
        uint32_t *out_cfg_keycache_bufsize,
        uint32_t *out_cfg_keycache_bigcount,
        uint32_t *out_cfg_keycache_bigbufsize,
        uint32_t *out_cfg_customcb_count,
        uint32_t *out_cfg_dmaaddr_count,
        uint32_t *out_debug_state,
        uint32_t *out_boot_state,
        uint32_t *out_lifecycle_state,
        uint32_t *out_nvm_state);

int wh_Client_CommCloseRequest(whClientContext* c);

int wh_Client_EnableCancel(whClientContext* c);

int wh_Client_DisableCancel(whClientContext* c);

int wh_Client_CancelRequest(whClientContext* c);
int wh_Client_CancelResponse(whClientContext* c);
int wh_Client_Cancel(whClientContext* c);

int wh_Client_CommCloseResponse(whClientContext* c);

int wh_Client_CommClose(whClientContext* c);

int wh_Client_EchoRequest(whClientContext* c, uint16_t size, const void* data);

int wh_Client_EchoResponse(whClientContext* c, uint16_t* out_size, void* data);

int wh_Client_Echo(whClientContext* c, uint16_t snd_len, const void* snd_data,
                   uint16_t* out_rcv_len, void* rcv_data);

int wh_Client_KeyCacheRequest_ex(whClientContext* c, uint32_t flags,
                                 uint8_t* label, uint16_t labelSz, uint8_t* in,
                                 uint16_t inSz, uint16_t keyId);

int wh_Client_KeyCacheRequest(whClientContext* c, uint32_t flags,
                              uint8_t* label, uint16_t labelSz, uint8_t* in,
                              uint16_t inSz);

int wh_Client_KeyCacheResponse(whClientContext* c, uint16_t* keyId);

int wh_Client_KeyCache(whClientContext* c, uint32_t flags, uint8_t* label,
                       uint16_t labelSz, uint8_t* in, uint16_t inSz,
                       uint16_t* keyId);

int wh_Client_KeyEvictRequest(whClientContext* c, uint16_t keyId);

int wh_Client_KeyEvictResponse(whClientContext* c);

int wh_Client_KeyEvict(whClientContext* c, uint16_t keyId);

int wh_Client_KeyExportRequest(whClientContext* c, uint16_t keyId);

int wh_Client_KeyExportResponse(whClientContext* c, uint8_t* label,
                                uint16_t labelSz, uint8_t* out,
                                uint16_t* outSz);

int wh_Client_KeyExport(whClientContext* c, uint16_t keyId, uint8_t* label,
                        uint16_t labelSz, uint8_t* out, uint16_t* outSz);

int wh_Client_KeyCommitRequest(whClientContext* c, whNvmId keyId);

int wh_Client_KeyCommitResponse(whClientContext* c);

int wh_Client_KeyCommit(whClientContext* c, whNvmId keyId);

int wh_Client_KeyEraseRequest(whClientContext* c, whNvmId keyId);

int wh_Client_KeyEraseResponse(whClientContext* c);

int wh_Client_KeyErase(whClientContext* c, whNvmId keyId);

#ifdef WOLFHSM_CFG_DMA

int wh_Client_KeyCacheDmaRequest(whClientContext* c, uint32_t flags,
                                 uint8_t* label, uint16_t labelSz,
                                 const void* keyAddr, uint16_t keySz,
                                 uint16_t keyId);

int wh_Client_KeyCacheDmaResponse(whClientContext* c, uint16_t* keyId);

int wh_Client_KeyCacheDma(whClientContext* c, uint32_t flags, uint8_t* label,
                          uint16_t labelSz, const void* keyAddr, uint16_t keySz,
                          uint16_t* keyId);

int wh_Client_KeyExportDmaRequest(whClientContext* c, uint16_t keyId,
                                  const void* keyAddr, uint16_t keySz);

int wh_Client_KeyExportDmaResponse(whClientContext* c, uint8_t* label,
                                   uint16_t labelSz, uint16_t* outSz);

int wh_Client_KeyExportDma(whClientContext* c, uint16_t keyId,
                           const void* keyAddr, uint16_t keySz, uint8_t* label,
                           uint16_t labelSz, uint16_t* outSz);
#endif /* WOLFHSM_CFG_DMA */


/* Counter functions */
int wh_Client_CounterInitRequest(whClientContext* c, whNvmId counterId,
    uint32_t counter);
int wh_Client_CounterInitResponse(whClientContext* c, uint32_t* counter);
int wh_Client_CounterInit(whClientContext* c, whNvmId counterId,
    uint32_t* counter);

int wh_Client_CounterResetRequest(whClientContext* c, whNvmId counterId);
int wh_Client_CounterResetResponse(whClientContext* c, uint32_t* counter);
int wh_Client_CounterReset(whClientContext* c, whNvmId counterId,
    uint32_t* counter);

int wh_Client_CounterIncrementRequest(whClientContext* c, whNvmId counterId);
int wh_Client_CounterIncrementResponse(whClientContext* c, uint32_t* counter);
int wh_Client_CounterIncrement(whClientContext* c, whNvmId counterId,
    uint32_t* counter);

int wh_Client_CounterReadRequest(whClientContext* c, whNvmId counterId);
int wh_Client_CounterReadResponse(whClientContext* c, uint32_t* counter);
int wh_Client_CounterRead(whClientContext* c, whNvmId counterId,
    uint32_t* counter);

int wh_Client_CounterDestroyRequest(whClientContext* c, whNvmId counterId);
int wh_Client_CounterDestroyResponse(whClientContext* c);
int wh_Client_CounterDestroy(whClientContext* c, whNvmId counterId);

int wh_Client_NvmInitRequest(whClientContext* c);

int wh_Client_NvmInitResponse(whClientContext* c, int32_t* out_rc,
                              uint32_t* out_clientnvm_id,
                              uint32_t* out_servernvm_id);

int wh_Client_NvmInit(whClientContext* c, int32_t* out_rc,
                      uint32_t* out_clientnvm_id, uint32_t* out_servernvm_id);

int wh_Client_NvmCleanupRequest(whClientContext* c);

int wh_Client_NvmCleanupResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_NvmCleanup(whClientContext* c, int32_t* out_rc);

int wh_Client_NvmGetAvailableRequest(whClientContext* c);

int wh_Client_NvmGetAvailableResponse(whClientContext* c, int32_t* out_rc,
                                      uint32_t* out_avail_size,
                                      whNvmId*  out_avail_objects,
                                      uint32_t* out_reclaim_size,
                                      whNvmId*  out_reclaim_objects);

int wh_Client_NvmGetAvailable(whClientContext* c, int32_t* out_rc,
                              uint32_t* out_avail_size,
                              whNvmId*  out_avail_objects,
                              uint32_t* out_reclaim_size,
                              whNvmId*  out_reclaim_objects);

int wh_Client_NvmAddObjectRequest(whClientContext* c, whNvmId id,
                                  whNvmAccess access, whNvmFlags flags,
                                  whNvmSize label_len, uint8_t* label,
                                  whNvmSize len, const uint8_t* data);

int wh_Client_NvmAddObjectResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_NvmAddObject(whClientContext* c, whNvmId id, whNvmAccess access,
                           whNvmFlags flags, whNvmSize label_len,
                           uint8_t* label, whNvmSize len, const uint8_t* data,
                           int32_t* out_rc);

int wh_Client_NvmListRequest(whClientContext* c, whNvmAccess access,
                             whNvmFlags flags, whNvmId start_id);

int wh_Client_NvmListResponse(whClientContext* c, int32_t* out_rc,
                              whNvmId* out_count, whNvmId* out_id);

int wh_Client_NvmList(whClientContext* c, whNvmAccess access, whNvmFlags flags,
                      whNvmId start_id, int32_t* out_rc, whNvmId* out_count,
                      whNvmId* out_id);

int wh_Client_NvmGetMetadataRequest(whClientContext* c, whNvmId id);

int wh_Client_NvmGetMetadataResponse(whClientContext* c, int32_t* out_rc,
                                     whNvmId* out_id, whNvmAccess* out_access,
                                     whNvmFlags* out_flags, whNvmSize* out_len,
                                     whNvmSize label_len, uint8_t* label);

int wh_Client_NvmGetMetadata(whClientContext* c, whNvmId id, int32_t* out_rc,
                             whNvmId* out_id, whNvmAccess* out_access,
                             whNvmFlags* out_flags, whNvmSize* out_len,
                             whNvmSize label_len, uint8_t* label);

int wh_Client_NvmDestroyObjectsRequest(whClientContext* c, whNvmId list_count,
                                       const whNvmId* id_list);

int wh_Client_NvmDestroyObjectsResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_NvmDestroyObjects(whClientContext* c, whNvmId list_count,
                                const whNvmId* id_list, int32_t* out_rc);

int wh_Client_NvmReadRequest(whClientContext* c, whNvmId id, whNvmSize offset,
                             whNvmSize data_len);

int wh_Client_NvmReadResponse(whClientContext* c, int32_t* out_rc,
                              whNvmSize* out_len, uint8_t* data);

int wh_Client_NvmRead(whClientContext* c, whNvmId id, whNvmSize offset,
                      whNvmSize data_len, int32_t* out_rc, whNvmSize* out_len,
                      uint8_t* data);


int wh_Client_NvmAddObjectDmaRequest(whClientContext* c,
                                     whNvmMetadata*   metadata,
                                     whNvmSize data_len, const uint8_t* data);

int wh_Client_NvmAddObjectDmaResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_NvmAddObjectDma(whClientContext* c, whNvmMetadata* metadata,
                              whNvmSize data_len, const uint8_t* data,
                              int32_t* out_rc);

/*
 * @brief Sends a request to the server to read data from non-volatile memory
 * (NVM) using DMA, with automatic detection of client address width (32-bit or
 * 64-bit).
 *
 * This function prepares and sends a request to the server to read data from
 * NVM using DMA. The client address width (32-bit or 64-bit) is automatically
 * detected. The request includes the NVM ID, offset, length of the data, and
 * the data client address. This function does not block; it returns immediately
 * after sending the request.
 *
 * @param[in] c Pointer to the client context.
 * @param[in] id The NVM ID of the object to read.
 * @param[in] offset The offset within the object to start reading from.
 * @param[in] data_len The length of the data to be read.
 * @param[in] data Pointer to the data buffer where the data will be read into.
 * @return int Returns 0 on success, or a negative error code on failure.
 */
int wh_Client_NvmReadDmaRequest(whClientContext* c, whNvmId id,
                                whNvmSize offset, whNvmSize data_len,
                                uint8_t* data);

int wh_Client_NvmReadDmaResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_NvmReadDma(whClientContext* c, whNvmId id, whNvmSize offset,
                         whNvmSize data_len, uint8_t* data, int32_t* out_rc);

/* Client custom-callback support */

int wh_Client_CustomCbRequest(whClientContext*                 c,
                              const whMessageCustomCb_Request* req);

int wh_Client_CustomCbResponse(whClientContext*            c,
                               whMessageCustomCb_Response* resp);

int wh_Client_CustomCheckRegisteredRequest(whClientContext* c, uint32_t id);

int wh_Client_CustomCbCheckRegisteredResponse(whClientContext* c,
                                              uint16_t*        outId,
                                              int*             responseError);

int wh_Client_CustomCbCheckRegistered(whClientContext* c, uint16_t id,
                                      int* responseError);

/* Certificate functions */

int wh_Client_CertInitRequest(whClientContext* c);

int wh_Client_CertInitResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_CertInit(whClientContext* c, int32_t* out_rc);

int wh_Client_CertAddTrustedRequest(whClientContext* c, whNvmId id,
                                    const uint8_t* cert, uint32_t cert_len);

int wh_Client_CertAddTrustedResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_CertAddTrusted(whClientContext* c, whNvmId id,
                             const uint8_t* cert, uint32_t cert_len,
                             int32_t* out_rc);

int wh_Client_CertEraseTrustedRequest(whClientContext* c, whNvmId id);

int wh_Client_CertEraseTrustedResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_CertEraseTrusted(whClientContext* c, whNvmId id, int32_t* out_rc);

int wh_Client_CertReadTrustedRequest(whClientContext* c, whNvmId id,
                                     uint32_t cert_len);

int wh_Client_CertReadTrustedResponse(whClientContext* c, uint8_t* cert,
                                      uint32_t* cert_len, int32_t* out_rc);

int wh_Client_CertReadTrusted(whClientContext* c, whNvmId id, uint8_t* cert,
                              uint32_t* cert_len, int32_t* out_rc);

int wh_Client_CertVerifyRequest(whClientContext* c, const uint8_t* cert,
                                uint32_t cert_len, whNvmId trustedRootNvmId);

int wh_Client_CertVerifyResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_CertVerify(whClientContext* c, const uint8_t* cert,
                         uint32_t cert_len, whNvmId trustedRootNvmId,
                         int32_t* out_rc);

int wh_Client_CertVerifyAndCacheLeafPubKeyRequest(whClientContext* c,
                                                  const uint8_t*   cert,
                                                  uint32_t         cert_len,
                                                  whNvmId trustedRootNvmId,
                                                  whKeyId keyId);

int wh_Client_CertVerifyAndCacheLeafPubKeyResponse(whClientContext* c,
                                                   whKeyId*         out_keyId,
                                                   int32_t*         out_rc);

int wh_Client_CertVerifyAndCacheLeafPubKey(
    whClientContext* c, const uint8_t* cert, uint32_t cert_len,
    whNvmId trustedRootNvmId, whKeyId* inout_keyId, int32_t* out_rc);


#ifdef WOLFHSM_CFG_DMA

int wh_Client_CertAddTrustedDmaRequest(whClientContext* c, whNvmId id,
                                       const void* cert, uint32_t cert_len);

int wh_Client_CertAddTrustedDmaResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_CertAddTrustedDma(whClientContext* c, whNvmId id,
                                const void* cert, uint32_t cert_len,
                                int32_t* out_rc);

int wh_Client_CertReadTrustedDmaRequest(whClientContext* c, whNvmId id,
                                        void* cert, uint32_t cert_len);

int wh_Client_CertReadTrustedDmaResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_CertReadTrustedDma(whClientContext* c, whNvmId id, void* cert,
                                 uint32_t cert_len, int32_t* out_rc);

int wh_Client_CertVerifyDmaRequest(whClientContext* c, const void* cert,
                                   uint32_t cert_len, whNvmId trustedRootNvmId);

int wh_Client_CertVerifyDmaResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_CertVerifyDma(whClientContext* c, const void* cert,
                            uint32_t cert_len, whNvmId trustedRootNvmId,
                            int32_t* out_rc);


int wh_Client_CertVerifyDmaAndCacheLeafPubKeyRequest(whClientContext* c,
                                                     const void*      cert,
                                                     uint32_t         cert_len,
                                                     whNvmId trustedRootNvmId,
                                                     whKeyId keyId);

int wh_Client_CertVerifyDmaAndCacheLeafPubKeyResponse(whClientContext* c,
                                                      whKeyId* out_keyId,
                                                      int32_t* out_rc);

int wh_Client_CertVerifyDmaAndCacheLeafPubKey(
    whClientContext* c, const void* cert, uint32_t cert_len,
    whNvmId trustedRootNvmId, whKeyId* inout_keyId, int32_t* out_rc);


#endif /* WOLFHSM_CFG_DMA */

int wh_Client_CertVerifyAcertRequest(whClientContext* c, const void* cert,
                                     uint32_t cert_len,
                                     whNvmId  trustedRootNvmId);

int wh_Client_CertVerifyAcertResponse(whClientContext* c, int32_t* out_rc);

int wh_Client_CertVerifyAcert(whClientContext* c, const void* cert,
                              uint32_t cert_len, whNvmId trustedRootNvmId,
                              int32_t* out_rc);

int wh_Client_CertVerifyAcertDmaRequest(whClientContext* c, const void* cert,
                                        uint32_t cert_len,
                                        whNvmId  trustedRootNvmId);

int wh_Client_CertVerifyAcertDmaResponse(whClientContext* c, int32_t* out_rc);

#if defined(WOLFHSM_CFG_DMA)
int wh_Client_CertVerifyAcertDma(whClientContext* c, const void* cert,
                                 uint32_t cert_len, whNvmId trustedRootNvmId,
                                 int32_t* out_rc);

#endif /* WOLFHSM_CFG_DMA */

#endif /* !WOLFHSM_WH_CLIENT_H_ */

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