Skip to content

wolfhsm/wh_client_crypto.h

Functions

Name
int wh_Client_RngGenerate(whClientContext * ctx, uint8_t * out, uint32_t size)
Generate random bytes.
int wh_Client_Curve25519SetKeyId(curve25519_key * key, whKeyId keyId)
Associates a Curve25519 key with a specific key ID.
int wh_Client_Curve25519GetKeyId(curve25519_key * key, whKeyId * outId)
Gets the wolfHSM keyId being used by the wolfCrypt struct.
int wh_Client_Curve25519ImportKey(whClientContext * ctx, curve25519_key * key, whKeyId * inout_keyId, whNvmFlags flags, uint16_t label_len, uint8_t * label)
Imports wolfCrypt Curve25519 key as a raw byte array into the wolfHSM server key cache.
int wh_Client_Curve25519ExportKey(whClientContext * ctx, whKeyId keyId, curve25519_key * key, uint16_t label_len, uint8_t * label)
Exports a serialized curve25519 key from the wolfHSM server keycache and decodes it into the wolfCrypt curve25519 key structure.
int wh_Client_Curve25519MakeCacheKey(whClientContext * ctx, uint16_t size, whKeyId * inout_key_id, whNvmFlags flags, const uint8_t * label, uint16_t label_len)
Generate a Curve25519 key in the server key cache.
int wh_Client_Curve25519MakeExportKey(whClientContext * ctx, uint16_t size, curve25519_key * key)
Generate a Curve25519 key by the server and export to the client.
int wh_Client_Curve25519SharedSecret(whClientContext * ctx, curve25519_key * priv_key, curve25519_key * pub_key, int endian, uint8_t * out, uint16_t * out_size)
Compute an X25519 shared secret using a public and private key.
int wh_Client_EccSetKeyId(ecc_key * key, whKeyId keyId)
Associates a Ecc key with a specific key ID.
int wh_Client_EccGetKeyId(ecc_key * key, whKeyId * outId)
Gets the wolfHSM keyId being used by the wolfCrypt struct.
int wh_Client_EccImportKey(whClientContext * ctx, ecc_key * key, whKeyId * inout_keyId, whNvmFlags flags, uint16_t label_len, uint8_t * label)
int wh_Client_EccExportKey(whClientContext * ctx, whKeyId keyId, ecc_key * key, uint16_t label_len, uint8_t * label)
int wh_Client_EccMakeExportKey(whClientContext * ctx, int size, int curveId, ecc_key * key)
int wh_Client_EccMakeCacheKey(whClientContext * ctx, int size, int curveId, whKeyId * inout_key_id, whNvmFlags flags, uint16_t label_len, uint8_t * label)
int wh_Client_EccSharedSecret(whClientContext * ctx, ecc_key * priv_key, ecc_key * pub_key, uint8_t * sig, uint16_t * out_size)
int wh_Client_EccSign(whClientContext * ctx, ecc_key * key, const uint8_t * hash, uint16_t hash_len, uint8_t * sig, uint16_t * inout_sig_len)
int wh_Client_EccVerify(whClientContext * ctx, ecc_key * key, const uint8_t * sig, uint16_t sig_len, const uint8_t * hash, uint16_t hash_len, int * out_res)
int wh_Client_RsaSetKeyId(RsaKey * key, whNvmId keyId)
Associates an RSA key with a specific key ID.
int wh_Client_RsaGetKeyId(RsaKey * key, whNvmId * outId)
Gets the wolfHSM keyId being used by the wolfCrypt struct.
int wh_Client_RsaImportKey(whClientContext * ctx, const RsaKey * key, whKeyId * inout_keyId, whNvmFlags flags, uint32_t label_len, uint8_t * label)
Imports wolfCrypt RSA key as a PCKS1 DER-formatted file into the wolfHSM server key cache.
int wh_Client_RsaExportKey(whClientContext * ctx, whKeyId keyId, RsaKey * key, uint32_t label_len, uint8_t * label)
Exports a PKCS1 DER-formated RSA key from the wolfHSM server keycache and decodes it into the wolfCrypt RSA key structure.
int wh_Client_RsaMakeExportKey(whClientContext * ctx, uint32_t size, uint32_t e, RsaKey * key)
int wh_Client_RsaMakeCacheKey(whClientContext * ctx, uint32_t size, uint32_t e, whKeyId * inout_keyId, whNvmFlags flags, uint32_t label_len, uint8_t * label)
int wh_Client_RsaFunction(whClientContext * ctx, RsaKey * key, int rsa_type, const uint8_t * in, uint16_t in_len, uint8_t * out, uint16_t * inout_out_len)
int wh_Client_RsaGetSize(whClientContext * ctx, const RsaKey * key, int * out_size)
int wh_Client_AesSetKeyId(Aes * key, whNvmId keyId)
Associates an AES key with a specific key ID.
int wh_Client_AesGetKeyId(Aes * key, whNvmId * outId)
Gets the wolfHSM keyId being used by the wolfCrypt struct.
int wh_Client_AesCbc(whClientContext * ctx, Aes * aes, int enc, const uint8_t * in, uint32_t len, uint8_t * out)
int wh_Client_AesGcm(whClientContext * ctx, Aes * aes, int enc, const uint8_t * in, uint32_t len, const uint8_t * iv, uint32_t iv_len, const uint8_t * authin, uint32_t authin_len, const uint8_t * dec_tag, uint8_t * enc_tag, uint32_t tag_len, uint8_t * out)
int wh_Client_Cmac(whClientContext * ctx, Cmac * cmac, CmacType type, const uint8_t * key, uint32_t keyLen, const uint8_t * in, uint32_t inLen, uint8_t * outMac, uint32_t * outMacLen)
Performs a CMAC operation on the input data.
int wh_Client_CmacCancelableResponse(whClientContext * c, Cmac * cmac, uint8_t * sig, uint16_t * outSz)
Handle cancelable CMAC response.
int wh_Client_CmacSetKeyId(Cmac * key, whNvmId keyId)
Associates a CMAC key with a specific key ID.
int wh_Client_CmacGetKeyId(Cmac * key, whNvmId * outId)
Gets the wolfHSM keyId being used by the wolfCrypt struct.
int wh_Client_CmacDma(whClientContext * ctx, Cmac * cmac, CmacType type, const uint8_t * key, uint32_t keyLen, const uint8_t * in, uint32_t inLen, uint8_t * outMac, uint32_t * outMacLen)
Performs CMAC operations using DMA for data transfer.
int wh_Client_Sha256(whClientContext * ctx, wc_Sha256 * sha, const uint8_t * in, uint32_t inLen, uint8_t * out)
Performs a SHA-256 hash operation on the input data.
int wh_Client_Sha256Dma(whClientContext * ctx, wc_Sha256 * sha, const uint8_t * in, uint32_t inLen, uint8_t * out)
Performs a SHA-256 hash operation on the input data using DMA.
int wh_Client_MlDsaSetKeyId(MlDsaKey * key, whKeyId keyId)
Associates a ML-DSA key with a specific key ID.
int wh_Client_MlDsaGetKeyId(MlDsaKey * key, whKeyId * outId)
Gets the wolfHSM keyId being used by the wolfCrypt struct.
int wh_Client_MlDsaImportKey(whClientContext * ctx, MlDsaKey * key, whKeyId * inout_keyId, whNvmFlags flags, uint16_t label_len, uint8_t * label)
Import a ML-DSA key to the server key cache.
int wh_Client_MlDsaExportKey(whClientContext * ctx, whKeyId keyId, MlDsaKey * key, uint16_t label_len, uint8_t * label)
Export a ML-DSA key from the server.
int wh_Client_MlDsaMakeExportKey(whClientContext * ctx, int type, int size, MlDsaKey * key)
Generate a new ML-DSA key pair and export the public key.
int wh_Client_MlDsaMakeCacheKey(whClientContext * ctx, int size, int level, whKeyId * inout_key_id, whNvmFlags flags, uint16_t label_len, uint8_t * label)
Create and cache a new ML-DSA key on the server.
int wh_Client_MlDsaSign(whClientContext * ctx, const byte * in, word32 in_len, byte * out, word32 * out_len, MlDsaKey * key)
Sign a message using a ML-DSA private key.
int wh_Client_MlDsaVerify(whClientContext * ctx, const byte * sig, word32 sig_len, const byte * msg, word32 msg_len, int * res, MlDsaKey * key)
Verify a ML-DSA signature.
int wh_Client_MlDsaCheckPrivKey(whClientContext * ctx, MlDsaKey * key, const byte * pubKey, word32 pubKeySz)
Check a ML-DSA private key.
int wh_Client_MlDsaImportKeyDma(whClientContext * ctx, MlDsaKey * key, whKeyId * inout_keyId, whNvmFlags flags, uint16_t label_len, uint8_t * label)
Import a ML-DSA key using DMA.
int wh_Client_MlDsaExportKeyDma(whClientContext * ctx, whKeyId keyId, MlDsaKey * key, uint16_t label_len, uint8_t * label)
Export a ML-DSA key using DMA.
int wh_Client_MlDsaMakeExportKeyDma(whClientContext * ctx, int level, MlDsaKey * key)
Generate a new ML-DSA key pair and export it using DMA.
int wh_Client_MlDsaSignDma(whClientContext * ctx, const byte * in, word32 in_len, byte * out, word32 * out_len, MlDsaKey * key)
Sign a message using ML-DSA with DMA.
int wh_Client_MlDsaVerifyDma(whClientContext * ctx, const byte * sig, word32 sig_len, const byte * msg, word32 msg_len, int * res, MlDsaKey * key)
Verify a ML-DSA signature with DMA.
int wh_Client_MlDsaCheckPrivKeyDma(whClientContext * ctx, MlDsaKey * key, const byte * pubKey, word32 pubKeySz)
Check a ML-DSA private key against public key with DMA.

