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

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

#include <openssl/sha.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 SHA256_CTX to store the state.
    SHA256_CTX *ctx = NULL;
    ctx = calloc(1, sizeof(*ctx));
    if (ctx == NULL) {
        return IQR_ENOMEM;
    }

    *state = ctx;

    return IQR_OK;
}

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

    SHA256_CTX *ctx = (SHA256_CTX *)state;

    // Let OpenSSL set up its context.
    int rc = SHA256_Init(ctx);
    if (rc != OPENSSL_OK) {
        return IQR_ENOTINIT;
    }

    return IQR_OK;
}

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

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

    // In this case, the state can't be NULL.
    if (state == NULL) {
        return IQR_ENULLPTR;
    }

    SHA256_CTX *ctx = (SHA256_CTX *)state;

    // Pass the buf pointer into the OpenSSL update function.
    int rc = SHA256_Update(ctx, buf, buf_size);
    if (rc != OPENSSL_OK) {
        // Update failed.
        return IQR_EINVOBJECT;
    }

    return IQR_OK;
}

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

    SHA256_CTX *ctx = (SHA256_CTX *)state;

    // Make sure there's enough room to store your digest.
    if (digest_size != IQR_SHA2_256_DIGEST_SIZE) {
        return IQR_EINVBUFSIZE;
    }

    // Pass the digest pointer into the OpenSSL final function.
    int rc = SHA256_Final(digest, ctx);
    if (rc != OPENSSL_OK) {
        return IQR_EINVOBJECT;
    }

    return IQR_OK;
}

static iqr_retval sha2_256_cleanup(void **state)
{
    SHA256_CTX *ctx = (SHA256_CTX *)*state;

    memset_s(ctx, 0, sizeof(*ctx));
    free(ctx);
    *state = NULL;

    return IQR_OK;
}

// 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"

// 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 iqr_retval 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 IQR_OK;
}

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

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

    // In this case, the state can't be NULL.
    if (state == NULL) {
        return IQR_ENULLPTR;
    }

    BCRYPT_HANDLES *handles = (BCRYPT_HANDLES *)state;

    NTSTATUS status = BCryptHashData(handles->hash, (PUCHAR)buf, (ULONG)buf_size, 0);
    if (NT_SUCCESS(status) == false) {
        return IQR_EINVOBJECT;
    }

    return IQR_OK;
}

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

    // Make sure there's enough room to store your digest.
    if (digest_size != IQR_SHA2_256_DIGEST_SIZE) {
        return IQR_EINVBUFSIZE;
    }

    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);
    if (NT_SUCCESS(status) == false) {
        return IQR_EINVOBJECT;
    }

    return IQR_OK;
}

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

    BCRYPT_HANDLES *handles = (BCRYPT_HANDLES *)*state;

    NTSTATUS status = BCryptDestroyHash(handles->hash);
    if (NT_SUCCESS(status) == false) {
        return IQR_EINVOBJECT;
    }

    status = BCryptCloseAlgorithmProvider(handles->alg, 0);
    if (NT_SUCCESS(status) == false) {
        return IQR_EINVOBJECT;
    }

    memset_s(handles, 0, sizeof(*handles));
    free(handles);
    *state = NULL;

    return IQR_OK;
}

// 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_dilithium.h"
#include "iqr_rng.h"
...
// Create an iqr_Context, context.
// Create and initialize a Random Number Generator, rng.
...
// Create Dilithium parameters using one of the variants from iqr_dilithium.h.
iqr_DilithiumParams *params = NULL;
iqr_retval result = iqr_DilithiumCreateParams(context, variant, &params);
if (result != IQR_OK) {
    // Handle error.
}

// Create the key pair.
iqr_DilithiumPublicKey *public_key = NULL;
iqr_DilithiumPrivateKey *private_key = NULL;
result = iqr_DilithiumCreateKeyPair(params, rng, &public_key, &private_key);
if (result != IQR_OK) {
    // Handle error.
}

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

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

