wolfSSL/wolfssl
1
0
Fork 1
mirror of https://github.com/wolfSSL/wolfssl.git synced 2026-08-04 03:54:10 +02:00
Code Issues Packages Projects Releases Wiki Activity

Falcon: add doxygen for the public API and document the algorithm

Browse Source 
Add doc/dox_comments/header_files/falcon.h covering every public wc_falcon_* /
wc_Falcon_* function (init/init_ex/init_id/init_label, set/get level, make_key,
sign/verify, import/export public+private, check_key, sizes, and the DER
encode/decode helpers), plus a Falcon \defgroup in doxygen_groups.h. List
Falcon in the INSTALL algorithm summary.

Docs refer to the algorithm only as "Falcon" (it is not standardized yet); the
temporary-name note and the configure --help / summary text are reworded to not
name a specific future standard.
This commit is contained in:
Daniele Lacamera
2026-07-01 10:27:58 +02:00
parent 84b6a59243
commit ad7b45dc7a
5 changed files with 617 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
INSTALL
+5 -5
View File
@@ -255,12 +255,12 @@
- ML-KEM (FIPS 203, CRYSTALS-KYBER) (key encapsulation mechanism)
- ML-DSA (FIPS 204, CRYSTALS-Dilithium) (signature scheme)
- SLH-DSA (FIPS 205, SPHINCS+) (signature scheme)
- Falcon (signature scheme) - experimental, not yet standardized
Falcon (signature scheme) is provided by the native wolfSSL
implementation; liboqs is no longer required or supported. NIST is
standardizing Falcon as FN-DSA (FIPS 206, still a draft). Because it is
not yet standardized and its API name is subject to change, enable it with
--enable-falcon --enable-experimental (CMake: -DWOLFSSL_FALCON=yes
Falcon is provided by the native wolfSSL implementation; liboqs is no
longer required or supported. Falcon has not been standardized by NIST yet,
and its wolfCrypt API name is experimental and subject to change, so enable
it with --enable-falcon --enable-experimental (CMake: -DWOLFSSL_FALCON=yes
-DWOLFSSL_EXPERIMENTAL=yes).
The following NIST Competition Round 3 finalist algorithms were supported,
configure.ac
+8 -8
View File
@@ -1829,7 +1829,7 @@ fi
# API name is subject to change, it requires --enable-experimental (checked in
# the CFLAG section, once all backend sub-options have been resolved).
AC_ARG_ENABLE([falcon],
[AS_HELP_STRING([--enable-falcon],[Enable Falcon post-quantum signatures (native, no liboqs; pre-standardization name for FN-DSA; requires --enable-experimental) (default: disabled)])],
[AS_HELP_STRING([--enable-falcon],[Enable Falcon post-quantum signatures (native, no liboqs; requires --enable-experimental) (default: disabled)])],
[ ENABLED_FALCON=$enableval ],
[ ENABLED_FALCON=no ])
@@ -1837,7 +1837,7 @@ AC_ARG_ENABLE([falcon],
# FN-DSA (currently x86-64 SSE2 only); the portable constant-time integer
# emulation remains the default. It implies --enable-falcon.
AC_ARG_ENABLE([falcon-asm],
[AS_HELP_STRING([--enable-falcon-asm],[Enable FN-DSA x86-64 assembly fpr backend (default: disabled)])],
[AS_HELP_STRING([--enable-falcon-asm],[Enable Falcon x86-64 assembly fpr backend (default: disabled)])],
[ ENABLED_FALCON_ASM=$enableval ],
[ ENABLED_FALCON_ASM=no ])
if test "$ENABLED_FALCON_ASM" = "yes"; then
@@ -1856,7 +1856,7 @@ fi
# but like --enable-falcon-asm it relies on the native FPU's rounding behavior.
# It implies --enable-falcon and is mutually exclusive with --enable-falcon-asm.
AC_ARG_ENABLE([falcon-double],
[AS_HELP_STRING([--enable-falcon-double],[Enable FN-DSA inline native-double fpr backend (default: disabled)])],
[AS_HELP_STRING([--enable-falcon-double],[Enable Falcon inline native-double fpr backend (default: disabled)])],
[ ENABLED_FALCON_DOUBLE=$enableval ],
[ ENABLED_FALCON_DOUBLE=no ])
if test "$ENABLED_FALCON_DOUBLE" = "yes"; then
@@ -1873,7 +1873,7 @@ fi
# host must support AVX2+FMA at run time. Signing is sampler-bound, so the FFT
# vectorization yields a modest (~1.1x) end-to-end speedup.
AC_ARG_ENABLE([falcon-avx2],
[AS_HELP_STRING([--enable-falcon-avx2],[Enable FN-DSA x86-64 AVX2 vectorized FFT (default: disabled)])],
[AS_HELP_STRING([--enable-falcon-avx2],[Enable Falcon x86-64 AVX2 vectorized FFT (default: disabled)])],
[ ENABLED_FALCON_AVX2=$enableval ],
[ ENABLED_FALCON_AVX2=no ])
if test "$ENABLED_FALCON_AVX2" = "yes"; then
@@ -1894,7 +1894,7 @@ fi
# implies). AArch64 Advanced SIMD is part of the ARMv8-A baseline, so no special
# -march is required.
AC_ARG_ENABLE([falcon-neon],
[AS_HELP_STRING([--enable-falcon-neon],[Enable FN-DSA AArch64 NEON vectorized FFT (default: disabled)])],
[AS_HELP_STRING([--enable-falcon-neon],[Enable Falcon AArch64 NEON vectorized FFT (default: disabled)])],
[ ENABLED_FALCON_NEON=$enableval ],
[ ENABLED_FALCON_NEON=no ])
if test "$ENABLED_FALCON_NEON" = "yes"; then
@@ -7920,7 +7920,7 @@ then
ENABLED_SHAKE128=yes
ENABLED_SHAKE256=yes
fi
# FN-DSA (native Falcon) uses SHA-3 / SHAKE256 for hash-to-point.
# Falcon uses SHA-3 / SHAKE256 for hash-to-point.
if test "$ENABLED_FALCON" != "no"
then
ENABLED_SHA3=yes
@@ -13520,7 +13520,7 @@ echo " * XMSS: $ENABLED_XMSS"
echo " * SLH-DSA $ENABLED_SLHDSA"
echo " * MLKEM: $ENABLED_MLKEM"
echo " * ML-DSA: $ENABLED_MLDSA"
echo " * FN-DSA (native Falcon): $ENABLED_FALCON"
echo " * Falcon: $ENABLED_FALCON"
echo " * ECCSI $ENABLED_ECCSI"
echo " * SAKKE $ENABLED_SAKKE"
echo " * ASN: $ENABLED_ASN"
@@ -13578,7 +13578,7 @@ echo " * Persistent session cache: $ENABLED_SAVESESSION"
echo " * Persistent cert cache: $ENABLED_SAVECERT"
echo " * Atomic User Record Layer: $ENABLED_ATOMICUSER"
echo " * Public Key Callbacks: $ENABLED_PKCALLBACKS"
echo " * Falcon (native FN-DSA): $ENABLED_FALCON"
echo " * Falcon: $ENABLED_FALCON"
echo " * Whitewood netRandom: $ENABLED_WNR"
echo " * Server Name Indication: $ENABLED_SNI"
echo " * ALPN: $ENABLED_ALPN"
doc/dox_comments/header_files/doxygen_groups.h
+9
View File
@@ -15,6 +15,15 @@
\defgroup ECC Algorithms - ECC
\defgroup ED25519 Algorithms - ED25519
\defgroup ED448 Algorithms - ED448
\defgroup Falcon Algorithms - Falcon
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 <wolfssl/wolfcrypt/falcon.h>.
\defgroup ML_DSA Algorithms - ML-DSA (FIPS 204)
ML-DSA (Module-Lattice-based Digital Signature Algorithm) is a
quantum-resistant digital signature scheme standardized by NIST as
doc/dox_comments/header_files/falcon.h
+586
View File
@@ -0,0 +1,586 @@
/*!
\ingroup Falcon
\brief 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.
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.
\return 0 on success.
\return BAD_FUNC_ARG if key is NULL.
\param [in,out] key Pointer to the falcon_key to initialize.
_Example_
\code
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);
\endcode
\sa wc_falcon_init_ex
\sa wc_falcon_set_level
\sa wc_falcon_free
*/
int wc_falcon_init(falcon_key* key);
/*!
\ingroup Falcon
\brief Initializes a falcon_key object with a heap hint and device
identifier for hardware crypto callbacks.
\return 0 on success.
\return BAD_FUNC_ARG if key is NULL.
\param [in,out] key Pointer to the falcon_key to initialize.
\param [in] heap Heap hint for dynamic memory allocation. May be NULL.
\param [in] devId Device identifier for hardware crypto callbacks; use
INVALID_DEVID for software-only.
_Example_
\code
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);
\endcode
\sa wc_falcon_init
\sa wc_falcon_set_level
\sa wc_falcon_free
*/
int wc_falcon_init_ex(falcon_key* key, void* heap, int devId);
/*!
\ingroup Falcon
\brief 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.
\return 0 on success.
\return BAD_FUNC_ARG if key or id is NULL, or len is out of range.
\param [in,out] key Pointer to the falcon_key to initialize.
\param [in] id Key identifier bytes.
\param [in] len Length of id in bytes.
\param [in] heap Heap hint. May be NULL.
\param [in] devId Device identifier for the crypto callback.
\sa wc_falcon_init_ex
\sa wc_falcon_init_label
*/
int wc_falcon_init_id(falcon_key* key, const unsigned char* id, int len,
void* heap, int devId);
/*!
\ingroup Falcon
\brief 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.
\return 0 on success.
\return BAD_FUNC_ARG if key or label is NULL, or the label is invalid.
\param [in,out] key Pointer to the falcon_key to initialize.
\param [in] label NUL-terminated label string.
\param [in] heap Heap hint. May be NULL.
\param [in] devId Device identifier for the crypto callback.
\sa wc_falcon_init_ex
\sa wc_falcon_init_id
*/
int wc_falcon_init_label(falcon_key* key, const char* label, void* heap,
int devId);
/*!
\ingroup Falcon
\brief Selects the Falcon parameter set (security level) for a key. Must be
set before key generation or import.
\return 0 on success.
\return BAD_FUNC_ARG if key is NULL or level is not 1 or 5.
\param [in,out] key Pointer to the falcon_key.
\param [in] level Parameter set: 1 for Falcon-512, 5 for Falcon-1024.
\sa wc_falcon_get_level
\sa wc_falcon_make_key
*/
int wc_falcon_set_level(falcon_key* key, byte level);
/*!
\ingroup Falcon
\brief Retrieves the Falcon parameter set (security level) currently set on
a key.
\return 0 on success.
\return BAD_FUNC_ARG if key or level is NULL, or no level has been set.
\param [in] key Pointer to the falcon_key.
\param [out] level Set to 1 (Falcon-512) or 5 (Falcon-1024).
\sa wc_falcon_set_level
*/
int wc_falcon_get_level(falcon_key* key, byte* level);
/*!
\ingroup Falcon
\brief Frees a falcon_key object and securely zeros any key material it
holds. The key may be re-initialized afterwards.
\param [in,out] key Pointer to the falcon_key to free. May be NULL.
\sa wc_falcon_init
\sa wc_falcon_init_ex
*/
void wc_falcon_free(falcon_key* key);
/*!
\ingroup Falcon
\brief 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).
\return 0 on success.
\return BAD_FUNC_ARG if key or rng is NULL or the level is unset.
\return MEMORY_E on allocation failure.
\param [in,out] key Pointer to an initialized falcon_key with a level set.
\param [in] rng Pointer to an initialized WC_RNG.
_Example_
\code
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);
\endcode
\sa wc_falcon_set_level
\sa wc_falcon_sign_msg
\sa wc_falcon_check_key
*/
int wc_falcon_make_key(falcon_key* key, WC_RNG* rng);
/*!
\ingroup Falcon
\brief 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.
\return 0 on success.
\return BAD_FUNC_ARG if a required pointer is NULL or the private key is not
set.
\return BUFFER_E if the out buffer is too small.
\param [in] in Message to sign.
\param [in] inLen Length of the message in bytes.
\param [out] out Buffer to receive the signature.
\param [in,out] outLen In: size of out; Out: signature length.
\param [in] key Pointer to a falcon_key holding a private key.
\param [in] rng Pointer to an initialized WC_RNG.
_Example_
\code
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
}
\endcode
\sa wc_falcon_verify_msg
\sa wc_falcon_make_key
\sa wc_falcon_sig_size
*/
int wc_falcon_sign_msg(const byte* in, word32 inLen, byte* out, word32 *outLen,
falcon_key* key, WC_RNG* rng);
/*!
\ingroup Falcon
\brief 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.
\return 0 on a completed verification (check *res for validity).
\return BAD_FUNC_ARG if a required pointer is NULL or the public key is not
set.
\param [in] sig Signature to verify.
\param [in] sigLen Length of the signature in bytes.
\param [in] msg Message the signature is over.
\param [in] msgLen Length of the message in bytes.
\param [out] res Set to 1 if the signature is valid, 0 otherwise.
\param [in] key Pointer to a falcon_key holding a public key.
_Example_
\code
int res = 0;
int ret;
ret = wc_falcon_verify_msg(sig, sigLen, msg, msgLen, &res, &key);
if (ret == 0 && res == 1) {
// signature is valid
}
\endcode
\sa wc_falcon_sign_msg
\sa wc_falcon_import_public
*/
int wc_falcon_verify_msg(const byte* sig, word32 sigLen, const byte* msg,
word32 msgLen, int* res, falcon_key* key);
/*!
\ingroup Falcon
\brief Imports a raw (Falcon-encoded) public key into key. The parameter
level must have been set first so the expected length is known.
\return 0 on success.
\return BAD_FUNC_ARG if a pointer is NULL, the level is unset, or inLen does
not match the expected public-key size.
\param [in] in Encoded public key bytes.
\param [in] inLen Length of in.
\param [in,out] key Pointer to a falcon_key with a level set.
\sa wc_falcon_export_public
\sa wc_falcon_verify_msg
*/
int wc_falcon_import_public(const byte* in, word32 inLen, falcon_key* key);
/*!
\ingroup Falcon
\brief Imports a raw (Falcon-encoded) private key into key, without a public
key. The parameter level must have been set first.
\return 0 on success.
\return BAD_FUNC_ARG if a pointer is NULL, the level is unset, or privSz is
wrong.
\param [in] priv Encoded private key bytes.
\param [in] privSz Length of priv.
\param [in,out] key Pointer to a falcon_key with a level set.
\sa wc_falcon_import_private_key
\sa wc_falcon_export_private
*/
int wc_falcon_import_private_only(const byte* priv, word32 privSz,
falcon_key* key);
/*!
\ingroup Falcon
\brief Imports a raw Falcon private key and (optionally) public key into
key. The parameter level must have been set first.
\return 0 on success.
\return BAD_FUNC_ARG if a required pointer is NULL, the level is unset, or a
size is wrong.
\param [in] priv Encoded private key bytes.
\param [in] privSz Length of priv.
\param [in] pub Encoded public key bytes. May be NULL.
\param [in] pubSz Length of pub (0 if pub is NULL).
\param [in,out] key Pointer to a falcon_key with a level set.
\sa wc_falcon_import_private_only
\sa wc_falcon_export_key
*/
int wc_falcon_import_private_key(const byte* priv, word32 privSz,
const byte* pub, word32 pubSz, falcon_key* key);
/*!
\ingroup Falcon
\brief 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.
\return 0 on success.
\return BAD_FUNC_ARG if a pointer is NULL or no public key is set.
\return BUFFER_E if out is too small.
\param [in] key Pointer to a falcon_key holding a public key.
\param [out] out Buffer to receive the encoded public key.
\param [in,out] outLen In: size of out; Out: bytes written.
\sa wc_falcon_import_public
\sa wc_falcon_pub_size
*/
int wc_falcon_export_public(falcon_key* key, byte* out, word32* outLen);
/*!
\ingroup Falcon
\brief Exports the raw (Falcon-encoded) private key from key.
\return 0 on success.
\return BAD_FUNC_ARG if a pointer is NULL or no private key is set.
\return BUFFER_E if out is too small.
\param [in] key Pointer to a falcon_key holding a private key.
\param [out] out Buffer to receive the encoded private key.
\param [in,out] outLen In: size of out; Out: bytes written.
\sa wc_falcon_import_private_only
\sa wc_falcon_priv_size
*/
int wc_falcon_export_private_only(falcon_key* key, byte* out, word32* outLen);
/*!
\ingroup Falcon
\brief Exports the raw (Falcon-encoded) private key from key. Equivalent to
wc_falcon_export_private_only().
\return 0 on success.
\return BAD_FUNC_ARG if a pointer is NULL or no private key is set.
\return BUFFER_E if out is too small.
\param [in] key Pointer to a falcon_key holding a private key.
\param [out] out Buffer to receive the encoded private key.
\param [in,out] outLen In: size of out; Out: bytes written.
\sa wc_falcon_export_private_only
\sa wc_falcon_export_key
*/
int wc_falcon_export_private(falcon_key* key, byte* out, word32* outLen);
/*!
\ingroup Falcon
\brief Exports both the raw private and public keys from key in a single
call. Each length parameter is In: buffer size, Out: bytes written.
\return 0 on success.
\return BAD_FUNC_ARG if a required pointer is NULL or a key half is missing.
\return BUFFER_E if a buffer is too small.
\param [in] key Pointer to a falcon_key holding a key pair.
\param [out] priv Buffer to receive the encoded private key.
\param [in,out] privSz In: size of priv; Out: bytes written.
\param [out] pub Buffer to receive the encoded public key.
\param [in,out] pubSz In: size of pub; Out: bytes written.
\sa wc_falcon_import_private_key
*/
int wc_falcon_export_key(falcon_key* key, byte* priv, word32 *privSz,
byte* pub, word32* pubSz);
/*!
\ingroup Falcon
\brief Checks the consistency of a Falcon key, verifying that the stored
public key matches the private key when both are present.
\return 0 on success.
\return BAD_FUNC_ARG if key is NULL.
\return PUBLIC_KEY_E if the public and private keys are inconsistent.
\param [in] key Pointer to a falcon_key to check.
\sa wc_falcon_make_key
\sa wc_falcon_import_private_key
*/
int wc_falcon_check_key(falcon_key* key);
/*!
\ingroup Falcon
\brief Returns the encoded private-key size in bytes for the key's
parameter set (level).
\return Private-key size in bytes on success.
\return BAD_FUNC_ARG if key is NULL or the level is unset.
\param [in] key Pointer to a falcon_key with a level set.
\sa wc_falcon_priv_size
\sa wc_falcon_pub_size
*/
int wc_falcon_size(falcon_key* key);
/*!
\ingroup Falcon
\brief Returns the encoded private-key size in bytes for the key's
parameter set (level).
\return Private-key size in bytes on success.
\return BAD_FUNC_ARG if key is NULL or the level is unset.
\param [in] key Pointer to a falcon_key with a level set.
\sa wc_falcon_size
\sa wc_falcon_export_private
*/
int wc_falcon_priv_size(falcon_key* key);
/*!
\ingroup Falcon
\brief Returns the encoded public-key size in bytes for the key's parameter
set (level).
\return Public-key size in bytes on success.
\return BAD_FUNC_ARG if key is NULL or the level is unset.
\param [in] key Pointer to a falcon_key with a level set.
\sa wc_falcon_export_public
\sa wc_falcon_priv_size
*/
int wc_falcon_pub_size(falcon_key* key);
/*!
\ingroup Falcon
\brief Returns the maximum signature size in bytes for the key's parameter
set (level).
\return Maximum signature size in bytes on success.
\return BAD_FUNC_ARG if key is NULL or the level is unset.
\param [in] key Pointer to a falcon_key with a level set.
\sa wc_falcon_sign_msg
*/
int wc_falcon_sig_size(falcon_key* key);
/*!
\ingroup Falcon
\brief Decodes a DER/ASN.1 (PKCS#8) Falcon private key into key. On return
*inOutIdx is advanced past the consumed input.
\return 0 on success.
\return ASN_PARSE_E or other negative error on a malformed input.
\param [in] input DER-encoded private key.
\param [in,out] inOutIdx In: offset to start; Out: offset after the key.
\param [in,out] key Pointer to an initialized falcon_key.
\param [in] inSz Total length of input.
\sa wc_Falcon_PrivateKeyToDer
\sa wc_Falcon_PublicKeyDecode
*/
int wc_Falcon_PrivateKeyDecode(const byte* input, word32* inOutIdx,
falcon_key* key, word32 inSz);
/*!
\ingroup Falcon
\brief Decodes a DER/ASN.1 (SubjectPublicKeyInfo) Falcon public key into
key. On return *inOutIdx is advanced past the consumed input.
\return 0 on success.
\return ASN_PARSE_E or other negative error on a malformed input.
\param [in] input DER-encoded public key.
\param [in,out] inOutIdx In: offset to start; Out: offset after the key.
\param [in,out] key Pointer to an initialized falcon_key.
\param [in] inSz Total length of input.
\sa wc_Falcon_PublicKeyToDer
\sa wc_Falcon_PrivateKeyDecode
*/
int wc_Falcon_PublicKeyDecode(const byte* input, word32* inOutIdx,
falcon_key* key, word32 inSz);
/*!
\ingroup Falcon
\brief 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.
\return Number of bytes written (or required, if output is NULL) on success.
\return BAD_FUNC_ARG or BUFFER_E on error.
\param [in] key Pointer to a falcon_key holding a private key.
\param [out] output Buffer to receive the DER. May be NULL to query length.
\param [in] inLen Size of output in bytes.
\sa wc_Falcon_PrivateKeyDecode
\sa wc_Falcon_PrivateKeyToDer
*/
int wc_Falcon_KeyToDer(falcon_key* key, byte* output, word32 inLen);
/*!
\ingroup Falcon
\brief Encodes only the Falcon private key as a DER/ASN.1 (PKCS#8)
structure. Pass a NULL output to query the required length.
\return Number of bytes written (or required, if output is NULL) on success.
\return BAD_FUNC_ARG or BUFFER_E on error.
\param [in] key Pointer to a falcon_key holding a private key.
\param [out] output Buffer to receive the DER. May be NULL to query length.
\param [in] inLen Size of output in bytes.
\sa wc_Falcon_PrivateKeyDecode
\sa wc_Falcon_KeyToDer
*/
int wc_Falcon_PrivateKeyToDer(falcon_key* key, byte* output, word32 inLen);
/*!
\ingroup Falcon
\brief 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.
\return Number of bytes written (or required, if output is NULL) on success.
\return BAD_FUNC_ARG or BUFFER_E on error.
\param [in] key Pointer to a falcon_key holding a public key.
\param [out] output Buffer to receive the DER. May be NULL to query length.
\param [in] inLen Size of output in bytes.
\param [in] withAlg Non-zero to include the algorithm identifier.
\sa wc_Falcon_PublicKeyDecode
*/
int wc_Falcon_PublicKeyToDer(falcon_key* key, byte* output, word32 inLen,
int withAlg);
wolfssl/wolfcrypt/falcon.h
+9 -11
View File
@@ -42,19 +42,17 @@
* must be visible unconditionally. */
#include <wolfssl/wolfcrypt/random.h>
/* Falcon is the PRE-STANDARDIZATION name for this NIST post-quantum signature
* scheme. NIST is standardizing it as FN-DSA (FIPS 206), which is still a draft.
* Until FN-DSA is finalized, wolfCrypt exposes the algorithm under its current
* name -- "falcon" (wc_falcon_* / falcon_key) -- and it requires
* --enable-experimental to build.
/* Falcon is a NIST post-quantum signature scheme that has NOT been standardized
* yet. wolfCrypt exposes it under its current name -- "falcon" (wc_falcon_* /
* falcon_key) -- and it requires --enable-experimental to build.
*
* NOTE: this API and its "falcon" spelling are TEMPORARY and subject to change.
* When FN-DSA is finalized the canonical API will be renamed to the
* standardized name -- exactly as the pre-standardization Kyber and Dilithium
* APIs were renamed to ML-KEM (FIPS 203) and ML-DSA (FIPS 204) in wolfSSL 5.7 --
* and this <falcon.h> is expected to be retained thereafter as a temporary
* compatibility shim. Application code that uses wc_falcon_* / falcon_key should
* expect to migrate to the standardized spelling. */
* Once the algorithm is standardized, the canonical API is expected to be
* renamed to the standardized name -- exactly as the pre-standardization Kyber
* and Dilithium APIs were renamed to ML-KEM (FIPS 203) and ML-DSA (FIPS 204) in
* wolfSSL 5.7 -- and this <falcon.h> is expected to be retained thereafter as a
* temporary compatibility shim. Application code that uses wc_falcon_* /
* falcon_key should expect to migrate to the standardized spelling. */
/* This is the native wolfCrypt implementation (no liboqs dependency). */