wc_xmss.h

Functions

	Name
int	wc_XmssKey_Init(XmssKey * key, void * heap, int devId) Initializes an XmssKey object. Must be called before any other XMSS/XMSS^MT operation. Use wc_XmssKey_Free() to release resources when done.
int	wc_XmssKey_InitId(XmssKey * key, const unsigned char * id, int len, void * heap, int devId) Initializes an XmssKey with a device_side key identifier. Equivalent to wc_XmssKey_Init() but also stashes a binary id that a crypto callback can use to look up the underlying key material on the device. Only available when wolfSSL is built with WOLF_PRIVATE_KEY_ID.
int	wc_XmssKey_InitLabel(XmssKey * key, const char * label, void * heap, int devId) Initializes an XmssKey with a device_side key label. Equivalent to wc_XmssKey_Init() but also stashes a label string that a crypto callback can use to look up the underlying key material on the device. Only available when wolfSSL is built with WOLF_PRIVATE_KEY_ID.
int	wc_XmssKey_SetParamStr(XmssKey * key, const char * str) Selects an XMSS or XMSS^MT parameter set by its RFC 8391 name. Accepted names take the form "XMSS_" (single_tree) or "XMSSMT_/" (multi_tree), for example "XMSS-SHA2_10_256" or "XMSSMT-SHA2_20/2_256". The set of names actually accepted depends on the hash families and tree heights enabled at build time.
int	wc_XmssKey_GetParamStr(const XmssKey * key, const char ** str) Retrieves the parameter set name currently selected on this key. The returned pointer is a static string and must not be freed by the caller.
int	wc_XmssKey_SetWriteCb(XmssKey * key, wc_xmss_write_private_key_cb write_cb) Registers the callback that wolfSSL invokes to persist updated private key state. Because XMSS/XMSS^MT is stateful, the application MUST persist the private key after each successful sign before the signature is released; otherwise a crash or restart can lead to one-time key reuse and break the scheme.
int	wc_XmssKey_SetReadCb(XmssKey * key, wc_xmss_read_private_key_cb read_cb) Registers the callback that wolfSSL invokes to load persisted private key state. Used by wc_XmssKey_Reload() to bring a saved key back into memory for further signing.
int	wc_XmssKey_SetContext(XmssKey * key, void * context) Sets the opaque context pointer passed to both the read and write private-key callbacks.
int	wc_XmssKey_MakeKey(XmssKey * key, WC_RNG * rng) Generates a fresh XMSS/XMSS^MT key pair. The parameter set must already be selected via wc_XmssKey_SetParamStr() and the read/write callbacks must be registered. The newly generated private key is persisted via the write callback before the function returns; on success the key transitions to state WC_XMSS_STATE_OK.
int	wc_XmssKey_Reload(XmssKey * key) Reloads a previously generated XMSS/XMSS^MT private key from persistent storage using the registered read callback, restoring the key to a state where it can sign further messages. On success the key is in state WC_XMSS_STATE_OK.
int	wc_XmssKey_GetPrivLen(const XmssKey * key, word32 * len) Returns the size in bytes of the encoded private key for the parameter set selected on this key.
int	wc_XmssKey_GetPubLen(const XmssKey * key, word32 * len) Returns the size in bytes of the XMSS/XMSS^MT public key for the parameter set selected on this key.
int	wc_XmssKey_GetSigLen(const XmssKey * key, word32 * len) Returns the signature size in bytes for the parameter set selected on this key.
int	wc_XmssKey_Sign(XmssKey * key, byte * sig, word32 * sigSz, const byte * msg, int msgSz) Signs msg with the XMSS/XMSS^MT private key in key. On entry *sigSz is the size of the sig buffer; on success it is updated to the bytes written.
int	wc_XmssKey_SigsLeft(XmssKey * key) Returns the number of one-time signatures still available from this key. When the count reaches zero the key can no longer sign and should be retired.
void	wc_XmssKey_Free(XmssKey * key) Releases resources held by an XmssKey. Safe to call with a NULL pointer. After this call the key is in state WC_XMSS_STATE_FREED and must be re-initialized before reuse.
int	wc_XmssKey_ExportPub(XmssKey * keyDst, const XmssKey * keySrc) Copies the public part of keySrc into keyDst. The destination key inherits the same parameter set and may be used for verification; it does not carry the private key state and cannot sign. Useful for handing a verifier the minimal data it needs.
int	wc_XmssKey_ExportPub_ex(XmssKey * keyDst, const XmssKey * keySrc, void * heap, int devId) Like wc_XmssKey_ExportPub() but the destination key is initialized fresh with the supplied heap and devId.
int	wc_XmssKey_ExportPubRaw(const XmssKey * key, byte * out, word32 * outLen) Exports the XMSS/XMSS^MT public key as a raw byte string. On entry *outLen is the size of out; on success it is updated to the bytes written.
int	wc_XmssKey_ImportPubRaw(XmssKey * key, const byte * in, word32 inLen) Imports a raw XMSS public key into key. The key must be in state WC_XMSS_STATE_INITED and the parameter set must already be selected (the raw encoding does NOT carry the parameter set, so the caller must apply it via wc_XmssKey_SetParamStr() first). On success the key transitions to state WC_XMSS_STATE_VERIFYONLY.
int	wc_XmssKey_ImportPubRaw_ex(XmssKey * key, const byte * in, word32 inLen, int is_xmssmt) Like wc_XmssKey_ImportPubRaw() but explicitly declares whether the encoded key is single_tree XMSS or multi_tree XMSS^MT (pass non_zero for XMSS^MT, zero for XMSS).
int	wc_XmssKey_Verify(XmssKey * key, const byte * sig, word32 sigSz, const byte * msg, int msgSz) Verifies an XMSS/XMSS^MT signature against msg using the public key held in key. The function returns 0 only when the signature is valid; any other value indicates the signature was rejected.

