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