Functions Documentation

function wh_Client_RngGenerate

int wh_Client_RngGenerate(
    whClientContext * ctx,
    uint8_t * out,
    uint32_t size
)

Generate random bytes.

Parameters:

  • ctx Pointer to the client context
  • out Pointer to the where the bytes are to be placed. May be NULL.
  • size Number of bytes to generate. *

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

This function requests the server to generate random bytes by repeatedly requesting the maximum block size of data from the server at a time

function wh_Client_Curve25519SetKeyId

int wh_Client_Curve25519SetKeyId(
    curve25519_key * key,
    whKeyId keyId
)

Associates a Curve25519 key with a specific key ID.

Parameters:

  • key Pointer to the Curve25519 key structure.
  • keyId Key ID to be associated with the Curve25519 key.

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

This function sets the device context of a Curve25519 key to the specified key ID. On the server side, this key ID is used to reference the key stored in the HSM

function wh_Client_Curve25519GetKeyId

int wh_Client_Curve25519GetKeyId(
    curve25519_key * key,
    whKeyId * outId
)

Gets the wolfHSM keyId being used by the wolfCrypt struct.

Parameters:

  • key Pointer to the Curve25519 key structure.
  • outId Pointer to the key ID to return.

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

This function gets the device context of a Curve25519 key that was previously set by either the crypto callback layer or wh_Client_SetKeyCurve25519.

function wh_Client_Curve25519ImportKey

int wh_Client_Curve25519ImportKey(
    whClientContext * ctx,
    curve25519_key * key,
    whKeyId * inout_keyId,
    whNvmFlags flags,
    uint16_t label_len,
    uint8_t * label
)

Imports wolfCrypt Curve25519 key as a raw byte array into the wolfHSM server key cache.