Functions Documentation

function wc_XmssKey_Init

int wc_XmssKey_Init(
    XmssKey * key,
    void * heap,
    int devId
)

Initializes an XmssKey object. Must be called before any other XMSS/XMSS^MT operation. Use wc_XmssKey_Free() to release resources when done.

Parameters:

key Pointer to the XmssKey to initialize.
heap Heap hint for dynamic memory allocation. May be NULL.
devId Device identifier for hardware crypto callbacks. Use INVALID_DEVID for software-only.

See:

Return:

0 on success.
BAD_FUNC_ARG if key is NULL.

XMSS (eXtended Merkle Signature Scheme) and its multi-tree variant XMSS^MT (RFC 8391, NIST SP 800-208) are STATEFUL hash-based signature schemes: each call to wc_XmssKey_Sign() consumes a one_time component of the private key, and reusing a one_time key destroys the security of the scheme. Applications MUST persist the private key state between sign calls; see wc_XmssKey_SetWriteCb() and wc_XmssKey_SetReadCb().

After init the key is in state WC_XMSS_STATE_INITED. The parameter set must be selected by name with wc_XmssKey_SetParamStr() before generating or reloading a key.

Example

XmssKey key;
int ret;

ret = wc_XmssKey_Init(&key, NULL, INVALID_DEVID);
if (ret != 0) {
    // error initializing key
}
wc_XmssKey_SetParamStr(&key, "XMSS-SHA2_10_256");
// ... use key ...
wc_XmssKey_Free(&key);

function wc_XmssKey_InitId

int wc_XmssKey_InitId(
    XmssKey * key,
    const unsigned char * id,
    int len,
    void * heap,
    int devId
)

Initializes an XmssKey with a device-side key identifier. Equivalent to wc_XmssKey_Init() but also stashes a binary id that a crypto callback can use to look up the underlying key material on the device. Only available when wolfSSL is built with WOLF_PRIVATE_KEY_ID.

