NewHope post-quantum key exchange algorithm. More...

#include <NewHope.h>

Public Types
enum	Variant { Ref, Torref }
	Describes the variant of the New Hope algorithm to implement. More...

Static Public Member Functions
static void	keygen (uint8_t send[NEWHOPE_SENDABYTES], NewHopePoly &sk, Variant variant=Ref, const uint8_t *random_seed=0)
	Generates the key pair for Alice in a New Hope key exchange. More...

static void	sharedb (uint8_t shared_key[NEWHOPE_SHAREDBYTES], uint8_t send[NEWHOPE_SENDBBYTES], uint8_t received[NEWHOPE_SENDABYTES], Variant variant=Ref, const uint8_t *random_seed=0)
	Generates the public key and shared secret for Bob. More...

static void	shareda (uint8_t shared_key[NEWHOPE_SHAREDBYTES], const NewHopePoly &sk, uint8_t received[NEWHOPE_SENDBBYTES])
	Generates the shared secret for Alice. More...

Detailed Description

NewHope post-quantum key exchange algorithm.

New Hope is an ephemeral key exchange algorithm, similar to Diffie-Hellman, which is believed to be resistant to quantum computers.

Note: The functions in this class need up to 7k of stack space to store temporary intermediate values in addition to up to 4k of memory in the application to store public and private key parameters. Due to these memory requirements, this class is only suitable for use on high-end ARM-based Arduino variants like the Arduino Due. It won't fit in the available memory on AVR-based Arduino variants.

Key exchange occurs between two parties, Alice and Bob, and results in a 32-byte (256-bit) shared secret. Alice's public key is 1824 bytes in size and Bob's public key is 2048 bytes in size.

Alice, either the client or the server depending upon the application, generates a key pair as follows:

uint8_t alice_public[NEWHOPE_SENDABYTES];
NewHopePoly alice_private;
NewHope::keygen(alice_public, alice_private);

Alice's application sends the contents of alice_public to Bob, who then performs the following operations:

uint8_t bob_public[NEWHOPE_SENDABYTES];
uint8_t shared_secret[NEWHOPE_SHAREDBYTES];
NewHope::sharedb(shared_secret, bob_public, alice_public);

Bob's application sends the contents of bob_public to Alice, and can then begin encrypting session traffic with shared_secret or some transformed version of it.

When Alice's application receives bob_public, the application performs the folllowing final steps to generate her version of the shared secret:

uint8_t shared_secret[NEWHOPE_SHAREDBYTES];

NewHope::shareda(shared_secret, alice_private, bob_public);

In the New Hope paper there are two versions of the algorithm described, referred to as "ref" and "torref" in author's reference C code. This class implements "ref" by default, but it is possible to enable the "torref" variant with an extra parameter on the keygen() and sharedb() function calls:

NewHope::keygen(alice_public, alice_private, NewHope::Torref);

NewHope::sharedb(shared_secret, bob_public, alice_public, NewHope::Torref);

The shareda() function is the same for both "ref" and "torref".

The "ref" and "torref" variants are not binary-compatible. Public keys generated with one variant will not work with the other variant. The application author must make a decision as to which variant they need and then use it universally. The paper contains more information on why an application may want to use "torref" instead of "ref".

Reference: https://cryptojedi.org/crypto/#newhope

Definition at line 48 of file NewHope.h.

Member Enumeration Documentation

enum NewHope::Variant

Describes the variant of the New Hope algorithm to implement.

Enumerator

Ref

The standard "reference" version of the New Hope algorithm.

Torref

The alternative "torref" version of the New Hope algorithm.

Note: The NewHope class can be compiled without support for "torref" to save memory. In that case, Torref is identical to Ref.

Definition at line 55 of file NewHope.h.

Member Function Documentation

void NewHope::keygen	(	uint8_t	send[NEWHOPE_SENDABYTES],
		NewHopePoly &	sk,
		Variant	variant = `Ref`,
		const uint8_t *	random_seed = `0`
	)

static

Generates the key pair for Alice in a New Hope key exchange.

Parameters

send	The public key value for Alice to be sent to Bob.
sk	The secret key value for Alice to be passed to shareda() later.
variant	The variant of the New Hope algorithm to use, usually Ref.
random_seed	Points to 64 bytes of random data to use to generate the key pair. This is intended for test vectors only and should be set to NULL in real applications.

The send value should be sent to Bob over the communications link and then it can be discarded. The sk value must be retained until the later call to sharedb().

See Also: sharedb(), shareda()

Definition at line 1039 of file NewHope.cpp.

void NewHope::shareda	(	uint8_t	shared_key[NEWHOPE_SHAREDBYTES],
		const NewHopePoly &	sk,
		uint8_t	received[NEWHOPE_SENDBBYTES]
	)

static

Generates the shared secret for Alice.

Parameters

shared_key	The shared secret key.
sk	Alice's secret private key which was generated by keygen().
received	The public key value that was received from Bob.

See Also: sharedb(), keygen()

Definition at line 1159 of file NewHope.cpp.

void NewHope::sharedb	(	uint8_t	shared_key[NEWHOPE_SHAREDBYTES],
		uint8_t	send[NEWHOPE_SENDBBYTES],
		uint8_t	received[NEWHOPE_SENDABYTES],
		Variant	variant = `Ref`,
		const uint8_t *	random_seed = `0`
	)

static

Generates the public key and shared secret for Bob.

Parameters

shared_key	The shared secret key.
send	The public key value for Bob to be sent to Alice.
received	The public key value that was received from Alice.
variant	The variant of the New Hope algorithm to use, usually Ref.
random_seed	Points to 32 bytes of random data to use to generate the temporary private key for Bob. This is intended for test vectors only and should be set to NULL in real applications.

The send value should be sent to Alice over the communications link and then it can be discarded. Bob can immediately start encrypting session traffic with shared_key or some transformed version of it.

See Also: shareda(), keygen()

Definition at line 1098 of file NewHope.cpp.

The documentation for this class was generated from the following files:

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation