ISARA Radiate™ Quantum-Safe Library 4.1 Developer’s Guide

#include "iqr_hash.h"
#include "iqr_retval.h"

#include <assert.h>
#include <openssl/evp.h>

// These OpenSSL APIs return 1 for success.
#define OPENSSL_OK 1

static iqr_retval sha2_256_initialize(void **state)
{
    // Sanity-check input.
    if (state == NULL) {
        return IQR_ENULLPTR;
    }

    if (*state != NULL) {
        return IQR_EINVPTR;
    }

    // Allocate an OpenSSL context to store the state.
    EVP_MD_CTX *ctx = EVP_MD_CTX_new();
    if (ctx == NULL) {
        return IQR_ENOMEM;
    }

    *state = ctx;

    return IQR_OK;
}

static void sha2_256_begin(void *state)
{
    // Sanity-check input.
    assert(state != NULL);

    EVP_MD_CTX *ctx = (EVP_MD_CTX *)state;

    // Let OpenSSL set up its context.
    int rc = EVP_DigestInit(ctx, EVP_sha256());
    assert(rc == OPENSSL_OK);
}

static void sha2_256_update(void *state, const uint8_t *buf, size_t buf_size)
{
    // Sanity-check input.
    assert(state != NULL && buf != NULL && buf_size != 0);

    EVP_MD_CTX *ctx = (EVP_MD_CTX *)state;

    // Pass the buf pointer into the OpenSSL update function.
    int rc = EVP_DigestUpdate(ctx, buf, buf_size);
    assert(rc == OPENSSL_OK);
}

static void sha2_256_end(void *state, uint8_t *digest, size_t digest_size)
{
    // Sanity-check input.
    assert(state != NULL && digest != NULL);

    // Make sure there's enough room to store your digest.
    assert(digest_size == IQR_SHA2_256_DIGEST_SIZE);

    EVP_MD_CTX *ctx = (EVP_MD_CTX *)state;

    // Pass the digest pointer into the OpenSSL final function.
    uint32_t return_size = digest_size;
    int rc = EVP_DigestFinal(ctx, digest, &return_size);
    assert(rc == OPENSSL_OK);
    assert(return_size == digest_size);
}

static void sha2_256_cleanup(void **state)
{
    // Sanity-check input.
    assert(state != NULL);

    EVP_MD_CTX *ctx = (EVP_MD_CTX *)*state;

    EVP_MD_CTX_free(ctx);
    *state = NULL;
}

// Create the callback structure.
static const iqr_HashCallbacks openssl_sha2_256 = {
    .initialize = sha2_256_initialize,
    .begin = sha2_256_begin,
    .update = sha2_256_update,
    .end = sha2_256_end,
    .cleanup = sha2_256_cleanup
};

// Register the OpenSSL implementation.
result = iqr_HashRegisterCallbacks(context, IQR_HASHALGO_SHA2_256,
    &openssl_sha2_256);
if (result != IQR_OK) {
    // Handle error.
}

iqr_Hash *hash = NULL;
iqr_retval result = iqr_HashCreate(context, IQR_HASHALGO_SHA2_256, &hash);
if (result != IQR_OK) {
    // Handle error.
}

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN  // Exclude rarely-used stuff from Windows headers.
#endif

#include <windows.h>
#include <bcrypt.h>
#include <ntstatus.h>

// This used to be in <ntstatus.h>, but was removed in recent versions of the
// Platform SDK.
#ifndef NT_SUCCESS
#define NT_SUCCESS(status) (status >= 0)
#endif

#include "iqr_hash.h"
#include "iqr_retval.h"

#include <assert.h>

// This will be our state.
typedef struct {
    BCRYPT_ALG_HANDLE alg;
    BCRYPT_HASH_HANDLE hash;
} BCRYPT_HANDLES;