Parameters:

key Pointer to the XmssKey to initialize.
id Pointer to the device-side key identifier bytes.
len Number of bytes in id; must be in [0, XMSS_MAX_ID_LEN].
heap Heap hint for dynamic memory allocation.
devId Device identifier for the crypto callback.

See:

Return:

0 on success.
BAD_FUNC_ARG if key is NULL, or id is NULL while len > 0.
BUFFER_E if len is negative or greater than XMSS_MAX_ID_LEN.

The id is copied into the key object; the caller may free its buffer immediately after this call returns.

function wc_XmssKey_InitLabel

int wc_XmssKey_InitLabel(
    XmssKey * key,
    const char * label,
    void * heap,
    int devId
)

Initializes an XmssKey with a device-side key label. Equivalent to wc_XmssKey_Init() but also stashes a label string that a crypto callback can use to look up the underlying key material on the device. Only available when wolfSSL is built with WOLF_PRIVATE_KEY_ID.

Parameters:

key Pointer to the XmssKey to initialize.
label NUL-terminated device-side key label.
heap Heap hint for dynamic memory allocation.
devId Device identifier for the crypto callback.

See:

Return:

0 on success.
BAD_FUNC_ARG if key or label is NULL.
BUFFER_E if label is empty or longer than XMSS_MAX_LABEL_LEN.

function wc_XmssKey_SetParamStr

int wc_XmssKey_SetParamStr(
    XmssKey * key,
    const char * str
)

Selects an XMSS or XMSS^MT parameter set by its RFC 8391 name. Accepted names take the form "XMSS-" (single-tree) or "XMSSMT-/" (multi-tree), for example "XMSS-SHA2_10_256" or "XMSSMT-SHA2_20/2_256". The set of names actually accepted depends on the hash families and tree heights enabled at build time.

Parameters:

key Pointer to an XmssKey in state WC_XMSS_STATE_INITED.
str Parameter set name (NUL-terminated).

See:

Return:

0 on success.
BAD_FUNC_ARG if key or str is NULL, or if the named parameter set is unknown or not compiled in.
BAD_STATE_E if key is not in state WC_XMSS_STATE_INITED.

Example

XmssKey key;

wc_XmssKey_Init(&key, NULL, INVALID_DEVID);
wc_XmssKey_SetParamStr(&key, "XMSS-SHA2_10_256");

function wc_XmssKey_GetParamStr

int wc_XmssKey_GetParamStr(
    const XmssKey * key,
    const char ** str
)

Retrieves the parameter set name currently selected on this key. The returned pointer is a static string and must not be freed by the caller.

Parameters:

key Pointer to an XmssKey with a parameter set selected.
str Receives a pointer to a static parameter name string.

See: wc_XmssKey_SetParamStr

Return:

0 on success.
BAD_FUNC_ARG if key or str is NULL, or no parameter set has been selected.

function wc_XmssKey_SetWriteCb

int wc_XmssKey_SetWriteCb(
    XmssKey * key,
    wc_xmss_write_private_key_cb write_cb
)

Registers the callback that wolfSSL invokes to persist updated private key state. Because XMSS/XMSS^MT is stateful, the application MUST persist the private key after each successful sign before the signature is released; otherwise a crash or restart can lead to one-time key reuse and break the scheme.

Parameters:

key Pointer to an XmssKey.
write_cb Callback invoked to persist the private key.

See:

Return:

0 on success.
BAD_FUNC_ARG if key or write_cb is NULL.

The callback returns one of the wc_XmssRc codes; WC_XMSS_RC_SAVED_TO_NV_MEMORY signals a durable write.

function wc_XmssKey_SetReadCb

int wc_XmssKey_SetReadCb(
    XmssKey * key,
    wc_xmss_read_private_key_cb read_cb
)

Registers the callback that wolfSSL invokes to load persisted private key state. Used by wc_XmssKey_Reload() to bring a saved key back into memory for further signing.

