Typedefs
typedef struct newhope_st *	newhope_t
	Newhope algorithm instance handle. More...

Enumerations
enum	newhope_parameterset_t { newhope_1024, newhope_last }
	Possible newhope parameters sets. More...

Functions
PQLR_API newhope_t	newhope_new (newhope_parameterset_t parameterset)
	Creates newhope instance initialized by parameterset. More...

PQLR_API void	newhope_free (newhope_t newhope)
	Frees newhope instance and all corresponding resources. More...

PQLR_API newhope_t	newhope_duplicate (const newhope_t newhope)
	Duplicates context of newhope instance. More...

PQLR_API uint32_t	newhope_get_initiator_secret_length (newhope_t newhope)
	Obtains initiator's secret length for current newhope instance. More...

PQLR_API uint32_t	newhope_get_encoded_request_length (newhope_t newhope)
	Obtains encoded request length for current newhope instance. More...

PQLR_API uint32_t	newhope_get_encoded_reply_length (newhope_t newhope)
	Obtains encoded reply length for current newhope instance. More...

PQLR_API uint32_t	newhope_get_keybytes_num (newhope_t newhope)
	Obtains number of symmetric secret key bytes for current newhope instance. More...

PQLR_API pqlr_t	newhope_to_pqlr (newhope_t newhope)
	Casts newhope instance to pqlr instance. More...

PQLR_API void	newhope_initiator_prepare (const newhope_t newhope, newhope_poly_t secret, uint8_t encoded_request)
	Initial step of key distribution. Generates private secret for key distribution initiator. More...

PQLR_API void	newhope_responder (const newhope_t newhope, const uint8_t encoded_request, uint8_t encoded_reply, uint8_t *key)
	Second step of key distribution. Generates symmetric secret key on responder side (opposite from initiator). More...

PQLR_API void	newhope_initiator_finalize (const newhope_t newhope, const newhope_poly_t secret, const uint8_t encoded_reply, uint8_t *key)
	Last step of key distribution. Generates symmetric secret key on initiator side. More...

Detailed Description

This module provides Newhope algorithm implementation, which is finite state machine for secure distribution of secret between two counterparties. Distributed secret is theoretically tolerant to attacks performed by quantum computers. Entry point is newhope_initiator_prepare

General usage

Key distribution algorithms consist of sequential function calls on two sides named initiator and responder.

Both sides call newhope_new
Initiator calls newhope_initiator_prepare, gets request
Initiator sends request to responder
Responder calls newhope_responder, gets reply and key
Responder sends reply to initiator
Initiator calls newhope_initiator_finalize, gets key
Both sides have similar cryptographically secure key
If no more key distribution required resources must be made free on both side by newhope_free

Note: In client-server applications client can represent initiator side, whereas server represents responder side, or vice versa.

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

#include <pqlr/newhope/newhope.h>

Example code is listed below:

#include <stdio.h>
#include <stdlib.h>
#include <pqlr/newhope/newhope.h>
#include <pqlr/common/sei.h>
void print_key(const char* message, uint8_t key[32])
{
    uint8_t i = 0;
    printf("%s", message);
    for (; i < 32; ++i) {
        printf("%.2X", key[i]);
    }
    printf("\n");
}
int main()
{
    // Create newhope instance
    newhope_t newhope = newhope_new(newhope_1024);
    // Newhope can act as pqlr instance
    pqlr_t newhope_as_pqlr = newhope_to_pqlr(newhope);
    // server side context
    newhope_poly_t* server_secret = (newhope_poly_t*)calloc(
        newhope_get_initiator_secret_length(newhope), sizeof(newhope_poly_t));
    uint8_t* request =
        (uint8_t*)malloc(newhope_get_encoded_request_length(newhope));
    uint8_t server_side_key[32] = {
        0,
    };
    // client side context
    uint8_t* reply =
        (uint8_t*)malloc(newhope_get_encoded_reply_length(newhope));
    uint8_t client_side_key[32] = {
        0,
    };
    // prepare encoded message to client and servers's secret
    newhope_initiator_prepare(newhope, server_secret, request);
    // generate secret key on the client side based on non secret message
    // encoded_a and generate non secret reply encoded_b back to server
    newhope_responder(newhope, request, reply, client_side_key);
    // generate secret key on the server side
    newhope_initiator_finalize(newhope, server_secret, reply, server_side_key);
    print_key("Server side:", server_side_key);
    print_key("Client side:", client_side_key);
    // Don't forget to free resources after use
    free(server_secret);
    free(request);
    free(reply);
    newhope_free(newhope);
    return 0;
}

Typedef Documentation

◆ newhope_t

typedef struct newhope_st* newhope_t

Newhope algorithm instance handle.

Note: It could be casted to pqlr_t instance linked to this handle

See also: newhope_to_pqlr

Enumeration Type Documentation

◆ newhope_parameterset_t

enum newhope_parameterset_t

Possible newhope parameters sets.

Enumerator
newhope_1024	1024 bytes secret length
newhope_last

Function Documentation

◆ newhope_duplicate()

PQLR_API newhope_t newhope_duplicate ( const newhope_t newhope )

Duplicates context of newhope instance.

Parameters

newhope instance to duplicate

Returns: new instance with a duplicated context

◆ newhope_free()

PQLR_API void newhope_free ( newhope_t newhope )

