PQLR common KEM interface

Typedefs
typedef struct pqlr_kem_st *	pqlr_kem
	PQLR KEM algorithm instance handle. More...

Functions
PQLR_API size_t	pqlr_kem_num_algs (void)
	Obtains the number of available PQLR KEM algorithms. More...
PQLR_API size_t	pqlr_kem_get_algs (const char **algs, size_t count)
	Fills the provided buffer with names of available KEM algorithms. More...
PQLR_API pqlr_kem	pqlr_kem_new (const pqlr_alg alg)
	Creates pqlr_kem instance initialized by alg. More...
PQLR_API void	pqlr_kem_free (pqlr_kem kem)
	Frees pqlr_kem instance and all corresponding resources. More...
PQLR_API pqlr_kem	pqlr_kem_duplicate (const pqlr_kem kem)
	duplicates the context of pqlr_kem algorithm More...
PQLR_API uint32_t	pqlr_kem_get_initiator_public_length (const pqlr_kem kem)
	Obtains initiator's public key length for the current pqlr_kem instance. More...
PQLR_API uint32_t	pqlr_kem_get_initiator_secret_length (const pqlr_kem kem)
	Obtains initiator's secret key length for the current pqlr_kem instance. More...
PQLR_API uint32_t	pqlr_kem_get_ciphertext_length (const pqlr_kem kem)
	Obtains ciphertext (request) length for the current pqlr_kem instance. More...
PQLR_API uint32_t	pqlr_kem_get_shared_secret_length (const pqlr_kem kem)
	Obtains shared secret (key) length for the current pqlr_kem instance. More...
PQLR_API int	pqlr_kem_keygen (const pqlr_kem kem, uint8_t *pk, uint8_t *sk)
	Initial step of key distribution. Generates a key pair for key distribution initiator. More...
PQLR_API int	pqlr_kem_encap (const pqlr_kem kem, const uint8_t *pk, uint8_t *ciphertext, uint8_t *session_key)
	Second step of key distribution. Encapsulates key on the responder side. More...
PQLR_API int	pqlr_kem_decap (const pqlr_kem kem, const uint8_t *sk, const uint8_t *ciphertext, uint8_t *session_key)
	Last step of key distribution. Decapsulates key on the initiator side. More...

Detailed Description

This module provides post-quantum key encapsulation mechanisms (KEM) for secure key distribution between two parties. The distributed secret is theoretically tolerant to attacks from both quantum and classical computers. Entry point is pqlr_kem_keygen

General usage

Key encapsulation mechanisms consist of sequential function calls on two sides named initiator and responder.

1. Both sides call pqlr_kem_new, algorithm context is initialized with chosen parameterset
2. Initiator calls pqlr_kem_keygen, initiator's public and secret keys are generated
3. Initiator sends public key to responder
4. Responder calls pqlr_kem_encap, gets encoded request, key
5. Responder sends request to initiator
6. Initiator calls pqlr_kem_decap, gets key
7. Both sides have similar cryptographically secure key
8. After the KEM is no more needed resources must be freed on both sides by pqlr_kem_free

Note

In client-server applications client can represent initiator side, whereas server represents responder side, or vice versa.

In order to use any SABER key distribution functions, add the following include:

#include <pqlr/common/kem.h>

Example code is listed below:

#include <pqlr/common/kem.h>
#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>
 