Parameters:

  • ctx Pointer to the wolfHSM client structure.
  • key Pointer to the curve25519 key structure.
  • inout_keyId Pointer to the key ID. Set to WH_KEYID_ERASED to have the server allocate a unique id. May be NULL.
  • flags Value of flags to indicate server usage
  • label_len Length of the optional label in bytes, Valid values are 0 to WH_NVM_LABEL_LEN.
  • label pointer to the optional label byte array. May be NULL.

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

This function converts the curve25519_key struct to serialized format, installs into the server's key cache, and provides the server-allocated keyId for reference.

function wh_Client_Curve25519ExportKey

int wh_Client_Curve25519ExportKey(
    whClientContext * ctx,
    whKeyId keyId,
    curve25519_key * key,
    uint16_t label_len,
    uint8_t * label
)

Exports a serialized curve25519 key from the wolfHSM server keycache and decodes it into the wolfCrypt curve25519 key structure.

Parameters:

  • ctx Pointer to the wolfHSM client structure.
  • out_keyId Server key ID to export.
  • key Pointer to the Curve25519 key structure.
  • label_len Length of the optional label in bytes, Valid values are 0 to WH_NVM_LABEL_LEN.
  • label pointer to the optional label byte array. May be NULL.

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

This function exports the specified key from wolfHSM server key cache as a serailized byte array and decodes the key into the wolfCrypt curve25519_key structure, optionally copying out the associated label as well.

function wh_Client_Curve25519MakeCacheKey

int wh_Client_Curve25519MakeCacheKey(
    whClientContext * ctx,
    uint16_t size,
    whKeyId * inout_key_id,
    whNvmFlags flags,
    const uint8_t * label,
    uint16_t label_len
)

Generate a Curve25519 key in the server key cache.

Parameters:

  • ctx Pointer to the client context
  • size Size of the key to generate in bytes, normally set to CURVE25519_KEY_SIZE.
  • inout_key_id. Set to WH_KEYID_ERASED to have the server select a unique id for this key.
  • flags Optional flags to be associated with the key while in the key cache or after being committed. Set to WH_NVM_FLAGS_NONE if not used.
  • label Optional label to be associated with the key while in the key cache or after being committed. Set to NULL if not used.
  • label_len Size of the label up to WH_NVM_LABEL_SIZE. Set to 0 if not used.

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

This function requests the server to generate a new Curve25519 key and insert it into the server's key cache.

function wh_Client_Curve25519MakeExportKey

int wh_Client_Curve25519MakeExportKey(
    whClientContext * ctx,
    uint16_t size,
    curve25519_key * key
)

Generate a Curve25519 key by the server and export to the client.

Parameters:

  • ctx Pointer to the client context
  • size Size of the key to generate in bytes, normally set to CURVE25519_KEY_SIZE.
  • key Pointer to a wolfCrypt key structure, which will be initialized to the new key pair when successful

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

This function requests the server to generate a new Curve25519 key pair and export it to the client, without using any key cache or additional resources

function wh_Client_Curve25519SharedSecret

int wh_Client_Curve25519SharedSecret(
    whClientContext * ctx,
    curve25519_key * priv_key,
    curve25519_key * pub_key,
    int endian,
    uint8_t * out,
    uint16_t * out_size
)

Compute an X25519 shared secret using a public and private key.

Parameters:

  • ctx Pointer to the client context
  • priv_key Pointer to a wolfCrypt key structure that holds the private key
  • pub_key Pointer to a wolfCrypt key structure that holds the public key
  • endian Endianness of the values. EC25519_BIG_ENDIAN (typical) or EC25519_LITTLE_ENDIAN

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

This function requests the server compute the shared secret using the provided wolfCrypt private and public keys. Note, the client will temporarily import any missing key material to the server as required.

function wh_Client_EccSetKeyId

int wh_Client_EccSetKeyId(
    ecc_key * key,
    whKeyId keyId
)

Associates a Ecc key with a specific key ID.

Parameters:

  • key Pointer to the Ecc key structure.
  • keyId Key ID to be associated with the Ecc key.

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

This function sets the device context of a Ecc key to the specified key ID. On the server side, this key ID is used to reference the key stored in the HSM

function wh_Client_EccGetKeyId

int wh_Client_EccGetKeyId(
    ecc_key * key,
    whKeyId * outId
)

Gets the wolfHSM keyId being used by the wolfCrypt struct.

Parameters:

  • key Pointer to the Ecc key structure.
  • outId Pointer to the key ID to return.

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

This function gets the device context of a Ecc key that was previously set by either the crypto callback layer or wh_Client_EccSetKeyId.

function wh_Client_EccImportKey

int wh_Client_EccImportKey(
    whClientContext * ctx,
    ecc_key * key,
    whKeyId * inout_keyId,
    whNvmFlags flags,
    uint16_t label_len,
    uint8_t * label
)

function wh_Client_EccExportKey

int wh_Client_EccExportKey(
    whClientContext * ctx,
    whKeyId keyId,
    ecc_key * key,
    uint16_t label_len,
    uint8_t * label
)

function wh_Client_EccMakeExportKey

int wh_Client_EccMakeExportKey(
    whClientContext * ctx,
    int size,
    int curveId,
    ecc_key * key
)

function wh_Client_EccMakeCacheKey

int wh_Client_EccMakeCacheKey(
    whClientContext * ctx,
    int size,
    int curveId,
    whKeyId * inout_key_id,
    whNvmFlags flags,
    uint16_t label_len,
    uint8_t * label
)

function wh_Client_EccSharedSecret

int wh_Client_EccSharedSecret(
    whClientContext * ctx,
    ecc_key * priv_key,
    ecc_key * pub_key,
    uint8_t * sig,
    uint16_t * out_size
)

function wh_Client_EccSign

int wh_Client_EccSign(
    whClientContext * ctx,
    ecc_key * key,
    const uint8_t * hash,
    uint16_t hash_len,
    uint8_t * sig,
    uint16_t * inout_sig_len
)

