wolfhsm/wh_server_keystore.h

Functions

	Name
int	wh_Server_KeystoreGetUniqueId(whServerContext * server, whNvmId * inout_id) Find a new unique key ID using the top bits of inout_id for user and type.
int	wh_Server_KeystoreGetCacheSlot(whServerContext * server, whKeyId keyId, uint16_t keySz, uint8_t outBuf, whNvmMetadata outMeta) Find an available cache slot for the specified key size.
int	wh_Server_KeystoreGetCacheSlotChecked(whServerContext * server, whKeyId keyId, uint16_t keySz, uint8_t outBuf, whNvmMetadata outMeta)
int	wh_Server_KeystoreCacheKey(whServerContext * server, whNvmMetadata * meta, uint8_t * in) Cache a key in server memory.
int	wh_Server_KeystoreCacheKeyChecked(whServerContext * server, whNvmMetadata * meta, uint8_t * in) Cache a key after enforcing keystore policy.
int	wh_Server_KeystoreFreshenKey(whServerContext * server, whKeyId keyId, uint8_t outBuf, whNvmMetadata outMeta) Ensure a key is in cache, loading it from NVM if necessary.
int	wh_Server_KeystoreReadKey(whServerContext * server, whKeyId keyId, whNvmMetadata * outMeta, uint8_t * out, uint32_t * outSz) Read a key from cache or NVM.
int	wh_Server_KeystoreReadKeyChecked(whServerContext * server, whKeyId keyId, whNvmMetadata * outMeta, uint8_t * out, uint32_t * outSz) Read a key with policy enforcement.
int	wh_Server_KeystoreReadKeyEnforce(whServerContext * server, whKeyId keyId, whNvmFlags requiredUsage, whNvmMetadata * outMeta, uint8_t * out, uint32_t * outSz) Atomically read a key and enforce its usage policy.
int	wh_Server_KeystoreEvictKey(whServerContext * server, whNvmId keyId) Remove a key from cache.
int	wh_Server_KeystoreEvictKeyChecked(whServerContext * server, whNvmId keyId) Evict a key with policy enforcement.
int	wh_Server_KeystoreCommitKey(whServerContext * server, whNvmId keyId) Commit a cached key to NVM storage.
int	wh_Server_KeystoreCommitKeyChecked(whServerContext * server, whNvmId keyId) Commit a cached key to NVM with policy enforcement.
int	wh_Server_KeystoreEraseKey(whServerContext * server, whNvmId keyId) Erase a key from both cache and NVM.
int	wh_Server_KeystoreEraseKeyChecked(whServerContext * server, whNvmId keyId) Erase a key with policy enforcement.
int	wh_Server_KeystoreRevokeKey(whServerContext * server, whKeyId keyId) Revoke a key (clears usage and marks non-modifiable)
int	wh_Server_HandleKeyRequest(whServerContext * server, uint16_t magic, uint16_t action, uint16_t req_size, const void * req_packet, uint16_t * out_resp_size, void * resp_packet) Handle key management requests from clients.
int	wh_Server_KeystoreCacheKeyDma(whServerContext * server, whNvmMetadata * meta, uint64_t keyAddr) Cache a key using DMA transfer.
int	wh_Server_KeystoreCacheKeyDmaChecked(whServerContext * server, whNvmMetadata * meta, uint64_t keyAddr) Cache a key with DMA after policy enforcement.
int	wh_Server_KeystoreExportKeyDma(whServerContext * server, whKeyId keyId, uint64_t keyAddr, uint64_t keySz, whNvmMetadata * outMeta) Export a key using DMA transfer.
int	wh_Server_KeystoreExportKeyDmaChecked(whServerContext * server, whKeyId keyId, uint64_t keyAddr, uint64_t keySz, whNvmMetadata * outMeta) Export a key with DMA after policy enforcement.
int	wh_Server_KeystoreEnforceKeyUsage(const whNvmMetadata * meta, whNvmFlags requiredUsage) Enforce key usage policy given metadata.

Functions Documentation

function wh_Server_KeystoreGetUniqueId

int wh_Server_KeystoreGetUniqueId(
    whServerContext * server,
    whNvmId * inout_id
)

Find a new unique key ID using the top bits of inout_id for user and type.

Parameters:

server Server context
inout_id Input: key ID with type and user set; Output: unique key ID

Return: 0 on success, error code on failure

Searches for an available key ID by checking against cache keys and NVM storage. The client_id and type should be set by caller on inout_id.

