Skip to content

Callbacks - CryptoCb

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.
int wc_KeyStore_ImportPlain(int devId, const byte * keyRef, word32 keyRefSz, word32 keyType, const byte * key, word32 keySz, word32 attrs, const void * ctx)
Place plaintext key material into a device's key store. This is the counterpart to wc_KeyStore_ImportWrapped for devices that accept a key in the clear; a device holding keys that may never appear in plaintext declines it and offers only the wrapped form.
int wc_KeyStore_ExportPlain(int devId, const byte * keyRef, word32 keyRefSz, byte * key, word32 * keySz, const void * ctx)
Read a stored key back as plaintext. Typically requires the key to have been created with WC_KEYSTORE_ATTR_EXPORTABLE, and many devices refuse this operation entirely; wc_KeyStore_ExportWrapped is the form that keeps the material inside the boundary.
int wc_KeyStore_ImportWrapped(int devId, const byte * keyRef, word32 keyRefSz, word32 keyType, const byte * wrapKeyRef, word32 wrapKeyRefSz, word32 format, const byte * blob, word32 blobSz, word32 attrs, const void * ctx)
Unwrap a key blob directly into a device's key store. The key material is never plaintext on this side of the boundary: the device unwraps it internally and the result exists only at keyRef.
int wc_KeyStore_ExportWrapped(int devId, const byte * keyRef, word32 keyRefSz, const byte * wrapKeyRef, word32 wrapKeyRefSz, word32 format, byte * blob, word32 * blobSz, const void * ctx)
Wrap a stored key under another stored key and emit the blob. Typically requires the key to have been created with WC_KEYSTORE_ATTR_EXPORTABLE, which is irrevocable on most hardware.
int wc_KeyStore_Derive(int devId, const byte * keyRef, word32 keyRefSz, word32 keyType, word32 keySz, const byte * srcKeyRef, word32 srcKeyRefSz, word32 kdfType, const byte * deriv, word32 derivSz, word32 attrs, const void * ctx)
Derive a new stored key from an existing one without either key touching RAM.
int wc_KeyStore_Delete(int devId, const byte * keyRef, word32 keyRefSz, const void * ctx)
Destroy a stored key. Deliberately separate from WC_ALGO_TYPE_FREE: freeing a wolfCrypt key object must never destroy the hardware key it refers to.
int wc_KeyStore_GetInfo(int devId, const byte * keyRef, word32 keyRefSz, word32 * keyType, word32 * keyBits, word32 * attrs, const void * ctx)
Report what a slot holds: key type, size in bits, and attributes.

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:

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:

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:

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.

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:

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.

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:

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:

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:

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:

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:

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.

function wc_KeyStore_ImportPlain

int wc_KeyStore_ImportPlain(
    int devId,
    const byte * keyRef,
    word32 keyRefSz,
    word32 keyType,
    const byte * key,
    word32 keySz,
    word32 attrs,
    const void * ctx
)

Place plaintext key material into a device's key store. This is the counterpart to wc_KeyStore_ImportWrapped for devices that accept a key in the clear; a device holding keys that may never appear in plaintext declines it and offers only the wrapped form.

Parameters:

  • devId crypto callback device ID
  • keyRef opaque reference naming where the key should land
  • keyRefSz length of keyRef in bytes
  • keyType what the key is for, from enum wc_KeyStoreKeyType
  • key plaintext key material
  • keySz length of key in bytes
  • attrs attributes for the key being created, WC_KEYSTORE_ATTR_*
  • ctx read-only caller context passed through to the device

See:

Return:

  • 0 on success
  • CRYPTOCB_UNAVAILABLE if no registered device handles the operation
  • BAD_FUNC_ARG if keyRef or key is NULL, or either size is zero

keyType says what the material is for, which is what lets the device set the stored key's properties: a raw byte string cannot tell an AES key from an HMAC key of the same length. It also fixes the encoding, so no further argument is needed to say: a symmetric type takes the raw key bytes, and an asymmetric type takes DER, a private key as PKCS#8 PrivateKeyInfo and a public key as SubjectPublicKeyInfo. keySz is the length of that encoding in bytes either way.

The caller owns the plaintext copy and should zeroize it once the import succeeds, for example with ForceZero().

