davo176 / sike Goto Github PK

# additional testing info in /Reference_Implementation/README.md

Supersingular Isogeny Key Encapsulation software
================================================

This document describes basic instructions to compile and test the
software implementations accompanying the Supersingular Isogeny Key
Encapsulation (SIKE) submission.

All of the code is available under the MIT License. 

- The implementations in the folders "Reference_Implementation" and
  "Additional_Implementations/SIKE-Weierstrass" were developed by Basil
  Hess (InfoSec Global).
- The implementations in the folders "Additional_Implementations/x64"
  and "Optimized_Implementation" were developed by Patrick Longa
  (Microsoft Research), Joost Renes (NXP), Geovandro Pereira
  (University of Waterloo), Aaron Hutchinson (University of Waterloo),
  and Koray Karabina (National Research Council of Canada).
- The ARM64 implementation in "Additional_Implementations/ARM64" was
  developed by Patrick Longa (Microsoft Research).
- The ARMv7 Cortex-M4 implementation in
  "Additional_Implementations/CortexM4" was developed by Hwajeong Seo
  (Hansung University), Amir Jalali (LinkedIn), and Reza Azarderakhsh
  (Florida Atlantic University).
- The VHDL implementation in "Additional_Implementations/VHDL" was
  developed by Brian Koziel (Texas Instruments), Reza Azarderakhsh,
  (Florida Atlantic University) and Rami El Khatib (Florida Atlantic 
  University).


1. CONTENT:
   -------

The SIKE submission includes implementations for four security levels.
Each security levels contains two variant: a standard variant and a
variant using compression techniques.

The corresponding schemes are called SIKEp434, SIKEp434_compressed,
SIKEp503, SIKEp503_compressed, SIKEp610, SIKEp610_compressed, SIKEp751
and SIKEp751_compressed.

The media folder accompanying this submission contains the following
folders:
 
- KAT/: KAT values generated with the code ("PQCgenKAT_kem.c") provided
  by NIST.
- Reference_Implementation/: simple and portable implementation
  exclusively written in ANSI C.
- Optimized_Implementation/portable/<SIKEp#>/: portable implementations
  optimized for speed and exclusively written in ANSI C.
- Additional_Implementations/x64/<SIKEp#>/: optimized, supplementary
  implementations exploiting x64 assembly.
- Additional_Implementations/ARM64/<SIKEp#>/: optimized, supplementary
  implementations exploiting ARM64 assembly.
- Additional_Implementations/CortexM4/<SIKEp#>/: optimized, supplementary
  implementations exploiting ARMv7 Cortex-M4 assembly.
- Additional_Implementations/VHDL/<SIKEp#>/: optimized VHDL model,
  implemented in both FPGA and ASIC 
- Additional_Implementations/SIKE-Weierstrass/: simple, textbook
  implementation using elliptic curves in short Weierstrass form
- Supporting_Documentation/: Specification of the SIKE protocol.

In this README, we describe basic instructions to compile and test the
software implementations in the folders "Optimized_Implementation" and
"Additional_Implementations".

COMPLEMENTARY CRYPTO FUNCTIONS:
------------------------------

Random values are generated with /dev/urandom. Check the folder
<implementation>/<SIKEp#>/random for details.


2. QUICK INSTRUCTIONS:
   ------------------

Instructions in this section apply only to the optimized implementation
and the assembly-optimized implementations.  Regarding the reference
implementation, refer to the README file in the Reference_Implementation
folder.

<SIKEp#> refers to any of {SIKEp434, SIKEp503, SIKEp610, SIKEp751,
SIKEp434_compressed, SIKEp503_compressed, SIKEp610_compressed,
SIKEp751_compressed}.

<implementation> refers to any of {Optimized_Implementation/portable,
Additional_Implementations/x64, Additional_Implementations/ARM64}.

Pick a given implementation and scheme, and then do:

$ cd <implementation>/<SIKEp#>
$ make clean
$ make

Testing and benchmarking results are obtained by running:

$ ./sike/test_KEM

To run the implementations against the KATs provided in the KAT folder,
execute:

$ ./sike/PQCtestKAT_kem

These instructions are intended for x64 platforms by default.
Compilation is performed with GNU GCC by default. To change these
values, use compilation options as described in the next section.


3. ADDITIONAL OPTIONS
   ------------------

For the optimized implementation, we have the following compilation
options: 

make CC=[gcc/clang] ARCH=[x64/x86/ARM/ARM64] SET=EXTENDED

For the additional assembly-optimized x64 implementation, we have the
following compilation options:

make CC=[gcc/clang] SET=EXTENDED USE_MULX=[TRUE/FALSE] USE_ADX=[TRUE/FALSE]

"SET=EXTENDED" adds the flags -fwrapv -fomit-frame-pointer -march=native

The use of mulx and adx instructions is included by
default in the additional implementations. The user is responsible for
checking if these instructions are supported in the targeted platform
and then setting the corresponding flags above accordingly.

Note: USE_ADX can only be set to TRUE if USE_MULX=TRUE.
The combination of `USE_MULX=FALSE` with `USE_ADX=FALSE` is only
supported on p503 and p751.


4. LICENSE:
   -------

The SIKE software is licensed under the MIT License; see License.txt for
details.  It includes some third party modules that are licensed
differently. In particular:

- <implementation>/<SIKEp#>/tests/aes/aes.c: public domain
- <implementation>/<SIKEp#>/tests/aes/aes_c.c: public domain
- <implementation>/<SIKEp#>/tests/rng/rng.c: copyrighted by Lawrence E.
  Bassham 
- <implementation>/<SIKEp#>/tests/PQCtestKAT_kem.c: copyrighted by
  Lawrence E. Bassham 
- <implementation>/<SIKEp#>/sha3/fips202.c: public domain


Contributors
------------

Other contributors include:

- Joost Renes, while he was an intern with Microsoft Research.