function wh_Server_KeystoreGetCacheSlot

int wh_Server_KeystoreGetCacheSlot(
    whServerContext * server,
    whKeyId keyId,
    uint16_t keySz,
    uint8_t ** outBuf,
    whNvmMetadata ** outMeta
)

Find an available cache slot for the specified key size.

Parameters:

server Server context
keyId Key ID (used to route to correct cache)
keySz Size of the key in bytes
outBuf Pointer to the cache buffer
outMeta Pointer to the metadata structure

Return: 0 on success, error code on failure

Searches for an empty slot or a slot with a committed key that can be evicted. Returns the slot's buffer (zeroed) and metadata. Routes to the appropriate cache (global or local) based on keyId.

function wh_Server_KeystoreGetCacheSlotChecked

int wh_Server_KeystoreGetCacheSlotChecked(
    whServerContext * server,
    whKeyId keyId,
    uint16_t keySz,
    uint8_t ** outBuf,
    whNvmMetadata ** outMeta
)

function wh_Server_KeystoreCacheKey

int wh_Server_KeystoreCacheKey(
    whServerContext * server,
    whNvmMetadata * meta,
    uint8_t * in
)

Cache a key in server memory.

Parameters:

server Server context
meta Key metadata
in Key data buffer

Return: 0 on success, error code on failure

Stores a key in the appropriate cache (regular or big) based on its size. Checks if the key is already committed to NVM.

function wh_Server_KeystoreCacheKeyChecked

int wh_Server_KeystoreCacheKeyChecked(
    whServerContext * server,
    whNvmMetadata * meta,
    uint8_t * in
)

Cache a key after enforcing keystore policy.

Runs policy checks (access/usage/etc.) before calling wh_Server_KeystoreCacheKey.

function wh_Server_KeystoreFreshenKey

int wh_Server_KeystoreFreshenKey(
    whServerContext * server,
    whKeyId keyId,
    uint8_t ** outBuf,
    whNvmMetadata ** outMeta
)

Ensure a key is in cache, loading it from NVM if necessary.

Parameters:

server Server context
keyId Key ID to freshen
outBuf Pointer to the cached key buffer
outMeta Pointer to the key metadata

Return: 0 on success, error code on failure

Tries to put the specified key into cache if it isn't already there. Returns pointers to the metadata and cached data.

function wh_Server_KeystoreReadKey

int wh_Server_KeystoreReadKey(
    whServerContext * server,
    whKeyId keyId,
    whNvmMetadata * outMeta,
    uint8_t * out,
    uint32_t * outSz
)

Read a key from cache or NVM.

Parameters:

server Server context
keyId Key ID to read
outMeta Key metadata (can be NULL)
out Buffer to store key data (can be NULL)
outSz Input: size of out buffer; Output: actual key size

Return: 0 on success, error code on failure

Retrieves a key from cache or NVM storage and returns its metadata and data.

function wh_Server_KeystoreReadKeyChecked

int wh_Server_KeystoreReadKeyChecked(
    whServerContext * server,
    whKeyId keyId,
    whNvmMetadata * outMeta,
    uint8_t * out,
    uint32_t * outSz
)

Read a key with policy enforcement.

Performs keystore policy checks before reading from cache/NVM.

function wh_Server_KeystoreReadKeyEnforce

int wh_Server_KeystoreReadKeyEnforce(
    whServerContext * server,
    whKeyId keyId,
    whNvmFlags requiredUsage,
    whNvmMetadata * outMeta,
    uint8_t * out,
    uint32_t * outSz
)

Atomically read a key and enforce its usage policy.

Parameters:

server Server context
keyId Key ID to read
requiredUsage Usage flags the key must have (may be WH_NVM_FLAGS_NONE for no usage requirement)
outMeta Key metadata (can be NULL)
out Buffer to store key data (can be NULL)
outSz Input: size of out buffer; Output: key size

Return: WH_ERROR_OK on success, WH_ERROR_USAGE if the key lacks the required usage flags, WH_ERROR_NOSPACE if the key does not fit in out, other error codes on read failure

Reads the key (as wh_Server_KeystoreReadKey) and checks the required usage flags against the same snapshot of the key, all under the NVM lock, so the policy checked can never belong to a different key generation than the key material returned. On a usage-policy failure the output buffer is cleared.

Acquires WH_SERVER_NVM_LOCK internally under WOLFHSM_CFG_THREADSAFE. The lock is non-recursive: callers that already hold it (e.g. the SHE or cert request dispatch) must use wh_Server_KeystoreReadKey plus wh_Server_KeystoreEnforceKeyUsage directly instead.

