Algorithms - FrodoKEM

More...

Functions

	Name
FrodoKemKey *	wc_FrodoKemKey_New(int type, void * heap, int devId) Allocates and initializes a new FrodoKemKey on the heap. The returned pointer must be released with wc_FrodoKemKey_Delete().
int	wc_FrodoKemKey_Delete(FrodoKemKey * key, FrodoKemKey ** key_p) Frees and zeros a heap-allocated FrodoKemKey previously returned by wc_FrodoKemKey_New(). On success the caller's pointer variable is set to NULL via key_p when key_p is not NULL.
int	wc_FrodoKemKey_Init(FrodoKemKey * key, int type, void * heap, int devId) Initializes a FrodoKemKey object in place. The type parameter selects the FrodoKEM variant: a base parameter set (WC_FRODOKEM_640_SHAKE, WC_FRODOKEM_976_SHAKE or WC_FRODOKEM_1344_SHAKE) optionally OR'd with FRODOKEM_AES and/or FRODOKEM_EPHEMERAL.
int	wc_FrodoKemKey_Free(FrodoKemKey * key) Releases the resources held by a FrodoKemKey initialized with wc_FrodoKemKey_Init() and zeroizes its secret material. The key object itself is not freed (it was not allocated by Init).
int	wc_FrodoKemKey_MakeKey(FrodoKemKey * key, WC_RNG * rng) Generates a FrodoKEM key pair into an initialized key using the provided random number generator. On success the key holds both the public and private keys, which can be serialized with wc_FrodoKemKey_EncodePublicKey() and wc_FrodoKemKey_EncodePrivateKey().
int	wc_FrodoKemKey_MakeKeyWithRandom(FrodoKemKey * key, const unsigned char * rand, int len) Generates a FrodoKEM key pair from caller-supplied random bytes rather than an RNG. This is primarily for testing and known answer tests; production code should use wc_FrodoKemKey_MakeKey(). The required length depends on the parameter set (for example WC_FRODOKEM_640_MAKEKEY_RAND_SZ for FrodoKEM-640).
int	wc_FrodoKemKey_CipherTextSize(FrodoKemKey * key, word32 * len) Returns, through len, the size in bytes of a ciphertext (encapsulation) for the key's parameter set. Use this to size the ct buffer passed to wc_FrodoKemKey_Encapsulate().
int	wc_FrodoKemKey_SharedSecretSize(FrodoKemKey * key, word32 * len) Returns, through len, the size in bytes of a shared secret for the key's parameter set. Use this to size the ss buffer passed to wc_FrodoKemKey_Encapsulate() and wc_FrodoKemKey_Decapsulate().
int	wc_FrodoKemKey_Encapsulate(FrodoKemKey * key, unsigned char * ct, unsigned char * ss, WC_RNG * rng) Encapsulates to a public key: generates a random shared secret and the ciphertext that encapsulates it under key's public key. The key must hold a public key (from wc_FrodoKemKey_MakeKey() or wc_FrodoKemKey_DecodePublicKey()). Size the ct and ss buffers with wc_FrodoKemKey_CipherTextSize() and wc_FrodoKemKey_SharedSecretSize().
int	wc_FrodoKemKey_EncapsulateWithRandom(FrodoKemKey * key, unsigned char * ct, unsigned char * ss, const unsigned char * rand, int len) Encapsulates using caller-supplied random bytes rather than an RNG. This is primarily for testing and known answer tests; production code should use wc_FrodoKemKey_Encapsulate(). The required length depends on the parameter set (for example WC_FRODOKEM_640_ENC_RAND_SZ for FrodoKEM-640).
int	wc_FrodoKemKey_Decapsulate(FrodoKemKey * key, unsigned char * ss, const unsigned char * ct, word32 len) Decapsulates a ciphertext to recover the shared secret using the key's private key. FrodoKEM is IND-CCA2 secure: a ciphertext that does not decrypt consistently yields a pseudo-random shared secret (implicit rejection) rather than an error, so decapsulation of a valid ciphertext reproduces the shared secret from encapsulation. Size the ss buffer with wc_FrodoKemKey_SharedSecretSize().
int	wc_FrodoKemKey_DecodePrivateKey(FrodoKemKey * key, const unsigned char * in, word32 len) Decodes (imports) a FrodoKEM private key from its serialized form into an initialized key. The expected length matches wc_FrodoKemKey_PrivateKeySize() for the key's parameter set.
int	wc_FrodoKemKey_DecodePublicKey(FrodoKemKey * key, const unsigned char * in, word32 len) Decodes (imports) a FrodoKEM public key from its serialized form into an initialized key. The expected length matches wc_FrodoKemKey_PublicKeySize() for the key's parameter set.
int	wc_FrodoKemKey_PrivateKeySize(FrodoKemKey * key, word32 * len) Returns, through len, the size in bytes of a serialized private key for the key's parameter set. Use this to size the buffer passed to wc_FrodoKemKey_EncodePrivateKey().
int	wc_FrodoKemKey_PublicKeySize(FrodoKemKey * key, word32 * len) Returns, through len, the size in bytes of a serialized public key for the key's parameter set. Use this to size the buffer passed to wc_FrodoKemKey_EncodePublicKey().
int	wc_FrodoKemKey_EncodePrivateKey(FrodoKemKey * key, unsigned char * out, word32 len) Encodes (exports) the private key held by key into its serialized form. The out buffer must be at least wc_FrodoKemKey_PrivateKeySize() bytes.
int	wc_FrodoKemKey_EncodePublicKey(FrodoKemKey * key, unsigned char * out, word32 len) Encodes (exports) the public key held by key into its serialized form. The out buffer must be at least wc_FrodoKemKey_PublicKeySize() bytes.

