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:

#include <pqlr/mceliece/mceliece.h>

Example code is listed below:

#include <pqlr/mceliece/mceliece.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[])
{
    // mceliece internal context and parameters
    // Context should be initialized before usage
    mceliece_t mceliece = mceliece_new(mceliece348864);
 
    // server side context
    uint8_t* public_key =
        (uint8_t*)malloc(mceliece_get_initiator_public_length(mceliece));
    uint8_t* secret_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,
        mceliece_get_shared_secret_length(mceliece));
    print_key(
        "Client side: ", client_side_key,
        mceliece_get_shared_secret_length(mceliece));
 
    // Don't forget to free resources after use
    free(public_key);
    free(secret_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

enum 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

mceliece

instance 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

mceliece

instance 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

mceliece

initialized 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

mceliece

initialized 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

mceliece

initialized 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

mceliece

initialized 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

	mceliece	McEliece algorithm context. If NULL, the fatal error occurs.
	secret_key	Secret key buffer. If NULL, the fatal error occurs. (mceliece_keygen)
	ciphertext	Ciphertext buffer. If NULL, the fatal error occurs.
[out]	session_key	Session 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

	mceliece	McEliece algorithm context. If NULL, the fatal error occurs.
	public_key	Public key buffer. If NULL, the fatal error occurs.
[out]	ciphertext	Ciphertext 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_key	Session 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

	mceliece	McEliece 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 mceliece_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 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

parameterset

McEliece 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

mceliece

initialized 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