PQLR  dev-1426-v1.4-474-b578073a
Postquantum Crypto Library by QAPP
McEliece key distribution

Typedefs

typedef struct mceliece_st * mceliece_t
 McEliece algorithm instance handle. More...
 

Enumerations

enum  mceliece_parameterset_t {
  mceliece348864, mceliece460896, mceliece6688128, mceliece6960119,
  mceliece8192128, mceliece348864f, mceliece460896f, mceliece6688128f,
  mceliece6960119f, mceliece8192128f, mceliece_last
}
 Possible mceliece parameters sets. More...
 

Functions

PQLR_API mceliece_t mceliece_new (mceliece_parameterset_t parameterset)
 Creates mceliece instance initialized by parameterset. More...
 
PQLR_API void mceliece_free (mceliece_t mceliece)
 Frees mceliece instance and all corresponding resources. More...
 
PQLR_API uint32_t mceliece_get_initiator_public_length (mceliece_t mceliece)
 Obtains initiator's public key length for the current mceliece instance. More...
 
PQLR_API uint32_t mceliece_get_initiator_secret_length (mceliece_t mceliece)
 Obtains initiator's secret key length for the current mceliece instance. More...
 
PQLR_API uint32_t mceliece_get_ciphertext_length (mceliece_t mceliece)
 Obtains ciphertext length for the current mceliece instance. More...
 
PQLR_API uint32_t mceliece_get_shared_secret_length (mceliece_t mceliece)
 Obtains shared secret length for the current mceliece instance. More...
 
PQLR_API pqlr_t mceliece_to_pqlr (mceliece_t mceliece)
 Casts mceliece instance to pqlr instance. More...
 
PQLR_API mceliece_t mceliece_duplicate (const mceliece_t mceliece)
 Duplicates context of mceliece instance. More...
 
