ML-KEM key distribution

Typedefs
typedef struct ml_kem_st *	ml_kem_t
	ML-KEM algorithm instance handle. More...

Enumerations
enum	ml_kem_parameterset_t { ml_kem_512 , ml_kem_768 , ml_kem_1024 , ml_kem_last }
	Possible ML-KEM parameters sets. More...

Functions
PQLR_API ml_kem_t	ml_kem_new (ml_kem_parameterset_t parameterset)
	Creates ML-KEM instance initialized by parameterset. More...
PQLR_API void	ml_kem_free (ml_kem_t ml_kem)
	Frees ML-KEM instance and all corresponding resources. More...
PQLR_API uint32_t	ml_kem_get_initiator_public_length (ml_kem_t ml_kem)
	Obtains initiator's public key length for the current ML-KEM instance. More...
PQLR_API uint32_t	ml_kem_get_initiator_secret_length (ml_kem_t ml_kem)
	Obtains initiator's secret key length for the current ML-KEM instance. More...
PQLR_API uint32_t	ml_kem_get_ciphertext_length (ml_kem_t ml_kem)
	Obtains ciphertext length for the current ML-KEM instance. More...
PQLR_API uint32_t	ml_kem_get_shared_secret_length (ml_kem_t ml_kem)
	Obtains shared secret length for the current ML-KEM instance. More...
PQLR_API pqlr_t	ml_kem_to_pqlr (ml_kem_t ml_kem)
	Gets pqlr instance linked to this ML-KEM instance. More...
PQLR_API ml_kem_t	ml_kem_duplicate (const ml_kem_t ml_kem)
	Duplicates context of ML-KEM instance. More...
