src/kem/kem.h

Key encapsulation mechanisms.

The file tests/example_kem.c contains two examples on using the OQS_KEM API.

The first example uses the individual scheme's algorithms directly and uses no dynamic memory allocation – all buffers are allocated on the stack, with sizes indicated using preprocessor macros. Since algorithms can be disabled at compile-time, the programmer should wrap the code in #ifdefs.

The second example uses an OQS_KEM object to use an algorithm specified at runtime. Therefore it uses dynamic memory allocation – all buffers must be malloc'ed by the programmer, with sizes indicated using the corresponding length member of the OQS_KEM object in question. Since algorithms can be disabled at compile-time, the programmer should check that the OQS_KEM object is not NULL.

SPDX-License-Identifier: MIT

Includes

---

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <oqs/oqs.h>

Typedefs

[src] typedef struct OQS_KEM OQS_KEM Key encapsulation mechanism object

Functions

OQS_API const char *	OQS_KEM_alg_identifier(size_t i)
OQS_API int	OQS_KEM_alg_count(void)
OQS_API int	OQS_KEM_alg_is_enabled(const char *method_name)
OQS_API OQS_KEM *	OQS_KEM_new(const char *method_name)
OQS_API OQS_STATUS	OQS_KEM_keypair_derand(const OQS_KEM *kem, uint8_t *public_key, uint8_t *secret_key, const uint8_t *seed)
OQS_API OQS_STATUS	OQS_KEM_keypair(const OQS_KEM *kem, uint8_t *public_key, uint8_t *secret_key)
OQS_API OQS_STATUS	OQS_KEM_encaps(const OQS_KEM *kem, uint8_t *ciphertext, uint8_t *shared_secret, const uint8_t *public_key)
OQS_API OQS_STATUS	OQS_KEM_decaps(const OQS_KEM *kem, uint8_t *shared_secret, const uint8_t *ciphertext, const uint8_t *secret_key)
OQS_API void	OQS_KEM_free(OQS_KEM *kem)

[src]

OQS_KEM_alg_identifier

OQS_API const char * OQS_KEM_alg_identifier(size_t i)

Returns identifiers for available key encapsulation mechanisms in liboqs. Used with OQS_KEM_new.

Note that algorithm identifiers are present in this list even when the algorithm is disabled at compile time.

Parameters

size_t

i

Index of the algorithm identifier to return, 0 <= i < OQS_KEM_algs_length

Returns

Algorithm identifier as a string, or NULL.

[src]

OQS_KEM_alg_count

OQS_API int OQS_KEM_alg_count(void)

Returns the number of key encapsulation mechanisms in liboqs. They can be enumerated with OQS_KEM_alg_identifier.

Note that some mechanisms may be disabled at compile time.

Returns

The number of key encapsulation mechanisms.

[src]

OQS_KEM_alg_is_enabled

OQS_API int OQS_KEM_alg_is_enabled(const char *method_name)

Indicates whether the specified algorithm was enabled at compile-time or not.

Parameters

const char *

method_name

Name of the desired algorithm; one of the names in OQS_KEM_algs.

Returns

1 if enabled, 0 if disabled or not found

[src]

OQS_KEM_new

OQS_API OQS_KEM * OQS_KEM_new(const char *method_name)

Constructs an OQS_KEM object for a particular algorithm.

Callers should always check whether the return value is NULL, which indicates either than an invalid algorithm name was provided, or that the requested algorithm was disabled at compile-time.

Parameters

const char *

method_name

Name of the desired algorithm; one of the names in OQS_KEM_algs.

Returns

An OQS_KEM for the particular algorithm, or NULL if the algorithm has been disabled at compile-time.

[src]

OQS_KEM_keypair_derand

OQS_API OQS_STATUS OQS_KEM_keypair_derand(const OQS_KEM *kem, uint8_t *public_key, uint8_t *secret_key, const uint8_t *seed)

Derandomized keypair generation algorithm.

Caller is responsible for allocating sufficient memory for public_key and secret_key, based on the length_* members in this object or the per-scheme compile-time macros OQS_KEM_*_length_*.

Parameters

const OQS_KEM *	kem	The OQS_KEM object representing the KEM.
uint8_t *	public_key	The public key represented as a byte string.
uint8_t *	secret_key	The secret key represented as a byte string.
const uint8_t *	seed	The input randomness represented as a byte string.

Returns

OQS_SUCCESS or OQS_ERROR

[src]

OQS_KEM_keypair

OQS_API OQS_STATUS OQS_KEM_keypair(const OQS_KEM *kem, uint8_t *public_key, uint8_t *secret_key)

Keypair generation algorithm.

Caller is responsible for allocating sufficient memory for public_key and secret_key, based on the length_* members in this object or the per-scheme compile-time macros OQS_KEM_*_length_*.

Parameters

const OQS_KEM *	kem	The OQS_KEM object representing the KEM.
uint8_t *	public_key	The public key represented as a byte string.
uint8_t *	secret_key	The secret key represented as a byte string.

Returns

OQS_SUCCESS or OQS_ERROR

[src]

OQS_KEM_encaps

OQS_API OQS_STATUS OQS_KEM_encaps(const OQS_KEM *kem, uint8_t *ciphertext, uint8_t *shared_secret, const uint8_t *public_key)

Encapsulation algorithm.

Caller is responsible for allocating sufficient memory for ciphertext and shared_secret, based on the length_* members in this object or the per-scheme compile-time macros OQS_KEM_*_length_*.

Parameters

const OQS_KEM *	kem	The OQS_KEM object representing the KEM.
uint8_t *	ciphertext	The ciphertext (encapsulation) represented as a byte string.
uint8_t *	shared_secret	The shared secret represented as a byte string.
const uint8_t *	public_key	The public key represented as a byte string.

