Algorithms - Falcon

Functions

	Name
int	wc_falcon_init(falcon_key * key) Initializes a falcon_key object with default settings (no heap hint, software-only). Must be called before any other Falcon operation. Call wc_falcon_set_level() to select a parameter set before generating or importing a key. Release resources with wc_falcon_free() when done: the structure can own heap allocations, so re-initializing a used key without freeing it first orphans them with the secret material still in them.
int	wc_falcon_init_ex(falcon_key * key, void * heap, int devId) Initializes a falcon_key object with a heap hint and device identifier for hardware crypto callbacks.
int	wc_falcon_init_id(falcon_key * key, const unsigned char * id, int len, void * heap, int devId) Initializes a falcon_key object and associates it with a key identifier for use with a hardware crypto callback / secure element. Only available when built with WOLF_PRIVATE_KEY_ID.
int	wc_falcon_init_label(falcon_key * key, const char * label, void * heap, int devId) Initializes a falcon_key object and associates it with a text label for use with a hardware crypto callback / secure element. Only available when built with WOLF_PRIVATE_KEY_ID.
int	wc_falcon_set_level(falcon_key * key, byte level) Selects the Falcon parameter set (security level) for a key. Must be set before key generation or import.
int	wc_falcon_get_level(falcon_key * key, byte * level) Retrieves the Falcon parameter set (security level) currently set on a key.
void	wc_falcon_free(falcon_key * key) Frees a falcon_key object and securely zeros any key material it holds. The key may be re-initialized afterwards. The structure can own heap allocations, so it must have been initialized (or zeroed) first; calling this on an untouched stack object frees indeterminate pointers.
int	wc_falcon_make_key(falcon_key * key, WC_RNG * rng) Generates a Falcon key pair into key. The parameter set must have been selected with wc_falcon_set_level() first. Not available in verify-only builds (WOLFSSL_FALCON_VERIFY_ONLY).
int	wc_falcon_sign_msg(const byte * in, word32 inLen, byte * out, word32 * outLen, falcon_key * key, WC_RNG * rng) Signs a message with a Falcon private key, producing a compressed signature. On entry *outLen holds the size of the out buffer; on return it holds the signature length. Not available in verify-only builds.
int	wc_falcon_verify_msg(const byte * sig, word32 sigLen, const byte * msg, word32 msgLen, int * res, falcon_key * key) Verifies a Falcon signature over a message with a public key. On a completed verification *res is set to 1 when the signature is valid and 0 otherwise; the function returns 0 in both cases. A non-zero return indicates an operational error.
int	wc_falcon_import_public(const byte * in, word32 inLen, falcon_key * key) Imports a raw (Falcon-encoded) public key into key. The parameter level must have been set first so the expected length is known.
int	wc_falcon_import_private_only(const byte * priv, word32 privSz, falcon_key * key) Imports a raw (Falcon-encoded) private key into key, without a public key. The parameter level must have been set first.
int	wc_falcon_import_private_key(const byte * priv, word32 privSz, const byte * pub, word32 pubSz, falcon_key * key) Imports a raw Falcon private key and (optionally) public key into key. The parameter level must have been set first.
int	wc_falcon_export_public(falcon_key * key, byte * out, word32 * outLen) Exports the raw (Falcon-encoded) public key from key. On entry outLen is the size of out; on return it is the number of bytes written.
int	wc_falcon_export_private_only(falcon_key * key, byte * out, word32 * outLen) Exports the raw (Falcon-encoded) private key from key.
int	wc_falcon_export_private(falcon_key * key, byte * out, word32 * outLen) Exports the raw (Falcon-encoded) private key from key. Equivalent to wc_falcon_export_private_only().
int	wc_falcon_export_key(falcon_key * key, byte * priv, word32 * privSz, byte * pub, word32 * pubSz) Exports both the raw private and public keys from key in a single call. Each length parameter is In: buffer size, Out: bytes written.
int	wc_falcon_check_key(falcon_key * key) Checks the consistency of a Falcon key. With WOLF_CRYPTO_CB, a key with a device id (or any key with WOLF_CRYPTO_CB_FIND) is first passed to the crypto callback, along with the public key when it is set. The device checks the key it contains, so neither key needs to be set locally. Otherwise, or when the callback returns CRYPTOCB_UNAVAILABLE, both the public and private keys must be present. When the native signing core is compiled in, the stored public key h is additionally verified against the private key by checking the defining relation h*f == g (mod q); in verify-only or crypto-callback-only builds only the presence of both keys is checked.
int	wc_falcon_size(falcon_key * key) Returns the encoded private-key size in bytes for the key's parameter set (level).
int	wc_falcon_priv_size(falcon_key * key) Returns the encoded private-key size in bytes for the key's parameter set (level).
int	wc_falcon_pub_size(falcon_key * key) Returns the encoded public-key size in bytes for the key's parameter set (level).
int	wc_falcon_sig_size(falcon_key * key) Returns the maximum signature size in bytes for the key's parameter set (level).
int	wc_Falcon_PrivateKeyDecode(const byte * input, word32 * inOutIdx, falcon_key * key, word32 inSz) Decodes a DER/ASN.1 (PKCS#8) Falcon private key into key. On return inOutIdx is advanced past the consumed input.
int	wc_Falcon_PublicKeyDecode(const byte * input, word32 * inOutIdx, falcon_key * key, word32 inSz) Decodes a DER/ASN.1 (SubjectPublicKeyInfo) Falcon public key into key. On return *inOutIdx is advanced past the consumed input.
int	wc_Falcon_KeyToDer(falcon_key * key, byte * output, word32 inLen) Encodes a Falcon private key (with its public key) as a DER/ASN.1 (PKCS#8) structure. Pass a NULL output to query the required length.
int	wc_Falcon_PrivateKeyToDer(falcon_key * key, byte * output, word32 inLen) Encodes only the Falcon private key as a DER/ASN.1 (PKCS#8) structure. Pass a NULL output to query the required length.
int	wc_Falcon_PublicKeyToDer(falcon_key * key, byte * output, word32 inLen, int withAlg) Encodes a Falcon public key as DER/ASN.1. When withAlg is non-zero the full SubjectPublicKeyInfo (with the algorithm identifier) is produced; otherwise only the raw public key bit string is written. Pass a NULL output to query the required length.

Detailed Description

Falcon is a quantum-resistant lattice-based digital signature scheme (NTRU / fast Fourier sampling). It has not been standardized by NIST yet; because the algorithm is not yet standardized and its API name is subject to change, wolfCrypt gates it behind –enable-experimental, and the wc_falcon_* / falcon_key spelling is expected to follow the standardized name once it is final. Two parameter sets are supported, selected with wc_falcon_set_level(): level 1 (Falcon-512) and level 5 (Falcon-1024). See .

Functions Documentation

function wc_falcon_init

int wc_falcon_init(
    falcon_key * key
)

Initializes a falcon_key object with default settings (no heap hint, software-only). Must be called before any other Falcon operation. Call wc_falcon_set_level() to select a parameter set before generating or importing a key. Release resources with wc_falcon_free() when done: the structure can own heap allocations, so re-initializing a used key without freeing it first orphans them with the secret material still in them.

Parameters:

key Pointer to the falcon_key to initialize.

See:

Return:

0 on success.
BAD_FUNC_ARG if key is NULL.

Falcon is a quantum-resistant lattice signature scheme. It has not been standardized by NIST yet, so the "falcon" API name is experimental and subject to change, and building it requires –enable-experimental.

Example

falcon_key key;
int ret;

ret = wc_falcon_init(&key);
if (ret != 0) {
    // error initializing key
}
ret = wc_falcon_set_level(&key, 1); // Falcon-512
// ... use key ...
wc_falcon_free(&key);

function wc_falcon_init_ex

int wc_falcon_init_ex(
    falcon_key * key,
    void * heap,
    int devId
)

Initializes a falcon_key object with a heap hint and device identifier for hardware crypto callbacks.

Parameters:

key Pointer to the falcon_key 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.

Example

falcon_key key;
int ret;

ret = wc_falcon_init_ex(&key, NULL, INVALID_DEVID);
if (ret != 0) {
    // error initializing key
}
ret = wc_falcon_set_level(&key, 5); // Falcon-1024
// ... use key ...
wc_falcon_free(&key);

function wc_falcon_init_id

int wc_falcon_init_id(
    falcon_key * key,
    const unsigned char * id,
    int len,
    void * heap,
    int devId
)

Initializes a falcon_key object and associates it with a key identifier for use with a hardware crypto callback / secure element. Only available when built with WOLF_PRIVATE_KEY_ID.

Parameters:

key Pointer to the falcon_key to initialize.
id Key identifier bytes.
len Length of id in bytes.
heap Heap hint. May be NULL.
devId Device identifier for the crypto callback.

See:

Return:

0 on success.
BAD_FUNC_ARG if key or id is NULL, or len is out of range.

function wc_falcon_init_label

int wc_falcon_init_label(
    falcon_key * key,
    const char * label,
    void * heap,
    int devId
)

Initializes a falcon_key object and associates it with a text label for use with a hardware crypto callback / secure element. Only available when built with WOLF_PRIVATE_KEY_ID.

Parameters:

key Pointer to the falcon_key to initialize.
label NUL-terminated label string.
heap Heap hint. May be NULL.
devId Device identifier for the crypto callback.

See:

Return:

0 on success.
BAD_FUNC_ARG if key or label is NULL, or the label is invalid.

function wc_falcon_set_level

int wc_falcon_set_level(
    falcon_key * key,
    byte level
)

Selects the Falcon parameter set (security level) for a key. Must be set before key generation or import.

Parameters:

key Pointer to the falcon_key.
level Parameter set: 1 for Falcon-512, 5 for Falcon-1024.

See:

Return:

0 on success.
BAD_FUNC_ARG if key is NULL, level is not 1 or 5, or that level was not built into the library (WOLFSSL_NO_FALCON_LEVEL1 / WOLFSSL_NO_FALCON_LEVEL5).
MEMORY_E if WOLFSSL_FALCON_DYNAMIC_KEYS is defined and the encoded key buffers could not be allocated.

function wc_falcon_get_level

int wc_falcon_get_level(
    falcon_key * key,
    byte * level
)

Retrieves the Falcon parameter set (security level) currently set on a key.

Parameters:

key Pointer to the falcon_key.
level Set to 1 (Falcon-512) or 5 (Falcon-1024).

See: wc_falcon_set_level

Return:

0 on success.
BAD_FUNC_ARG if key or level is NULL, or no level has been set.

function wc_falcon_free

void wc_falcon_free(
    falcon_key * key
)

Frees a falcon_key object and securely zeros any key material it holds. The key may be re-initialized afterwards. The structure can own heap allocations, so it must have been initialized (or zeroed) first; calling this on an untouched stack object frees indeterminate pointers.

Parameters:

key Pointer to the falcon_key to free. May be NULL.

See:

function wc_falcon_make_key

int wc_falcon_make_key(
    falcon_key * key,
    WC_RNG * rng
)

Generates a Falcon key pair into key. The parameter set must have been selected with wc_falcon_set_level() first. Not available in verify-only builds (WOLFSSL_FALCON_VERIFY_ONLY).

Parameters:

key Pointer to an initialized falcon_key with a level set.
rng Pointer to an initialized WC_RNG.

See:

Return:

0 on success.
BAD_FUNC_ARG if key or rng is NULL or the level is unset.
MEMORY_E on allocation failure.
NO_VALID_DEVID if the key was initialized with an id or label and its devId, or the device a WOLF_CRYPTO_CB_FIND callback picks for it, is a registered device that did not generate it, unless WOLF_CRYPTO_CB_KEYGEN_SW_FALLBACK is defined.

Example

falcon_key key;
WC_RNG rng;
int ret;

wc_InitRng(&rng);
wc_falcon_init(&key);
wc_falcon_set_level(&key, 1);

ret = wc_falcon_make_key(&key, &rng);
if (ret != 0) {
    // error generating key
}
wc_falcon_free(&key);
wc_FreeRng(&rng);

function wc_falcon_sign_msg

int wc_falcon_sign_msg(
    const byte * in,
    word32 inLen,
    byte * out,
    word32 * outLen,
    falcon_key * key,
    WC_RNG * rng
)

Signs a message with a Falcon private key, producing a compressed signature. On entry *outLen holds the size of the out buffer; on return it holds the signature length. Not available in verify-only builds.

Parameters:

in Message to sign.
inLen Length of the message in bytes.
out Buffer to receive the signature.
outLen In: size of out; Out: signature length.
key Pointer to a falcon_key holding a private key. With WC_FALCON_CACHE_EXPANDED_KEY or WC_FALCON_CACHE_PRIV_BASIS the first call fills a per-key cache and later calls read it. That cache is not synchronized: such a key must not be signed with from two threads at once, nor freed, re-levelled or re-imported while a signature is in flight.
rng Pointer to an initialized WC_RNG.

See:

Return:

0 on success.
BAD_FUNC_ARG if a required pointer is NULL or the private key is not set.
BUFFER_E if the out buffer is too small.

Example

byte sig[FALCON_MAX_SIG_SIZE];
word32 sigLen = sizeof(sig);
int ret;

ret = wc_falcon_sign_msg(msg, msgLen, sig, &sigLen, &key, &rng);
if (ret != 0) {
    // error signing
}

function wc_falcon_verify_msg

int wc_falcon_verify_msg(
    const byte * sig,
    word32 sigLen,
    const byte * msg,
    word32 msgLen,
    int * res,
    falcon_key * key
)

Verifies a Falcon signature over a message with a public key. On a completed verification *res is set to 1 when the signature is valid and 0 otherwise; the function returns 0 in both cases. A non-zero return indicates an operational error.

Parameters:

sig Signature to verify.
sigLen Length of the signature in bytes.
msg Message the signature is over.
msgLen Length of the message in bytes.
res Set to 1 if the signature is valid, 0 otherwise, including when an error is returned.
key Pointer to a falcon_key holding a public key.

See:

Return:

0 on a completed verification (check *res for validity).
BAD_FUNC_ARG if a required pointer is NULL or the public key is not set.
MEMORY_E if the working buffer could not be allocated. Verify allocates 4*n bytes per call, unless WOLFSSL_NO_MALLOC is defined to use the stack or WOLFSSL_FALCON_VERIFY_NO_MALLOC is defined to use a buffer in the key (so one key must not verify two signatures at the same time).

Example

int res = 0;
int ret;

ret = wc_falcon_verify_msg(sig, sigLen, msg, msgLen, &res, &key);
if (ret == 0 && res == 1) {
    // signature is valid
}

function wc_falcon_import_public

int wc_falcon_import_public(
    const byte * in,
    word32 inLen,
    falcon_key * key
)

Imports a raw (Falcon-encoded) public key into key. The parameter level must have been set first so the expected length is known.

Parameters:

in Encoded public key bytes.
inLen Length of in.
key Pointer to a falcon_key with a level set.

See:

Return:

0 on success.
BAD_FUNC_ARG if a pointer is NULL, the level is unset, or inLen does not match the expected public-key size.

function wc_falcon_import_private_only

int wc_falcon_import_private_only(
    const byte * priv,
    word32 privSz,
    falcon_key * key
)

Imports a raw (Falcon-encoded) private key into key, without a public key. The parameter level must have been set first.

Parameters:

priv Encoded private key bytes.
privSz Length of priv.
key Pointer to a falcon_key with a level set.

See:

Return:

0 on success.
BAD_FUNC_ARG if a pointer is NULL, the level is unset, or privSz is wrong.

function wc_falcon_import_private_key

int wc_falcon_import_private_key(
    const byte * priv,
    word32 privSz,
    const byte * pub,
    word32 pubSz,
    falcon_key * key
)

Imports a raw Falcon private key and (optionally) public key into key. The parameter level must have been set first.

Parameters:

priv Encoded private key bytes.
privSz Length of priv.
pub Encoded public key bytes. May be NULL.
pubSz Length of pub (0 if pub is NULL).
key Pointer to a falcon_key with a level set.

See:

Return:

0 on success.
BAD_FUNC_ARG if a required pointer is NULL, the level is unset, or a size is wrong.

function wc_falcon_export_public

int wc_falcon_export_public(
    falcon_key * key,
    byte * out,
    word32 * outLen
)

Exports the raw (Falcon-encoded) public key from key. On entry outLen is the size of out; on return it is the number of bytes written.

Parameters:

key Pointer to a falcon_key holding a public key.
out Buffer to receive the encoded public key.
outLen In: size of out; Out: bytes written.

See:

Return:

0 on success.
BAD_FUNC_ARG if a pointer is NULL or no public key is set.
BUFFER_E if out is too small.

function wc_falcon_export_private_only

int wc_falcon_export_private_only(
    falcon_key * key,
    byte * out,
    word32 * outLen
)

Exports the raw (Falcon-encoded) private key from key.

Parameters:

key Pointer to a falcon_key holding a private key.
out Buffer to receive the encoded private key.
outLen In: size of out; Out: bytes written.

See:

Return:

0 on success.
BAD_FUNC_ARG if a pointer is NULL or no private key is set.
BUFFER_E if out is too small.

function wc_falcon_export_private

int wc_falcon_export_private(
    falcon_key * key,
    byte * out,
    word32 * outLen
)

Exports the raw (Falcon-encoded) private key from key. Equivalent to wc_falcon_export_private_only().

Parameters:

key Pointer to a falcon_key holding a private key.
out Buffer to receive the encoded private key.
outLen In: size of out; Out: bytes written.

See:

Return:

0 on success.
BAD_FUNC_ARG if a pointer is NULL or no private key is set.
BUFFER_E if out is too small.

function wc_falcon_export_key

int wc_falcon_export_key(
    falcon_key * key,
    byte * priv,
    word32 * privSz,
    byte * pub,
    word32 * pubSz
)

Exports both the raw private and public keys from key in a single call. Each length parameter is In: buffer size, Out: bytes written.

Parameters:

key Pointer to a falcon_key holding a key pair.
priv Buffer to receive the encoded private key.
privSz In: size of priv; Out: bytes written.
pub Buffer to receive the encoded public key.
pubSz In: size of pub; Out: bytes written.

See: wc_falcon_import_private_key

Return:

0 on success.
BAD_FUNC_ARG if a required pointer is NULL or a key half is missing.
BUFFER_E if a buffer is too small.

function wc_falcon_check_key

int wc_falcon_check_key(
    falcon_key * key
)

Checks the consistency of a Falcon key. With WOLF_CRYPTO_CB, a key with a device id (or any key with WOLF_CRYPTO_CB_FIND) is first passed to the crypto callback, along with the public key when it is set. The device checks the key it contains, so neither key needs to be set locally. Otherwise, or when the callback returns CRYPTOCB_UNAVAILABLE, both the public and private keys must be present. When the native signing core is compiled in, the stored public key h is additionally verified against the private key by checking the defining relation h*f == g (mod q); in verify-only or crypto-callback-only builds only the presence of both keys is checked.

Parameters:

key Pointer to a falcon_key to check.

See:

Return:

0 on success.
BAD_FUNC_ARG if key is NULL, the level is unset, or the level was changed without wc_falcon_set_level() to one the key buffers do not fit.
PUBLIC_KEY_E if the public or private key is missing, or if the public and private keys are cryptographically inconsistent.
Other negative values returned by the crypto callback.

function wc_falcon_size

int wc_falcon_size(
    falcon_key * key
)

Returns the encoded private-key size in bytes for the key's parameter set (level).

Parameters:

key Pointer to a falcon_key with a level set.

See:

Return:

Private-key size in bytes on success.
BAD_FUNC_ARG if key is NULL or the level is unset.

function wc_falcon_priv_size

int wc_falcon_priv_size(
    falcon_key * key
)

Returns the encoded private-key size in bytes for the key's parameter set (level).

Parameters:

key Pointer to a falcon_key with a level set.

See:

Return:

Private-key size in bytes on success.
BAD_FUNC_ARG if key is NULL or the level is unset.

function wc_falcon_pub_size

int wc_falcon_pub_size(
    falcon_key * key
)

Returns the encoded public-key size in bytes for the key's parameter set (level).

Parameters:

key Pointer to a falcon_key with a level set.

See:

Return:

Public-key size in bytes on success.
BAD_FUNC_ARG if key is NULL or the level is unset.

function wc_falcon_sig_size

int wc_falcon_sig_size(
    falcon_key * key
)

Returns the maximum signature size in bytes for the key's parameter set (level).

Parameters:

key Pointer to a falcon_key with a level set.

See: wc_falcon_sign_msg

Return:

Maximum signature size in bytes on success.
BAD_FUNC_ARG if key is NULL or the level is unset.

function wc_Falcon_PrivateKeyDecode

int wc_Falcon_PrivateKeyDecode(
    const byte * input,
    word32 * inOutIdx,
    falcon_key * key,
    word32 inSz
)

Decodes a DER/ASN.1 (PKCS#8) Falcon private key into key. On return inOutIdx is advanced past the consumed input.

Parameters:

input DER-encoded private key.
inOutIdx In: offset to start; Out: offset after the key.
key Pointer to an initialized falcon_key.
inSz Total length of input.

See:

Return:

0 on success.
ASN_PARSE_E or other negative error on a malformed input.

function wc_Falcon_PublicKeyDecode

int wc_Falcon_PublicKeyDecode(
    const byte * input,
    word32 * inOutIdx,
    falcon_key * key,
    word32 inSz
)

Decodes a DER/ASN.1 (SubjectPublicKeyInfo) Falcon public key into key. On return *inOutIdx is advanced past the consumed input.

Parameters:

input DER-encoded public key.
inOutIdx In: offset to start; Out: offset after the key.
key Pointer to an initialized falcon_key.
inSz Total length of input.

See:

Return:

0 on success.
ASN_PARSE_E or other negative error on a malformed input.

function wc_Falcon_KeyToDer

int wc_Falcon_KeyToDer(
    falcon_key * key,
    byte * output,
    word32 inLen
)

Encodes a Falcon private key (with its public key) as a DER/ASN.1 (PKCS#8) structure. Pass a NULL output to query the required length.

Parameters:

key Pointer to a falcon_key holding a private key.
output Buffer to receive the DER. May be NULL to query length.
inLen Size of output in bytes.

See:

Return:

Number of bytes written (or required, if output is NULL) on success.
BAD_FUNC_ARG or BUFFER_E on error.

function wc_Falcon_PrivateKeyToDer

int wc_Falcon_PrivateKeyToDer(
    falcon_key * key,
    byte * output,
    word32 inLen
)

Encodes only the Falcon private key as a DER/ASN.1 (PKCS#8) structure. Pass a NULL output to query the required length.

Parameters:

key Pointer to a falcon_key holding a private key.
output Buffer to receive the DER. May be NULL to query length.
inLen Size of output in bytes.

See:

Return:

Number of bytes written (or required, if output is NULL) on success.
BAD_FUNC_ARG or BUFFER_E on error.

function wc_Falcon_PublicKeyToDer

int wc_Falcon_PublicKeyToDer(
    falcon_key * key,
    byte * output,
    word32 inLen,
    int withAlg
)

Encodes a Falcon public key as DER/ASN.1. When withAlg is non-zero the full SubjectPublicKeyInfo (with the algorithm identifier) is produced; otherwise only the raw public key bit string is written. Pass a NULL output to query the required length.

Parameters:

key Pointer to a falcon_key holding a public key.
output Buffer to receive the DER. May be NULL to query length.
inLen Size of output in bytes.
withAlg Non-zero to include the algorithm identifier.

See: wc_Falcon_PublicKeyDecode

Return:

Number of bytes written (or required, if output is NULL) on success.
BAD_FUNC_ARG or BUFFER_E on error.

Updated on 2026-11-13 at 01:20:07 +0000