Skip to content

cryptocb.h

Functions

Name
int wc_CryptoCb_RegisterDevice(int devId, CryptoDevCallbackFunc cb, void * ctx)
This function registers a unique device identifier (devID) and callback function for offloading crypto operations to external hardware such as Key Store, Secure Element, HSM, PKCS11 or TPM.
void wc_CryptoCb_UnRegisterDevice(int devId)
This function un_registers a unique device identifier (devID) callback function.
int wc_CryptoCb_DefaultDevID(void )
This function returns the default device ID for crypto callbacks. This is useful when you want to get the device ID that was set as the default for the library.
void wc_CryptoCb_SetDeviceFindCb(CryptoDevCallbackFind cb)
This function sets a callback for finding crypto devices. The callback is invoked when a device ID needs to be resolved to a device context. This is useful for dynamic device management.
void wc_CryptoCb_InfoString(wc_CryptoInfo * info)
This function converts a wc_CryptoInfo structure to a human-readable string for debugging purposes. The string is printed to stdout and describes the cryptographic operation being performed.
int wc_CryptoCb_AesSetKey(Aes * aes, const byte * key, word32 keySz)
Import an AES key into a CryptoCB device for hardware offload.
int wc_CryptoCb_EccMakePub(ecc_key * key, ecc_point * pubOut)
Offload deriving an ECC public key Q = d*G from its private key to a CryptoCB device.
int wc_CryptoCb_EccCheckPubKey(ecc_key * key, int checkOrder, int checkPriv)
Offload validating an ECC key to a CryptoCB device.

Functions Documentation

function wc_CryptoCb_RegisterDevice

int wc_CryptoCb_RegisterDevice(
    int devId,
    CryptoDevCallbackFunc cb,
    void * ctx
)

This function registers a unique device identifier (devID) and callback function for offloading crypto operations to external hardware such as Key Store, Secure Element, HSM, PKCS11 or TPM.

Parameters:

  • devId any unique value, not -2 (INVALID_DEVID)
  • cb a callback function with prototype: typedef int (CryptoDevCallbackFunc)(int devId, wc_CryptoInfo info, void* ctx);

See:

Return:

  • CRYPTOCB_UNAVAILABLE to fallback to using software crypto
  • 0 for success
  • negative value for failure

For STSAFE with Crypto Callbacks example see wolfcrypt/src/port/st/stsafe.c and the wolfSSL_STSAFE_CryptoDevCb function.

For TPM based crypto callbacks example see the wolfTPM2_CryptoDevCb function in wolfTPM src/tpm2_wrap.c

Example

#include <wolfssl/wolfcrypt/settings.h>
#include <wolfssl/wolfcrypt/cryptocb.h>
static int myCryptoCb_Func(int devId, wc_CryptoInfo* info, void* ctx)
{
    int ret = CRYPTOCB_UNAVAILABLE;

    if (info->algo_type == WC_ALGO_TYPE_PK) {
    #ifndef NO_RSA
        if (info->pk.type == WC_PK_TYPE_RSA) {
            switch (info->pk.rsa.type) {
                case RSA_PUBLIC_ENCRYPT:
                case RSA_PUBLIC_DECRYPT:
                    // RSA public op
                    ret = wc_RsaFunction(
                        info->pk.rsa.in, info->pk.rsa.inLen,
                        info->pk.rsa.out, info->pk.rsa.outLen,
                        info->pk.rsa.type, info->pk.rsa.key,
                        info->pk.rsa.rng);
                    break;
                case RSA_PRIVATE_ENCRYPT:
                case RSA_PRIVATE_DECRYPT:
                    // RSA private op
                    ret = wc_RsaFunction(
                        info->pk.rsa.in, info->pk.rsa.inLen,
                        info->pk.rsa.out, info->pk.rsa.outLen,
                        info->pk.rsa.type, info->pk.rsa.key,
                        info->pk.rsa.rng);
                    break;
            }
        }
    #endif
    #if defined(WC_RSA_PSS) && !defined(NO_RSA)
        if (info->pk.type == WC_PK_TYPE_RSA_PSS) {
            // RSA-PSS sign/verify
            ret = wc_RsaPSS_Sign_ex(
                info->pk.rsa.in, info->pk.rsa.inLen,
                info->pk.rsa.out, *info->pk.rsa.outLen,
                WC_HASH_TYPE_SHA256, WC_MGF1SHA256,
                RSA_PSS_SALT_LEN_DEFAULT,
                info->pk.rsa.key, info->pk.rsa.rng);
        }
    #endif
    #ifdef HAVE_ECC
        if (info->pk.type == WC_PK_TYPE_ECDSA_SIGN) {
            // ECDSA
            ret = wc_ecc_sign_hash(
                info->pk.eccsign.in, info->pk.eccsign.inlen,
                info->pk.eccsign.out, info->pk.eccsign.outlen,
                info->pk.eccsign.rng, info->pk.eccsign.key);
        }
    #endif
    #ifdef HAVE_ED25519
        if (info->pk.type == WC_PK_TYPE_ED25519_SIGN) {
            // ED25519 sign
            ret = wc_ed25519_sign_msg_ex(
                info->pk.ed25519sign.in, info->pk.ed25519sign.inLen,
                info->pk.ed25519sign.out, info->pk.ed25519sign.outLen,
                info->pk.ed25519sign.key, info->pk.ed25519sign.type,
                info->pk.ed25519sign.context,
                info->pk.ed25519sign.contextLen);
        }
    #endif
    }
    return ret;
}