Returns

OQS_SUCCESS or OQS_ERROR

[src]

OQS_KEM_decaps

OQS_API OQS_STATUS OQS_KEM_decaps(const OQS_KEM *kem, uint8_t *shared_secret, const uint8_t *ciphertext, const uint8_t *secret_key)

Decapsulation algorithm.

Caller is responsible for allocating sufficient memory for shared_secret, based on the length_* members in this object or the per-scheme compile-time macros OQS_KEM_*_length_*.

Parameters

const OQS_KEM *	kem	The OQS_KEM object representing the KEM.
uint8_t *	shared_secret	The shared secret represented as a byte string.
const uint8_t *	ciphertext	The ciphertext (encapsulation) represented as a byte string.
const uint8_t *	secret_key	The secret key represented as a byte string.

Returns

OQS_SUCCESS or OQS_ERROR

[src]

OQS_KEM_free

OQS_API void OQS_KEM_free(OQS_KEM *kem)

Frees an OQS_KEM object that was constructed by OQS_KEM_new.

Parameters

OQS_KEM *

kem

The OQS_KEM object to free.

Macros

[src] #define OQS_KEM_alg_bike_l1 "BIKE-L1" Algorithm identifier for BIKE-L1 KEM (Round-4).

[src] #define OQS_KEM_alg_bike_l3 "BIKE-L3" Algorithm identifier for BIKE-L3 KEM (Round-4).

[src] #define OQS_KEM_alg_bike_l5 "BIKE-L5" Algorithm identifier for BIKE-L5 KEM (Round-4).

[src] #define OQS_KEM_alg_classic_mceliece_348864 "Classic-McEliece-348864" Algorithm identifier for Classic-McEliece-348864 KEM.

[src] #define OQS_KEM_alg_classic_mceliece_348864f "Classic-McEliece-348864f" Algorithm identifier for Classic-McEliece-348864f KEM.

[src] #define OQS_KEM_alg_classic_mceliece_460896 "Classic-McEliece-460896" Algorithm identifier for Classic-McEliece-460896 KEM.

[src] #define OQS_KEM_alg_classic_mceliece_460896f "Classic-McEliece-460896f" Algorithm identifier for Classic-McEliece-460896f KEM.

[src] #define OQS_KEM_alg_classic_mceliece_6688128 "Classic-McEliece-6688128" Algorithm identifier for Classic-McEliece-6688128 KEM.

[src] #define OQS_KEM_alg_classic_mceliece_6688128f "Classic-McEliece-6688128f" Algorithm identifier for Classic-McEliece-6688128f KEM.

[src] #define OQS_KEM_alg_classic_mceliece_6960119 "Classic-McEliece-6960119" Algorithm identifier for Classic-McEliece-6960119 KEM.

[src] #define OQS_KEM_alg_classic_mceliece_6960119f "Classic-McEliece-6960119f" Algorithm identifier for Classic-McEliece-6960119f KEM.

[src] #define OQS_KEM_alg_classic_mceliece_8192128 "Classic-McEliece-8192128" Algorithm identifier for Classic-McEliece-8192128 KEM.

[src] #define OQS_KEM_alg_classic_mceliece_8192128f "Classic-McEliece-8192128f" Algorithm identifier for Classic-McEliece-8192128f KEM.

[src] #define OQS_KEM_alg_hqc_128 "HQC-128" Algorithm identifier for HQC-128 KEM.

[src] #define OQS_KEM_alg_hqc_192 "HQC-192" Algorithm identifier for HQC-192 KEM.

[src] #define OQS_KEM_alg_hqc_256 "HQC-256" Algorithm identifier for HQC-256 KEM.

[src] #define OQS_KEM_alg_kyber_512 "Kyber512" Algorithm identifier for Kyber512 KEM.

[src] #define OQS_KEM_alg_kyber_768 "Kyber768" Algorithm identifier for Kyber768 KEM.

[src] #define OQS_KEM_alg_kyber_1024 "Kyber1024" Algorithm identifier for Kyber1024 KEM.

[src] #define OQS_KEM_alg_ml_kem_512 "ML-KEM-512" Algorithm identifier for ML-KEM-512 KEM.

[src] #define OQS_KEM_alg_ml_kem_768 "ML-KEM-768" Algorithm identifier for ML-KEM-768 KEM.

[src] #define OQS_KEM_alg_ml_kem_1024 "ML-KEM-1024" Algorithm identifier for ML-KEM-1024 KEM.

[src] #define OQS_KEM_alg_ntruprime_sntrup761 "sntrup761" Algorithm identifier for sntrup761 KEM.

[src] #define OQS_KEM_alg_frodokem_640_aes "FrodoKEM-640-AES" Algorithm identifier for FrodoKEM-640-AES KEM.

[src] #define OQS_KEM_alg_frodokem_640_shake "FrodoKEM-640-SHAKE" Algorithm identifier for FrodoKEM-640-SHAKE KEM.

[src] #define OQS_KEM_alg_frodokem_976_aes "FrodoKEM-976-AES" Algorithm identifier for FrodoKEM-976-AES KEM.

[src] #define OQS_KEM_alg_frodokem_976_shake "FrodoKEM-976-SHAKE" Algorithm identifier for FrodoKEM-976-SHAKE KEM.

[src] #define OQS_KEM_alg_frodokem_1344_aes "FrodoKEM-1344-AES" Algorithm identifier for FrodoKEM-1344-AES KEM.

[src] #define OQS_KEM_alg_frodokem_1344_shake "FrodoKEM-1344-SHAKE" Algorithm identifier for FrodoKEM-1344-SHAKE KEM.

[src] #define OQS_KEM_algs_length 29 Number of algorithm identifiers above.