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.
int	wc_CryptoCb_IsDeviceRegistered(int devId) This function reports whether a crypto callback device identifier (devID) is currently registered. It is useful for checking registration state before calling wc_CryptoCb_RegisterDevice, which now rejects an already-registered devID with ALREADY_E.
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.
int	wc_CryptoCb_Ed25519MakePub(ed25519_key * key, byte * pubKey, word32 pubKeySz) Offload deriving an Ed25519 public key from its private key to a CryptoCB device.
int	wc_CryptoCb_Ed25519CheckKey(ed25519_key * key) Offload validating an Ed25519 key to a CryptoCB device.
int	wc_CryptoCb_Ed448Gen(WC_RNG * rng, int keySize, ed448_key * key) Offload Ed448 key generation to a CryptoCB device.
int	wc_CryptoCb_Ed448MakePub(ed448_key * key, byte * pubKey, word32 pubKeySz) Offload deriving an Ed448 public key from its private key to a CryptoCB device.
int	wc_CryptoCb_Ed448CheckKey(ed448_key * key) Offload validating an Ed448 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);
• ctx user context handed back to the callback on every invocation. With WOLF_CRYPTO_CB_CMD, a register command handler may replace it by updating info->cmd.ctx on success.

See:

• wc_CryptoCb_UnRegisterDevice
• wolfSSL_SetDevId
• wolfSSL_CTX_SetDevId

Return:

• CRYPTOCB_UNAVAILABLE to fallback to using software crypto
• 0 for success
• ALREADY_E if devId is already registered. A devId must be un-registered with wc_CryptoCb_UnRegisterDevice before it can be registered again; re-registering an active devId is not an in-place update.
• BAD_FUNC_ARG if devId is INVALID_DEVID (-2)
• 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

With WOLF_CRYPTO_CB_CMD defined, the callback is invoked during this call with a WC_CRYPTOCB_CMD_TYPE_REGISTER command (and later with WC_CRYPTOCB_CMD_TYPE_UNREGISTER from wc_CryptoCb_UnRegisterDevice). A register command handler may itself call wc_CryptoCb_RegisterDevice to register additional devIds, such as a driver exposing several devices. It must not dispatch through, or re-register, the devId it is being registered with: that devId is not published until this call returns, so a nested registration of it is not caught by the ALREADY_E check and consumes fresh slots until the table fills and BUFFER_E unwinds them. If the handler returns an error other than CRYPTOCB_UNAVAILABLE or NOT_COMPILED_IN, the registration is unwound and the error returned; devIds the handler already registered stay registered and are the caller's to clean up.

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_IsDeviceRegistered

int wc_CryptoCb_IsDeviceRegistered(
    int devId
)

This function reports whether a crypto callback device identifier (devID) is currently registered. It is useful for checking registration state before calling wc_CryptoCb_RegisterDevice, which now rejects an already-registered devID with ALREADY_E.

Parameters:

• devId the device identifier to query

See:

• wc_CryptoCb_RegisterDevice
• wc_CryptoCb_UnRegisterDevice

Return:

• 1 if the device ID is registered
• 0 if the device ID is not registered, or if devId is INVALID_DEVID (-2)

Example

if (!wc_CryptoCb_IsDeviceRegistered(devId)) {
    wc_CryptoCb_RegisterDevice(devId, myCryptoCb_Func, &myCtx);
}

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:

• wc_CryptoCb_RegisterDevice
• wolfSSL_SetDevId
• wolfSSL_CTX_SetDevId

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:

• wc_CryptoCb_RegisterDevice
• wc_CryptoCb_UnRegisterDevice

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:

• wc_CryptoCb_RegisterDevice
• wc_AesInit

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.

If the callback returns success (0), the device owns the key. A callback that keeps the key only on the device must leave aes->rounds at 0: wolfCrypt takes a non-zero aes->rounds to mean the callback also built a software key schedule, by calling wc_AesSetKey() on the same object with aes_>devId set to a devId no device is registered under, then restoring it. INVALID_DEVID only works without WOLF_CRYPTO_CB_FIND, whose find callback can map it back to the device. Without a schedule, wolfCrypt keeps no copy in devKey and derives no GCM hash subkey or tables, so the callback must handle SetKey, Encrypt, Decrypt, and Free. The streaming GCM API then returns MISSING_KEY, and so does a mode the callback declines when WOLFSSL_AES_REQUIRE_KEY_SET is in effect (the default). The same applies to a WOLF_CRYPTO_CB_SETKEY callback for WC_SETKEY_AES. Only that request carries the key direction, so only such a callback can build a software key schedule.

A callback that returns CRYPTOCB_UNAVAILABLE for a new key must first release any key it holds for this object and set aes->devCtx to NULL. wolfCrypt sets the new key up in software and leaves aes->devCtx alone, so a stale handle would keep the operations the callback accepts on the old key. A WOLF_CRYPTO_CB_SETKEY callback must do the same before it returns an error, since wolfCrypt clears aes->devCtx only after an error from this request.

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:

• wc_CryptoCb_RegisterDevice
• wc_ecc_make_pub

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:

• wc_CryptoCb_RegisterDevice
• wc_ecc_check_key

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.

function wc_CryptoCb_Ed25519MakePub

int wc_CryptoCb_Ed25519MakePub(
    ed25519_key * key,
    byte * pubKey,
    word32 pubKeySz
)

Offload deriving an Ed25519 public key from its private key to a CryptoCB device.

Parameters:

• key Ed25519 key providing the device id, heap hint and the private key
• pubKey [out] resulting compressed public key
• pubKeySz size of pubKey buffer, must be ED25519_PUB_KEY_SIZE

See:

• wc_CryptoCb_RegisterDevice
• wc_ed25519_make_public

Return:

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

Used by wc_ed25519_make_public (and so by key generation and private-key import). The boundary is byte-oriented: the device writes the compressed public key into wc_CryptoInfo.pk.ed25519makepub (pubOut / pubOutSz, always ED25519_PUB_KEY_SIZE). The private key is taken from the ed25519_key (resident in a secure element, or key->k). On success the caller marks the public key set.

function wc_CryptoCb_Ed25519CheckKey

int wc_CryptoCb_Ed25519CheckKey(
    ed25519_key * key
)

Offload validating an Ed25519 key to a CryptoCB device.

Parameters:

• key Ed25519 key to validate

See:

• wc_CryptoCb_RegisterDevice
• wc_ed25519_check_key

Return:

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

Used by wc_ed25519_check_key and the key import validation paths. The public key crosses the callback boundary as its compressed wire bytes in wc_CryptoInfo.pk.ed25519checkkey (pubKey / pubKeySz), so a device handler only deals with byte arrays. The dispatch only runs when a public key is present; checkPriv is 1 when a private key is also set or referenced by id or label, and the device should additionally validate priv/pub consistency.

function wc_CryptoCb_Ed448Gen

int wc_CryptoCb_Ed448Gen(
    WC_RNG * rng,
    int keySize,
    ed448_key * key
)

Offload Ed448 key generation to a CryptoCB device.

Parameters:

• rng random number generator for the device to use
• keySize private key size, ED448_KEY_SIZE
• key Ed448 key providing the device id, receives the new key

See:

• wc_CryptoCb_RegisterDevice
• wc_ed448_make_key

Return:

• 0 on success
• CRYPTOCB_UNAVAILABLE if no device handles the operation (wolfCrypt falls back to software key generation)
• other negative values are device errors, returned to the caller without a software fallback

Used by wc_ed448_make_key. The device receives wc_CryptoInfo.pk.ed448kg (rng, size, key). On success it stores the private key followed by the public key in key->k, the public key in key->p, and sets key->privKeySet and key->pubKeySet. For a key bound by id or label, the device may keep the private key and leave key->k and key->privKeySet clear. No make-public callback follows a device-generated key.

function wc_CryptoCb_Ed448MakePub

int wc_CryptoCb_Ed448MakePub(
    ed448_key * key,
    byte * pubKey,
    word32 pubKeySz
)

Offload deriving an Ed448 public key from its private key to a CryptoCB device.

Parameters:

• key Ed448 key providing the device id, heap hint and the private key
• pubKey [out] resulting compressed public key
• pubKeySz size of pubKey buffer, must be ED448_PUB_KEY_SIZE

See:

• wc_CryptoCb_RegisterDevice
• wc_ed448_make_public

Return:

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

Used by wc_ed448_make_public (and so by software key generation and private-key import). The device writes the compressed public key into wc_CryptoInfo.pk.ed448makepub (pubOut / pubOutSz, always ED448_PUB_KEY_SIZE).

function wc_CryptoCb_Ed448CheckKey

int wc_CryptoCb_Ed448CheckKey(
    ed448_key * key
)

Offload validating an Ed448 key to a CryptoCB device.

Parameters:

• key Ed448 key to validate

See:

• wc_CryptoCb_RegisterDevice
• wc_ed448_check_key

Return:

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

Used by wc_ed448_check_key and when checking a device private key against a certificate. The compressed public key is passed in wc_CryptoInfo.pk.ed448checkkey (pubKey / pubKeySz). checkPriv is 1 when a private key is set or referenced by id or label, and the device should also check that it matches the public key.

Source code

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

int wc_CryptoCb_IsDeviceRegistered(int devId);

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);

int wc_CryptoCb_Ed25519MakePub(ed25519_key* key, byte* pubKey,
    word32 pubKeySz);

int wc_CryptoCb_Ed25519CheckKey(ed25519_key* key);

int wc_CryptoCb_Ed448Gen(WC_RNG* rng, int keySize, ed448_key* key);

int wc_CryptoCb_Ed448MakePub(ed448_key* key, byte* pubKey, word32 pubKeySz);

int wc_CryptoCb_Ed448CheckKey(ed448_key* key);

---

Updated on 2026-11-10 at 01:14:25 +0000