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], NewHopePrivateKey &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 NewHopePrivateKey &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 a substantial amount of memory for function parameters and stack space. On an 8-bit AVR system it is possible to operate with around 2K of parameter space and 4.5K of stack space if the parameters are in shared buffers. More information on the memory requirements and how they were reduced are on this page.

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];
NewHopePrivateKey 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.

To reduce the memory requirements, the second and third parameters to sharedb() can point to the same 2048-byte buffer. On entry, the first 1824 bytes of the buffer are filled with Alice's public key. On exit, the buffer is filled with the 2048 bytes of Bob's public key:

uint8_t shared_secret[NEWHOPE_SHAREDBYTES];

NewHope::sharedb(shared_secret, public_key, public_key);

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);

NewHope::shareda

static void shareda(uint8_t shared_key[NEWHOPE_SHAREDBYTES], const NewHopePrivateKey &sk, uint8_t received[NEWHOPE_SENDBBYTES])

Generates the shared secret for Alice.

Definition: NewHope.cpp:1319

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);

NewHope::Torref

@ Torref

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

Definition: NewHope.h:60

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 50 of file NewHope.h.

Member Enumeration Documentation

◆ Variant

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 57 of file NewHope.h.

Member Function Documentation

◆ keygen()

void NewHope::keygen	(	uint8_t	send[NEWHOPE_SENDABYTES],
		NewHopePrivateKey &	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 private 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 1025 of file NewHope.cpp.

◆ shareda()

void NewHope::shareda	(	uint8_t	shared_key[NEWHOPE_SHAREDBYTES],
		const NewHopePrivateKey &	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 1319 of file NewHope.cpp.

◆ sharedb()

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. This is allowed to be the same pointer as received to replace the received value from Alice with the new value to send for Bob.
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.

It is assumed that if send and received overlap, then they are the same pointer. The bytes at the end of send may be used for temporary storage while the leading bytes of send / received are being processed.

See also: shareda(), keygen()

Definition at line 1137 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

◆ Variant

Member Function Documentation

◆ keygen()

◆ shareda()

◆ sharedb()