function wh_Client_EccVerify

int wh_Client_EccVerify(
    whClientContext * ctx,
    ecc_key * key,
    const uint8_t * sig,
    uint16_t sig_len,
    const uint8_t * hash,
    uint16_t hash_len,
    int * out_res
)

function wh_Client_RsaSetKeyId

int wh_Client_RsaSetKeyId(
    RsaKey * key,
    whNvmId keyId
)

Associates an RSA key with a specific key ID.

Parameters:

  • key Pointer to the RSA key structure.
  • keyId Key ID to be associated with the RSA key.

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

This function sets the device context of an RSA key to the specified key ID. On the server side, this key ID is used to reference the key stored in the HSM.

function wh_Client_RsaGetKeyId

int wh_Client_RsaGetKeyId(
    RsaKey * key,
    whNvmId * outId
)

Gets the wolfHSM keyId being used by the wolfCrypt struct.

Parameters:

  • key Pointer to the RSA key structure.
  • outId Pointer to the key ID to return.

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

This function gets the device context of a RSA key that was previously set by either the crypto callback layer or wh_Client_SetKeyRsa.

function wh_Client_RsaImportKey

int wh_Client_RsaImportKey(
    whClientContext * ctx,
    const RsaKey * key,
    whKeyId * inout_keyId,
    whNvmFlags flags,
    uint32_t label_len,
    uint8_t * label
)

Imports wolfCrypt RSA key as a PCKS1 DER-formatted file into the wolfHSM server key cache.

Parameters:

  • ctx Pointer to the wolfHSM client structure.
  • key Pointer to the RSA key structure.
  • flags Value of flags to indicate server usage
  • label_len Length of the optional label in bytes, Valid values are 0 to WH_NVM_LABEL_LEN.
  • label pointer to the optional label byte array. May be NULL.
  • out_keyId Pointer to the key ID to return.

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

This function converts the RsaKey struct to DER format, installs into the server's key cache, and provides the server-allocated keyId for reference.

function wh_Client_RsaExportKey

int wh_Client_RsaExportKey(
    whClientContext * ctx,
    whKeyId keyId,
    RsaKey * key,
    uint32_t label_len,
    uint8_t * label
)

Exports a PKCS1 DER-formated RSA key from the wolfHSM server keycache and decodes it into the wolfCrypt RSA key structure.

Parameters:

  • ctx Pointer to the wolfHSM client structure.
  • out_keyId Server key ID to export.
  • key Pointer to the RSA key structure.
  • label_len Length of the optional label in bytes, Valid values are 0 to WH_NVM_LABEL_LEN.
  • label pointer to the optional label byte array. May be NULL.

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

This function exports the specified key from wolfHSM server key cache as a PCKS1 DER file and decodes the key into the wolfCrypt RsaKey structure, optionally copying out the associated label as well.

function wh_Client_RsaMakeExportKey

int wh_Client_RsaMakeExportKey(
    whClientContext * ctx,
    uint32_t size,
    uint32_t e,
    RsaKey * key
)

function wh_Client_RsaMakeCacheKey

int wh_Client_RsaMakeCacheKey(
    whClientContext * ctx,
    uint32_t size,
    uint32_t e,
    whKeyId * inout_keyId,
    whNvmFlags flags,
    uint32_t label_len,
    uint8_t * label
)

function wh_Client_RsaFunction

int wh_Client_RsaFunction(
    whClientContext * ctx,
    RsaKey * key,
    int rsa_type,
    const uint8_t * in,
    uint16_t in_len,
    uint8_t * out,
    uint16_t * inout_out_len
)

function wh_Client_RsaGetSize

int wh_Client_RsaGetSize(
    whClientContext * ctx,
    const RsaKey * key,
    int * out_size
)

function wh_Client_AesSetKeyId

int wh_Client_AesSetKeyId(
    Aes * key,
    whNvmId keyId
)

Associates an AES key with a specific key ID.

Parameters:

  • key Pointer to the AES key structure.
  • keyId Key ID to be associated with the AES key.

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

This function sets the device context of an AES key to the specified key ID. On the server side, this key ID is used to reference the key stored in the HSM

function wh_Client_AesGetKeyId

int wh_Client_AesGetKeyId(
    Aes * key,
    whNvmId * outId
)

Gets the wolfHSM keyId being used by the wolfCrypt struct.

Parameters:

  • key Pointer to the AES key structure.
  • outId Pointer to the key ID to return.

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

This function gets the device context of a AES key that was previously set by either the crypto callback layer or wh_Client_SetKeyAes.

function wh_Client_AesCbc

int wh_Client_AesCbc(
    whClientContext * ctx,
    Aes * aes,
    int enc,
    const uint8_t * in,
    uint32_t len,
    uint8_t * out
)

function wh_Client_AesGcm

int wh_Client_AesGcm(
    whClientContext * ctx,
    Aes * aes,
    int enc,
    const uint8_t * in,
    uint32_t len,
    const uint8_t * iv,
    uint32_t iv_len,
    const uint8_t * authin,
    uint32_t authin_len,
    const uint8_t * dec_tag,
    uint8_t * enc_tag,
    uint32_t tag_len,
    uint8_t * out
)

function wh_Client_Cmac

int wh_Client_Cmac(
    whClientContext * ctx,
    Cmac * cmac,
    CmacType type,
    const uint8_t * key,
    uint32_t keyLen,
    const uint8_t * in,
    uint32_t inLen,
    uint8_t * outMac,
    uint32_t * outMacLen
)

Performs a CMAC operation on the input data.

Parameters:

  • ctx Pointer to the wolfHSM client context.
  • cmac Pointer to the CMAC structure.
  • type The type of CMAC operation.
  • key Pointer to the key buffer, or NULL if using a key stored in HSM.
  • keyLen Length of the key in bytes.
  • in Pointer to the input data buffer, or NULL for finalization.
  • inLen Length of the input data in bytes.
  • outMac Pointer to the output buffer for the CMAC tag.
  • outMacLen Pointer to the size of the output buffer, updated with actual size.

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