result = iqr_DilithiumSign(private_key, digest, digest_size, signature,
    signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
result = iqr_DilithiumVerify(public_key, digest, digest_size, signature,
    signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
size_t public_key_data_size = 0;
result = iqr_DilithiumGetPublicKeySize(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_DilithiumExportPublicKey(public_key, public_key_data,
    public_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

size_t private_key_data_size = 0;
result = iqr_DilithiumGetPrivateKeySize(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_DilithiumExportPrivateKey(private_key, private_key_data,
    private_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

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

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

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

uint8_t seed[32];  // The RNG seed used to create the public key.
uint8_t t1[];  // POLY16 encoded t1 data.

uint8_t c[];
uint8_t z[];
uint8_t h[];

#include "iqr_context.h"
#include "iqr_hash.h"
#include "iqr_hss.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 HSS parameters.
iqr_HSSParams *params = NULL;
iqr_retval result = iqr_HSSCreateParams(context,
    &IQR_HSS_MEMORY_CONSTRAINED_STRATEGY, IQR_HSS_2E15_FAST, &params);
if (result != IQR_OK) {
    // Handle error.
}

// Create the key pair.
iqr_HSSPublicKey *public_key = NULL;
iqr_HSSPrivateKey *private_key = NULL;
iqr_HSSPrivateKeyState *state = NULL;
result = iqr_HSSCreateKeyPair(params, rng, &public_key, &private_key,
    &state);
if (result != IQR_OK) {
    // Handle error.
}

#include "iqr_hss.h"
...
// This assumes you've already got an HSS private key and state, and that
// you've registered a SHA2-256 hash implementation.
...
iqr_HSSPrivateKeyState *new_state = NULL;
iqr_retval result = iqr_HSSDetachState(private_key, original_state,
    num_sigs, &new_state)
if (result != IQR_OK) {
    // Handle error.
}

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

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

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

  You must detach a state to use for signing, and write the remaining state
  to non-volatile memory, before signing. Failure to do so could result in
  a security breach as it could lead to the re-use of a one-time signature.

  This step has been omitted for brevity.

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

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

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

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

...
size_t public_key_data_size = 0;
result = iqr_HSSGetPublicKeySize(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_HSSExportPublicKey(public_key, public_key_data,
    public_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

size_t private_key_data_size = 0;
result = iqr_HSSGetPrivateKeySize(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_HSSExportPrivateKey(private_key, private_key_data,
    private_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

size_t state_size = 0;
result = iqr_HSSGetStateSize(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_HSSExportState(state, state_data, state_size);
if (result != IQR_OK) {
    // Handle error.
}

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

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

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

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

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

// Create the key pair.
iqr_SPHINCSPublicKey *public_key = NULL;
iqr_SPHINCSPrivateKey *private_key = NULL;
result = iqr_SPHINCSCreateKeyPair(params, rng, &public_key, &private_key);
if (result != IQR_OK) {
    // Handle error.
}

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

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

result = iqr_SPHINCSSign(private_key, rng, digest, digest_size,
    signature, signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
result = iqr_SPHINCSVerify(public_key, digest, digest_size, signature,
    signature_size);
if (result != IQR_OK) {
    // Handle error.
}

...
size_t public_key_data_size = 0;
result = iqr_SPHINCSGetPublicKeySize(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_SPHINCSExportPublicKey(public_key, public_key_data,
    public_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

size_t private_key_data_size = 0;
result = iqr_SPHINCSGetPrivateKeySize(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_SPHINCSExportPrivateKey(private_key, private_key_data,
    private_key_data_size);
if (result != IQR_OK) {
    // Handle error.
}

...
// Create an iqr_SPHINCSParams object.
...

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

iqr_SPHINCSPrivateKey *private_key = NULL;
result = iqr_SPHINCSImportPrivateKey(params, private_key_data,
    private_key_data_size, &private_key);
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_XMSSPrivateKeyState *state = NULL;
result = iqr_XMSSCreateKeyPair(params, rng, &public_key, &private_key,
    &state);
if (result != IQR_OK) {
    // Handle error.
}

#include "iqr_xmss.h"
...
// This assumes you've already got an XMSS private key and state, and that
// you've registered a SHA2-256 hash implementation.
...
iqr_XMSSPrivateKeyState *new_state = NULL;
iqr_retval result = iqr_XMSSDetachState(private_key, original_state,
    num_sigs, &new_state)
if (result != IQR_OK) {
    // Handle error.
}

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

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

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

  You must detach a state to use for signing, and write the remaining state
  to non-volatile memory, before signing. Failure to do so could result in
  a security breach as it could lead to the re-use of a one-time signature.

  This step has been omitted for brevity.

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

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

result = iqr_XMSSSign(private_key, message, message_size, 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_XMSSGetStateSize(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_XMSSExportState(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_XMSSPrivateKeyState *state = NULL;
result = iqr_XMSSImportState(params, state_data, state_data_size, &state);
if (result != IQR_OK) {
    // Handle error.
}

#include "iqr_context.h"
#include "iqr_kyber.h"
#include "iqr_rng.h"
...
// Create an iqr_Context, context.
// Create and initialize a Random Number Generator, rng.
...
// The variant can be IQR_KYBER_512, IQR_KYBER_768, or IQR_KYBER_1024.
iqr_KyberParams *params = NULL;
iqr_retval result = iqr_KyberCreateParams(context, variant, &params);
if (result != IQR_OK) {
    // Handle error.
}

iqr_KyberPrivateKey *private_key = NULL;
iqr_KyberPublicKey *public_key = NULL;
result = iqr_KyberCreateKeyPair(params, rng, &public_key, &private_key);
if (result != IQR_OK) {
    // Handle error.
}

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

uint8_t *public_key_buffer = calloc(1, public_key_size);
if (public_key == NULL) {
    // Handle error.
}

result = iqr_KyberExportPublicKey(public_key, public_key_buffer, public_key_size);
if (result != IQR_OK) {
    // Handle error.
}

// The public_key can now be sent to other users.
...

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

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

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

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

result = iqr_KyberEncapsulate(public_key, rng, ciphertext, ciphertext_size,
    shared_key, shared_key_size);
if (result != IQR_OK) {
    // Handle error.
}

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

// Get the ciphertext from the sender.
...

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

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

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

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

result = iqr_KyberDecapsulate(private_key, ciphertext, ciphertext_size,
    shared_key, shared_key_size);
if (result != IQR_OK) {
    // Handle error.
}

#include "iqr_classicmceliece.h"
#include "iqr_context.h"
#include "iqr_rng.h"
...
// Create an iqr_Context, context.
// Create and initialize a Random Number Generator, rng.
...
// The variant can be IQR_CLASSICMCELIECE_6 or IQR_CLASSICMCELIECE_8.
iqr_ClassicMcElieceParams *params = NULL;
iqr_retval result = iqr_ClassicMcElieceCreateParams(context, variant, &params);
if (result != IQR_OK) {
    // Handle error.
}

iqr_ClassicMcEliecePrivateKey *private_key = NULL;
iqr_ClassicMcEliecePublicKey *public_key = NULL;
result = iqr_ClassicMcElieceCreateKeyPair(params, rng, &public_key,
    &private_key);
if (result != IQR_OK) {
    // Handle error.
}

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

uint8_t *public_key_buffer = calloc(1, public_key_size);
if (public_key == NULL) {
    // Handle error.
}

result = iqr_ClassicMcElieceExportPublicKey(public_key, public_key_buffer,
    public_key_size);
if (result != IQR_OK) {
    // Handle error.
}

// The public_key can now be sent to other users.
...

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

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

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

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

result = iqr_ClassicMcElieceEncapsulate(public_key, rng, ciphertext,
    ciphertext_size, shared_key, shared_key_size);
if (result != IQR_OK) {
    // Handle error.
}

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

// Get the ciphertext from the sender.
...

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

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

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

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

result = iqr_ClassicMcElieceDecapsulate(private_key, ciphertext,
    ciphertext_size, shared_key, shared_key_size);
if (result != IQR_OK) {
    // Handle error.
}