Building Your Program with E3

Bob and Alice

Two executable files can be built in E3: bob.exe and alice.exe. bob.exe always returns an encrypted set of computation results if not decrypted otherwise using cgt.exe. n the other hand, alice.exe allows the user to immediately access the decrypted result. In order to do so, a slight modification in your C++ codes is necessary. First, you need to include the "e3key.h" file in your program. Then, you only need to wrap your variables with 'e3::decrypt()'. Keep your variables as they are when declaring them. Here is a simple example:

 #include <iostream>
 #include "e3int.h"

 #include "e3key.h"

 using SecureInt = MyTypeInt<32>;
 SecureInt f(SecureInt x, SecureInt y){ return x + y; }

 int main()
 {
     SecureInt x = _7_EN, y = _3_ENn;
     auto z = f(x, y);
     std::cout << e3::decrypt(x) << "-" << e3::decrypt(y) << "=" << e3::decrypt(z) << "\n";
 }

When the computation results are printed, they will be automatically decrypted.

NOTE: when compiled for bob.exe, the decryption function is just a mock-up that returns the ciphertext.

Automatic Building

E3 provides two methods for building a program: automatic building using the make command and manual building. Automatic building can build the program using one simple command, while manual building requires multiple steps. Automatic building is explained in detail in this section.

Using Built-In Encryption Library

By default, E3 includes a built-in encryption library. To build bob.exe from your program using the built-in encryption library, go to the e3/src directory and specify the pathway to your program directory:

cd e3/src
make bob USER=[pathway to user program directory] CGT=[Optional: pathway to configuration file]

To build alice.exe, use a similar command:

cd e3/src
make alice USER=[pathway to user program directory] CGT=[Optional: pathway to configuration file]

Note that, in both the alice and bob commands, the CGT flag is optional if your configuration file is in the program directory with the C++ file. If the configuration file is in a different directory, then the CGT flag must be used to specify the pathway.

NOTE: When you are building programs more than once (e.g. using other encryption library), make sure to clean:

make clean

make clean cleans all the FHE API files, executable files, and object files.
make cleankey cleans all files related to keys.
make cleanall runs both make clean and make cleanall.
make c cleans everything generated by building your program on E3 platform.

Using External Encryption Library

If you are using external encryption library (e.g. TFHE, HElib, FHEW, SEAL, PALISADE), you need to first install the libraries. See [Installing External Libraries] section for more information on installing the libraries. Once the libraries are installed, build your program. To build bob.exe, run:

cd e3/src
make bob USER=[user program directory] CGT=[Optional: pathway to cfg file] [library name]=1

To build alice, use a similar command:

cd e3/src
make alice USER=[user program directory] CGT=[Optional: pathway to cfg file] [library name]=1

For example,

make bob USER=../../user/to_be_encrypted TFHE=1

Here, your program and corresponding configuration file are stored in 'user/to_be_encrypted' directory outside 'e3' directory, and, thus, a relative path from 'e3/src' directory is specified. TFHE library is used for encryption.

Running the Executable and Decrypting the Output

Once the executable bob.exe is built, you can run it to get the encrypted result:

./bob.exe

To decrypt the received output (using the cgt.exe tool), run:

./bob.exe | ./cgt.exe dec [-c cfg] [-n name] [-s bitsize]

Similarly, to run the alice.exe executable:

./alice.exe

This will immediately display the decrypted output.

Manual Building

You can also manually build and run your program on E3 framework. This section provides details on how to build your program manually.

Using Built-In Encryption Library

To build bob.exe or alice.exe manually using the built-in encryption library, follow these steps:

1. You need to build the build tool (cgt.exe):

cd e3/src
make cgt.exe

2. Then, the framework needs to generate appropriate set of secret/evaluation keys. This process is required once per program. You can re-use the same keys for different programs by setting the configuration file parameters accordingly, given that the keys are stored in a file. Generation of keys is required before the first compilation, since the secret key is needed to encrypt the constants in the source code. As a result of following command, you will get a set of private/evaluation keys, secint.cpp, secint.h, and secint.inc.

./cgt.exe gen -c [user configuration file] -d [user program directory]

3. You also need to compile object files needed to build bob.exe and alice.exe. This task will be automatically done using the amalgamation script (amalgam.sh). As a result of following command, you will get cgtshared.cpp and cgtshared.h. Run:

./amalgam.sh

If you are building alice.exe, in addition to the previous command, you also need to run:

bash amalkey.sh

This command will create the cgtkey.cpp and cgtkey.h files required to decrypt the output of alice.exe.

4. The last part of the building process is to compile and link all necessary files (cgtshared.cpp, secint.cpp, cgtkey.cpp for alice, and user codes) to generate the executable. To build bob.exe: In Linux, run:

g++ -I./ -I[user program directory] cgtshared.cpp secint.cpp [user program directory]/*.cpp -o ./bob.exe

In Windows, run:

cl -EHsc -I./ -I[user program directory] cgtshared.cpp secint.cpp [user program directory]/*.cpp -Febob.exe

To build alice.exe: In Linux, run:

g++ -I./ -I[user program directory] cgtshared.cpp secint.cpp cgtkey.cpp [user program directory]/*.cpp -DE3KEY=1 -o alice.exe

In Windows, run:

cl -EHsc -I./ -I[user program directory] cgtshared.cpp secint.cpp cgtkey.cpp [user program directory]/*.cpp -DE3KEY=1 -Fealice.exe