Kyber key distribution

Typedefs
typedef struct kyber_st *	kyber_t
	Kyber algorithm instance handle. More...

Enumerations
enum	kyber_parameterset_t { kyber512 , kyber768 , kyber1024 , kyber_last }
	Possible kyber parameters sets. More...

Functions
PQLR_API kyber_t	kyber_new (kyber_parameterset_t parameterset)
	Creates kyber instance initialized by parameterset. More...
PQLR_API void	kyber_free (kyber_t kyber)
	Frees kyber instance and all corresponding resources. More...
PQLR_API uint32_t	kyber_get_initiator_public_length (kyber_t kyber)
	Obtains initiator's public key length for the current kyber instance. More...
PQLR_API uint32_t	kyber_get_initiator_secret_length (kyber_t kyber)
	Obtains initiator's secret key length for the current kyber instance. More...
PQLR_API uint32_t	kyber_get_ciphertext_length (kyber_t kyber)
	Obtains ciphertext length for the current kyber instance. More...
PQLR_API uint32_t	kyber_get_shared_secret_length (kyber_t kyber)
	Obtains shared secret length for the current kyber instance. More...
PQLR_API pqlr_t	kyber_to_pqlr (kyber_t kyber)
	Gets pqlr instance linked to this kyber instance. More...
PQLR_API kyber_t	kyber_duplicate (const kyber_t kyber)
	Duplicates context of kyber instance. More...
PQLR_API void	kyber_keygen (const kyber_t kyber, uint8_t *public_key, uint8_t *secret_key)
	Initial step of key distribution. Generates a key pair for key distribution initiator. More...
PQLR_API void	kyber_key_encap (const kyber_t kyber, const uint8_t *public_key, uint8_t *ciphertext, uint8_t *session_key)
	Key encapsulation. More...
PQLR_API void	kyber_key_decap (const kyber_t kyber, const uint8_t *secret_key, const uint8_t *ciphertext, uint8_t *session_key)
	Key decapsulation. More...

Detailed Description

This module provides Kyber algorithm implementation, which is finite state machine for secure distribution of secret between two counterparties. The distributed secret is theoretically tolerant to attacks performed by quantum computers. Entry point is kyber_keygen

General usage

Key distribution algorithm consists of sequential function calls on two sides: initiator (e.g. server side) and responder (e.g. client side).

1. Both sides call kyber_new
2. Initiator calls kyber_keygen, gets public key.
3. Initiator sends public key to responder.
4. Responder calls kyber_key_encap, gets ciphertext and session key.
5. Responder sends ciphertext to initiator by insecure channel.
6. Initiator calls kyber_key_decap, gets session key.
7. Both sides have similar cryptographically secure session key
8. If no more key distribution required resources must be made free on both side by kyber_free

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

#include <pqlr/kyber/kyber.h>

Example code is listed below:

#include <pqlr/kyber/kyber.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.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[])
{
    // kyber internal context and parameters
    // Context should be initialized before usage
    kyber_t kyber = kyber_new(kyber512);
 
    // server side context
    uint8_t* public_key =
        (uint8_t*)malloc(kyber_get_initiator_public_length(kyber));
    uint8_t* secret_key =
        (uint8_t*)malloc(kyber_get_initiator_secret_length(kyber));
    uint8_t* server_side_key = (uint8_t*)calloc(
        kyber_get_shared_secret_length(kyber), sizeof(uint8_t));
 
    // client side context
    uint8_t* ciphertext = (uint8_t*)malloc(kyber_get_ciphertext_length(kyber));
    uint8_t* client_side_key = (uint8_t*)calloc(
        kyber_get_shared_secret_length(kyber), sizeof(uint8_t));
 
    // prepare server's secret and public keys
    kyber_keygen(kyber, 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
    kyber_key_encap(kyber, public_key, ciphertext, client_side_key);
 
    // ... ciphertext is transferred from client to server by insecure channel
 
    // generate secret key on the server side
    kyber_key_decap(kyber, secret_key, ciphertext, server_side_key);
 
    // client and server keys will be the same
    print_key(
        "Server side: ", server_side_key,
        kyber_get_shared_secret_length(kyber));
    print_key(
        "Client side: ", client_side_key,
        kyber_get_shared_secret_length(kyber));
 
    // Don't forget to free resources after use
    free(public_key);
    free(secret_key);
    free(server_side_key);
    free(client_side_key);
    free(ciphertext);
 
    kyber_free(kyber);
 
    return 0;
}

Typedef Documentation

kyber_t

typedef struct kyber_st* kyber_t

Kyber algorithm instance handle.

Note

pqlr_t instance linked to this handle can be obtained

See also

kyber_to_pqlr

Enumeration Type Documentation

kyber_parameterset_t

enum kyber_parameterset_t

Possible kyber parameters sets.

Enumerator
kyber512
kyber768
kyber1024
kyber_last

Function Documentation

kyber_duplicate()

PQLR_API kyber_t kyber_duplicate

(

const kyber_t

kyber

)

Duplicates context of kyber instance.

Parameters

kyber

instance to duplicate

Returns

new instance with a duplicated context

kyber_free()

PQLR_API void kyber_free

(

kyber_t

kyber

)

Frees kyber instance and all corresponding resources.

Parameters

kyber

instance to free

See also

kyber_t

kyber_new

kyber_get_ciphertext_length()

PQLR_API uint32_t kyber_get_ciphertext_length

(

kyber_t

kyber

)

Obtains ciphertext length for the current kyber instance.

Parameters

kyber

initialized kyber instance

See also

kyber_t

kyber_new

Returns

ciphertext length

kyber_get_initiator_public_length()

PQLR_API uint32_t kyber_get_initiator_public_length

(

kyber_t

kyber

)

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

Parameters

kyber

initialized kyber instance

See also

kyber_t

kyber_new

Returns

initiator's public key length

kyber_get_initiator_secret_length()

PQLR_API uint32_t kyber_get_initiator_secret_length

(

kyber_t

kyber

)

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

Parameters

kyber

initialized kyber instance

See also

kyber_t

kyber_new

Returns

initiator's secret key length

kyber_get_shared_secret_length()

PQLR_API uint32_t kyber_get_shared_secret_length

(

kyber_t

kyber

)

Obtains shared secret length for the current kyber instance.

Parameters

kyber

initialized kyber instance

See also

kyber_t

kyber_new

Returns

shared secret length

kyber_key_decap()

PQLR_API void kyber_key_decap	(	const kyber_t	kyber,
		const uint8_t *	secret_key,
		const uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Key decapsulation.

Parameters

	kyber	Kyber algorithm context. If NULL, the fatal error occurs.
	secret_key	Secret key buffer. Must point to array of uint8_t with elements count at least kyber_get_initiator_secret_length. If NULL, the fatal error occurs. (kyber_keygen)
	ciphertext	Ciphertext buffer. Must point to array of uint8_t with elements count at least kyber_get_ciphertext_length. If NULL, the fatal error occurs
[out]	session_key	Session key buffer. Must point to array of uint8_t with elements count at least kyber_get_shared_secret_length. If NULL, the fatal error occurs.

See also

kyber_new

kyber_keygen

kyber_key_encap

kyber_key_encap()

PQLR_API void kyber_key_encap	(	const kyber_t	kyber,
		const uint8_t *	public_key,
		uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Key encapsulation.

Note

Called on initiator side.

Parameters

	kyber	Kyber algorithm context. If NULL, the fatal error occurs.
	public_key	Public key buffer. Must point to array of uint8_t with elements count at least kyber_get_initiator_public_length. If NULL, the fatal error occurs.
[out]	ciphertext	Ciphertext buffer. Must point to array of uint8_t with elements count at least kyber_get_ciphertext_length. If NULL, the fatal error occurs.
[out]	session_key	Session key buffer. Must point to array of uint8_t with elements count at least kyber_get_shared_secret_length. If NULL, the fatal error occurs.

See also

kyber_new

kyber_keygen

kyber_keygen()

PQLR_API void kyber_keygen	(	const kyber_t	kyber,
		uint8_t *	public_key,
		uint8_t *	secret_key
	)

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

Note

Called on initiator side.

Parameters

	kyber	Kyber algorithm context. If NULL, the fatal error occurs.
[out]	public_key	Public key buffer. Must point to array of uint8_t with elements count at least kyber_get_initiator_public_length. If NULL, the fatal error occurs.
[out]	secret_key	Secret key buffer. Must point to array of uint8_t with elements count at least kyber_get_initiator_secret_length. If NULL, the fatal error occurs.

See also

kyber_new

kyber_new()

PQLR_API kyber_t kyber_new

(

kyber_parameterset_t

parameterset

)

Creates kyber instance initialized by parameterset.

Note

Called on both sides.

Parameters

parameterset

Kyber configuration parameters set (see kyber_parameterset_t for availible options).

See also

kyber_parameterset_t

kyber_t

kyber_free

Returns

new kyber instance or NULL if out of memory

kyber_to_pqlr()

PQLR_API pqlr_t kyber_to_pqlr

(

kyber_t

kyber

)

Gets pqlr instance linked to this kyber instance.

Parameters

kyber

initialized kyber instance

Note

this call leaves kyber instance intact
the returned pqlr instance will be released on call to kyber_free()

See also

kyber_t

pqlr_t

kyber_free

Returns

operable pqlr instance or NULL if kyber is NULL