void print_key(const char* message, uint8_t* key, uint32_t key_size)
{
    uint8_t i = 0;
    printf("%s", message);
 
    for (; i < key_size; ++i) {
        printf("%.2X", key[i]);
    }
    printf("\n");
}
 
 
int main(int argc, char* argv[])
{
    // algorithm's internal parameters
    // Should be initialized before usage
    pqlr_alg alg = pqlr_alg_new("saber");
 
    // KEM's internal context
    pqlr_kem saber = pqlr_kem_new(alg);
 
    // pqlr_alg object can be freed after initializing pqlr_kem
    pqlr_alg_free(alg);
 
    // server side context
    uint8_t* public_key =
        (uint8_t*)malloc(pqlr_kem_get_initiator_public_length(saber));
    uint8_t* secret_key =
        (uint8_t*)malloc(pqlr_kem_get_initiator_secret_length(saber));
    uint8_t* server_side_key = (uint8_t*)calloc(
        pqlr_kem_get_shared_secret_length(saber), sizeof(uint8_t));
 
    // client side context
    uint8_t* ciphertext =
        (uint8_t*)malloc(pqlr_kem_get_ciphertext_length(saber));
    uint8_t* client_side_key = (uint8_t*)calloc(
        pqlr_kem_get_shared_secret_length(saber), sizeof(uint8_t));
 
    // prepare server's secret and public keys
    pqlr_kem_keygen(saber, public_key, secret_key);
 
    // ... public_key is transferred from server to client by insecure channel
 
    // generate secret key on the client side based on non encoded public_key
    // received from server, also generate non secret reply ciphertext
    // to be sent back to server
    pqlr_kem_encap(saber, public_key, ciphertext, client_side_key);
 
    // ... ciphertext is transferred from client to server by insecure channel
 
    // generate secret key on the server side
    pqlr_kem_decap(saber, secret_key, ciphertext, server_side_key);
 
    // client and server keys will be the same
    print_key(
        "Server side: ", server_side_key,
        pqlr_kem_get_shared_secret_length(saber));
    print_key(
        "Client side: ", client_side_key,
        pqlr_kem_get_shared_secret_length(saber));
 
    // Don't forget to free resources after use
    free(public_key);
    free(secret_key);
    free(server_side_key);
    free(client_side_key);
    free(ciphertext);
 
    pqlr_kem_free(saber);
 
    return 0;
}

Typedef Documentation

pqlr_kem

typedef struct pqlr_kem_st* pqlr_kem

PQLR KEM algorithm instance handle.

Function Documentation

pqlr_kem_decap()

