-
Notifications
You must be signed in to change notification settings - Fork 43
tutorial_hello
This step-by-step tutorial is designed to guide you on how you can write a new application, configure it and make it optimized and run within Cingulata. You may also want to take a look at the different code examples, present in the tests/ directory.
By now, you have installed and configured the compilation chain and the runtime. You have a main directory named 'cingulata' and several sub-directories, including 'build' and 'tests'.
To create a new test "hello", go to the 'tests' sub-directory of 'cingulata' and create a new directory 'hello':
#!shell
cd tests/
mkdir hello
Inside this directory, you will write your source code 'hello.cxx' and the execution script 'run.sh'.
Let's create a new testing file named 'hello.cxx' doing the addition of two integers:
#!c++
/* compiler includes */
#include <iostream>
#include <fstream>
/* local includes */
#include <integer.hxx>
/* namespaces */
using namespace std;
int main()
{
Integer8 a,b,c;
cin>>a;
cin>>b;
c=a+b;
cout<<c;
FINALIZE_CIRCUIT("hello.blif");
}
As you can see, the two integers a and b are defined using the special type Integer8 and are read from the console. The result is a variable c of type Integer8 which will be displayed on the standard output. The final line specifies that the Boolean circuit associated with this input code will be saved in a file named "hello.blif".
Now, we will create the shell script 'run.sh' with the following content:
#!shell
#!/bin/bash
CURR_DIR=$PWD
FILE=hello
APPS_DIR=$CURR_DIR/../../apps/
mkdir -p input
rm -f input/*.ct
mkdir -p output
rm -f output/*.ct
# Generate keys
echo "FHE key generation"
time $APPS_DIR/generate_keys
echo "Input encryption"
NR_THREADS=1
$APPS_DIR/encrypt -v --public-key fhe_key.pk --threads $NR_THREADS `$APPS_DIR/helper --bit-cnt 8 --msb-first --prefix input/i_ --idx-places 0 5 3`
echo "Homomorphic execution..."
time $APPS_DIR/dyn_omp $FILE'-opt.blif' --threads $NR_THREADS # -v
echo "Output decryption"
OUT_FILES=`ls -v output/*`
$APPS_DIR/helper --from-bin --bit-cnt 8 --msb-first `$APPS_DIR/decrypt --secret-key fhe_key.sk $OUT_FILES`
This script creates two empty directories: 'input' and 'output' (or clean them if they were created before). It calls the binary 'generate_keys' to generate the binary files for the private, public and respectively the evaluation keys. The encryption of the two input variables is done bitwise, on 8 bits (--bit-cnt option) (remember they were defined as Integer8 in the input code), in most significant order first (msb-first option) using a given number of threads. The encrypted bits will be saved in the input directory as individual binary files with the prefix i_ starting from 'i_2' (the first two i_0 and i_1 names being allocated for the 0 and respectively 1 constants).
The homomorphic execution is realized by calling the runtime 'dyn-omp' on the optimized circuit: 'hello-opt.blif' in parallel using $NR_THREADS. Finally, the result is decrypted by looking into the output directory, decrypt each bit and pack them in a 'nice' format using the "helper" script.
You're almost at the end but, before running the test, you will have to create a file 'CMakeLists.txt' into the directory 'hello'. Here is the content of it:
#!cmake
cmake_minimum_required(VERSION 3.0)
set(TEST_NAME hello)
set(SRCS
${TEST_NAME}.cxx
)
set(BLIF_NAME ${TEST_NAME}.blif)
set(BLOP_NAME ${TEST_NAME}-opt.blif)
# choose other than default security params
#set(MODEL bkz_sieve)
#set(MIN_SECU 192)
add_compile_options(-Wall -std=c++11 -Dblif_name="${BLIF_NAME}")
set(GEN_NAME ${TEST_NAME}-gen)
add_executable(${GEN_NAME} ${SRCS})
target_link_libraries(${GEN_NAME} generator)
add_custom_command(OUTPUT ${BLIF_NAME}
COMMAND ./${GEN_NAME} < /dev/null
DEPENDS ${GEN_NAME})
add_custom_command(OUTPUT ${BLOP_NAME}
COMMAND python3 ../../optim/abc_optimize.py -i ${BLIF_NAME} -o ${BLOP_NAME} -v
DEPENDS abc ${BLIF_NAME})
set(XML_PARAMS fhe_params.xml)
set(SCRIPT_DIR ../../../runtime/fhe_fv/script)
add_custom_command(OUTPUT ${XML_PARAMS}
COMMAND bash ${SCRIPT_DIR}/selectParams.sh ${TEST_NAME} ${BLOP_NAME} ${MODEL} ${MIN_SECU}
DEPENDS ${BLOP_NAME})
set(LAST_DEPEND ${XML_PARAMS})
add_custom_target(${TEST_NAME} ALL
DEPENDS ${LAST_DEPEND})
configure_file("run.sh" "run.sh" COPYONLY)
As you can see, at the beginning it specifies information about the C++ compilation options. Afterwards, it calls 'ABC' for the optimization of the initial 'hello.blif' which results in the creation of a new blif file named 'hello-opt.blif'. The parameters of FHE schemes are specified in the XML file: 'fhe_params.xml' and are selected though a shell script, taking as input different options such as the multiplicate depth, the BKZ reduction cost model, the desired security level 'lambda_p', etc.
Note 1: The script python 'graph_info.py' analyses the Boolean circuit specified as a .blif file and gives information about the size of the circuit, the number of particular gates (AND and XOR),the maximal multiplicative depth, etc.
Note 2: The 'CMakeLists.txt' file is very similar from a test to another. You can just copy one from an existing test and slightly modify it, by setting the right test name:
#!cmake
set(TEST_NAME hello)
Once you wrote your 'CMakeLists.txt' file in the directory 'hello', you have to add this directory to the general 'CMakeLists' from the 'test' directory:
#!cmake
cmake_minimum_required(VERSION 3.5)
project(tests)
...
add_subdirectory(hello)
Note 3: In order to avoid to compile the other tests, you may want to comment the associated lines from the CMakeLists file. For example, to remove 'hello' test, just comment the line:
#!cmake
#add_subdirectory(hello)
That's all for the configuration of the application. All you have to do now is to compile and run it. For this, you have to go to the 'build' directory and run:
#!shell
cd ../build/
cmake
make
At the end, in 'build' a new directory named 'hello' is created containing all the necessary files and executables for running the test (the xml file with the FHE parameters, the blif files - the original and optimized one, the script 'run.sh', etc.).
Now, you can finally execute your first application with Cingulata:
#!shell
cd tests/hello/
bash run.sh
If all went well, you can see in the terminal all the steps: the key generation, the encryption (bit by bit), the execution details, and the output result:
#!shell
FHE key generation
Input encryption
Command line arguments:
FHE parameters file fhe_params.xml
Public key file fhe_key.pk
Encrypting message [0] into file input/i_2.ct
Encrypting message [0] into file input/i_3.ct
Encrypting message [0] into file input/i_4.ct
Encrypting message [0] into file input/i_5.ct
Encrypting message [0] into file input/i_6.ct
Encrypting message [1] into file input/i_7.ct
Encrypting message [0] into file input/i_8.ct
Encrypting message [1] into file input/i_9.ct
Encrypting message [0] into file input/i_10.ct
Encrypting message [0] into file input/i_11.ct
Encrypting message [0] into file input/i_12.ct
Encrypting message [0] into file input/i_13.ct
Encrypting message [0] into file input/i_14.ct
Encrypting message [0] into file input/i_15.ct
Encrypting message [1] into file input/i_16.ct
Encrypting message [1] into file input/i_17.ct
Homomorphic execution...
Total execution real time 3.86473 seconds
CPU time:
READ time 0.0944455 seconds, #execs 16
COPY time 0.0457448 seconds, #execs 49
XOR gates execution time 0.0652091 seconds, #execs 27
NOT gates execution time 0.0128676 seconds, #execs 15
AND gates execution time 3.54002 seconds, #execs 7
OR gates execution time 0 seconds, #execs 0
WRITE time 0.0321538 seconds, #execs 8
Maximal number of simultaneously allocated ciphertexts 16
real 0m3,942s
user 0m3,789s
sys 0m0,110s
Output decryption
8
It is not a surprise: the sum of 5 and 3 is 8!
For more complicated examples of applications using Cingulata, go to the tests/ directory.
We hope that you have found this tutorial helpful! If you have any issues or suggestions, please drop us a note on how we can improve !
Enjoy your walk through Cingulata world!