Zemlyanika key distribution

Typedefs
typedef struct zemlyanika_st *	zemlyanika_t
	Zemlyanika algorithm instance handle.

Enumerations
enum	zemlyanika_parameterset_t {   zemlyanika_512 , zemlyanika_768R , zemlyanika_768C , zemlyanika_1024 ,   zemlyanika_parameterset_last }
	Possible Zemlyanika parameter sets. More...

Functions
PQLR_API zemlyanika_t	zemlyanika_new (zemlyanika_parameterset_t parameterset)
	Creates Zemlyanika instance initialized by parameterset.
PQLR_API void	zemlyanika_free (zemlyanika_t zemlyanika)
	Frees Zemlyanika instance and all corresponding resources.
PQLR_API uint32_t	zemlyanika_get_initiator_public_length (zemlyanika_t zemlyanika)
	Obtains initiator's public key length for the current Zemlyanika instance.
PQLR_API uint32_t	zemlyanika_get_initiator_secret_length (zemlyanika_t zemlyanika)
	Obtains initiator's secret key length for the current Zemlyanika instance.
PQLR_API uint32_t	zemlyanika_get_ciphertext_length (zemlyanika_t zemlyanika)
	Obtains ciphertext length for the current Zemlyanika instance.
PQLR_API uint32_t	zemlyanika_get_shared_secret_length (zemlyanika_t zemlyanika)
	Obtains shared secret length for the current Zemlyanika instance.
PQLR_API pqlr_t	zemlyanika_to_pqlr (zemlyanika_t zemlyanika)
	Gets pqlr instance linked to this Zemlyanika instance.
PQLR_API zemlyanika_t	zemlyanika_duplicate (const zemlyanika_t zemlyanika)
	Duplicates context of Zemlyanika instance.
PQLR_API int	zemlyanika_keygen (const zemlyanika_t zemlyanika, uint8_t *public_key, uint8_t *secret_key)
	Initial step of key distribution. Generates a key pair for key distribution initiator.
PQLR_API int	zemlyanika_key_encap (const zemlyanika_t zemlyanika, const uint8_t *public_key, uint8_t *ciphertext, uint8_t *session_key)
	Key encapsulation.
PQLR_API int	zemlyanika_key_decap (const zemlyanika_t zemlyanika, const uint8_t *secret_key, const uint8_t *ciphertext, uint8_t *session_key)
	Key decapsulation.

Detailed Description

This module provides Zemlyanika algorithm implementation, which is an algorithm for secure distribution of secret between two counterparties. The distributed secret is theoretically resistant to attacks performed by quantum computers. Entry point is zemlyanika_keygen

General usage

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

1. Both sides call zenlyanika_new to initialize local contexts
2. Initiator calls zemlyanika_keygen, gets public key.
3. Initiator sends public key to responder via insecure channel.
4. Responder calls zenlyanika_key_encap, gets ciphertext and session key.
5. Responder sends ciphertext to initiator via insecure channel.
6. Initiator calls zemlyanika_key_decap, gets session key.
7. Both sides now have the same cryptographically secure session key.
8. If no more key distribution is required, the resources must be freed on both sides by calling zemlyanika_free

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

#include <pqlr/zemlyanika/zemlyanika.h>