This function performs a CMAC operation with the specified parameters. It can be used for initialization, update, or finalization of CMAC operations, depending on the input arguments.

function wh_Client_CmacCancelableResponse

int wh_Client_CmacCancelableResponse(
    whClientContext * c,
    Cmac * cmac,
    uint8_t * sig,
    uint16_t * outSz
)

Handle cancelable CMAC response.

Parameters:

  • c Pointer to the client context structure.
  • cmac Pointer to the CMAC key structure.
  • out Buffer to store the CMAC result, only required after wc_CmacFinal.
  • outSz Pointer to the size of the out buffer in bytes, will be set to the size returned by the server on return.

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

This function handles a CMAC operation response from the server when cancellation has been enabled, since wolfCrypt won't automatically block and wait for the response. Note that DMA-based CMAC operations are NOT cancellable and if a cancel is requested, the cancellation will be aborted.

function wh_Client_CmacSetKeyId

int wh_Client_CmacSetKeyId(
    Cmac * key,
    whNvmId keyId
)

Associates a CMAC key with a specific key ID.

Parameters:

  • key Pointer to the CMAC key structure.
  • keyId Key ID to be associated with the CMAC key.

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

This function sets the device context of a CMAC key to the specified key ID. On the server side, this key ID is used to reference the key stored in the HSM

function wh_Client_CmacGetKeyId

int wh_Client_CmacGetKeyId(
    Cmac * key,
    whNvmId * outId
)

Gets the wolfHSM keyId being used by the wolfCrypt struct.

Parameters:

  • key Pointer to the CMAC key structure.
  • outId Pointer to the key ID to return.

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

This function gets the device context of a CMAC key that was previously set by either the crypto callback layer or wh_Client_SetKeyCmac.

function wh_Client_CmacDma

int wh_Client_CmacDma(
    whClientContext * ctx,
    Cmac * cmac,
    CmacType type,
    const uint8_t * key,
    uint32_t keyLen,
    const uint8_t * in,
    uint32_t inLen,
    uint8_t * outMac,
    uint32_t * outMacLen
)

Performs CMAC operations using DMA for data transfer.

Parameters:

  • ctx Pointer to the client context structure.
  • cmac Pointer to the CMAC structure to be used.
  • type The type of CMAC operation (e.g., WC_CMAC_AES).
  • key Pointer to the key data. NULL if using a stored key.
  • keyLen Length of the key in bytes.
  • in Pointer to the input data. NULL if not performing an update.
  • inLen Length of the input data in bytes.
  • outMac Pointer to store the CMAC result. NULL if not finalizing.
  • outMacLen Pointer to the size of the outMac buffer. Updated with actual size on return.

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

This function performs CMAC operations (initialize, update, finalize) using DMA for efficient data transfer between client and server. The operation performed depends on which parameters are non-NULL.

function wh_Client_Sha256

int wh_Client_Sha256(
    whClientContext * ctx,
    wc_Sha256 * sha,
    const uint8_t * in,
    uint32_t inLen,
    uint8_t * out
)

Performs a SHA-256 hash operation on the input data.

Parameters:

  • ctx Pointer to the client context structure.
  • sha Pointer to the SHA-256 context structure.
  • in Pointer to the input data.
  • inLen Length of the input data in bytes.
  • out Pointer to the output buffer.

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

This function performs a SHA-256 hash operation on the input data and stores the result in the output buffer.

function wh_Client_Sha256Dma

int wh_Client_Sha256Dma(
    whClientContext * ctx,
    wc_Sha256 * sha,
    const uint8_t * in,
    uint32_t inLen,
    uint8_t * out
)

Performs a SHA-256 hash operation on the input data using DMA.

Parameters:

  • ctx Pointer to the client context structure.
  • sha Pointer to the SHA-256 context structure.
  • in Pointer to the input data.
  • inLen Length of the input data in bytes.
  • out Pointer to the output buffer.

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

This function performs a SHA-256 hash operation on the input data and stores the result in the output buffer using DMA.

function wh_Client_MlDsaSetKeyId

int wh_Client_MlDsaSetKeyId(
    MlDsaKey * key,
    whKeyId keyId
)

Associates a ML-DSA key with a specific key ID.

Parameters:

  • key Pointer to the ML-DSA key structure.
  • keyId Key ID to be associated with the ML-DSA key.

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

This function sets the device context of a ML-DSA key to the specified key ID. On the server side, this key ID is used to reference the key stored in the HSM

function wh_Client_MlDsaGetKeyId

int wh_Client_MlDsaGetKeyId(
    MlDsaKey * key,
    whKeyId * outId
)

Gets the wolfHSM keyId being used by the wolfCrypt struct.

Parameters:

  • key Pointer to the ML-DSA key structure.
  • outId Pointer to the key ID to return.

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

This function gets the device context of a ML-DSA key that was previously set by either the crypto callback layer or wh_Client_MlDsaSetKeyId.

function wh_Client_MlDsaImportKey

int wh_Client_MlDsaImportKey(
    whClientContext * ctx,
    MlDsaKey * key,
    whKeyId * inout_keyId,
    whNvmFlags flags,
    uint16_t label_len,
    uint8_t * label
)

Import a ML-DSA key to the server key cache.

Parameters:

  • ctx Pointer to the client context
  • key Pointer to the key to import
  • inout_keyId Pointer to key ID to use/receive
  • flags Flags to control key persistence
  • label_len Length of optional label
  • label Optional label to associate with key

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

function wh_Client_MlDsaExportKey

int wh_Client_MlDsaExportKey(
    whClientContext * ctx,
    whKeyId keyId,
    MlDsaKey * key,
    uint16_t label_len,
    uint8_t * label
)

