wolfhsm/wh_server_cert.h

Functions

	Name
int	wh_Server_CertInit(whServerContext * server) Initialize the certificate manager.
int	wh_Server_CertAddTrusted(whServerContext * server, whNvmId id, whNvmAccess access, whNvmFlags flags, const uint8_t * label, whNvmSize label_len, const uint8_t * cert, uint32_t cert_len) Add a trusted certificate to NVM storage.
int	wh_Server_CertEraseTrusted(whServerContext * server, whNvmId id) Delete a trusted certificate from NVM storage.
int	wh_Server_CertReadTrusted(whServerContext * server, whNvmId id, uint8_t * cert, uint32_t * inout_cert_len) Get a trusted certificate from NVM storage.
int	wh_Server_CertVerify(whServerContext * server, const uint8_t * cert, uint32_t cert_len, whNvmId trustedRootNvmId, whCertFlags flags, whNvmFlags cachedKeyFlags, whKeyId * inout_keyId) Verify a certificate against trusted certificates.
int	wh_Server_CertVerifyMultiRoot(whServerContext * server, const uint8_t * cert, uint32_t cert_len, const whNvmId * trustedRootNvmIds, uint16_t numRoots, whCertFlags flags, whNvmFlags cachedKeyFlags, whKeyId * inout_keyId) Verify a certificate chain against a set of trusted root anchors.
int	wh_Server_CertSetVerifyCb(whServerContext * server, VerifyCallback cb) Register a verify callback at runtime.
int	wh_Server_CertVerifyAcert(whServerContext * server, const uint8_t * cert, uint32_t cert_len, whNvmId trustedRootNvmId) Verifies an attribute certificate against a trusted root certificate.
int	wh_Server_HandleCertRequest(whServerContext * server, uint16_t magic, uint16_t action, uint16_t seq, uint16_t req_size, const void * req_packet, uint16_t * out_resp_size, void * resp_packet) Handle a certificate request and generate a response.

Functions Documentation

function wh_Server_CertInit

int wh_Server_CertInit(
    whServerContext * server
)

Initialize the certificate manager.

Parameters:

server The server context

Return: WH_ERROR_OK on success, error code on failure

function wh_Server_CertAddTrusted

int wh_Server_CertAddTrusted(
    whServerContext * server,
    whNvmId id,
    whNvmAccess access,
    whNvmFlags flags,
    const uint8_t * label,
    whNvmSize label_len,
    const uint8_t * cert,
    uint32_t cert_len
)

Add a trusted certificate to NVM storage.

Parameters:

server The server context
id The NVM ID to store the certificate under
cert The certificate data buffer
cert_len Length of the certificate data
flags NVM flags for the certificate storage

Return: WH_ERROR_OK on success, error code on failure

function wh_Server_CertEraseTrusted

int wh_Server_CertEraseTrusted(
    whServerContext * server,
    whNvmId id
)

Delete a trusted certificate from NVM storage.

Parameters:

server The server context
id The NVM ID of the certificate to delete

Return: WH_ERROR_OK on success, error code on failure

function wh_Server_CertReadTrusted

int wh_Server_CertReadTrusted(
    whServerContext * server,
    whNvmId id,
    uint8_t * cert,
    uint32_t * inout_cert_len
)

Get a trusted certificate from NVM storage.

Parameters:

server The server context
id The NVM ID of the certificate to read
cert Buffer to store the certificate data
inout_cert_len On input, size of cert buffer. On output, actual cert size

Return: WH_ERROR_OK on success, error code on failure. If certificate is too large for the buffer, WH_ERROR_BUFFER_SIZE will be returned and inout_cert_len will be updated to the actual certificate size.

function wh_Server_CertVerify

int wh_Server_CertVerify(
    whServerContext * server,
    const uint8_t * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId,
    whCertFlags flags,
    whNvmFlags cachedKeyFlags,
    whKeyId * inout_keyId
)

Verify a certificate against trusted certificates.

Parameters:

server The server context
cert The certificate data to verify
cert_len Length of the certificate data
trustedRootNvmId NVM ID of the trusted root certificate
flags Flags for the certificate verification (see WH_CERT_FLAGS_* in wh_common.h)
cachedKeyFlags NVM usage flags to apply when caching the leaf public key (only used if WH_CERT_FLAGS_CACHE_LEAF_PUBKEY is set)
inout_keyId Only valid if WH_CERT_FLAGS_CACHE_LEAF_PUBKEY is set. On input, set to the keyId to use when caching the leaf public key. If set to WH_KEYID_ERASED then a new unique keyId will be generated. On output, holds the keyId used for the leaf certificate.

Return: WH_ERROR_OK on success, error code on failure

function wh_Server_CertVerifyMultiRoot

int wh_Server_CertVerifyMultiRoot(
    whServerContext * server,
    const uint8_t * cert,
    uint32_t cert_len,
    const whNvmId * trustedRootNvmIds,
    uint16_t numRoots,
    whCertFlags flags,
    whNvmFlags cachedKeyFlags,
    whKeyId * inout_keyId
)

Verify a certificate chain against a set of trusted root anchors.

