FourQlib/FourQ_ARM_side_channel

                                        FourQlib v3.0 (C Edition)

                                        =========================

	   Optimized implementation for 32-bit ARM and ARM Cortex-M4 with side-channel countermeasures

	   ===========================================================================================

 

1. CONTENTS:

   --------



The "FourQ_ARM_side_channel" folder contains:



makefile                        - Makefile for compilation on ARM processors (ARMv6 and ARMv7) using GNU GCC

                                  on Linux. 

makefile_Cortex-M4              - Makefile for compilation on ARM Cortex-M4 (STM32F4xx series) using GNU GCC 

                                  on Linux. 

*.c, *.h                        - Library and header files. Public API for ECC scalar multiplication, key

                                  exchange and signatures is located in FourQ_api.h        

ARM/                            - Folder with library files implementing low-level arithmetic for ARM.

libopencm3/                     - Folder with firmware library files for ARM Cortex-M microcontrollers  

random/                         - Folder with pseudo-random generation function for ARM Cortex-M4.

tests/                          - Test files for 32-bit ARM.

tests_Cortex-M4/                - Test files for ARM Cortex-M4.

README.txt                      - This readme file.



stm32f4_wrapper.c and stm32f4_wrapper.h are by Joost Rijneveld and can be found at:

https://github.com/joostrijneveld/STM32-getting-started



Files in the folder libopencm3 are from the libopencm3 project (http://libopencm3.org/):

https://github.com/libopencm3/libopencm3





2. SUPPORTED PLATFORMS:

   -------------------



This implementation is supported on ARM platforms and includes two variants: 

(i)  Implementation for ARM processors based on ARMv6 and ARMv7 architectures. This implementation was optimized

     for a first generation Raspberry Pi using a 700 MHz ARM1176JZF-S processor (ARMv6 architecture).

(ii) Implementation for ARM Cortex-M4 processors based on the ARMv7-M architecture. This implementation was 

     developed and optimized on a STM32F4Discovery development board containing a Cortex-M4 STM32F407VG micro-

	 controller (ARMv7-M architecture). It should be possible to extend the support to Cortex-M3 and Cortex-M7 

	 based devices with small modifications.   



See instructions below to choose an implementation option and compile on one of the supported platforms.





3. COMPLEMENTARY CRYPTO FUNCTIONS:

   ------------------------------



Random values are generated with /dev/urandom in the case of the 32-bit ARM implementation, and with the function

random_int() in the case of the ARM Cortex-M4 implementation.

  

The library includes an implementation of SHA-512 which is used by default by SchnorrQ signatures.



Users can experiment with different options by replacing functions in the folders "random" and "sha512" and 

applying the corresponding changes to the settings in FourQ.h. 





4. INSTRUCTIONS:

   ------------



4.1. BUILDING THE LIBRARY FOR ARMv6 or ARMv7:

     ---------------------------------------



To compile on Linux using the GNU GCC compiler or the clang compiler, execute the following command from the 

command prompt:

 

make CC=[gcc/clang] EXTENDED_SET=[TRUE/FALSE]



After compilation, run fp_tests, ecc_tests or crypto_tests.



By default GNU GCC is used, as well as the extended settings. 



For example, to compile using GNU GCC, execute:



make



As another example, to compile using clang, execute:



make CC=clang



By default EXTENDED_SET is enabled, which sets the following compilation flags: -fwrapv -fomit-frame-pointer 

-funroll-loops. To disable this, use EXTENDED_SET=FALSE.

Users are encouraged to experiment with the different flag options.



4.2. BUILDING THE LIBRARY FOR CORTEX-M4 ON THE STM32F4DISCOVERY BOARD:

     ----------------------------------------------------------------



The following instructions have been tested on a Ubuntu 16.04 Linux machine.



First, install the ARM GNU GCC cross-compiler on the server machine:



sudo apt-get install gcc-arm-none-eabi libc6-dev-i386



Then, download, build and install stlink: https://github.com/texane/stlink



sudo apt-get install libusb-1.0-0-dev

git clone https://github.com/texane/stlink.git

cd stlink

make

cd build/Release/ && sudo make install 



To compile the code, execute the following command from the FourQ_ARM_side_channel folder on the server machine:

 

make -f makefile_Cortex-M4



Power the STM32F4DISCOVERY board (with a USB to mini-USB cable) and connect it to the server machine via a 

USB-TTL converter as follows:



VDD -> VDD

GND -> GND 

TX  -> PA3 

RX  -> PA2 



Then, run from the server machine:



sudo ./tests_Cortex-M4/monitor.sh



From a different terminal window on the server machine, program the device with one of the following commands

from the FourQ_ARM_side_channel folder:



st-flash write tests_Cortex-M4/fp_tests.bin 0x8000000

st-flash write tests_Cortex-M4/ecc_tests.bin 0x8000000

st-flash write tests_Cortex-M4/crypto_tests.bin 0x8000000



The tests should begin to run on the first terminal window.