int devId = 1;
wc_CryptoCb_RegisterDevice(devId, myCryptoCb_Func, &myCtx);
wolfSSL_CTX_SetDevId(ctx, devId);

function wc_CryptoCb_UnRegisterDevice

void wc_CryptoCb_UnRegisterDevice(
    int devId
)

This function un-registers a unique device identifier (devID) callback function.

Parameters:

  • devId any unique value, not -2 (INVALID_DEVID)

See:

Return: none No returns.

Example

wc_CryptoCb_UnRegisterDevice(devId);
devId = INVALID_DEVID;
wolfSSL_CTX_SetDevId(ctx, devId);

function wc_CryptoCb_DefaultDevID

int wc_CryptoCb_DefaultDevID(
    void 
)

This function returns the default device ID for crypto callbacks. This is useful when you want to get the device ID that was set as the default for the library.

See:

Return: The default device ID, or INVALID_DEVID if no default is set.

Example

int devId = wc_CryptoCb_DefaultDevID();
if (devId != INVALID_DEVID) {
    // default device ID is set
}

function wc_CryptoCb_SetDeviceFindCb

void wc_CryptoCb_SetDeviceFindCb(
    CryptoDevCallbackFind cb
)

This function sets a callback for finding crypto devices. The callback is invoked when a device ID needs to be resolved to a device context. This is useful for dynamic device management.

Parameters:

  • cb callback function with prototype: typedef void (CryptoDevCallbackFind)(int devId);

See: wc_CryptoCb_RegisterDevice

Return: none No returns.

Example

void* myDeviceFindCb(int devId) {
    // lookup device context by ID
    return deviceContext;
}

wc_CryptoCb_SetDeviceFindCb(myDeviceFindCb);

function wc_CryptoCb_InfoString

void wc_CryptoCb_InfoString(
    wc_CryptoInfo * info
)

This function converts a wc_CryptoInfo structure to a human-readable string for debugging purposes. The string is printed to stdout and describes the cryptographic operation being performed.

Parameters:

  • info pointer to the wc_CryptoInfo structure to convert

See: wc_CryptoCb_RegisterDevice

Return: none No returns.

Example

int myCryptoCb(int devId, wc_CryptoInfo* info, void* ctx) {
    // print debug info about the operation
    wc_CryptoCb_InfoString(info);

    // handle the operation
    return CRYPTOCB_UNAVAILABLE;
}

function wc_CryptoCb_AesSetKey

int wc_CryptoCb_AesSetKey(
    Aes * aes,
    const byte * key,
    word32 keySz
)

Import an AES key into a CryptoCB device for hardware offload.

Parameters:

  • aes AES context
  • key Pointer to raw AES key material
  • keySz Size of key in bytes

See:

Return:

  • 0 on success
  • CRYPTOCB_UNAVAILABLE if device does not support this operation
  • BAD_FUNC_ARG on invalid parameters

This function allows AES keys to be handled by an external device (e.g. Secure Element or HSM). When supported, the device callback stores the key internally and sets an opaque handle in aes->devCtx.

When CryptoCB AES SetKey support is enabled (WOLF_CRYPTO_CB_AES_SETKEY), wolfCrypt routes AES-GCM operations through the CryptoCB interface.

TLS Builds (Default):**

  • Key bytes ARE stored in wolfCrypt memory (devKey) for fallback
  • GCM tables ARE generated for software fallback
  • Provides hardware acceleration with automatic fallback Crypto-Only Builds (–disable-tls):**
  • Key bytes NOT stored in wolfCrypt memory (true key isolation)
  • GCM tables skipped (true hardware offload)
  • Callback must handle all GCM operations (SetKey, Encrypt, Decrypt, Free)