Export a ML-DSA key from the server.

Parameters:

  • ctx Pointer to the client context
  • keyId ID of key to export
  • key Pointer to receive exported key
  • label_len Length of optional label buffer
  • label Optional buffer to receive key label

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

function wh_Client_MlDsaMakeExportKey

int wh_Client_MlDsaMakeExportKey(
    whClientContext * ctx,
    int type,
    int size,
    MlDsaKey * key
)

Generate a new ML-DSA key pair and export the public key.

Parameters:

  • ctx Pointer to the client context structure.
  • type The ML-DSA algorithm type.
  • size Size of the key in bits.
  • key Pointer to the ML-DSA key structure to store the key.

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

This function generates a new ML-DSA key pair in the HSM and exports the public key to the client. The private key remains securely stored in the HSM.

function wh_Client_MlDsaMakeCacheKey

int wh_Client_MlDsaMakeCacheKey(
    whClientContext * ctx,
    int size,
    int level,
    whKeyId * inout_key_id,
    whNvmFlags flags,
    uint16_t label_len,
    uint8_t * label
)

Create and cache a new ML-DSA key on the server.

Parameters:

  • ctx Pointer to the client context
  • size Size of key to generate
  • level ML-DSA security level of the key to generate
  • inout_key_id Pointer to key ID to use/receive
  • flags Flags to control key persistence
  • label_len Length of optional label
  • label Optional label to associate with key

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

function wh_Client_MlDsaSign

int wh_Client_MlDsaSign(
    whClientContext * ctx,
    const byte * in,
    word32 in_len,
    byte * out,
    word32 * out_len,
    MlDsaKey * key
)

Sign a message using a ML-DSA private key.

Parameters:

  • ctx Pointer to the client context structure.
  • in Pointer to the message to sign.
  • in_len Length of the message in bytes.
  • out Buffer to store the signature.
  • out_len Pointer to size of output buffer, updated with actual size.
  • key Pointer to the ML-DSA key structure.

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

This function signs a message using a ML-DSA private key stored in the HSM.

function wh_Client_MlDsaVerify

int wh_Client_MlDsaVerify(
    whClientContext * ctx,
    const byte * sig,
    word32 sig_len,
    const byte * msg,
    word32 msg_len,
    int * res,
    MlDsaKey * key
)

Verify a ML-DSA signature.

Parameters:

  • ctx Pointer to the client context structure.
  • sig Pointer to the signature to verify.
  • sig_len Length of the signature in bytes.
  • msg Pointer to the original message.
  • msg_len Length of the message in bytes.
  • res Pointer to store verification result (1=success, 0=failure).
  • key Pointer to the ML-DSA key structure.

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

This function verifies a ML-DSA signature using the HSM.

function wh_Client_MlDsaCheckPrivKey

int wh_Client_MlDsaCheckPrivKey(
    whClientContext * ctx,
    MlDsaKey * key,
    const byte * pubKey,
    word32 pubKeySz
)

Check a ML-DSA private key.

Parameters:

  • ctx Pointer to the client context structure.
  • key Pointer to the ML-DSA key structure.
  • pubKey Pointer to the public key data.
  • pubKeySz Size of the public key in bytes.

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

This function validates a ML-DSA private key against its public key using the HSM.

function wh_Client_MlDsaImportKeyDma

int wh_Client_MlDsaImportKeyDma(
    whClientContext * ctx,
    MlDsaKey * key,
    whKeyId * inout_keyId,
    whNvmFlags flags,
    uint16_t label_len,
    uint8_t * label
)

Import a ML-DSA key using DMA.

Parameters:

  • ctx Pointer to the client context structure.
  • key Pointer to the ML-DSA key structure representing the key to import.
  • inout_keyId Pointer to store/provide the key ID.
  • flags NVM flags for key storage.
  • label_len Length of the key label in bytes.
  • label Pointer to the key label.

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

This function imports a ML-DSA key into the HSM using DMA.

function wh_Client_MlDsaExportKeyDma

int wh_Client_MlDsaExportKeyDma(
    whClientContext * ctx,
    whKeyId keyId,
    MlDsaKey * key,
    uint16_t label_len,
    uint8_t * label
)

Export a ML-DSA key using DMA.

Parameters:

  • ctx Pointer to the client context structure.
  • keyId ID of the key to export.
  • key Pointer to the ML-DSA key structure to hold the exported key.
  • label_len Length of the key label in bytes.
  • label Pointer to the key label.

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

This function exports a ML-DSA key from the HSM using DMA.

function wh_Client_MlDsaMakeExportKeyDma

int wh_Client_MlDsaMakeExportKeyDma(
    whClientContext * ctx,
    int level,
    MlDsaKey * key
)

Generate a new ML-DSA key pair and export it using DMA.

Parameters:

  • ctx Pointer to the client context structure.
  • level The ML-DSA security level.
  • key Pointer to the ML-DSA key structure to store the key.

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

This function generates a new ML-DSA key pair in the HSM and exports it using DMA.

function wh_Client_MlDsaSignDma

int wh_Client_MlDsaSignDma(
    whClientContext * ctx,
    const byte * in,
    word32 in_len,
    byte * out,
    word32 * out_len,
    MlDsaKey * key
)

Sign a message using ML-DSA with DMA.

Parameters:

  • ctx Pointer to the client context structure.
  • in Pointer to the message to sign.
  • in_len Length of the message in bytes.
  • out Pointer to store the signature.
  • out_len On input, size of out buffer. On output, length of signature.
  • key Pointer to the ML-DSA key structure.

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

This function signs a message using ML-DSA with DMA.

function wh_Client_MlDsaVerifyDma

int wh_Client_MlDsaVerifyDma(
    whClientContext * ctx,
    const byte * sig,
    word32 sig_len,
    const byte * msg,
    word32 msg_len,
    int * res,
    MlDsaKey * key
)

Verify a ML-DSA signature with DMA.