Parameters:

server Server context.
cert Candidate certificate chain (DER).
cert_len Length of cert in bytes.
trustedRootNvmIds Array of root NVM IDs to load as anchors. Order is informational only.
numRoots Number of entries in trustedRootNvmIds. Must be 1..WOLFHSM_CFG_CERT_MAX_VERIFY_ROOTS.
flags See WH_CERT_FLAGS_*.
cachedKeyFlags NVM flags applied to the cached leaf key (only used if WH_CERT_FLAGS_CACHE_LEAF_PUBKEY).
inout_keyId Cached leaf key id (only used if WH_CERT_FLAGS_CACHE_LEAF_PUBKEY).

Return: WH_ERROR_OK on chain trust success. WH_ERROR_CERT_VERIFY if no loaded anchor matches the chain. WH_ERROR_NOTFOUND if every supplied root id is absent from NVM. WH_ERROR_BADARGS / other negative codes on argument or environment errors.

Loads each available root identified by trustedRootNvmIds into a freshly allocated cert manager and verifies the supplied chain once. Succeeds if the chain anchors to any loaded root. Roots whose NVM objects are absent are skipped silently; non-absent failures to read or load any root are reported.

function wh_Server_CertSetVerifyCb

int wh_Server_CertSetVerifyCb(
    whServerContext * server,
    VerifyCallback cb
)

Register a verify callback at runtime.

Parameters:

server The server context.
cb The callback to register, or NULL to unregister.

Return: WH_ERROR_OK on success, WH_ERROR_BADARGS if server is NULL.

Replaces the callback previously set via whServerCertConfig.verifyCb (or by a prior call to this function). Pass NULL to unregister.

The callback is applied to the per-request WOLFSSL_CERT_MANAGER created by wh_Server_CertVerify, so it participates in chain verification the same way a callback registered with wolfSSL_CertManagerSetVerify would. Verify-cache hits (when WOLFHSM_CFG_CERTIFICATE_VERIFY_CACHE is enabled) bypass the callback because they bypass wolfSSL's verify path entirely.

function wh_Server_CertVerifyAcert

int wh_Server_CertVerifyAcert(
    whServerContext * server,
    const uint8_t * cert,
    uint32_t cert_len,
    whNvmId trustedRootNvmId
)

Verifies an attribute certificate against a trusted root certificate.

Parameters:

server Pointer to the server context
cert Pointer to the attribute certificate data to verify
cert_len Length of the certificate data in bytes
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 retrieves a trusted root certificate from NVM using the specified NVM ID and verifies the provided attribute certificate against it.

function wh_Server_HandleCertRequest

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

Handle a certificate request and generate a response.

Parameters:

server The server context
magic Magic number for message validation
action The certificate action to perform
seq Sequence number for the request
req_size Size of the request packet
req_packet The request packet data
out_resp_size Size of the response packet
resp_packet Buffer to store the response packet

Return: WH_ERROR_OK on success, error code on failure

Source code

/*
 * Copyright (C) 2025 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_cert.h
 */

#ifndef WOLFHSM_WH_SERVER_CERT_H_
#define WOLFHSM_WH_SERVER_CERT_H_

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

#include <stdint.h>

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

int wh_Server_CertInit(whServerContext* server);

int wh_Server_CertAddTrusted(whServerContext* server, whNvmId id,
                             whNvmAccess access, whNvmFlags flags,
                             const uint8_t* label, whNvmSize label_len,
                             const uint8_t* cert, uint32_t cert_len);

int wh_Server_CertEraseTrusted(whServerContext* server, whNvmId id);

int wh_Server_CertReadTrusted(whServerContext* server, whNvmId id,
                              uint8_t* cert, uint32_t* inout_cert_len);

int wh_Server_CertVerify(whServerContext* server, const uint8_t* cert,
                         uint32_t cert_len, whNvmId trustedRootNvmId,
                         whCertFlags flags, whNvmFlags cachedKeyFlags,
                         whKeyId* inout_keyId);

int wh_Server_CertVerifyMultiRoot(whServerContext* server, const uint8_t* cert,
                                  uint32_t       cert_len,
                                  const whNvmId* trustedRootNvmIds,
                                  uint16_t numRoots, whCertFlags flags,
                                  whNvmFlags cachedKeyFlags,
                                  whKeyId*   inout_keyId);

#if defined(WOLFHSM_CFG_CERTIFICATE_MANAGER) && !defined(WOLFHSM_CFG_NO_CRYPTO)
int wh_Server_CertSetVerifyCb(whServerContext* server, VerifyCallback cb);
#endif /* WOLFHSM_CFG_CERTIFICATE_MANAGER && !WOLFHSM_CFG_NO_CRYPTO */

#if defined(WOLFHSM_CFG_CERTIFICATE_MANAGER_ACERT)
int wh_Server_CertVerifyAcert(whServerContext* server, const uint8_t* cert,
                              uint32_t cert_len, whNvmId trustedRootNvmId);
#endif

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

#endif /* !WOLFHSM_WH_SERVER_CERT_H_ */

Updated on 2026-06-11 at 01:20:09 +0000