Frees newhope instance and all corresponding resources.

Parameters

newhope instance to free

See also: newhope_t; newhope_new

◆ newhope_get_encoded_reply_length()

PQLR_API uint32_t newhope_get_encoded_reply_length ( newhope_t newhope )

Obtains encoded reply length for current newhope instance.

Parameters

newhope initialized newhope instance

See also: newhope_t; newhope_new

Returns: encoded reply length

◆ newhope_get_encoded_request_length()

PQLR_API uint32_t newhope_get_encoded_request_length ( newhope_t newhope )

Obtains encoded request length for current newhope instance.

Parameters

newhope initialized newhope instance

See also: newhope_t; newhope_new

Returns: encoded request length

◆ newhope_get_initiator_secret_length()

PQLR_API uint32_t newhope_get_initiator_secret_length ( newhope_t newhope )

Obtains initiator's secret length for current newhope instance.

Parameters

newhope initialized newhope instance

See also: newhope_t; newhope_new

Returns: initiator's secret length

◆ newhope_get_keybytes_num()

PQLR_API uint32_t newhope_get_keybytes_num ( newhope_t newhope )

Obtains number of symmetric secret key bytes for current newhope instance.

Parameters

newhope initialized newhope instance

See also: newhope_t; newhope_new

Returns: number of symmetric secret key bytes

◆ newhope_initiator_finalize()

PQLR_API void newhope_initiator_finalize	(	const newhope_t	newhope,
		const newhope_poly_t *	secret,
		const uint8_t *	encoded_reply,
		uint8_t *	key
	)

Last step of key distribution. Generates symmetric secret key on initiator side.

Note: Called on initiator side

Parameters

	newhope	Newhope algorithm context. If `NULL`, the fatal error occurs.
	secret	Initiator secret buffer obtained on initial step. If `NULL`, the fatal error occurs.
	encoded_reply	Encoded message from client obtained on second step. If `NULL`, the fatal error occurs.
[out]	key	Distributed key, equal to key to be obtained on client side. If `NULL`, the fatal error occurs.

Note: key should be used for data encryption.

See also: newhope_new; newhope_initiator_prepare; newhope_responder

◆ newhope_initiator_prepare()

PQLR_API void newhope_initiator_prepare	(	const newhope_t	newhope,
		newhope_poly_t *	secret,
		uint8_t *	encoded_request
	)

Initial step of key distribution. Generates private secret for key distribution initiator.

Note: Called on initiator side.

Parameters

	newhope	Newhope algorithm context. If `NULL`, the fatal error occurs.
[out]	secret	Initiator secret buffer. Must point to array of `newhope_poly_t` with elements count at least `newhope_get_initiator_secret_length`. If `NULL`, the fatal error occurs.
[out]	encoded_request	Encoded message to client. Must point to array of `uint8_t` with elements count at least `newhope_get_encoded_request_length`. If `NULL`, the fatal error occurs.

Warning: secret should be kept in secret.

See also: newhope_get_encoded_request_length; newhope_get_initiator_secret_length; newhope_new; newhope_responder

◆ newhope_new()

PQLR_API newhope_t newhope_new ( newhope_parameterset_t parameterset )

Creates newhope instance initialized by parameterset.

Note: Called on both sides.

Parameters

parameterset Newhope configuration parameters set (see newhope_parameterset_t for availible options).

See also: newhope_parameterset_t; newhope_t; newhope_free

Returns: new newhope instance or NULL if out of memory

◆ newhope_responder()

PQLR_API void newhope_responder	(	const newhope_t	newhope,
		const uint8_t *	encoded_request,
		uint8_t *	encoded_reply,
		uint8_t *	key
	)

Second step of key distribution. Generates symmetric secret key on responder side (opposite from initiator).

Note: Called on responder side.

Parameters

	newhope	Newhope algorithm context. If `NULL`, the fatal error occurs.
	encoded_request	Encoded request from initiator.
[out]	encoded_reply	Encoded reply to initiator, must point to array of `uint8_t`, with elements count at least `newhope_get_encoded_reply_length`. If `NULL`, the fatal error occurs.
[out]	key	Distributed key, equal to key to be obtained on initiator side. If `NULL`, the fatal error occurs.

Note: key should be used for data encryption.

See also: newhope_get_encoded_reply_length; newhope_get_encoded_request_length; newhope_initiator_finalize; newhope_initiator_prepare; newhope_new

◆ newhope_to_pqlr()

PQLR_API pqlr_t newhope_to_pqlr ( newhope_t newhope )

Casts newhope instance to pqlr instance.

Parameters

newhope initialized newhope instance

Note: this pqlr instance will be released by newhope_free

See also: newhope_t; pqlr_t; newhope_free

Returns: operable pqlr instance or NULL if newhope is NULL

Typedefs

Enumerations

Functions

Detailed Description

General usage

Typedef Documentation

◆ newhope_t

Enumeration Type Documentation

◆ newhope_parameterset_t

Function Documentation

◆ newhope_duplicate()

◆ newhope_free()

◆ newhope_get_encoded_reply_length()

◆ newhope_get_encoded_request_length()

◆ newhope_get_initiator_secret_length()

◆ newhope_get_keybytes_num()

◆ newhope_initiator_finalize()

◆ newhope_initiator_prepare()

◆ newhope_new()

◆ newhope_responder()

◆ newhope_to_pqlr()