If the callback returns success (0), full AES-GCM offload is assumed. The callback must handle SetKey, Encrypt, Decrypt, and Free operations.

Example

#include <wolfssl/wolfcrypt/cryptocb.h>
#include <wolfssl/wolfcrypt/aes.h>

Aes aes;
byte key[32] = { /* 256-bit key */ };
int devId = 1;

/* Register your CryptoCB callback first */
wc_CryptoCb_RegisterDevice(devId, myCryptoCallback, NULL);

wc_AesInit(&aes, NULL, devId);
/* wc_AesGcmSetKey internally calls wc_CryptoCb_AesSetKey */
if (wc_CryptoCb_AesSetKey(&aes, key, sizeof(key)) == 0) {
    /* Key successfully imported to device via callback */
    /* aes.devCtx now contains device handle */
    /* Full GCM offload is assumed - callback must handle all operations */
}

function wc_CryptoCb_EccMakePub

int wc_CryptoCb_EccMakePub(
    ecc_key * key,
    ecc_point * pubOut
)

Offload deriving an ECC public key Q = d*G from its private key to a CryptoCB device.

Parameters:

  • key ECC key providing the device id, curve identity, heap hint and the private scalar
  • pubOut [out] resulting affine public point Q = d*G

See:

Return:

  • 0 on success
  • CRYPTOCB_UNAVAILABLE if no device handles the operation, or key or pubOut is NULL (wolfCrypt falls back to software, which reports the argument error)

Used by wc_ecc_make_pub / wc_ecc_make_pub_ex. The callback boundary is math-free: the resulting public point crosses as X9.63 uncompressed bytes (0x04 || X || Y, each ordinate zero-padded to the curve size) in wc_CryptoInfo.pk.ecc_make_pub (pubOut / pubOutSz). This wrapper performs all bignum (de)serialization, so a device handler only deals with byte arrays and never with wolfCrypt's internal mp_int representation. The private scalar is taken from the ecc_key (resident in a secure element, or key->k); curve identity comes from key->dp.

function wc_CryptoCb_EccCheckPubKey

int wc_CryptoCb_EccCheckPubKey(
    ecc_key * key,
    int checkOrder,
    int checkPriv
)

Offload validating an ECC key to a CryptoCB device.

Parameters:

  • key ECC key to validate (curve identity from key->dp)
  • checkOrder when 1 the caller requested validation that the point has the curve order (point * order == infinity)
  • checkPriv when 1 the caller also requested validation of the private part (scalar range, consistency with the public point)

See:

Return:

  • 0 if the key is valid
  • CRYPTOCB_UNAVAILABLE if no device handles the operation (wolfCrypt falls back to software)

Used by wc_ecc_check_key and the key generation / import validation paths. The public point crosses the (math-free) callback boundary as X9.63 uncompressed bytes in wc_CryptoInfo.pk.ecc_check_pub (pubKey / pubKeySz); this wrapper serializes key->pubkey so a device handler only deals with byte arrays. When the key state is ECC_PRIVATEKEY_ONLY, pubKey is NULL and pubKeySz is 0 so the handler can distinguish "no public point" from an invalid zero-coordinate public point that must be validated and rejected. The caller's intent crosses in checkOrder and checkPriv.

Source code


int  wc_CryptoCb_RegisterDevice(int devId, CryptoDevCallbackFunc cb, void* ctx);

void wc_CryptoCb_UnRegisterDevice(int devId);

int wc_CryptoCb_DefaultDevID(void);

void wc_CryptoCb_SetDeviceFindCb(CryptoDevCallbackFind cb);

void wc_CryptoCb_InfoString(wc_CryptoInfo* info);
 };
    int devId = 1;

    /* Register your CryptoCB callback first */
    wc_CryptoCb_RegisterDevice(devId, myCryptoCallback, NULL);

    wc_AesInit(&aes, NULL, devId);
    /* wc_AesGcmSetKey internally calls wc_CryptoCb_AesSetKey */
    if (wc_CryptoCb_AesSetKey(&aes, key, sizeof(key)) == 0) {
        /* Key successfully imported to device via callback */
        /* aes.devCtx now contains device handle */
        /* Full GCM offload is assumed - callback must handle all operations */
    }
    \endcode

    \sa wc_CryptoCb_RegisterDevice
    \sa wc_AesInit
*/
int wc_CryptoCb_AesSetKey(Aes* aes, const byte* key, word32 keySz);

int wc_CryptoCb_EccMakePub(ecc_key* key, ecc_point* pubOut);

int wc_CryptoCb_EccCheckPubKey(ecc_key* key, int checkOrder, int checkPriv);

Updated on 2026-07-04 at 05:06:01 +0000