This copies the key out rather than handing back a pointer into the cache slot, which is what lets the caller use the key after the lock is dropped. The copy is bounded by the caller's buffer, so a key larger than *outSz is rejected with WH_ERROR_NOSPACE and nothing is written.

function wh_Server_KeystoreEvictKey

int wh_Server_KeystoreEvictKey(
    whServerContext * server,
    whNvmId keyId
)

Remove a key from cache.

Parameters:

server Server context
keyId Key ID to evict

Return: 0 on success, error code on failure

Marks the key as erased in the cache if present.

function wh_Server_KeystoreEvictKeyChecked

int wh_Server_KeystoreEvictKeyChecked(
    whServerContext * server,
    whNvmId keyId
)

Evict a key with policy enforcement.

Checks policy before removing the key from cache.

function wh_Server_KeystoreCommitKey

int wh_Server_KeystoreCommitKey(
    whServerContext * server,
    whNvmId keyId
)

Commit a cached key to NVM storage.

Parameters:

server Server context
keyId Key ID to commit

Return: 0 on success, error code on failure

Writes a key from cache to non-volatile memory and marks it as committed.

function wh_Server_KeystoreCommitKeyChecked

int wh_Server_KeystoreCommitKeyChecked(
    whServerContext * server,
    whNvmId keyId
)

Commit a cached key to NVM with policy enforcement.

Runs keystore policy checks before committing.

function wh_Server_KeystoreEraseKey

int wh_Server_KeystoreEraseKey(
    whServerContext * server,
    whNvmId keyId
)

Erase a key from both cache and NVM.

Parameters:

server Server context
keyId Key ID to erase

Return: 0 on success, error code on failure

Removes the key from cache if present and destroys it in NVM.

function wh_Server_KeystoreEraseKeyChecked

int wh_Server_KeystoreEraseKeyChecked(
    whServerContext * server,
    whNvmId keyId
)

Erase a key with policy enforcement.

Parameters:

server Server context
keyId Key ID to erase

Return: 0 on success, including when the key does not exist. WH_ERROR_ACCESS if policy denies the erase (the persisted key stays; a cached copy may still be evicted). Other error codes on failure.

Runs keystore policy checks before evicting/destroying. An absent key is a successful erase, whether or not NVM is configured.

function wh_Server_KeystoreRevokeKey

int wh_Server_KeystoreRevokeKey(
    whServerContext * server,
    whKeyId keyId
)

Revoke a key (clears usage and marks non-modifiable)

Placeholder implementation for key revocation.

function wh_Server_HandleKeyRequest

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

Handle key management requests from clients.

Parameters:

server Server context
magic Message magic number
action Key operation to perform
req_size Size of request packet
req_packet Request packet data
out_resp_size Size of response packet
resp_packet Response packet data

Return: 0 on success, error code on failure

Processes various key operations including cache, export, evict, commit, and erase. Supports DMA operations if configured.

function wh_Server_KeystoreCacheKeyDma

int wh_Server_KeystoreCacheKeyDma(
    whServerContext * server,
    whNvmMetadata * meta,
    uint64_t keyAddr
)

Cache a key using DMA transfer.

Parameters:

server Server context
meta Key metadata
keyAddr Client memory address containing key data

Return: 0 on success, error code on failure

Allocates a cache slot and copies key data from client memory using DMA.

function wh_Server_KeystoreCacheKeyDmaChecked

int wh_Server_KeystoreCacheKeyDmaChecked(
    whServerContext * server,
    whNvmMetadata * meta,
    uint64_t keyAddr
)

Cache a key with DMA after policy enforcement.

Performs policy checks before exporting a key via DMA.

function wh_Server_KeystoreExportKeyDma

int wh_Server_KeystoreExportKeyDma(
    whServerContext * server,
    whKeyId keyId,
    uint64_t keyAddr,
    uint64_t keySz,
    whNvmMetadata * outMeta
)

Export a key using DMA transfer.

Parameters:

server Server context
keyId Key ID to export
keyAddr Client memory address to receive key data
keySz Size of client memory buffer
outMeta Buffer to receive key metadata

Return: 0 on success, error code on failure

Copies key data from server cache to client memory using DMA.

function wh_Server_KeystoreExportKeyDmaChecked