PQLR_API void mceliece_keygen (const mceliece_t mceliece, 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 mceliece_key_encap (const mceliece_t mceliece, const uint8_t *public_key, uint8_t *ciphertext, uint8_t *session_key)
 Key encapsulation. More...
 
PQLR_API void mceliece_key_decap (const mceliece_t mceliece, const uint8_t *secret_key, const uint8_t *ciphertext, uint8_t *session_key)
 Key decapsulation. More...
 

Detailed Description

This module provides McEliece 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 mceliece_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 mceliece_new
  2. Initiator calls mceliece_keygen, gets public key.
  3. Initiator sends public key to responder.
  4. Responder calls mceliece_key_encap, gets ciphertext and session key.
  5. Responder sends ciphertext to initiator by insecure channel.
  6. Initiator calls mceliece_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 mceliece_free

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

Example code is listed below:

#include <stdint.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[])
{
// mceliece internal context and parameters
// Context should be initialized before usage
// server side context
uint8_t* public_key =
(uint8_t*)malloc(mceliece_get_initiator_public_length(mceliece));
uint8_t* private_key =
(uint8_t*)malloc(mceliece_get_initiator_secret_length(mceliece));
uint8_t* server_side_key = (uint8_t*)calloc(
mceliece_get_shared_secret_length(mceliece), sizeof(uint8_t));
// client side context
uint8_t* ciphertext =
(uint8_t*)malloc(mceliece_get_ciphertext_length(mceliece));
uint8_t* client_side_key = (uint8_t*)calloc(
mceliece_get_shared_secret_length(mceliece), sizeof(uint8_t));
// prepare server's secret and public keys
mceliece_keygen(mceliece, 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
mceliece_key_encap(mceliece, public_key, ciphertext, client_side_key);
// ... ciphertext is transferred from client to server by insecure channel
// generate secret key on the server side
mceliece_key_decap(mceliece, 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(private_key);
free(server_side_key);
free(client_side_key);
free(ciphertext);
mceliece_free(mceliece);
return 0;
}

Typedef Documentation

◆ mceliece_t

typedef struct mceliece_st* mceliece_t

McEliece algorithm instance handle.

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

Enumeration Type Documentation

◆ mceliece_parameterset_t

Possible mceliece parameters sets.

Enumerator
mceliece348864 
mceliece460896 
mceliece6688128 
mceliece6960119 
mceliece8192128 
mceliece348864f 
mceliece460896f 
mceliece6688128f 
mceliece6960119f 
mceliece8192128f 
mceliece_last 

Function Documentation

◆ mceliece_duplicate()

PQLR_API mceliece_t mceliece_duplicate ( const mceliece_t  mceliece)

Duplicates context of mceliece instance.

Parameters
mcelieceinstance to duplicate
Returns
new instance with a duplicated context

◆ mceliece_free()

PQLR_API void mceliece_free ( mceliece_t  mceliece)

Frees mceliece instance and all corresponding resources.

Parameters
mcelieceinstance to free
See also
mceliece_t
mceliece_new

◆ mceliece_get_ciphertext_length()

PQLR_API uint32_t mceliece_get_ciphertext_length ( mceliece_t  mceliece)

Obtains ciphertext length for the current mceliece instance.

Parameters
mcelieceinitialized mceliece instance
See also
mceliece_t
mceliece_new
Returns
ciphertext length

◆ mceliece_get_initiator_public_length()

PQLR_API uint32_t mceliece_get_initiator_public_length ( mceliece_t  mceliece)

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

Parameters
mcelieceinitialized mceliece instance
See also
mceliece_t
mceliece_new
Returns
initiator's public key length

◆ mceliece_get_initiator_secret_length()

PQLR_API uint32_t mceliece_get_initiator_secret_length ( mceliece_t  mceliece)

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

Parameters
mcelieceinitialized mceliece instance
See also
mceliece_t
mceliece_new
Returns
initiator's secret key length

◆ mceliece_get_shared_secret_length()

PQLR_API uint32_t mceliece_get_shared_secret_length ( mceliece_t  mceliece)

Obtains shared secret length for the current mceliece instance.

Parameters
mcelieceinitialized mceliece instance
See also
mceliece_t
mceliece_new
Returns
shared secret length

◆ mceliece_key_decap()

PQLR_API void mceliece_key_decap ( const mceliece_t  mceliece,
const uint8_t *  secret_key,
const uint8_t *  ciphertext,
uint8_t *  session_key 
)

Key decapsulation.

Parameters
mcelieceMcEliece algorithm context. If NULL, the fatal error occurs.
secret_keySecret key buffer. If NULL, the fatal error occurs. (mceliece_keygen)
ciphertextCiphertext buffer. If NULL, the fatal error occurs.
[out]session_keySession key buffer.
See also
mceliece_new
mceliece_keygen
mceliece_key_encap

◆ mceliece_key_encap()

PQLR_API void mceliece_key_encap ( const mceliece_t  mceliece,
const uint8_t *  public_key,
uint8_t *  ciphertext,
uint8_t *  session_key 
)

Key encapsulation.

Note
Called on initiator side.
Parameters
mcelieceMcEliece 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 mceliece_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 mceliece_get_initiator_key_length. If NULL, the fatal error occurs.
See also
mceliece_new
mceliece_keygen

◆ mceliece_keygen()

PQLR_API void mceliece_keygen ( const mceliece_t  mceliece,
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
mcelieceMcEliece 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 mceliece_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 mceliece_get_initiator_secret_length. If NULL, the fatal error occurs.
See also
mceliece_new

◆ mceliece_new()

PQLR_API mceliece_t mceliece_new ( mceliece_parameterset_t  parameterset)

Creates mceliece instance initialized by parameterset.

Note
Called on both sides.
Parameters
parametersetMcEliece configuration parameters set (see mceliece_parameterset_t for availible options).
See also
mceliece_parameterset_t
mceliece_t
mceliece_free
Returns
new mceliece instance or NULL if out of memory

◆ mceliece_to_pqlr()

PQLR_API pqlr_t mceliece_to_pqlr ( mceliece_t  mceliece)

Casts mceliece instance to pqlr instance.

Parameters
mcelieceinitialized mceliece instance
Note
this pqlr instance will be released by mceliece_free
See also
mceliece_t
pqlr_t
mceliece_free
Returns
operable pqlr instance or NULL if mceliece is NULL