static iqr_retval cng_sha2_256_initialize(void **state)
{
    // Sanity-check input.
    if (state == NULL) {
        return IQR_ENULLPTR;
    }

    if (*state != NULL) {
        return IQR_EINVPTR;
    }

    BCRYPT_HANDLES *handles = NULL;

    // Allocate the state that will be passed around.
    handles = calloc(1, sizeof(BCRYPT_HANDLES));
    if (handles == NULL) {
        return IQR_ENOMEM;
    }

    // A reusable hash object will automatically reset for reuse following a
    // call to BCryptFinishHash(). Thus it is not necessary to recreate a
    // hashing handle.
    DWORD flag = BCRYPT_HASH_REUSABLE_FLAG;

    NTSTATUS status = BCryptOpenAlgorithmProvider(&handles->alg,
        BCRYPT_SHA256_ALGORITHM, NULL, flag);
    if (NT_SUCCESS(status) == false) {
        goto cleanup;
    }

    status = BCryptCreateHash(handles->alg, &handles->hash, NULL, 0, NULL, 0,
        flag);
    if (NT_ERROR(status)) {
        goto cleanup;
    }

    // Success! Set the state and exit.
    *state = handles;

    return IQR_OK;

cleanup:
    BCryptCloseAlgorithmProvider(handles->alg, 0);
    free(handles);

    return IQR_ENOTINIT;
}

static void cng_sha2_256_begin(void *state)
{
    // A reusable hash object automatically resets its internal state.
    //
    // By reusing a hash object, this implementation favours speed by
    // utilizing more memory. An alternative implementation could call
    // BCryptCreateHash() here without the use of BCRYPT_HASH_REUSABLE_FLAG.
    return;
}

static void cng_sha2_256_update(void *state, const uint8_t *buf,
    size_t buf_size)
{
    // Sanity-check input.
    assert(state != NULL && buf != NULL && buf_size != 0);

    BCRYPT_HANDLES *handles = (BCRYPT_HANDLES *)state;

    NTSTATUS status = BCryptHashData(handles->hash, (PUCHAR)buf,
        (ULONG)buf_size, 0);
    assert(NT_SUCCESS(status) == true);
}

static void cng_sha2_256_end(void *state, uint8_t *digest, size_t digest_size)
{
    // Sanity-check input.
    assert(state != NULL && digest != NULL);

    // Make sure there's enough room to store your digest.
    assert(digest_size == IQR_SHA2_256_DIGEST_SIZE);

    BCRYPT_HANDLES *handles = (BCRYPT_HANDLES *)state;

    // The hash object automatically resets once this call succeeds.
    NTSTATUS status = BCryptFinishHash(handles->hash, (PUCHAR)digest,
        (ULONG)digest_size, 0);
    assert(NT_SUCCESS(status) == true);
}

static void cng_sha2_256_cleanup(void **state)
{
    // Sanity-check input.
    assert(state != NULL);

    BCRYPT_HANDLES *handles = (BCRYPT_HANDLES *)*state;

    NTSTATUS status = BCryptDestroyHash(handles->hash);
    assert(NT_SUCCESS(status) == true);

    status = BCryptCloseAlgorithmProvider(handles->alg, 0);
    assert(NT_SUCCESS(status) == true);

    memset_s(handles, 0, sizeof(*handles));
    free(handles);

    *state = NULL;
}

// Create the callback structure.
const iqr_HashCallbacks cng_sha2_256 = {
    .initialize = cng_sha2_256_initialize,
    .begin = cng_sha2_256_begin,
    .update = cng_sha2_256_update,
    .end = cng_sha2_256_end,
    .cleanup = cng_sha2_256_cleanup
};

// Register the CNG implementation.
result = iqr_HashRegisterCallbacks(context, IQR_HASHALGO_SHA2_256,
    &cng_sha2_256);
if (result != IQR_OK) {
    // Handle error.
}

iqr_Hash *hash = NULL;
iqr_retval result = iqr_HashCreate(context, IQR_HASHALGO_SHA2_256, &hash);
if (result != IQR_OK) {
    // Handle error.
}

#include <fcntl.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#include "iqr_context.h"
#include "iqr_retval.h"
#include "iqr_rng.h"