PQLR_API void	ml_kem_keygen (const ml_kem_t ml_kem, 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	ml_kem_key_encap (const ml_kem_t ml_kem, const uint8_t *public_key, uint8_t *ciphertext, uint8_t *session_key)
	Key encapsulation. More...
PQLR_API void	ml_kem_key_decap (const ml_kem_t ml_kem, const uint8_t *secret_key, const uint8_t *ciphertext, uint8_t *session_key)
	Key decapsulation. More...

Detailed Description

This module provides ML-KEM 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 ml_kem_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 ml_kem_new
2. Initiator calls ml_kem_keygen, gets public key.
3. Initiator sends public key to responder.
4. Responder calls ml_kem_key_encap, gets ciphertext and session key.
5. Responder sends ciphertext to initiator by insecure channel.
6. Initiator calls ml_kem_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 ml_kem_free

In order to use any ML-KEM key distribution functions, add the following include:

#include <pqlr/ml_kem/ml_kem.h>

Example code is listed below:

#include <pqlr/ml_kem/ml_kem.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[])
{
    // ML-KEM internal context and parameters
    // Context should be initialized before usage
    ml_kem_t ml_kem = ml_kem_new(ml_kem_512);
 
    // server side context
    uint8_t* public_key =
        (uint8_t*)malloc(ml_kem_get_initiator_public_length(ml_kem));
    uint8_t* secret_key =
        (uint8_t*)malloc(ml_kem_get_initiator_secret_length(ml_kem));
    uint8_t* server_side_key = (uint8_t*)calloc(
        ml_kem_get_shared_secret_length(ml_kem), sizeof(uint8_t));
 
    // client side context
    uint8_t* ciphertext =
        (uint8_t*)malloc(ml_kem_get_ciphertext_length(ml_kem));
    uint8_t* client_side_key = (uint8_t*)calloc(
        ml_kem_get_shared_secret_length(ml_kem), sizeof(uint8_t));
 
    // prepare server's secret and public keys
    ml_kem_keygen(ml_kem, 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
    ml_kem_key_encap(ml_kem, public_key, ciphertext, client_side_key);
 
    // ... ciphertext is transferred from client to server by insecure channel
 
    // generate secret key on the server side
    ml_kem_key_decap(ml_kem, secret_key, ciphertext, server_side_key);
 
    // client and server keys will be the same
    print_key(
        "Server side: ", server_side_key,
        ml_kem_get_shared_secret_length(ml_kem));
    print_key(
        "Client side: ", client_side_key,
        ml_kem_get_shared_secret_length(ml_kem));
 
    // Don't forget to free resources after use
    free(public_key);
    free(secret_key);
    free(server_side_key);
    free(client_side_key);
    free(ciphertext);
 
    ml_kem_free(ml_kem);
 
    return 0;
}

Typedef Documentation

ml_kem_t

typedef struct ml_kem_st* ml_kem_t

ML-KEM algorithm instance handle.

Note

pqlr_t instance linked to this handle can be obtained

See also

ml_kem_to_pqlr

Enumeration Type Documentation

ml_kem_parameterset_t

enum ml_kem_parameterset_t

Possible ML-KEM parameters sets.

Enumerator
ml_kem_512
ml_kem_768
ml_kem_1024
ml_kem_last

Function Documentation

ml_kem_duplicate()

PQLR_API ml_kem_t ml_kem_duplicate

(

const ml_kem_t

ml_kem

)

Duplicates context of ML-KEM instance.

Parameters

ml_kem

instance to duplicate

Returns

new instance with a duplicated context

ml_kem_free()

PQLR_API void ml_kem_free

(

ml_kem_t

ml_kem

)

Frees ML-KEM instance and all corresponding resources.

Parameters

ml_kem

instance to free

See also

ml_kem_t

ml_kem_new

ml_kem_get_ciphertext_length()

PQLR_API uint32_t ml_kem_get_ciphertext_length

(

ml_kem_t

ml_kem

)

Obtains ciphertext length for the current ML-KEM instance.

Parameters

ml_kem

initialized ML-KEM instance

See also

ml_kem_t

ml_kem_new

Returns

ciphertext length

ml_kem_get_initiator_public_length()

PQLR_API uint32_t ml_kem_get_initiator_public_length

(

ml_kem_t

ml_kem

)

Obtains initiator's public key length for the current ML-KEM instance.

Parameters

ml_kem

initialized ML-KEM instance

See also

ml_kem_t

ml_kem_new

Returns

initiator's public key length

ml_kem_get_initiator_secret_length()

PQLR_API uint32_t ml_kem_get_initiator_secret_length

(

ml_kem_t

ml_kem

)

Obtains initiator's secret key length for the current ML-KEM instance.

Parameters

ml_kem

initialized ML-KEM instance

See also

ml_kem_t

ml_kem_new

Returns

initiator's secret key length

ml_kem_get_shared_secret_length()

PQLR_API uint32_t ml_kem_get_shared_secret_length

(

ml_kem_t

ml_kem

)

Obtains shared secret length for the current ML-KEM instance.

Parameters

ml_kem

initialized ML-KEM instance

See also

ml_kem_t

ml_kem_new

Returns

shared secret length

ml_kem_key_decap()

PQLR_API void ml_kem_key_decap	(	const ml_kem_t	ml_kem,
		const uint8_t *	secret_key,
		const uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Key decapsulation.

Parameters

	ml_kem	ML-KEM 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 ml_kem_get_initiator_secret_length. If NULL, the fatal error occurs. (ml_kem_keygen)
	ciphertext	Ciphertext buffer. Must point to array of uint8_t with elements count at least ml_kem_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 ml_kem_get_shared_secret_length. If NULL, the fatal error occurs.

See also

ml_kem_new

ml_kem_keygen

ml_kem_key_encap

ml_kem_key_encap()

PQLR_API void ml_kem_key_encap	(	const ml_kem_t	ml_kem,
		const uint8_t *	public_key,
		uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Key encapsulation.

Note

Called on initiator side.

If public_key validation failed, ml_kem_err is set in context

Parameters

	ml_kem	ML-KEM 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 ml_kem_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 ml_kem_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 ml_kem_get_shared_secret_length. If NULL, the fatal error occurs.

See also

ml_kem_new

ml_kem_keygen

ml_kem_keygen()

PQLR_API void ml_kem_keygen	(	const ml_kem_t	ml_kem,
		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

	ml_kem	ML-KEM 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 ml_kem_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 ml_kem_get_initiator_secret_length. If NULL, the fatal error occurs.

See also

ml_kem_new

ml_kem_new()

PQLR_API ml_kem_t ml_kem_new

(

ml_kem_parameterset_t

parameterset

)

Creates ML-KEM instance initialized by parameterset.

Note

Called on both sides.

Parameters

parameterset

ML-KEM configuration parameters set (see ml_kem_parameterset_t for availible options).

See also

ml_kem_parameterset_t

ml_kem_t

ml_kem_free

Returns

new ML-KEM instance or NULL if out of memory

ml_kem_to_pqlr()

PQLR_API pqlr_t ml_kem_to_pqlr

(

ml_kem_t

ml_kem

)

Gets pqlr instance linked to this ML-KEM instance.

Parameters

ml_kem

initialized ML-KEM instance

Note

this call leaves ML-KEM instance intact
the returned pqlr instance will be released on call to ml_kem_free()

See also

ml_kem_t

pqlr_t

ml_kem_free

Returns

operable pqlr instance or NULL if ml_kem is NULL