Detailed Description

FrodoKEM is a conservative, unstructured-lattice (plain LWE) key encapsulation mechanism. This is an experimental reference implementation following the ISO/CFRG (salted) FrodoKEM and the ephemeral eFrodoKEM (salt-less) variants. Three parameter sets are provided - FrodoKEM-640 (NIST level 1), FrodoKEM-976 (level 3) and FrodoKEM-1344 (level 5) - each with either SHAKE-128 or AES-128 generation of the public matrix A. The variant is selected by the key type (a base parameter set optionally OR'd with FRODOKEM_AES and/or FRODOKEM_EPHEMERAL) when the key is initialized via wc_FrodoKemKey_Init() or wc_FrodoKemKey_New().

Functions Documentation

function wc_FrodoKemKey_New

FrodoKemKey * wc_FrodoKemKey_New(
    int type,
    void * heap,
    int devId
)

Allocates and initializes a new FrodoKemKey on the heap. The returned pointer must be released with wc_FrodoKemKey_Delete().

Parameters:

• type FrodoKEM key type: a base parameter set optionally OR'd with FRODOKEM_AES and/or FRODOKEM_EPHEMERAL.
• heap Heap hint for dynamic memory allocation. May be NULL.
• devId Device identifier for hardware crypto callbacks. Use INVALID_DEVID for software-only.

See:

• wc_FrodoKemKey_Delete
• wc_FrodoKemKey_Init

Return:

• Pointer to a freshly allocated FrodoKemKey on success.
• NULL on allocation failure or if type is invalid.

FrodoKEM is a conservative, unstructured-lattice key encapsulation mechanism. The type parameter is a base parameter set - WC_FRODOKEM_640_SHAKE (NIST level 1), WC_FRODOKEM_976_SHAKE (level 3) or WC_FRODOKEM_1344_SHAKE (level 5) - optionally OR'd with FRODOKEM_AES (generate matrix A with AES-128 instead of SHAKE-128) and/or FRODOKEM_EPHEMERAL (eFrodoKEM: ephemeral, no salt). Named combinations such as WC_FRODOKEM_640_AES and WC_EFRODOKEM_1344_SHAKE are provided.

Example

FrodoKemKey* key = wc_FrodoKemKey_New(WC_FRODOKEM_640_SHAKE, NULL,
    INVALID_DEVID);
if (key == NULL) {
    // allocation failed
}
// ... use key ...
wc_FrodoKemKey_Delete(key, &key);

function wc_FrodoKemKey_Delete

int wc_FrodoKemKey_Delete(
    FrodoKemKey * key,
    FrodoKemKey ** key_p
)

Frees and zeros a heap-allocated FrodoKemKey previously returned by wc_FrodoKemKey_New(). On success the caller's pointer variable is set to NULL via key_p when key_p is not NULL.

Parameters:

• key The FrodoKemKey to free.
• key_p Optional address of the caller's pointer variable; when not NULL, it is set to NULL on success.

See: wc_FrodoKemKey_New

Return:

• 0 on success.
• BAD_FUNC_ARG if key is NULL.

function wc_FrodoKemKey_Init

int wc_FrodoKemKey_Init(
    FrodoKemKey * key,
    int type,
    void * heap,
    int devId
)

Initializes a FrodoKemKey object in place. The type parameter selects the FrodoKEM variant: a base parameter set (WC_FRODOKEM_640_SHAKE, WC_FRODOKEM_976_SHAKE or WC_FRODOKEM_1344_SHAKE) optionally OR'd with FRODOKEM_AES and/or FRODOKEM_EPHEMERAL.

Parameters:

• key Pointer to the FrodoKemKey to initialize.
• type FrodoKEM key type: a base parameter set optionally OR'd with FRODOKEM_AES and/or FRODOKEM_EPHEMERAL.
• heap Heap hint for dynamic memory allocation. May be NULL.
• devId Device identifier for hardware crypto callbacks.

See:

• wc_FrodoKemKey_Free
• wc_FrodoKemKey_MakeKey

Return:

• 0 on success.
• BAD_FUNC_ARG if key is NULL or type has bits set outside a base parameter set, FRODOKEM_AES and FRODOKEM_EPHEMERAL.
• NOT_COMPILED_IN if type names a valid variant whose parameter set or matrix-A generation method was disabled at build time.

Example

FrodoKemKey key;
int ret;

ret = wc_FrodoKemKey_Init(&key, WC_FRODOKEM_640_SHAKE, NULL,
    INVALID_DEVID);
if (ret != 0) {
    // error initializing key
}
// ... use key ...
wc_FrodoKemKey_Free(&key);

function wc_FrodoKemKey_Free

int wc_FrodoKemKey_Free(
    FrodoKemKey * key
)

Releases the resources held by a FrodoKemKey initialized with wc_FrodoKemKey_Init() and zeroizes its secret material. The key object itself is not freed (it was not allocated by Init).

Parameters:

• key The FrodoKemKey to free.

See: wc_FrodoKemKey_Init

Return:

• 0 on success.
• BAD_FUNC_ARG if key is NULL.

function wc_FrodoKemKey_MakeKey

int wc_FrodoKemKey_MakeKey(
    FrodoKemKey * key,
    WC_RNG * rng
)

Generates a FrodoKEM key pair into an initialized key using the provided random number generator. On success the key holds both the public and private keys, which can be serialized with wc_FrodoKemKey_EncodePublicKey() and wc_FrodoKemKey_EncodePrivateKey().

Parameters:

• key An initialized FrodoKemKey to hold the generated key pair.
• rng An initialized random number generator.

See:

• wc_FrodoKemKey_MakeKeyWithRandom
• wc_FrodoKemKey_Encapsulate
• wc_FrodoKemKey_EncodePublicKey

Return:

• 0 on success.
• BAD_FUNC_ARG if key or rng is NULL.
• MEMORY_E on allocation failure.
• A negative error code from the RNG or hashing on failure.

Example

FrodoKemKey key;
WC_RNG rng;
int ret;

wc_InitRng(&rng);
wc_FrodoKemKey_Init(&key, WC_FRODOKEM_640_SHAKE, NULL, INVALID_DEVID);

ret = wc_FrodoKemKey_MakeKey(&key, &rng);
if (ret != 0) {
    // error generating key pair
}

wc_FrodoKemKey_Free(&key);
wc_FreeRng(&rng);

function wc_FrodoKemKey_MakeKeyWithRandom

int wc_FrodoKemKey_MakeKeyWithRandom(
    FrodoKemKey * key,
    const unsigned char * rand,
    int len
)

Generates a FrodoKEM key pair from caller-supplied random bytes rather than an RNG. This is primarily for testing and known answer tests; production code should use wc_FrodoKemKey_MakeKey(). The required length depends on the parameter set (for example WC_FRODOKEM_640_MAKEKEY_RAND_SZ for FrodoKEM-640).

Parameters:

• key An initialized FrodoKemKey to hold the generated key pair.
• rand Buffer of random bytes.
• len Length of rand in bytes; must equal the parameter set's WC_FRODOKEM__MAKEKEY_RAND_SZ.

See: wc_FrodoKemKey_MakeKey

Return:

• 0 on success.
• BAD_FUNC_ARG if key or rand is NULL.
• BUFFER_E if len is not the length required for the key's parameter set.

function wc_FrodoKemKey_CipherTextSize

int wc_FrodoKemKey_CipherTextSize(
    FrodoKemKey * key,
    word32 * len
)

Returns, through len, the size in bytes of a ciphertext (encapsulation) for the key's parameter set. Use this to size the ct buffer passed to wc_FrodoKemKey_Encapsulate().

Parameters:

• key An initialized FrodoKemKey.
• len Set to the ciphertext size in bytes.

See:

• wc_FrodoKemKey_Encapsulate
• wc_FrodoKemKey_SharedSecretSize

Return:

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

function wc_FrodoKemKey_SharedSecretSize

int wc_FrodoKemKey_SharedSecretSize(
    FrodoKemKey * key,
    word32 * len
)

Returns, through len, the size in bytes of a shared secret for the key's parameter set. Use this to size the ss buffer passed to wc_FrodoKemKey_Encapsulate() and wc_FrodoKemKey_Decapsulate().

Parameters:

• key An initialized FrodoKemKey.
• len Set to the shared secret size in bytes.

See:

• wc_FrodoKemKey_CipherTextSize
• wc_FrodoKemKey_Encapsulate

Return:

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

function wc_FrodoKemKey_Encapsulate

int wc_FrodoKemKey_Encapsulate(
    FrodoKemKey * key,
    unsigned char * ct,
    unsigned char * ss,
    WC_RNG * rng
)

Encapsulates to a public key: generates a random shared secret and the ciphertext that encapsulates it under key's public key. The key must hold a public key (from wc_FrodoKemKey_MakeKey() or wc_FrodoKemKey_DecodePublicKey()). Size the ct and ss buffers with wc_FrodoKemKey_CipherTextSize() and wc_FrodoKemKey_SharedSecretSize().

Parameters:

• key A FrodoKemKey holding a public key.
• ct Buffer to receive the ciphertext.
• ss Buffer to receive the shared secret.
• rng An initialized random number generator.

See:

• wc_FrodoKemKey_Decapsulate
• wc_FrodoKemKey_EncapsulateWithRandom
• wc_FrodoKemKey_CipherTextSize

Return:

• 0 on success.
• BAD_FUNC_ARG if key, ct, ss or rng is NULL.
• BAD_STATE_E if key does not hold a public key.
• MEMORY_E on allocation failure.

Example

FrodoKemKey key;
WC_RNG rng;
word32 ctSz, ssSz;
byte ct[WC_FRODOKEM_640_CIPHER_TEXT_SIZE];
byte ss[WC_FRODOKEM_640_SS_SIZE];
int ret;

// key holds a decoded/generated public key
wc_FrodoKemKey_CipherTextSize(&key, &ctSz);
wc_FrodoKemKey_SharedSecretSize(&key, &ssSz);

ret = wc_FrodoKemKey_Encapsulate(&key, ct, ss, &rng);
if (ret != 0) {
    // error encapsulating
}

function wc_FrodoKemKey_EncapsulateWithRandom

int wc_FrodoKemKey_EncapsulateWithRandom(
    FrodoKemKey * key,
    unsigned char * ct,
    unsigned char * ss,
    const unsigned char * rand,
    int len
)

Encapsulates using caller-supplied random bytes rather than an RNG. This is primarily for testing and known answer tests; production code should use wc_FrodoKemKey_Encapsulate(). The required length depends on the parameter set (for example WC_FRODOKEM_640_ENC_RAND_SZ for FrodoKEM-640).

Parameters:

• key A FrodoKemKey holding a public key.
• ct Buffer to receive the ciphertext.
• ss Buffer to receive the shared secret.
• rand Buffer of random bytes.
• len Length of rand in bytes; must equal the parameter set's WC_FRODOKEM__ENC_RAND_SZ.

See: wc_FrodoKemKey_Encapsulate

Return:

• 0 on success.
• BAD_FUNC_ARG if key, ct, ss or rand is NULL.
• BUFFER_E if len is not the length required for the key's parameter set.
• BAD_STATE_E if key does not hold a public key.

function wc_FrodoKemKey_Decapsulate

int wc_FrodoKemKey_Decapsulate(
    FrodoKemKey * key,
    unsigned char * ss,
    const unsigned char * ct,
    word32 len
)

Decapsulates a ciphertext to recover the shared secret using the key's private key. FrodoKEM is IND-CCA2 secure: a ciphertext that does not decrypt consistently yields a pseudo-random shared secret (implicit rejection) rather than an error, so decapsulation of a valid ciphertext reproduces the shared secret from encapsulation. Size the ss buffer with wc_FrodoKemKey_SharedSecretSize().

Parameters:

• key A FrodoKemKey holding a private key.
• ss Buffer to receive the shared secret.
• ct The ciphertext to decapsulate.
• len Length of ct in bytes; must equal the ciphertext size for the key's parameter set.

See:

• wc_FrodoKemKey_Encapsulate
• wc_FrodoKemKey_SharedSecretSize

Return:

• 0 on success (a shared secret is always produced for a correctly sized ciphertext).
• BAD_FUNC_ARG if key, ss or ct is NULL.
• BUFFER_E if len is not the ciphertext size for the key's parameter set.
• BAD_STATE_E if key does not hold a private key.
• MEMORY_E on allocation failure.

Example

FrodoKemKey key;
word32 ssSz;
byte ss[WC_FRODOKEM_640_SS_SIZE];
int ret;

// key holds a decoded/generated private key
wc_FrodoKemKey_SharedSecretSize(&key, &ssSz);

ret = wc_FrodoKemKey_Decapsulate(&key, ss, ct, ctSz);
if (ret != 0) {
    // error decapsulating
}

function wc_FrodoKemKey_DecodePrivateKey

int wc_FrodoKemKey_DecodePrivateKey(
    FrodoKemKey * key,
    const unsigned char * in,
    word32 len
)

Decodes (imports) a FrodoKEM private key from its serialized form into an initialized key. The expected length matches wc_FrodoKemKey_PrivateKeySize() for the key's parameter set.

Parameters:

• key An initialized FrodoKemKey to hold the private key.
• in The serialized private key.
• len Length of in in bytes.

See:

• wc_FrodoKemKey_EncodePrivateKey
• wc_FrodoKemKey_PrivateKeySize
• wc_FrodoKemKey_Decapsulate

Return:

• 0 on success.
• BAD_FUNC_ARG if key or in is NULL, or len is not the private key size for the key's parameter set.

function wc_FrodoKemKey_DecodePublicKey

int wc_FrodoKemKey_DecodePublicKey(
    FrodoKemKey * key,
    const unsigned char * in,
    word32 len
)

Decodes (imports) a FrodoKEM public key from its serialized form into an initialized key. The expected length matches wc_FrodoKemKey_PublicKeySize() for the key's parameter set.

Parameters:

• key An initialized FrodoKemKey to hold the public key.
• in The serialized public key.
• len Length of in in bytes.

See:

• wc_FrodoKemKey_EncodePublicKey
• wc_FrodoKemKey_PublicKeySize
• wc_FrodoKemKey_Encapsulate

Return:

• 0 on success.
• BAD_FUNC_ARG if key or in is NULL, or len is not the public key size for the key's parameter set.

function wc_FrodoKemKey_PrivateKeySize

int wc_FrodoKemKey_PrivateKeySize(
    FrodoKemKey * key,
    word32 * len
)

Returns, through len, the size in bytes of a serialized private key for the key's parameter set. Use this to size the buffer passed to wc_FrodoKemKey_EncodePrivateKey().

Parameters:

• key An initialized FrodoKemKey.
• len Set to the private key size in bytes.

See:

• wc_FrodoKemKey_EncodePrivateKey
• wc_FrodoKemKey_DecodePrivateKey

Return:

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

function wc_FrodoKemKey_PublicKeySize

int wc_FrodoKemKey_PublicKeySize(
    FrodoKemKey * key,
    word32 * len
)

Returns, through len, the size in bytes of a serialized public key for the key's parameter set. Use this to size the buffer passed to wc_FrodoKemKey_EncodePublicKey().

Parameters:

• key An initialized FrodoKemKey.
• len Set to the public key size in bytes.

See:

• wc_FrodoKemKey_EncodePublicKey
• wc_FrodoKemKey_DecodePublicKey

Return:

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

function wc_FrodoKemKey_EncodePrivateKey

int wc_FrodoKemKey_EncodePrivateKey(
    FrodoKemKey * key,
    unsigned char * out,
    word32 len
)

Encodes (exports) the private key held by key into its serialized form. The out buffer must be at least wc_FrodoKemKey_PrivateKeySize() bytes.

Parameters:

• key A FrodoKemKey holding a private key.
• out Buffer to receive the serialized private key.
• len Length of the out buffer in bytes.

See:

• wc_FrodoKemKey_DecodePrivateKey
• wc_FrodoKemKey_PrivateKeySize

Return:

• 0 on success.
• BAD_FUNC_ARG if key or out is NULL, or len is smaller than the private key size for the key's parameter set.
• BAD_STATE_E if key does not hold a private key.

function wc_FrodoKemKey_EncodePublicKey

int wc_FrodoKemKey_EncodePublicKey(
    FrodoKemKey * key,
    unsigned char * out,
    word32 len
)

Encodes (exports) the public key held by key into its serialized form. The out buffer must be at least wc_FrodoKemKey_PublicKeySize() bytes.

Parameters:

• key A FrodoKemKey holding a public key.
• out Buffer to receive the serialized public key.
• len Length of the out buffer in bytes.

See:

• wc_FrodoKemKey_DecodePublicKey
• wc_FrodoKemKey_PublicKeySize

Return:

• 0 on success.
• BAD_FUNC_ARG if key or out is NULL, or len is smaller than the public key size for the key's parameter set.
• BAD_STATE_E if key does not hold a public key.

---

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