static iqr_retval devurandom_initialize(void **state, const uint8_t *seed,
    size_t seed_size)
{
    // Sanity-check inputs.
    if (state == NULL || seed == NULL) {
        return IQR_ENULLPTR;
    }

    if (*state != NULL) {
        return IQR_EINVPTR;
    }

    // The caller must provide seed data.
    if (seed_size == 0) {
        return IQR_EINVBUFSIZE;
    }

    int *device_handle = calloc(1, sizeof(int));
    if (device_handle == NULL) {
        return IQR_ENOMEM;
    }

    iqr_retval result = IQR_OK;

    // Write our seed data to the device.
    *device_handle = open("/dev/random", O_RDWR);
    if (*device_handle == -1) {
        result = IQR_ENOTINIT;
        goto cleanup;
    }

    ssize_t bytes_written = 0;
    while (seed_size > 0) {
        bytes_written = write(*device_handle, seed, seed_size);
        if (bytes_written == -1) {
            result = IQR_EINVOBJECT;
            goto cleanup;
        }
        seed_size -= (size_t)bytes_written;
    }

    // We don't need to allocate state, just store the file descriptor.
    *state = device_handle;
    return result;

cleanup:
    if (*device_handle != -1) {
        close(*device_handle);
    }
    free(device_handle);
    device_handle = NULL;

    return result;
}

static iqr_retval devurandom_reseed(void *state, const uint8_t *entropy,
    size_t entropy_size)
{
    // Sanity-check input.
    if (state == NULL || entropy == NULL) {
        return IQR_ENULLPTR;
    }

    if (entropy_size == 0) {
        return IQR_EINVBUFSIZE;
    }

    // Add the data to your RNG's entropy.
    int *device_handle = state;
    ssize_t bytes_written = 0;
    while (entropy_size > 0) {
        bytes_written = write(*device_handle, entropy, entropy_size);
        if (bytes_written == -1) {
            return IQR_EINVOBJECT;
        }
        entropy += bytes_written;
        entropy_size -= (size_t)bytes_written;
    }

    return IQR_OK;
}

static iqr_retval devurandom_getbytes(void *state, uint8_t *buf,
    size_t buf_size)
{
    // Sanity-check input.
    if (state == NULL || buf == NULL) {
        return IQR_ENULLPTR;
    }

    if (buf_size == 0) {
        return IQR_EINVBUFSIZE;
    }

    // Generate random bytes and write them into the buffer.
    int *device_handle = state;
    ssize_t bytes_read = 0;
    while (buf_size > 0) {
        bytes_read = read(*device_handle, buf, buf_size);
        if (bytes_read == -1) {
            return IQR_EINVDATA;
        }
        buf += bytes_read;
        buf_size -= (size_t)bytes_read;
    }

    return IQR_OK;
}

static iqr_retval devurandom_cleanup(void **state)
{
    // Sanity-check input.
    if (state == NULL) {
        return IQR_ENULLPTR;
    }

    // Clean up and deallocate any state you allocated.
    int *device_handle = *state;
    close(*device_handle);
    free(device_handle);
    *state = NULL;

    return IQR_OK;
}

// Create the callback structure.
static const iqr_RNGCallbacks devurandom_rng = {
    .initialize = devurandom_initialize,
    .reseed = devurandom_reseed,
    .getbytes = devurandom_getbytes,
    .cleanup = devurandom_cleanup
};

iqr_RNG *rng = NULL;
iqr_retval result = iqr_RNGCreate(context, &devurandom_rng, &rng);
if (result != IQR_OK) {
    // Handle error.
}

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN  // Exclude rarely-used stuff from Windows headers.
#endif

#include <windows.h>
#include <bcrypt.h>
#include <ntstatus.h>

#include <stdbool.h>
#include <stdio.h>

// This may not exist in <ntstatus.h>
#ifndef NT_SUCCESS
#define NT_SUCCESS(status) (status >= 0)
#endif

#include "iqr_context.h"
#include "iqr_retval.h"
#include "iqr_rng.h"

