PQLR
Postquantum Crypto Library by QWall
NewHope key distribution

Typedefs

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

Enumerations

enum  newhope_parameterset_t { newhope_1024 = 0x1 }
 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 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. All this calls performed after library entropy source was set (see pqlr_set_entropy_source)

  1. Both sides call newhope_new
  2. Initiator calls newhope_initiator_prepare, gets request
  3. Initiator sends request to responder
  4. Responder calls newhope_responder, gets reply and key
  5. Responder sends reply to initiator
  6. Initiator calls newhope_initiator_finalize, 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:

Example code is listed below:

#include <stdio.h>
#include <stdlib.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 can act as pqlr instance
pqlr_t newhope_as_pqlr = newhope_to_pqlr(newhope);
// You are able to select entropy source from built-ins or your own
pqlr_get_entropy_from_libc, // The callback
NULL // The context
};
pqlr_set_entropy_source(newhope_as_pqlr, &callback);
// server side context
newhope_poly_t* server_secret = (newhope_poly_t*)calloc(
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

Possible newhope parameters sets.

Enumerator
newhope_1024 

1024 bytes secret length

Function Documentation

◆ newhope_free()

PQLR_API void newhope_free ( newhope_t  newhope)

Frees newhope instance and all corresponding resources.

Parameters
newhopeinstance 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
newhopeinitialized 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
newhopeinitialized 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
newhopeinitialized 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
newhopeinitialized 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
newhopeNewhope algorithm context. If NULL, the fatal error occurs.
secretInitiator secret buffer obtained on initial step. If NULL, the fatal error occurs.
encoded_replyEncoded message from client obtained on second step. If NULL, the fatal error occurs.
[out]keyDistributed 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
newhopeNewhope algorithm context. If NULL, the fatal error occurs.
[out]secretInitiator 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_requestEncoded 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
parametersetNewhope configuration parameters set (see newhope_parameterset_t for availible options).
See also
newhope_parameterset_t
newhope_t
newhope_free
Returns
new newhope instance

◆ 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
newhopeNewhope algorithm context. If NULL, the fatal error occurs.
encoded_requestEncoded request from initiator.
[out]encoded_replyEncoded 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]keyDistributed 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
newhopeinitialized 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