Create README.md

FourQ_64bit_and_portable/README.md

@@ -0,0 +1,126 @@
+# FourQlib v3.0 (C Edition): portable and 64-bit optimized implementation
+
+## Contents
+
+The `FourQ_64bit_and_portable` folder contains:
+
+* [`FourQ_64bit_and_portable/Visual Studio/`](FourQ_64bit_and_portable/Visual%20Studio/): folder with Visual Studio 2015 solution and 
+project files for compilation and testing in Windows.
+* [`FourQ_64bit_and_portable/makefile`](FourQ_64bit_and_portable/makefile): Makefile for compilation using GNU GCC or clang compilers 
+on Linux. 
+* Main .c and .h files: library and header files. Public API for ECC scalar multiplication, key exchange and signatures is in 
+[`FourQ_64bit_and_portable\FourQ_api.h`](FourQ_64bit_and_portable\FourQ_api.h).        
+* [`FourQ_64bit_and_portable/AMD64/`](FourQ_64bit_and_portable/AMD64/): folder with library files for optimized x64 implementation.
+* [`FourQ_64bit_and_portable/ARM64/`](FourQ_64bit_and_portable/ARM64/): folder with library files for optimized 64-bit ARM 
+implementation.
+* [`FourQ_64bit_and_portable/generic/`](FourQ_64bit_and_portable/generic/): folder with library files for portable implementation.
+* [`FourQ_64bit_and_portable/tests/`](FourQ_64bit_and_portable/tests/): test files.
+* [`FourQ_64bit_and_portable/README.md`](FourQ_64bit_and_portable/README.md): this readme file.
+
+## Supported platforms
+
+This implementation is supported in a wide range of platforms including x64, x86, 32-bit ARM and 64-bit ARM,
+running Windows or Linux. We have tested the library with Microsoft Visual Studio 2015, GNU GCC v4.9 and 
+clang v3.8. 
+
+See instructions below to choose an implementation option and compile on one of the supported platforms. 
+
+## Complementary crypto functions
+
+Random values are generated with `/dev/urandom` in the case of Linux, and with the function `BCryptGenRandom()` in the case of Windows.
+
+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 [`random`](random/) and [`sha512`](sha512/) folders and 
+applying the corresponding changes to the settings in [`FourQ.h`](FourQ_64bit_and_portable/FourQ.h). 
+
+## Implementation options
+
+The following compilation options are available for the `FourQ_64bit_and_portable` implementation:
+
+* A portable implementation (enabled by the "GENERIC" option).
+* Optimized implementations for x64 and 64-bit ARM (ARMv8). Note that the rest of platforms are only supported
+  by the generic implementation. 
+* Use of AVX or AVX2 instructions enabled by defining `_AVX_` or `_AVX2_` (Windows) or by the "AVX" and "AVX2" 
+  options (Linux).
+* Optimized x64 assembly implementations in Linux.
+* Use of fast endomorphisms enabled by the "USE_ENDO" option.
+
+Follow the instructions below to configure these different options.
+
+## Instructions for Windows
+
+### Building the library with Visual Studio
+
+Open the solution file ([`FourQ.sln`](FourQ_64bit_and_portable/Visual%20Studio/FourQ/FourQ.sln)) in Visual Studio 2015, select 
+one of the available configurations from
+the Solution Configurations menu ("Release" corresponding to the high-speed x64 implementation and "Generic" 
+corresponding to the portable implementation) and select one of the Solution Platforms (x64 or Win32). Note 
+that Win32 is only supported with the "Generic" solution configuration.
+
+By default, `USE_ENDO=true` and (for x64) `_AVX_` is defined. To modify this configuration, go to the property 
+window of the FourQ project, go to `Configuration Properties > C/C++ > Preprocessor`. Make any suitable changes, 
+e.g., delete `_AVX_` if AVX instructions are not supported, replace `_AVX_` by `_AVX2_` if AVX2 instructions
+are supported, or set `USE_ENDO=true` or `false`. Repeat these steps for the `fp_tests`, `ecc_tests` and `crypto_tests` projects.
+
+Finally, select "Build Solution" from the "Build" menu. 
+
+### Running the tests
+
+After building the solution, run `fp_tests.exe`, `ecc_tests.exe` and `crypto_tests.exe`.
+
+### Using the library
+
+After building the solution, add the `FourQ.lib` file to the set of References for a project, and add 
+[`FourQ.h`](FourQ_64bit_and_portable/FourQ.h) and [`FourQ_api.h`](FourQ_64bit_and_portable\FourQ_api.h) to the list of 
+header files of a project.
+
+## Instructions for Linux
+
+### Building the library and executing the tests with GNU GCC or clang
+
+To compile on Linux using the GNU GCC compiler or the clang compiler, execute the following command from the 
+command prompt:
+
+```sh
+$ make ARCH=[x64/x86/ARM/ARM64] CC=[gcc/clang] ASM=[TRUE/FALSE] AVX=[TRUE/FALSE] AVX2=[TRUE/FALSE] 
+     EXTENDED_SET=[TRUE/FALSE] USE_ENDO=[TRUE/FALSE] GENERIC=[TRUE/FALSE] SERIAL_PUSH=[TRUE/FALSE] 
+```
+
+After compilation, run `fp_tests`, `ecc_tests` or `crypto_tests`.
+
+By default GNU GCC is used, as well as the endomorphisms and the extended settings.
+
+In the case of x64, AVX2 instructions and the high-speed assembly implementation are enabled by default.
+In the case of x86 and ARM, the portable ("GENERIC") implementation is used by default.
+
+For example, to compile the optimized x64 implementation in assembly with GNU GCC using the efficient
+endomorphisms on a machine with AVX2 support (e.g, Intel's Haswell or Broadwell), execute:
+
+```sh
+$ make ARCH=x64
+```
+
+For example, to compile the optimized ARM64 implementation with GNU GCC using the efficient endomorphisms, 
+execute:
+
+```sh
+$ make ARCH=ARM64
+```
+
+As another example, to compile the portable implementation with clang using the efficient endomorphisms 
+on an x86 machine, execute:
+
+```sh
+$ make ARCH=x86 CC=clang
+```
+
+`SERIAL_PUSH` can be enabled in some platforms (e.g., AMD without AVX2 support) to boost performance.
+
+By default `EXTENDED_SET` is enabled, which sets the following compilation flags: `-fwrapv -fomit-frame-pointer 
+-march=native`. To disable this, use `EXTENDED_SET=FALSE`.
+Users are encouraged to experiment with the different flag options.
+
+Whenever an unsupported configuration is applied, the following message will be displayed: `#error -- "Unsupported configuration". 
+For example, the use of assembly or any of the AVX options is not supported when selecting the portable implementation 
+(i.e., if `GENERIC=TRUE` or if `ARCH=[x86/ARM]`).