static iqr_retval cng_rng_initialize(void **state, const uint8_t *seed,
    size_t seed_size)
{
    (void)seed;  // Unused by Windows CNG.
    (void)seed_size;

    // Sanity-check inputs.
    if (state == NULL) {
        return IQR_ENULLPTR;
    }

    if (*state != NULL) {
        return IQR_EINVPTR;
    }

    BCRYPT_ALG_HANDLE alg = NULL;

    // Open a handle to the CNG.
    NTSTATUS status = BCryptOpenAlgorithmProvider(&alg, BCRYPT_RNG_ALGORITHM,
        NULL, 0);
    if (NT_SUCCESS(status) == false) {
        return IQR_ENOTINIT;
    }

    *state = alg;
    return IQR_OK;
}

static iqr_retval cng_rng_reseed(void *state, const uint8_t *entropy,
    size_t entropy_size)
{
    (void)state;  // Unused variables.
    (void)entropy;
    (void)entropy_size;

    // The CNG random number generator will never need reseeding.
    return IQR_OK;
}

static iqr_retval cng_rng_getbytes(void *state, uint8_t *buf, size_t buf_size)
{
    // Sanity-check input.
    if (state == NULL || buf == NULL) {
        return IQR_ENULLPTR;
    }

    if (buf_size == 0) {
        return IQR_EINVBUFSIZE;
    }

    BCRYPT_ALG_HANDLE alg = (BCRYPT_ALG_HANDLE)state;

    // Generate requested random bytes.
    NTSTATUS status = BCryptGenRandom(alg, (PUCHAR)buf, (ULONG)buf_size, 0);
    if (NT_SUCCESS(status) == false) {
        return IQR_EINVOBJECT;
    }

    return IQR_OK;
}

static iqr_retval cng_rng_cleanup(void **state)
{
    // Sanity-check input.
    if (state == NULL) {
        return IQR_ENULLPTR;
    }

    BCRYPT_ALG_HANDLE alg = (BCRYPT_ALG_HANDLE)*state;

    // Close the provider handle.
    NTSTATUS status = BCryptCloseAlgorithmProvider(alg, 0);
    if (NT_SUCCESS(status) == false) {
        return IQR_EINVOBJECT;
    }

    *state = NULL;
    return IQR_OK;
}

// Create the callback structure.
static const iqr_RNGCallbacks cng_rng = {
    .initialize = cng_rng_initialize,
    .reseed = cng_rng_reseed,
    .getbytes = cng_rng_getbytes,
    .cleanup = cng_rng_cleanup
};

iqr_RNG *rng = NULL;
iqr_retval result = iqr_RNGCreate(context, &cng_rng, &rng);
if (result != IQR_OK) {
    // Handle error.
}

#include "iqr_context.h"
#include "iqr_mldsa.h"
#include "iqr_rng.h"
...
// Create an iqr_Context, context.
// Create and initialize a Random Number Generator, rng.
...
// Create ML-DSA parameters using one of the variants from iqr_mldsa.h.
iqr_MLDSA_Params *params = NULL;
iqr_retval result = iqr_MLDSA_CreateParams(context, variant, &params);
if (result != IQR_OK) {
    // Handle error.
}

// Create the key pair.
iqr_MLDSA_PublicKey *public_key = NULL;
iqr_MLDSA_PrivateKey *private_key = NULL;
uint8_t seed_buf[IQR_MLDSA_SEED_SIZE] = { 0 };
result = iqr_MLDSA_KeyGen(params, rng, &public_key, &private_key, seed_buf,
    sizeof(seed_buf));
if (result != IQR_OK) {
    // Handle error.
}

