PQLR
Postquantum Crypto Library by QAPP
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)
 Casts kyber instance to pqlr 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:

Example code is listed below:

#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
// 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,
print_key(
"Client side: ", client_side_key,
// 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;
}
PQLR_API void kyber_free(kyber_t kyber)
Frees kyber instance and all corresponding resources.
PQLR_API uint32_t kyber_get_ciphertext_length(kyber_t kyber)
Obtains ciphertext length for the current kyber instance.
PQLR_API uint32_t kyber_get_initiator_public_length(kyber_t kyber)
Obtains initiator's public key length for the current kyber instance.
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.
struct kyber_st * kyber_t
Kyber algorithm instance handle.
Definition: kyber.h:55
PQLR_API uint32_t kyber_get_shared_secret_length(kyber_t kyber)
Obtains shared secret length for the current kyber instance.
PQLR_API uint32_t kyber_get_initiator_secret_length(kyber_t kyber)
Obtains initiator's secret key length for the current kyber instance.
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.
PQLR_API void kyber_key_encap(const kyber_t kyber, const uint8_t *public_key, uint8_t *ciphertext, uint8_t *session_key)
Key encapsulation.
PQLR_API kyber_t kyber_new(kyber_parameterset_t parameterset)
Creates kyber instance initialized by parameterset.
@ kyber512
Definition: kyber.h:48

Typedef Documentation

◆ kyber_t

typedef struct kyber_st* kyber_t

Kyber algorithm instance handle.

Note
It could be casted to pqlr_t instance linked to this handle
See also
kyber_to_pqlr

Enumeration Type Documentation

◆ 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
kyberinstance 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
kyberinstance 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
kyberinitialized 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
kyberinitialized 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
kyberinitialized 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
kyberinitialized 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
kyberKyber algorithm context. If NULL, the fatal error occurs.
secret_keySecret key buffer. If NULL, the fatal error occurs. (kyber_keygen)
ciphertextCiphertext buffer. If NULL, the fatal error occurs.
[out]session_keySession key buffer.
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
kyberKyber algorithm context. If NULL, the fatal error occurs.
public_keyPublic key buffer. If NULL, the fatal error occurs.
[out]ciphertextCiphertext 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_keySession key buffer. Must point to array of uint8_t with elements count at least kyber_get_initiator_key_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
kyberKyber algorithm context. If NULL, the fatal error occurs.
[out]public_keyPublic 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_keySecret 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
parametersetKyber 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)

Casts kyber instance to pqlr instance.

Parameters
kyberinitialized kyber instance
Note
this pqlr instance will be released by kyber_free
See also
kyber_t
pqlr_t
kyber_free
Returns
operable pqlr instance or NULL if kyber is NULL