Parameters:

key Pointer to an XmssKey.
read_cb Callback invoked to load the private key.

See:

Return:

0 on success.
BAD_FUNC_ARG if key or read_cb is NULL.

function wc_XmssKey_SetContext

int wc_XmssKey_SetContext(
    XmssKey * key,
    void * context
)

Sets the opaque context pointer passed to both the read and write private-key callbacks.

Parameters:

key Pointer to an XmssKey.
context Application-defined pointer; may be NULL.

See:

Return:

0 on success.
BAD_FUNC_ARG if key is NULL.

function wc_XmssKey_MakeKey

int wc_XmssKey_MakeKey(
    XmssKey * key,
    WC_RNG * rng
)

Generates a fresh XMSS/XMSS^MT key pair. The parameter set must already be selected via wc_XmssKey_SetParamStr() and the read/write callbacks must be registered. The newly generated private key is persisted via the write callback before the function returns; on success the key transitions to state WC_XMSS_STATE_OK.

Parameters:

key Pointer to an XmssKey in state WC_XMSS_STATE_PARMSET with callbacks set.
rng Pointer to an initialized WC_RNG.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL.
MEMORY_E on allocation failure.

Key generation can be slow for large tree heights; XMSS^MT variants amortize the cost over multiple smaller trees and generate noticeably faster than equivalent single-tree XMSS parameter sets.

Example

XmssKey key;
WC_RNG rng;

wc_XmssKey_Init(&key, NULL, INVALID_DEVID);
wc_XmssKey_SetParamStr(&key, "XMSS-SHA2_10_256");
wc_XmssKey_SetWriteCb(&key, my_write_cb);
wc_XmssKey_SetReadCb(&key, my_read_cb);
wc_XmssKey_SetContext(&key, &my_storage);
wc_InitRng(&rng);

if (wc_XmssKey_MakeKey(&key, &rng) != 0) {
    // error generating key
}

function wc_XmssKey_Reload

int wc_XmssKey_Reload(
    XmssKey * key
)

Reloads a previously generated XMSS/XMSS^MT private key from persistent storage using the registered read callback, restoring the key to a state where it can sign further messages. On success the key is in state WC_XMSS_STATE_OK.

Parameters:

key Pointer to an XmssKey with parameters and read callback set.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL.
WC_XMSS_RC_* mapped error if the read callback fails.

The same parameter set selected at key-generation time must be reapplied with wc_XmssKey_SetParamStr() before calling Reload.

function wc_XmssKey_GetPrivLen

int wc_XmssKey_GetPrivLen(
    const XmssKey * key,
    word32 * len
)

Returns the size in bytes of the encoded private key for the parameter set selected on this key.

Parameters:

key Pointer to an XmssKey with parameters set.
len Receives the private key size in bytes.

See:

Return:

0 on success.
BAD_FUNC_ARG if key or len is NULL.

function wc_XmssKey_GetPubLen

int wc_XmssKey_GetPubLen(
    const XmssKey * key,
    word32 * len
)

Returns the size in bytes of the XMSS/XMSS^MT public key for the parameter set selected on this key.

Parameters:

key Pointer to an XmssKey with parameters set.
len Receives the public key size in bytes.

See: wc_XmssKey_ExportPubRaw

Return:

0 on success.
BAD_FUNC_ARG if key or len is NULL.

function wc_XmssKey_GetSigLen

int wc_XmssKey_GetSigLen(
    const XmssKey * key,
    word32 * len
)

Returns the signature size in bytes for the parameter set selected on this key.

Parameters:

key Pointer to an XmssKey with parameters set.
len Receives the signature size in bytes.

See: wc_XmssKey_Sign

Return:

0 on success.
BAD_FUNC_ARG if key or len is NULL.

function wc_XmssKey_Sign