Parameters:

  • ctx Pointer to the client context structure.
  • sig Pointer to the signature to verify.
  • sig_len Length of the signature in bytes.
  • msg Pointer to the message that was signed.
  • msg_len Length of the message in bytes.
  • res Result of verification (1 = success, 0 = failure).
  • key Pointer to the ML-DSA key structure.

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

This function verifies a ML-DSA signature with DMA.

function wh_Client_MlDsaCheckPrivKeyDma

int wh_Client_MlDsaCheckPrivKeyDma(
    whClientContext * ctx,
    MlDsaKey * key,
    const byte * pubKey,
    word32 pubKeySz
)

Check a ML-DSA private key against public key with DMA.

Parameters:

  • ctx Pointer to the client context structure.
  • key Pointer to the ML-DSA private key structure.
  • pubKey Pointer to the public key to check against.
  • pubKeySz Size of the public key in bytes.

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

This function checks if a ML-DSA private key matches a public key with DMA.

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_crypto.h
 */

#ifndef WOLFHSM_WH_CLIENT_CRYPTO_H_
#define WOLFHSM_WH_CLIENT_CRYPTO_H_

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

#ifndef WOLFHSM_CFG_NO_CRYPTO

/* 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_client.h"

#include "wolfssl/wolfcrypt/settings.h"
#include "wolfssl/wolfcrypt/types.h"
#include "wolfssl/wolfcrypt/error-crypt.h"
#include "wolfssl/wolfcrypt/wc_port.h"
#include "wolfssl/wolfcrypt/cryptocb.h"
#include "wolfssl/wolfcrypt/aes.h"
#include "wolfssl/wolfcrypt/cmac.h"
#include "wolfssl/wolfcrypt/curve25519.h"
#include "wolfssl/wolfcrypt/rsa.h"
#include "wolfssl/wolfcrypt/ecc.h"
#include "wolfssl/wolfcrypt/dilithium.h"

int wh_Client_RngGenerate(whClientContext* ctx, uint8_t* out, uint32_t size);

#ifdef HAVE_CURVE25519
int wh_Client_Curve25519SetKeyId(curve25519_key* key, whKeyId keyId);

int wh_Client_Curve25519GetKeyId(curve25519_key* key, whKeyId* outId);

int wh_Client_Curve25519ImportKey(whClientContext* ctx, curve25519_key* key,
        whKeyId *inout_keyId, whNvmFlags flags,
        uint16_t label_len, uint8_t* label);

int wh_Client_Curve25519ExportKey(whClientContext* ctx, whKeyId keyId,
        curve25519_key* key, uint16_t label_len, uint8_t* label);

int wh_Client_Curve25519MakeCacheKey(whClientContext* ctx,
        uint16_t size,
        whKeyId *inout_key_id, whNvmFlags flags,
        const uint8_t* label, uint16_t label_len);

int wh_Client_Curve25519MakeExportKey(whClientContext* ctx,
        uint16_t size, curve25519_key* key);

int wh_Client_Curve25519SharedSecret(whClientContext* ctx,
        curve25519_key* priv_key, curve25519_key* pub_key,
        int endian, uint8_t* out, uint16_t *out_size);

#endif /* HAVE_CURVE25519 */

#ifdef HAVE_ECC
int wh_Client_EccSetKeyId(ecc_key* key, whKeyId keyId);

int wh_Client_EccGetKeyId(ecc_key* key, whKeyId* outId);

/* TODO: Send key to server */
int wh_Client_EccImportKey(whClientContext* ctx, ecc_key* key,
        whKeyId *inout_keyId, whNvmFlags flags,
        uint16_t label_len, uint8_t* label);
/* TODO: Recv key from server */
int wh_Client_EccExportKey(whClientContext* ctx, whKeyId keyId,
        ecc_key* key,
        uint16_t label_len, uint8_t* label);

/* TODO: Server creates and exports a key, without caching */
int wh_Client_EccMakeExportKey(whClientContext* ctx,
        int size, int curveId, ecc_key* key);
/* TODO: Server creates and imports the key to cache. */
int wh_Client_EccMakeCacheKey(whClientContext* ctx,
        int size, int curveId,
        whKeyId *inout_key_id, whNvmFlags flags,
        uint16_t label_len, uint8_t* label);

/* TODO: Perform shared secret computation (ECDH) */
int wh_Client_EccSharedSecret(whClientContext* ctx,
                                ecc_key* priv_key, ecc_key* pub_key,
                                uint8_t* sig, uint16_t *out_size);

/* TODO: Server generates signature of input hash */
int wh_Client_EccSign(whClientContext* ctx,
        ecc_key* key,
        const uint8_t* hash, uint16_t hash_len,
        uint8_t* sig, uint16_t *inout_sig_len);

/* TODO: Server verifies the signature of the provided hash */
int wh_Client_EccVerify(whClientContext* ctx, ecc_key* key,
        const uint8_t* sig, uint16_t sig_len,
        const uint8_t* hash, uint16_t hash_len,
        int *out_res);

#endif /* HAVE_ECC */

#ifndef NO_RSA
int wh_Client_RsaSetKeyId(RsaKey* key, whNvmId keyId);

int wh_Client_RsaGetKeyId(RsaKey* key, whNvmId* outId);

int wh_Client_RsaImportKey(whClientContext* ctx, const RsaKey* key,
        whKeyId *inout_keyId, whNvmFlags flags,
        uint32_t label_len, uint8_t* label);

int wh_Client_RsaExportKey(whClientContext* ctx, whKeyId keyId,
        RsaKey* key, uint32_t label_len, uint8_t* label);

/* Generate an RSA key on the server and export it inta an RSA struct */
int wh_Client_RsaMakeExportKey(whClientContext* ctx,
        uint32_t size, uint32_t e, RsaKey* key);