...
size_t signature_size = 0;
result = iqr_MLDSA_GetSignatureSize(params, &signature_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *signature = calloc(1, signature_size);
if (signature == NULL) {
    // Handle error.
}

bool is_deterministic = false;
const uint8_t ctx[] = "context string";
result = iqr_MLDSA_Sign(private_key, rng, is_deterministic, ctx, sizeof(ctx),
    message, message_size, signature, signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
result = iqr_MLDSA_Verify(public_key, ctx, sizeof(ctx), message,
    message_size, signature, signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
size_t signature_size = 0;
result = iqr_MLDSA_GetSignatureSize(params, &signature_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *signature = calloc(1, signature_size);
if (signature == NULL) {
    // Handle error.
}

iqr_HashAlgorithmType hash_algo = IQR_HASHALGO_SHA2_256;
bool is_deterministic = false;
const uint8_t ctx[] = "context string";
result = iqr_HashMLDSA_Sign(private_key, hash_algo, rng, is_deterministic,
    ctx, sizeof(ctx), message, message_size, signature, signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
result = iqr_HashMLDSA_Verify(public_key, hash_algo, ctx, sizeof(ctx),
    message, message_size, signature, signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
size_t public_key_data_size = 0;
result = iqr_MLDSA_GetPublicKeySize(params, &public_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *public_key_data = calloc(1, public_key_data_size);
if (public_key_data == NULL) {
    // Handle error.
}

result = iqr_MLDSA_GetPublicKeySize(public_key, public_key_data,
    public_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

size_t private_key_data_size = 0;
result = iqr_MLDSA_GetPrivateKeySize(params, &private_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *private_key_data = calloc(1, private_key_data_size);
if (private_key_data == NULL) {
    // Handle error.
}

result = iqr_MLDSA_ExportPrivateKey(private_key, private_key_data,
    private_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

...
// Create an iqr_MLDSA_Params object using the same variant that was used to
// create the keys.
...

iqr_MLDSA_PrivateKey *private_key = NULL;
result = iqr_MLDSA_ImportPrivateKey(params, private_key_data,
    private_key_data_size, &private_key);
if (result != IQR_OK) {
    // Handle error.
}

iqr_MLDSA_PublicKey *public_key = NULL;
result = iqr_MLDSA_ImportPublicKey(params, public_key_data,
    public_key_data_size, &public_key);
if (result != IQR_OK) {
    // Handle error.
}

// If you have the "seed" output from `iqr_MLDSA_KeyGen()`, you can also use
// it to recreate the key pair.
result = iqr_MLDSA_ImportKeyPairFromSeed(params, seed_buf, sizeof(seed_buf),
    &public_key, &private_key);
if (result != IQR_OK) {
    // Handle error.
}

#include "iqr_context.h"
#include "iqr_hash.h"
#include "iqr_lms.h"
#include "iqr_rng.h"
...
// Create an iqr_Context, context.
// Register a SHA2-256 hash algorithm.
// Create and initialize a Random Number Generator, rng.
...
// Create LMS parameters.
iqr_LMSParams *params = NULL;
iqr_retval result = iqr_LMSCreateParams(context,
    &IQR_LMS_FULL_TREE_STRATEGY, IQR_LMS_2E15_FAST, &params);
if (result != IQR_OK) {
    // Handle error.
}

// Create the key pair.
iqr_LMSPublicKey *public_key = NULL;
iqr_LMSPrivateKey *private_key = NULL;
iqr_LMSStorageState *storage_state = NULL;
result = iqr_LMSCreateKeyPair(params, rng, &public_key, &private_key,
    &storage_state);
if (result != IQR_OK) {
    // Handle error.
}

...
iqr_LMSSigningState *signing_state = NULL;
bool storage_state_depleted = false;
result = iqr_LMSCreateSigningState(private_key, storage_state, 1,
    &signing_state, &storage_state_depleted);
if (result != IQR_OK) {
    // Handle error.
}

/*********************** CRITICALLY IMPORTANT STEP *************************

  You must save the storage state to non-volatile memory before using the
  newly created signing state. Failure to do so could result in a security
  breach as it could lead to the re-use of a one-time signature.

  For more information about this property of the LMS state, please refer
  to the LMS specification.

 **************************************************************************/

size_t export_state_size = 0;
result = iqr_LMSGetStorageStateSize(params, &export_state_size);
if (result != IQR_OK) {
    // Handle error.
}

if (storage_state_depleted == true) {
    /* Remove the state file from non-volatile storage. */
    ...

    /* Remember, do not skip the wipe step and "cheat". If the state isn't
     * properly wiped there is a risk of undermining your security.
     */
    result = iqr_LMSConfirmStorageStateWiped(storage_state, signing_state);
    if (result != IQR_OK) {
        // Handle error.
    }
} else {
    uint8_t *export_state = calloc(1, export_state_size);
    if (export_state == NULL) {
        // Handle error.
    }

    result = iqr_LMSExportStorageState(storage_state, export_state,
        export_state_size);
    if (result != IQR_OK) {
        // Handle error.
    }

    /* Save the updated state. */
    ...

    /* Remember, do not skip the save step and "cheat". If the state isn't
     * properly saved there is a risk of undermining your security.
     */
    result = iqr_LMSConfirmStorageStateCommitted(storage_state, signing_state);
    if (result != IQR_OK) {
        // Handle error.
    }
}

/* Determine the size of the resulting signature and allocate memory. */
result = iqr_LMSGetSignatureSize(params, &signature_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *signature = calloc(1, signature_size);
if (signature == NULL) {
    // Handle error.
}

result = iqr_LMSSign(private_key, message, message_size,
    signing_state, signature, signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
result = iqr_LMSVerify(public_key, message, message_size, signature,
    signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
size_t public_key_data_size = 0;
result = iqr_LMSGetPublicKeySize(params, &public_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *public_key_data = calloc(1, public_key_data_size);
if (public_key_data == NULL) {
    // Handle error.
}

result = iqr_LMSExportPublicKey(public_key, public_key_data,
    public_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

size_t private_key_data_size = 0;
result = iqr_LMSGetPrivateKeySize(params, &private_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *private_key_data = calloc(1, private_key_data_size);
if (private_key_data == NULL) {
    // Handle error.
}

result = iqr_LMSExportPrivateKey(private_key, private_key_data,
    private_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

size_t state_size = 0;
result = iqr_LMSGetStorageStateSize(params, &state_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *state_data = calloc(1, state_size);
if (state_data == NULL) {
    // Handle error.
}

result = iqr_LMSExportStorageState(state, state_data, state_size);
if (result != IQR_OK) {
    // Handle error.
}

...
// Create an iqr_LMSParams object using the same parameters that were used
// to create the keys.
...

iqr_LMSPublicKey *public_key = NULL;
result = iqr_LMSImportPublicKey(params, public_key_data, public_key_data_size,
    &public_key);
if (result != IQR_OK) {
    // Handle error.
}

iqr_LMSPrivateKey *private_key = NULL;
result = iqr_LMSImportPrivateKey(params, private_key_data,
    private_key_data_size, &private_key);
if (result != IQR_OK) {
    // Handle error.
}

iqr_LMSPrivateKeyState *state = NULL;
result = iqr_LMSImportStorageState(params, state_data, state_data_size, &state);
if (result != IQR_OK) {
    // Handle error.
}

#include "iqr_context.h"
#include "iqr_hash.h"
#include "iqr_rng.h"
#include "iqr_xmss.h"
...
// Create an iqr_Context, context.
// Register a SHA2-256 hash algorithm.
// Create and initialize a Random Number Generator, rng.
...
// Create XMSS parameters.
iqr_XMSSParams *params = NULL;
iqr_retval result = iqr_XMSSCreateParams(context, &IQR_XMSS_FULL_TREE_STRATEGY,
    variant, &params);
if (result != IQR_OK) {
    // Handle error.
}

// Create the key pair.
iqr_XMSSPublicKey *public_key = NULL;
iqr_XMSSPrivateKey *private_key = NULL;
iqr_XMSSStorageState *storage_state = NULL;
result = iqr_XMSSCreateKeyPair(params, rng, &public_key, &private_key,
    &storage_state);
if (result != IQR_OK) {
    // Handle error.
}

...
iqr_XMSSSigningState *signing_state = NULL;
bool storage_state_depleted = false;

result = iqr_XMSSCreateSigningState(private_key, storage_state, 1,
    &signing_state, &storage_state_depleted);
if (result != IQR_OK) {
    // Handle error.
}

/*********************** CRITICALLY IMPORTANT STEP *************************

  You must save the storage state to non-volatile memory before using the
  newly created signing state. Failure to do so could result in a security
  breach as it could lead to the re-use of a one-time signature.

  For more information about this property of the XMSS state, please refer
  to the XMSS specification.

 **************************************************************************/

if (storage_state_depleted == true) {
    /* Remove the state from non-volatile storage. */
    ...

    /* Remember, do not skip the wipe step and "cheat". If the state isn't
     * properly wiped there is a risk of undermining your security.
     */
    result = iqr_XMSSConfirmStorageStateWiped(storage_state, signing_state);
    if (result != IQR_OK) {
        // Handle error.
    }
} else {
    size_t export_state_size = 0;
    result = iqr_XMSSGetStorageStateSize(params, &export_state_size);
    if (result != IQR_OK) {
        // Handle error.
    }

    uint8_t *export_state = calloc(1, export_state_size);
    if (export_state == NULL) {
        // Handle error.
    }

    result = iqr_XMSSExportStorageState(storage_state, export_state,
        export_state_size);
    if (result != IQR_OK) {
        // Handle error.
    }

    /* Save the updated state. */
    ...

    /* Remember, do not skip the save step and "cheat". If the state isn't
     * properly saved there is a risk of undermining your security.
     */
    result = iqr_XMSSConfirmStorageStateCommitted(storage_state, signing_state);
    if (result != IQR_OK) {
        // Handle error.
    }
}

/* Determine the size of the resulting signature and allocate memory. */
result = iqr_XMSSGetSignatureSize(params, &signature_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *signature = calloc(1, sig_size);
if (signature == NULL) {
    // Handle error.
}

result = iqr_XMSSSign(priv, message, message_size, signing_state,
    signature, signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
result = iqr_XMSSVerify(public_key, message, message_size, signature,
    signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
size_t public_key_data_size = 0;
result = iqr_XMSSGetPublicKeySize(params, &public_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *public_key_data = calloc(1, public_key_data_size);
if (public_key_data == NULL) {
    // Handle error.
}

result = iqr_XMSSExportPublicKey(public_key, public_key_data,
    public_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

size_t private_key_data_size = 0;
result = iqr_XMSSGetPrivateKeySize(params, &private_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *private_key_data = calloc(1, private_key_data_size);
if (private_key_data == NULL) {
    // Handle error.
}

result = iqr_XMSSExportPrivateKey(private_key, private_key_data,
    private_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

size_t state_size = 0;
result = iqr_XMSSGetStorageStateSize(params, &state_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *state_data = calloc(1, state_size);
if (state_data == NULL) {
    // Handle error.
}

result = iqr_XMSSExportStorageState(state, state_data, state_size);
if (result != IQR_OK) {
    // Handle error.
}

...
// Create an iqr_XMSSParams object using the same parameters that were used
// to create the keys.
...

iqr_XMSSPublicKey *public_key = NULL;
result = iqr_XMSSImportPublicKey(params, public_key_data, public_key_data_size,
    &public_key);
if (result != IQR_OK) {
    // Handle error.
}

iqr_XMSSPrivateKey *private_key = NULL;
result = iqr_XMSSImportPrivateKey(params, private_key_data,
    private_key_data_size, &private_key);
if (result != IQR_OK) {
    // Handle error.
}

iqr_XMSSStorageState *state = NULL;
result = iqr_XMSSImportStorageState(params, state_data, state_data_size,
    &state);
if (result != IQR_OK) {
    // Handle error.
}

iqr_retval iqr_MLKEM_KeyGen(
    const iqr_MLKEM_Params *params,
    const iqr_RNG *rng,
    iqr_MLKEM_EncapKey **encap_key,
    iqr_MLKEM_DecapKey **decap_key,
    uint8_t *seed_buf, size_t seed_buf_size);

#include "iqr_context.h"
#include "iqr_mlkem.h"
...
// Create an iqr_Context, context.
// Create and initialize a Random Number Generator, rng.
// See 'iqr_mlkem.h' for rng security requirement.
...

// The variant can be IQR_MLKEM_512, IQR_MLKEM_768, or IQR_MLKEM_1024.
iqr_MLKEM_Params *params = NULL;
iqr_retval result = iqr_MLKEM_CreateParams(context, variant, &params);
if (result != IQR_OK) {
    // Handle error.
}

iqr_MLKEM_EncapKey *encap_key = NULL;
iqr_MLKEM_DecapKey *decap_key = NULL;
result = iqr_MLKEM_KeyGen(params, rng, &encap_key, &decap_key, NULL, 0);
if (result != IQR_OK) {
    // Handle error.
}

// The generated encapsulation and decapsulation keys can now be used for
// encapsulation and decapsulation operations.

// Export the encapsulation key to a byte buffer in FIPS-203 compliant
// format.
size_t encap_key_size = 0;
result = iqr_MLKEM_GetEncapKeySize(params, &encap_key_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *encap_key_buffer = calloc(1, encap_key_size);
if (encap_key_buffer == NULL) {
    // Handle error.
}

result = iqr_MLKEM_ExportEncapKey(encap_key, encap_key_buffer,
    encap_key_size);
if (result != IQR_OK) {
    // Handle error.
}

result = iqr_MLKEM_DestroyEncapKey(&encap_key);
if (result != IQR_OK) {
    // Handle error.
}

// The exported encapsulation key stored in encap_key_buffer can now be sent
// to other peers.

// Import an encapsulation key to be used for the encapsulation operation.
iqr_MLKEM_EncapKey *imported_encap_key = NULL;
result = iqr_MLKEM_ImportEncapKey(params, encap_key_buffer, encap_key_size,
    &imported_encap_key);
if (result != IQR_OK) {
    // Handle error.
}

// Similar key export and import operations can be performed on the
// decapsulation key as well. See 'iqr_mlkem.h' for more information on
// key utility functions.
...

iqr_retval iqr_MLKEM_Encapsulate(
    const iqr_MLKEM_EncapKey *encap_key,
    const iqr_RNG *rng,
    uint8_t *shared_secret_key, size_t shared_secret_key_size,
    uint8_t *ciphertext, size_t ciphertext_size);

#include "iqr_mlkem.h"
...
// Create and initialize a Random Number Generator, rng.
// See 'iqr_mlkem.h' for rng security requirement.
...

// Generate a shared secret key and encapsulate it into a ciphertext.
uint8_t *shared_secret_key = calloc(1, IQR_MLKEM_SHARED_SECRET_KEY_SIZE);
if (shared_secret_key == NULL) {
    // Handle error.
}

size_t ciphertext_size = 0;
result = iqr_MLKEM_GetCiphertextSize(params, &ciphertext_size);
if (result != IQR_OK) {
    // Handle error.
}

uint8_t *ciphertext = calloc(1, ciphertext_size);
if (ciphertext == NULL) {
    // Handle error.
}

result = iqr_MLKEM_Encapsulate(encap_key, rng, shared_secret_key,
    IQR_MLKEM_SHARED_SECRET_KEY_SIZE, ciphertext, ciphertext_size);
if (result != IQR_OK) {
    // Handle error.
}

// The ciphertext can now be sent to the peer.
...

iqr_retval iqr_MLKEM_Decapsulate(
    const iqr_MLKEM_DecapKey *decap_key,
    const uint8_t *ciphertext, size_t ciphertext_size,
    uint8_t *shared_secret_key, size_t shared_secret_key_size);

#include "iqr_mlkem.h"
...
// Get the ciphertext from the peer.
...

size_t ciphertext_size = 0;
result = iqr_MLKEM_GetCiphertextSize(params, &ciphertext_size);
if (result != IQR_OK) {
    // Handle error.
}

if (ciphertext_size != received_ciphertext_size) {
    // Handle error.
}

uint8_t *shared_secret_key = calloc(1, IQR_MLKEM_SHARED_SECRET_KEY_SIZE);
if (shared_secret_key == NULL) {
    // Handle error.
}

result = iqr_MLKEM_Decapsulate(private_key, ciphertext, ciphertext_size,
    shared_secret_key, IQR_MLKEM_SHARED_SECRET_KEY_SIZE);
if (result != IQR_OK) {
    // Handle error.
}
...