PQLR_API int pqlr_kem_decap	(	const pqlr_kem	kem,
		const uint8_t *	sk,
		const uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Last step of key distribution. Decapsulates key on the initiator side.

Parameters

[in]	kem	pqlr_kem algorithm context. If NULL, the fatal error occurs.
[in]	sk	Secret key buffer ( pqlr_kem_keygen ). Must point to array of uint8_t with elements count at least pqlr_kem_get_initiator_secret_length. If NULL, the fatal error occurs.
[in]	ciphertext	Encoded request from the responder. Must point to array of uint8_t, with elements count at least pqlr_kem_get_ciphertext_length. If NULL, the fatal error occurs.
[out]	session_key	Distributed key, equal to the key to be obtained on the responder side. Must point to array of uint8_t, with elements count at least pqlr_kem_get_shared_secret_length. If NULL, the fatal error occurs.

See also

pqlr_kem_new

pqlr_kem_keygen

pqlr_kem_key_encap

Returns

0 on success or non-zero value on failure

pqlr_kem_duplicate()

PQLR_API pqlr_kem pqlr_kem_duplicate

(

const pqlr_kem

kem

)

duplicates the context of pqlr_kem algorithm

Parameters

[in]

kem

instance to duplicate

See also

pqlr_kem

Returns

new instance with duplicated context

pqlr_kem_encap()

PQLR_API int pqlr_kem_encap	(	const pqlr_kem	kem,
		const uint8_t *	pk,
		uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Second step of key distribution. Encapsulates key on the responder side.

Parameters

[in]	kem	pqlr_kem algorithm context. If NULL, the fatal error occurs.
[in]	pk	Public key buffer ( pqlr_kem_keygen ). Must point to array of uint8_t with elements count at least pqlr_kem_get_initiator_public_length. If NULL, the fatal error occurs.
[out]	ciphertext	Encoded request from the responder. Must point to array of uint8_t, with elements count at least pqlr_kem_get_ciphertext_length. If NULL, the fatal error occurs.
[out]	session_key	Distributed key, equal to the key to be obtained on the initiator side. Must point to array of uint8_t, with elements count at least pqlr_kem_get_shared_secret_length. If NULL, the fatal error occurs.

See also

pqlr_kem_new

pqlr_kem_keygen

pqlr_kem_get_initiator_public_length

pqlr_kem_get_ciphertext_length

pqlr_kem_get_shared_secret_length

pqlr_kem

Returns

0 on success or non-zero value on failure

pqlr_kem_free()

PQLR_API void pqlr_kem_free

(

pqlr_kem

kem

)

Frees pqlr_kem instance and all corresponding resources.

Parameters

[in]

kem

instance to free

See also

pqlr_kem

pqlr_kem_new

pqlr_kem_get_algs()

PQLR_API size_t pqlr_kem_get_algs	(	const char **	algs,
		size_t	count
	)

Fills the provided buffer with names of available KEM algorithms.

Note

If the number of KEM algorithms is more than the array size, then it'll be truncated. Individual strings in the output array must not be freed.

Parameters

[out]	algs	Array of KEM names
[in]	count	Array size

Returns

number of algorithms in the output array.

See also

pqlr_alg

pqlr_alg_new

pqlr_kem_num_algs

pqlr_kem_get_ciphertext_length()

PQLR_API uint32_t pqlr_kem_get_ciphertext_length

(

const pqlr_kem

kem

)

Obtains ciphertext (request) length for the current pqlr_kem instance.

Parameters

[in]

kem

initialized pqlr_kem instance

See also

pqlr_kem

pqlr_kem_new

Returns

ciphertext length

pqlr_kem_get_initiator_public_length()

PQLR_API uint32_t pqlr_kem_get_initiator_public_length

(

const pqlr_kem

kem

)

Obtains initiator's public key length for the current pqlr_kem instance.

Parameters

[in]

kem

initialized pqlr_kem instance

See also

pqlr_kem

pqlr_kem_new

Returns

initiator's public key length

pqlr_kem_get_initiator_secret_length()

PQLR_API uint32_t pqlr_kem_get_initiator_secret_length

(

const pqlr_kem

kem

)

Obtains initiator's secret key length for the current pqlr_kem instance.

Parameters

[in]

kem

initialized pqlr_kem instance

See also

pqlr_kem

pqlr_kem_new

Returns

initiator's secret key length

pqlr_kem_get_shared_secret_length()

PQLR_API uint32_t pqlr_kem_get_shared_secret_length

(

const pqlr_kem

kem

)

Obtains shared secret (key) length for the current pqlr_kem instance.

Parameters

[in]

kem

initialized pqlr_kem instance

See also

pqlr_kem

pqlr_kem_new

Returns

shared secret length

pqlr_kem_keygen()

PQLR_API int pqlr_kem_keygen	(	const pqlr_kem	kem,
		uint8_t *	pk,
		uint8_t *	sk
	)

Initial step of key distribution. Generates a key pair for key distribution initiator.

Note

Called on initiator side.

Parameters

[in]	kem	pqlr_kem algorithm context. If NULL, the fatal error occurs.
[out]	pk	Public key buffer. Must point to array of uint8_t with elements count at least pqlr_kem_get_initiator_public_length. If NULL, the fatal error occurs.
[out]	sk	Secret key buffer. Must point to array of uint8_t with elements count at least pqlr_kem_get_initiator_secret_length. If NULL, the fatal error occurs.

See also

pqlr_kem_new

pqlr_kem_get_initiator_public_length

pqlr_kem_get_initiator_secret_length

pqlr_kem

Returns

0 on success or non-zero value on failure

pqlr_kem_new()

PQLR_API pqlr_kem pqlr_kem_new

(

const pqlr_alg

alg

)

Creates pqlr_kem instance initialized by alg.

Note

Called on both sides.

Parameters

[in]

alg

Initialized PQLR KEM algorithm instance

See also

pqlr_alg_conf

pqlr_kem

pqlr_kem_free

Returns

new pqlr_kem instance or NULL if out of memory

pqlr_kem_num_algs()

PQLR_API size_t pqlr_kem_num_algs

(

void

)

Obtains the number of available PQLR KEM algorithms.

Returns

number of algorithms

See also

pqlr_kem_get_algs

pqlr_alg

pqlr_alg_new