int wc_XmssKey_Sign(
    XmssKey * key,
    byte * sig,
    word32 * sigSz,
    const byte * msg,
    int msgSz
)

Signs msg with the XMSS/XMSS^MT private key in key. On entry *sigSz is the size of the sig buffer; on success it is updated to the bytes written.

Parameters:

key Pointer to an XmssKey in state WC_XMSS_STATE_OK.
sig Buffer that receives the signature.
sigSz In: size of sig. Out: bytes written.
msg Message to sign.
msgSz Length of msg in bytes.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL.
BUFFER_E if *sigSz is smaller than the signature size.
Negative error if all one-time keys have been used.

Each successful sign call consumes a one-time component of the private key. The updated key state is persisted via the registered write callback BEFORE the new signature is returned to the caller. If the write callback fails the sign call fails and the signature is not released. When the supply of one-time keys is exhausted the key transitions to state WC_XMSS_STATE_NOSIGS and further sign attempts fail – query wc_XmssKey_SigsLeft() to detect this condition in advance.

function wc_XmssKey_SigsLeft

int wc_XmssKey_SigsLeft(
    XmssKey * key
)

Returns the number of one-time signatures still available from this key. When the count reaches zero the key can no longer sign and should be retired.

Parameters:

key Pointer to an XmssKey in state WC_XMSS_STATE_OK.

See: wc_XmssKey_Sign

Return:

Non-negative number of remaining signatures on success.
Negative error code on failure (e.g. BAD_FUNC_ARG if key is NULL).

function wc_XmssKey_Free

void wc_XmssKey_Free(
    XmssKey * key
)

Releases resources held by an XmssKey. Safe to call with a NULL pointer. After this call the key is in state WC_XMSS_STATE_FREED and must be re-initialized before reuse.

Parameters:

key Pointer to the XmssKey to free.

See: wc_XmssKey_Init

function wc_XmssKey_ExportPub

int wc_XmssKey_ExportPub(
    XmssKey * keyDst,
    const XmssKey * keySrc
)

Copies the public part of keySrc into keyDst. The destination key inherits the same parameter set and may be used for verification; it does not carry the private key state and cannot sign. Useful for handing a verifier the minimal data it needs.

Parameters:

keyDst Pointer to an initialized destination XmssKey.
keySrc Pointer to an XmssKey with the public key.

See:

Return:

0 on success.
BAD_FUNC_ARG if keyDst or keySrc is NULL.

function wc_XmssKey_ExportPub_ex

int wc_XmssKey_ExportPub_ex(
    XmssKey * keyDst,
    const XmssKey * keySrc,
    void * heap,
    int devId
)

Like wc_XmssKey_ExportPub() but the destination key is initialized fresh with the supplied heap and devId.

Parameters:

keyDst Pointer to an XmssKey to populate.
keySrc Pointer to an XmssKey with the public key.
heap Heap hint for keyDst.
devId Device identifier for keyDst.

See: wc_XmssKey_ExportPub

Return:

0 on success.
BAD_FUNC_ARG if keyDst or keySrc is NULL.

function wc_XmssKey_ExportPubRaw

int wc_XmssKey_ExportPubRaw(
    const XmssKey * key,
    byte * out,
    word32 * outLen
)

Exports the XMSS/XMSS^MT public key as a raw byte string. On entry *outLen is the size of out; on success it is updated to the bytes written.

Parameters:

key Pointer to an XmssKey.
out Buffer that receives the public key.
outLen In: size of out. Out: bytes written.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL.
BUFFER_E if *outLen is smaller than the public key size.

function wc_XmssKey_ImportPubRaw

int wc_XmssKey_ImportPubRaw(
    XmssKey * key,
    const byte * in,
    word32 inLen
)

Imports a raw XMSS public key into key. The key must be in state WC_XMSS_STATE_INITED and the parameter set must already be selected (the raw encoding does NOT carry the parameter set, so the caller must apply it via wc_XmssKey_SetParamStr() first). On success the key transitions to state WC_XMSS_STATE_VERIFYONLY.

