NewHope key distribution

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_initiator_public_length (newhope_t newhope)
	Obtains initiator's public key length for current newhope instance. More...
PQLR_API uint32_t	newhope_get_ciphertext_length (newhope_t newhope)
	Obtains encoded reply length for current newhope instance. More...
PQLR_API uint32_t	newhope_get_shared_secret_length (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)
	Gets pqlr instance linked to this newhope instance. More...
PQLR_API void	newhope_keygen (const newhope_t newhope, 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	newhope_key_encap (const newhope_t newhope, const uint8_t *public_key, uint8_t *ciphertext, uint8_t *session_key)
	Second step of key distribution. Generates symmetric secret key on responder side (opposite from initiator). More...
PQLR_API void	newhope_key_decap (const newhope_t newhope, const uint8_t *secret_key, const uint8_t *ciphertext, uint8_t *session_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_keygen

General usage

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

1. Both sides call newhope_new
2. Initiator calls newhope_keygen, gets request
3. Initiator sends request to responder
4. Responder calls newhope_key_encap, gets reply and key
5. Responder sends reply to initiator
6. Initiator calls newhope_key_decap, gets key
7. Both sides have similar cryptographically secure key
8. 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(void)
{
    // 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
    uint8_t* server_secret = (uint8_t*)calloc(
        newhope_get_initiator_secret_length(newhope), sizeof(uint8_t));
 
    uint8_t* request =
        (uint8_t*)malloc(newhope_get_initiator_public_length(newhope));
    uint8_t server_side_key[32] = {
        0,
    };
 
    // client side context
    uint8_t* reply = (uint8_t*)malloc(newhope_get_ciphertext_length(newhope));
    uint8_t client_side_key[32] = {
        0,
    };
 
    // prepare encoded message to client and servers's secret
    newhope_keygen(newhope, request, server_secret);
 
    // 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_key_encap(newhope, request, reply, client_side_key);
 
    // generate secret key on the server side
    newhope_key_decap(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

pqlr_t instance linked to this handle can be obtained

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_ciphertext_length()

PQLR_API uint32_t newhope_get_ciphertext_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_initiator_public_length()

PQLR_API uint32_t newhope_get_initiator_public_length

(

newhope_t

newhope

)

Obtains initiator's public key 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_shared_secret_length()

PQLR_API uint32_t newhope_get_shared_secret_length

(

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_key_decap()

PQLR_API void newhope_key_decap	(	const newhope_t	newhope,
		const uint8_t *	secret_key,
		const uint8_t *	ciphertext,
		uint8_t *	session_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_key	Initiator secret buffer obtained on initial step. Must point to array of newhope_poly_t with elements count at least newhope_get_initiator_secret_length. If NULL, the fatal error occurs.
	ciphertext	Ciphertext buffer. Must point to array of uint8_t with elements count at least newhope_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 newhope_get_shared_secret_length. If NULL, the fatal error occurs.

Note

session_key should be used for data encryption.

See also

newhope_new

newhope_keygen

newhope_key_encap

newhope_key_encap()

PQLR_API void newhope_key_encap	(	const newhope_t	newhope,
		const uint8_t *	public_key,
		uint8_t *	ciphertext,
		uint8_t *	session_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.
	public_key	Encoded message to client. Must point to array of uint8_t with elements count at least newhope_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 newhope_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 newhope_get_shared_secret_length. If NULL, the fatal error occurs.

Note

session_key should be used for data encryption.

See also

newhope_get_ciphertext_length

newhope_get_initiator_public_length

newhope_key_decap

newhope_keygen

newhope_new

newhope_keygen()

PQLR_API void newhope_keygen	(	const newhope_t	newhope,
		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

	newhope	Newhope algorithm context. If NULL, the fatal error occurs.
[out]	public_key	Encoded message to client. Must point to array of uint8_t with elements count at least newhope_get_initiator_public_length. If NULL, the fatal error occurs.
[out]	secret_key	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.

Warning

secret_key should be kept in secret.

See also

newhope_get_initiator_public_length

newhope_get_initiator_secret_length

newhope_new

newhope_key_encap

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_to_pqlr()

PQLR_API pqlr_t newhope_to_pqlr

(

newhope_t

newhope

)

Gets pqlr instance linked to this newhope instance.

Parameters

newhope

initialized newhope instance

Note

this call leaves newhope instance intact
the returned pqlr instance will be released on call to newhope_free()

See also

newhope_t

pqlr_t

newhope_free

Returns

operable pqlr instance or NULL if newhope is NULL