Key references are opaque byte strings, interpreted only by the device. They are the same identifier WOLF_PRIVATE_KEY_ID uses, so the bytes that name a key here are the bytes wc_ecc_init_id() or wc_AesInit_Id() take to bind a wolfCrypt object to that key.

attrs sits at the end of the argument list rather than beside keyRef, because WC_KEYSTORE_ATTR_EXPORTABLE and WC_KEYSTORE_KEY_WRAP are both 1 and a swap between two adjacent control words would compile cleanly.

Example

byte keyRef[8];
byte aesKey[32];

ret = wc_KeyStore_ImportPlain(devId, keyRef, sizeof(keyRef),
                              WC_KEYSTORE_KEY_AES, aesKey, sizeof(aesKey),
                              WC_KEYSTORE_ATTR_PERSISTENT, NULL);
ForceZero(aesKey, sizeof(aesKey));
if (ret != 0) {
    // handle error
}

function wc_KeyStore_ExportPlain

int wc_KeyStore_ExportPlain(
    int devId,
    const byte * keyRef,
    word32 keyRefSz,
    byte * key,
    word32 * keySz,
    const void * ctx
)

Read a stored key back as plaintext. Typically requires the key to have been created with WC_KEYSTORE_ATTR_EXPORTABLE, and many devices refuse this operation entirely; wc_KeyStore_ExportWrapped is the form that keeps the material inside the boundary.

Parameters:

  • devId crypto callback device ID
  • keyRef opaque reference naming the key to export
  • keyRefSz length of keyRef in bytes
  • key buffer receiving the plaintext key, or NULL to query the size
  • keySz in: capacity of key in bytes, out: bytes written
  • ctx read-only caller context passed through to the device

See:

Return:

  • 0 on success
  • CRYPTOCB_UNAVAILABLE if no registered device handles the operation
  • BAD_FUNC_ARG if keyRef or keySz is NULL, keyRefSz is zero, or key is non-NULL with a zero capacity

The encoding matches wc_KeyStore_ImportPlain(): raw bytes for a symmetric key, DER for an asymmetric one. Call wc_KeyStore_GetInfo() to learn which the stored key is.

keySz is in/out: the capacity of key on entry, the number of bytes written on return. Passing key as NULL is a size query, which returns the size the device would produce through keySz. keySz is cleared first in that form, so any value passed in is discarded rather than preserved.

Call wc_KeyStore_GetInfo() first to learn whether the key is exportable, rather than attempting the export and interpreting the failure.

Example

byte   out[32];
word32 outSz = sizeof(out);

ret = wc_KeyStore_ExportPlain(devId, keyRef, sizeof(keyRef),
                              out, &outSz, NULL);
if (ret != 0) {
    // handle error
}

function wc_KeyStore_ImportWrapped

int wc_KeyStore_ImportWrapped(
    int devId,
    const byte * keyRef,
    word32 keyRefSz,
    word32 keyType,
    const byte * wrapKeyRef,
    word32 wrapKeyRefSz,
    word32 format,
    const byte * blob,
    word32 blobSz,
    word32 attrs,
    const void * ctx
)

Unwrap a key blob directly into a device's key store. The key material is never plaintext on this side of the boundary: the device unwraps it internally and the result exists only at keyRef.

Parameters:

  • devId crypto callback device ID
  • keyRef opaque reference naming where the key should land
  • keyRefSz length of keyRef in bytes
  • keyType what the wrapped key is for, from enum wc_KeyStoreKeyType, or WC_KEYSTORE_KEY_NONE to leave it to the container
  • wrapKeyRef opaque reference naming the wrapping key, or NULL when the device uses an implicit one
  • wrapKeyRefSz length of wrapKeyRef in bytes, zero when wrapKeyRef is NULL
  • format container format, from enum wc_KeyWrapFormat
  • blob the wrapped key blob
  • blobSz length of blob in bytes
  • attrs WC_KEYSTORE_ATTR_* for the key being created. Used only when the format carries no attributes of its own; a container that carries them wins and this is ignored. Call wc_KeyStore_GetInfo() afterwards to confirm what the import actually produced
  • ctx read-only caller context passed through to the device

See:

Return:

  • 0 on success
  • CRYPTOCB_UNAVAILABLE if no registered device handles the operation
  • BAD_FUNC_ARG if keyRef or blob is NULL, if either size is zero, or if wrapKeyRef is NULL with a non-zero wrapKeyRefSz

keyType says what the wrapped key is for. A bare RFC 3394 wrap (WC_KEYWRAP_FORMAT_AESKW) is a pure data transformation carrying no metadata, so for that format keyType is the device's only source. A vendor container that carries its own property word stays authoritative, and keyType is then a cross-check the device must refuse a mismatch on, since a mismatch means the right blob is going into the wrong kind of slot.

Key references are opaque byte strings, interpreted only by the device. They are the same identifier WOLF_PRIVATE_KEY_ID uses, so the bytes that name a key here are the bytes wc_ecc_init_id() or wc_AesInit_Id() take to bind a wolfCrypt object to that key.

Example

byte keyRef[8];
byte kekRef[8];

ret = wc_KeyStore_ImportWrapped(devId, keyRef, sizeof(keyRef),
                                WC_KEYSTORE_KEY_AES,
                                kekRef, sizeof(kekRef),
                                WC_KEYWRAP_FORMAT_AESKW,
                                blob, blobSz,
                                WC_KEYSTORE_ATTR_EXPORTABLE, NULL);
if (ret != 0) {
    // handle error
}

function wc_KeyStore_ExportWrapped

int wc_KeyStore_ExportWrapped(
    int devId,
    const byte * keyRef,
    word32 keyRefSz,
    const byte * wrapKeyRef,
    word32 wrapKeyRefSz,
    word32 format,
    byte * blob,
    word32 * blobSz,
    const void * ctx
)

Wrap a stored key under another stored key and emit the blob. Typically requires the key to have been created with WC_KEYSTORE_ATTR_EXPORTABLE, which is irrevocable on most hardware.

Parameters:

  • devId crypto callback device ID
  • keyRef opaque reference naming the key to wrap out
  • keyRefSz length of keyRef in bytes
  • wrapKeyRef opaque reference naming the wrapping key, or NULL when the device uses an implicit one
  • wrapKeyRefSz length of wrapKeyRef in bytes, zero when wrapKeyRef is NULL
  • format container format, from enum wc_KeyWrapFormat
  • blob buffer receiving the wrapped key, or NULL to query the size
  • blobSz in/out capacity then length, in bytes
  • ctx read-only caller context passed through to the device

See:

Return:

  • 0 on success
  • CRYPTOCB_UNAVAILABLE if no registered device handles the operation
  • BAD_FUNC_ARG if keyRef or blobSz is NULL, if keyRefSz is zero, if blob is non-NULL with a zero capacity, or if wrapKeyRef is NULL with a non-zero wrapKeyRefSz

blobSz is in/out: the capacity of blob on entry, the number of bytes written on return. Passing blob as NULL is a size query, which returns the size the device would produce through blobSz. blobSz is cleared first in that form, so any value passed in is discarded rather than preserved.

Example

word32 blobSz = 0;

// ask how large the container will be
ret = wc_KeyStore_ExportWrapped(devId, keyRef, sizeof(keyRef),
                                kekRef, sizeof(kekRef),
                                WC_KEYWRAP_FORMAT_AESKW,
                                NULL, &blobSz, NULL);

function wc_KeyStore_Derive

int wc_KeyStore_Derive(
    int devId,
    const byte * keyRef,
    word32 keyRefSz,
    word32 keyType,
    word32 keySz,
    const byte * srcKeyRef,
    word32 srcKeyRefSz,
    word32 kdfType,
    const byte * deriv,
    word32 derivSz,
    word32 attrs,
    const void * ctx
)

Derive a new stored key from an existing one without either key touching RAM.

Parameters:

  • devId crypto callback device ID
  • keyRef opaque reference naming where the derived key should land
  • keyRefSz length of keyRef in bytes
  • keyType what the derived key is for, from enum wc_KeyStoreKeyType, or WC_KEYSTORE_KEY_NONE to leave it to the device
  • keySz size in bytes of the key to create, or 0 to leave it to the device. Unlike the other operations there is nothing else to infer it from: the derivation data length is the input's, not the output's
  • srcKeyRef opaque reference naming the derivation key
  • srcKeyRefSz length of srcKeyRef in bytes
  • kdfType derivation function, from enum wc_KdfType. WC_KDF_TYPE_NONE asks for the device's own derivation, which is all many key stores offer
  • deriv derivation data
  • derivSz length of deriv in bytes, often fixed by the hardware
  • attrs WC_KEYSTORE_ATTR_* requested for the key being created
  • ctx read-only caller context passed through to the device