Parameters:

key Pointer to an XmssKey with a parameter set.
in Raw public key bytes.
inLen Length of in in bytes.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL.
BUFFER_E if inLen does not match the expected public key size.

function wc_XmssKey_ImportPubRaw_ex

int wc_XmssKey_ImportPubRaw_ex(
    XmssKey * key,
    const byte * in,
    word32 inLen,
    int is_xmssmt
)

Like wc_XmssKey_ImportPubRaw() but explicitly declares whether the encoded key is single_tree XMSS or multi_tree XMSS^MT (pass non_zero for XMSS^MT, zero for XMSS).

Parameters:

key Pointer to an XmssKey with a parameter set.
in Raw public key bytes.
inLen Length of in in bytes.
is_xmssmt Non-zero if the key is XMSS^MT, zero if plain XMSS.

See: wc_XmssKey_ImportPubRaw

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL.
BUFFER_E if inLen does not match the expected public key size.

function wc_XmssKey_Verify

int wc_XmssKey_Verify(
    XmssKey * key,
    const byte * sig,
    word32 sigSz,
    const byte * msg,
    int msgSz
)

Verifies an XMSS/XMSS^MT signature against msg using the public key held in key. The function returns 0 only when the signature is valid; any other value indicates the signature was rejected.

Parameters:

key Pointer to an XmssKey with the public key.
sig Signature bytes to verify.
sigSz Length of sig in bytes.
msg Message that was signed.
msgSz Length of msg in bytes.

See:

Return:

0 on a valid signature.
BAD_FUNC_ARG if any required pointer is NULL.
SIG_VERIFY_E (or similar) if the signature is invalid or malformed.

Source code


int wc_XmssKey_Init(XmssKey* key, void* heap, int devId);

int wc_XmssKey_InitId(XmssKey* key, const unsigned char* id, int len,
    void* heap, int devId);

int wc_XmssKey_InitLabel(XmssKey* key, const char* label, void* heap,
    int devId);

int wc_XmssKey_SetParamStr(XmssKey* key, const char* str);

int wc_XmssKey_GetParamStr(const XmssKey* key, const char** str);

int wc_XmssKey_SetWriteCb(XmssKey* key, wc_xmss_write_private_key_cb write_cb);

int wc_XmssKey_SetReadCb(XmssKey* key, wc_xmss_read_private_key_cb read_cb);

int wc_XmssKey_SetContext(XmssKey* key, void* context);

int wc_XmssKey_MakeKey(XmssKey* key, WC_RNG* rng);

int wc_XmssKey_Reload(XmssKey* key);

int wc_XmssKey_GetPrivLen(const XmssKey* key, word32* len);

int wc_XmssKey_GetPubLen(const XmssKey* key, word32* len);

int wc_XmssKey_GetSigLen(const XmssKey* key, word32* len);

int wc_XmssKey_Sign(XmssKey* key, byte* sig, word32* sigSz, const byte* msg,
    int msgSz);

int wc_XmssKey_SigsLeft(XmssKey* key);

void wc_XmssKey_Free(XmssKey* key);

int wc_XmssKey_ExportPub(XmssKey* keyDst, const XmssKey* keySrc);

int wc_XmssKey_ExportPub_ex(XmssKey* keyDst, const XmssKey* keySrc,
    void* heap, int devId);

int wc_XmssKey_ExportPubRaw(const XmssKey* key, byte* out, word32* outLen);

int wc_XmssKey_ImportPubRaw(XmssKey* key, const byte* in, word32 inLen);

int wc_XmssKey_ImportPubRaw_ex(XmssKey* key, const byte* in, word32 inLen,
    int is_xmssmt);

int wc_XmssKey_Verify(XmssKey* key, const byte* sig, word32 sigSz,
    const byte* msg, int msgSz);

Updated on 2026-07-16 at 03:12:19 +0000