/* Generate an RSA key on the server and put it in the server keycache */
int wh_Client_RsaMakeCacheKey(whClientContext* ctx,
        uint32_t size, uint32_t e,
        whKeyId *inout_keyId, whNvmFlags flags,
        uint32_t label_len, uint8_t* label);

/* TODO: Request server to perform the RSA function */
int wh_Client_RsaFunction(whClientContext* ctx,
        RsaKey* key, int rsa_type,
        const uint8_t* in, uint16_t in_len,
        uint8_t* out, uint16_t *inout_out_len);

/* TODO: Request server to get the RSA size */
int wh_Client_RsaGetSize(whClientContext* ctx,
        const RsaKey* key, int* out_size);


#endif /* !NO_RSA */

#ifndef NO_AES
int wh_Client_AesSetKeyId(Aes* key, whNvmId keyId);

int wh_Client_AesGetKeyId(Aes* key, whNvmId* outId);

#ifdef HAVE_AES_CBC
int wh_Client_AesCbc(whClientContext* ctx,
        Aes* aes, int enc,
        const uint8_t* in, uint32_t len,
        uint8_t* out);
#endif /* HAVE_AES_CBC */

#ifdef HAVE_AESGCM
/* TODO: Add documentation */
int wh_Client_AesGcm(whClientContext* ctx,
        Aes* aes, int enc,
        const uint8_t* in, uint32_t len,
        const uint8_t* iv, uint32_t iv_len,
        const uint8_t* authin, uint32_t authin_len,
        const uint8_t* dec_tag, uint8_t* enc_tag, uint32_t tag_len,
        uint8_t* out);
#endif /* HAVE_AESGCM */

#endif /* !NO_AES */


#ifdef WOLFSSL_CMAC

int wh_Client_Cmac(whClientContext* ctx, Cmac* cmac, CmacType type,
                   const uint8_t* key, uint32_t keyLen, const uint8_t* in,
                   uint32_t inLen, uint8_t* outMac, uint32_t* outMacLen);

int wh_Client_CmacCancelableResponse(whClientContext* c, Cmac* cmac,
    uint8_t* sig, uint16_t* outSz);

int wh_Client_CmacSetKeyId(Cmac* key, whNvmId keyId);

int wh_Client_CmacGetKeyId(Cmac* key, whNvmId* outId);

#ifdef WOLFHSM_CFG_DMA
int wh_Client_CmacDma(whClientContext* ctx, Cmac* cmac, CmacType type,
                      const uint8_t* key, uint32_t keyLen, const uint8_t* in,
                      uint32_t inLen, uint8_t* outMac, uint32_t* outMacLen);
#endif /* WOLFHSM_CFG_DMA */

#endif /* WOLFSSL_CMAC */

#ifndef NO_SHA256

int wh_Client_Sha256(whClientContext* ctx, wc_Sha256* sha, const uint8_t* in,
                     uint32_t inLen, uint8_t* out);

int wh_Client_Sha256Dma(whClientContext* ctx, wc_Sha256* sha, const uint8_t* in,
                        uint32_t inLen, uint8_t* out);

#endif /* !NO_SHA256 */

#ifdef HAVE_DILITHIUM

int wh_Client_MlDsaSetKeyId(MlDsaKey* key, whKeyId keyId);

int wh_Client_MlDsaGetKeyId(MlDsaKey* key, whKeyId* outId);

int wh_Client_MlDsaImportKey(whClientContext* ctx, MlDsaKey* key,
                             whKeyId* inout_keyId, whNvmFlags flags,
                             uint16_t label_len, uint8_t* label);

int wh_Client_MlDsaExportKey(whClientContext* ctx, whKeyId keyId, MlDsaKey* key,
                             uint16_t label_len, uint8_t* label);

int wh_Client_MlDsaMakeExportKey(whClientContext* ctx, int type, int size,
                                 MlDsaKey* key);
int wh_Client_MlDsaMakeCacheKey(whClientContext* ctx, int size, int level,
                                whKeyId* inout_key_id, whNvmFlags flags,
                                uint16_t label_len, uint8_t* label);
int wh_Client_MlDsaSign(whClientContext* ctx, const byte* in, word32 in_len,
                        byte* out, word32* out_len, MlDsaKey* key);

int wh_Client_MlDsaVerify(whClientContext* ctx, const byte* sig, word32 sig_len,
                          const byte* msg, word32 msg_len, int* res,
                          MlDsaKey* key);

int wh_Client_MlDsaCheckPrivKey(whClientContext* ctx, MlDsaKey* key,
                                const byte* pubKey, word32 pubKeySz);


#ifdef WOLFHSM_CFG_DMA
int wh_Client_MlDsaImportKeyDma(whClientContext* ctx, MlDsaKey* key,
                                whKeyId* inout_keyId, whNvmFlags flags,
                                uint16_t label_len, uint8_t* label);

int wh_Client_MlDsaExportKeyDma(whClientContext* ctx, whKeyId keyId,
                                MlDsaKey* key, uint16_t label_len,
                                uint8_t* label);

int wh_Client_MlDsaMakeExportKeyDma(whClientContext* ctx, int level,
                                    MlDsaKey* key);


int wh_Client_MlDsaSignDma(whClientContext* ctx, const byte* in, word32 in_len,
                           byte* out, word32* out_len, MlDsaKey* key);

int wh_Client_MlDsaVerifyDma(whClientContext* ctx, const byte* sig,
                             word32 sig_len, const byte* msg, word32 msg_len,
                             int* res, MlDsaKey* key);

int wh_Client_MlDsaCheckPrivKeyDma(whClientContext* ctx, MlDsaKey* key,
                                   const byte* pubKey, word32 pubKeySz);

#endif /* WOLFHSM_CFG_DMA */

#endif /* HAVE_DILITHIUM */

#endif /* !WOLFHSM_CFG_NO_CRYPTO */
#endif /* !WOLFHSM_WH_CLIENT_CRYPTO_H_ */

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