Example code is listed below:

 
#include <pqlr/zemlyanika/zemlyanika.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[])
{
    // Zemlyanika internal context and parameters
    // Context must be initialized before usage
    zemlyanika_t zemlyanika = zemlyanika_new(zemlyanika_512);
 
    // server side context
    uint8_t* public_key =
        (uint8_t*)malloc(zemlyanika_get_initiator_public_length(zemlyanika));
    uint8_t* secret_key =
        (uint8_t*)malloc(zemlyanika_get_initiator_secret_length(zemlyanika));
    uint8_t* server_side_key = (uint8_t*)calloc(
        zemlyanika_get_shared_secret_length(zemlyanika), sizeof(uint8_t));
 
    // client side context
    uint8_t* ciphertext =
        (uint8_t*)malloc(zemlyanika_get_ciphertext_length(zemlyanika));
    uint8_t* client_side_key = (uint8_t*)calloc(
        zemlyanika_get_shared_secret_length(zemlyanika), sizeof(uint8_t));
 
    // prepare server's secret and public keys
    zemlyanika_keygen(zemlyanika, 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
    zemlyanika_key_encap(zemlyanika, public_key, ciphertext, client_side_key);
 
    // ... ciphertext is transferred from client to server by insecure channel
 
    // generate secret key on the server side
    zemlyanika_key_decap(zemlyanika, secret_key, ciphertext, server_side_key);
 
    // client and server keys will be the same
    print_key(
        "Server side: ", server_side_key,
        zemlyanika_get_shared_secret_length(zemlyanika));
    print_key(
        "Client side: ", client_side_key,
        zemlyanika_get_shared_secret_length(zemlyanika));
 
    // Don't forget to free resources after use
    free(public_key);
    free(secret_key);
    free(server_side_key);
    free(client_side_key);
    free(ciphertext);
 
    zemlyanika_free(zemlyanika);
 
    return 0;
}

Typedef Documentation

zemlyanika_t

typedef struct zemlyanika_st* zemlyanika_t

Zemlyanika algorithm instance handle.

Note

pqlr_t instance linked to this handle can be obtained

See also

zemlyanika_to_pqlr

Enumeration Type Documentation

zemlyanika_parameterset_t

enum zemlyanika_parameterset_t

Possible Zemlyanika parameter sets.

Zemlyanika can be parametrized with one of predefined parameter sets. Property values are summarized in table below.

Paramset	Security level	Private key size, B	Public key size, B	Ciphertext size, B	Shared secret size, B
zemlyanika_512	128	832	672	768	32
zemlyanika_768R	192	1216	992	1280	32
zemlyanika_768C	192	1408	1088	1152	32
zemlyanika_1024	256	1856	1440	1568	32

Enumerator
zemlyanika_512
zemlyanika_768R
zemlyanika_768C
zemlyanika_1024
zemlyanika_parameterset_last

Function Documentation

zemlyanika_duplicate()

PQLR_API zemlyanika_t zemlyanika_duplicate

(

const zemlyanika_t

zemlyanika

)

Duplicates context of Zemlyanika instance.

Parameters

zemlyanika

instance to duplicate

Returns

new instance with a duplicated context

zemlyanika_free()

PQLR_API void zemlyanika_free

(

zemlyanika_t

zemlyanika

)

Frees Zemlyanika instance and all corresponding resources.

Parameters

zemlyanika

instance to free

See also

zemlyanika_t

zemlyanika_new

zemlyanika_get_ciphertext_length()

PQLR_API uint32_t zemlyanika_get_ciphertext_length

(

zemlyanika_t

zemlyanika

)

Obtains ciphertext length for the current Zemlyanika instance.

Parameters

zemlyanika

initialized Zemlyanika instance

See also

zemlyanika_t

zemlyanika_new

Returns

ciphertext length

zemlyanika_get_initiator_public_length()

PQLR_API uint32_t zemlyanika_get_initiator_public_length

(

zemlyanika_t

zemlyanika

)

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

Parameters

zemlyanika

initialized Zemlyanika instance

See also

zemlyanika_t

zemlyanika_new

Returns

initiator's public key length

zemlyanika_get_initiator_secret_length()

PQLR_API uint32_t zemlyanika_get_initiator_secret_length

(

zemlyanika_t

zemlyanika

)

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

Parameters

zemlyanika

initialized Zemlyanika instance

See also

zemlyanika_t

zemlyanika_new

Returns

initiator's secret key length

zemlyanika_get_shared_secret_length()

PQLR_API uint32_t zemlyanika_get_shared_secret_length

(

zemlyanika_t

zemlyanika

)

Obtains shared secret length for the current Zemlyanika instance.

Parameters

zemlyanika

initialized Zemlyanika instance

See also

zemlyanika_t

zemlyanika_new

Returns

shared secret length

zemlyanika_key_decap()

PQLR_API int zemlyanika_key_decap	(	const zemlyanika_t	zemlyanika,
		const uint8_t *	secret_key,
		const uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Key decapsulation.

Parameters

	zemlyanika	Zemlyanika 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 zemlyanika_get_initiator_secret_length. If NULL, the fatal error occurs. (zemlyanika_keygen)
	ciphertext	Ciphertext buffer. Must point to array of uint8_t with elements count at least zemlyanika_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 zemlyanika_get_shared_secret_length. If NULL, the fatal error occurs.

Returns

0 on success or non-zero error code on failure

See also

zemlyanika_new

zemlyanika_keygen

zemlyanika_key_encap

zemlyanika_key_encap()

PQLR_API int zemlyanika_key_encap	(	const zemlyanika_t	zemlyanika,
		const uint8_t *	public_key,
		uint8_t *	ciphertext,
		uint8_t *	session_key
	)

Key encapsulation.

Parameters

	zemlyanika	Zemlyanika 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 zemlyanika_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 zemlyanika_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 zemlyanika_get_shared_secret_length. If NULL, the fatal error occurs.

Returns

0 on success. Always succeeds.

See also

zemlyanika_new

zemlyanika_keygen

zemlyanika_keygen()

PQLR_API int zemlyanika_keygen	(	const zemlyanika_t	zemlyanika,
		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

	zemlyanika	Zemlyanika 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 zemlyanika_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 zemlyanika_get_initiator_secret_length. If NULL, the fatal error occurs.

Returns

0 on success. Always succeeds.

See also

zemlyanika_new

zemlyanika_new()

PQLR_API zemlyanika_t zemlyanika_new

(

zemlyanika_parameterset_t

parameterset

)

Creates Zemlyanika instance initialized by parameterset.

Note

Must be called on both sides obtaining a shared key.

Parameters

parameterset

Zemlyanika configuration parameter set (see zemlyanika_parameterset_t for availible options).

See also

zemlyanika_parameterset_t

zemlyanika_t

zemlyanika_free

Returns

new Zemlyanika instance or NULL if out of memory

zemlyanika_to_pqlr()

PQLR_API pqlr_t zemlyanika_to_pqlr

(

zemlyanika_t

zemlyanika

)

Gets pqlr instance linked to this Zemlyanika instance.

Parameters

zemlyanika

initialized Zemlyanika instance

Note

this call leaves Zemlyanika instance intact
the returned pqlr instance will be released on call to zemlyanika_free()

See also

zemlyanika_t

pqlr_t

zemlyanika_free

Returns

operable pqlr instance or NULL if zemlyanika is NULL