See: wc_KeyStore_GetInfo

Return:

  • 0 on success
  • CRYPTOCB_UNAVAILABLE if no registered device handles the operation
  • BAD_FUNC_ARG if keyRef or srcKeyRef is NULL, if keyRefSz or srcKeyRefSz is zero, or if deriv is NULL with a non-zero derivSz. A zero derivSz is legal: it is the form used when the KDF takes no extra input

Nothing in a derivation says what its result is for, so keyType does. A device that encodes the key's purpose inside its own key references may treat this as a cross-check, but it must not require that, since a reference is opaque to wolfCrypt and need carry no such field.

Argument order follows the rule used throughout this API: no two interchangeable control words sit next to each other. keyType names the key being created and follows its reference, kdfType precedes the derivation data, and attrs moves to the tail rather than sit beside keyType, since WC_KEYSTORE_ATTR_EXPORTABLE and WC_KEYSTORE_KEY_WRAP are both 1.

Example

ret = wc_KeyStore_Derive(devId, keyRef, sizeof(keyRef),
                         WC_KEYSTORE_KEY_AES, AES_256_KEY_SIZE,
                         parentRef, sizeof(parentRef),
                         WC_KDF_TYPE_NONE, deriv, sizeof(deriv),
                         WC_KEYSTORE_ATTR_EXPORTABLE, NULL);

function wc_KeyStore_Delete

int wc_KeyStore_Delete(
    int devId,
    const byte * keyRef,
    word32 keyRefSz,
    const void * ctx
)

Destroy a stored key. Deliberately separate from WC_ALGO_TYPE_FREE: freeing a wolfCrypt key object must never destroy the hardware key it refers to.

Parameters:

  • devId crypto callback device ID
  • keyRef opaque reference naming the key to destroy
  • keyRefSz length of keyRef in bytes
  • ctx read-only caller context passed through to the device

See: wc_KeyStore_ImportWrapped

Return:

  • 0 on success
  • CRYPTOCB_UNAVAILABLE if no registered device handles the operation
  • BAD_FUNC_ARG if keyRef is NULL or keyRefSz is zero

Example

ret = wc_KeyStore_Delete(devId, keyRef, sizeof(keyRef), NULL);

function wc_KeyStore_GetInfo

int wc_KeyStore_GetInfo(
    int devId,
    const byte * keyRef,
    word32 keyRefSz,
    word32 * keyType,
    word32 * keyBits,
    word32 * attrs,
    const void * ctx
)

Report what a slot holds: key type, size in bits, and attributes.

Parameters:

  • devId crypto callback device ID
  • keyRef opaque reference naming the key to query
  • keyRefSz length of keyRef in bytes
  • keyType out, a value from enum wc_KeyStoreKeyType
  • keyBits out, key size in bits
  • attrs out, WC_KEYSTORE_ATTR_* the key carries
  • ctx read-only caller context passed through to the device

See:

Return:

  • 0 on success
  • CRYPTOCB_UNAVAILABLE if no registered device handles the operation
  • BAD_FUNC_ARG if keyRef is NULL or keyRefSz is zero

Any WC_KEYSTORE_ATTR_* the device can represent is reported here, so a caller can ask whether an export is permitted rather than attempting one and interpreting the failure. Attributes the device cannot represent read as absent, and out parameters the device does not fill are cleared rather than left holding the caller's stack.

Example

word32 keyType = 0, keyBits = 0, attrs = 0;

ret = wc_KeyStore_GetInfo(devId, keyRef, sizeof(keyRef),
                          &keyType, &keyBits, &attrs, NULL);
if (ret == 0 && (attrs & WC_KEYSTORE_ATTR_EXPORTABLE)) {
    // the key may be wrapped out
}

Updated on 2026-11-19 at 01:14:08 +0000