int wh_Server_KeystoreExportKeyDmaChecked(
    whServerContext * server,
    whKeyId keyId,
    uint64_t keyAddr,
    uint64_t keySz,
    whNvmMetadata * outMeta
)

Export a key with DMA after policy enforcement.

Performs policy checks before exporting a key via DMA.

function wh_Server_KeystoreEnforceKeyUsage

int wh_Server_KeystoreEnforceKeyUsage(
    const whNvmMetadata * meta,
    whNvmFlags requiredUsage
)

Enforce key usage policy given metadata.

Parameters:

meta Pointer to key metadata
requiredUsage Required usage policy flags (e.g., WH_NVM_FLAGS_USAGE_ENCRYPT | WH_NVM_FLAGS_USAGE_DECRYPT)

Return:

WH_ERROR_OK if the key has all required usage flags set
WH_ERROR_USAGE if the key does not have the required flags
WH_ERROR_BADARGS if meta is NULL

Validates that a key has the required usage policy flags set in its metadata. This is a pure policy check function that does not perform any key lookups. Use this when you already have the key metadata available to avoid duplicate key freshening operations.

Source code

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

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

#include <stdint.h>

#include "wolfhsm/wh_common.h"
#include "wolfhsm/wh_server.h"

int wh_Server_KeystoreGetUniqueId(whServerContext* server, whNvmId* inout_id);

int wh_Server_KeystoreGetCacheSlot(whServerContext* server, whKeyId keyId,
                                   uint16_t keySz, uint8_t** outBuf,
                                   whNvmMetadata** outMeta);
int wh_Server_KeystoreGetCacheSlotChecked(whServerContext* server,
                                          whKeyId keyId, uint16_t keySz,
                                          uint8_t**       outBuf,
                                          whNvmMetadata** outMeta);

int wh_Server_KeystoreCacheKey(whServerContext* server, whNvmMetadata* meta,
                               uint8_t* in);

int wh_Server_KeystoreCacheKeyChecked(whServerContext* server,
                                      whNvmMetadata* meta, uint8_t* in);

int wh_Server_KeystoreFreshenKey(whServerContext* server, whKeyId keyId,
                                 uint8_t** outBuf, whNvmMetadata** outMeta);

int wh_Server_KeystoreReadKey(whServerContext* server, whKeyId keyId,
                              whNvmMetadata* outMeta, uint8_t* out,
                              uint32_t* outSz);

int wh_Server_KeystoreReadKeyChecked(whServerContext* server, whKeyId keyId,
                                     whNvmMetadata* outMeta, uint8_t* out,
                                     uint32_t* outSz);

int wh_Server_KeystoreReadKeyEnforce(whServerContext* server, whKeyId keyId,
                                     whNvmFlags     requiredUsage,
                                     whNvmMetadata* outMeta, uint8_t* out,
                                     uint32_t* outSz);

int wh_Server_KeystoreEvictKey(whServerContext* server, whNvmId keyId);

int wh_Server_KeystoreEvictKeyChecked(whServerContext* server, whNvmId keyId);

int wh_Server_KeystoreCommitKey(whServerContext* server, whNvmId keyId);

int wh_Server_KeystoreCommitKeyChecked(whServerContext* server, whNvmId keyId);

int wh_Server_KeystoreEraseKey(whServerContext* server, whNvmId keyId);

int wh_Server_KeystoreEraseKeyChecked(whServerContext* server, whNvmId keyId);

int wh_Server_KeystoreRevokeKey(whServerContext* server, whKeyId keyId);

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

int wh_Server_KeystoreCacheKeyDma(whServerContext* server, whNvmMetadata* meta,
                                  uint64_t keyAddr);

int wh_Server_KeystoreCacheKeyDmaChecked(whServerContext* server,
                                         whNvmMetadata* meta, uint64_t keyAddr);
int wh_Server_KeystoreExportKeyDma(whServerContext* server, whKeyId keyId,
                                   uint64_t keyAddr, uint64_t keySz,
                                   whNvmMetadata* outMeta);

int wh_Server_KeystoreExportKeyDmaChecked(whServerContext* server,
                                          whKeyId keyId, uint64_t keyAddr,
                                          uint64_t       keySz,
                                          whNvmMetadata* outMeta);


int wh_Server_KeystoreEnforceKeyUsage(const whNvmMetadata* meta,
                                      whNvmFlags           requiredUsage);

#endif /* !WOLFHSM_WH_SERVER_KEYSTORE_H_ */

Updated on 2026-08-11 at 13:07:17 +0000