Skip to content

Latest commit

 

History

History
249 lines (208 loc) · 8.87 KB

README.md

File metadata and controls

249 lines (208 loc) · 8.87 KB
Raw

Introduction to hekit

The hekit tool can be used by the user to easily set up the required environment to evaluate homomorphic encryption technology.

Contents

Global Options

-h, --help: shows the help message.

--version: displays Intel HE toolkit version.

--debug: enables debug mode. Currently only prints a backtrace of error raised.

--config CONFIG: use a non-default configuration file instead of default path.

Commands

The option -h can be used to get details about the arguments and usage of each command.

Command Description Usage
init Initializes hekit. hekit init [--default-config]
list Lists installed components. hekit list
install Installs components defined in recipe file. hekit install [--recipe_arg RECIPE_ARG] [-f] recipe-file
build Builds components defined in recipe file. hekit build [--recipe_arg RECIPE_ARG] [-f] recipe-file
fetch Fetches components defined in recipe file hekit fetch [--recipe_arg RECIPE_ARG] recipe-file
remove Uninstalls instances or components. hekit remove [--all] [component] [instance]
check-dependencies Checks system dependencies. hekit check-dependencies dependencies-file
new Create a new project. hekit new [--directory DIRECTORY] [--based-on {logistic-regression,psi,secure-query}] name
plugins Handle third party plugins. See Plugins. hekit plugins {list,install,remove,enable,disable}
docker-build Builds the HE Toolkit Docker container. See Docker Build. hekit docker-build [--id ID] [--clean] [--check-only] [--enable {vscode,...}] [--platform PLATFORM]
gen-primes Generates primes in range [n, m] where n, m are positive integers. See Tools. hekit gen-primes start stop
algebras Generates ZZ_p[x]/phi(X) algebras. . See Tools. hekit algebras [-p P] [-d D] [--no-corrected] [--no-header]

Configuration file

The configuration file defines the working directory where the libraries will be available, for instance:

repo_location = "~/.hekit/components"

The commands list, fetch, build, install and remove use by default a configuration file located in ~/.hekit/default.config. However, the argument --config CONFIG_FILE can be used to define the location of a non-default configuration file.

The toolkit provides a default.config file that can be used as a template and it is a valid option for the --config argument.

Recipe file

The hekit tool relies on recipe files written in TOML to perform its fetch, build, and install commands.

Simple example

The recipe file is a TOML file that defines the libraries and the required actions to install them, as shown in the following example:

[[library]]
skip = false
version = "5.2.1"
name = "instance"
init_fetch_dir = "fetch"
init_build_dir = "build"
init_install_dir = "build"
export_install_dir = "install"
fetch = "git clone https://gitlab.com/library/library-release.git --branch %name%"
pre-build = """cmake -S %init_fetch_dir%/library-release -B %init_build_dir%
               -DWITH_INTEL_HEXL=ON
               -DHEXL_DIR=$%hexl%/export_cmake$"""
build = "cmake --build %init_build_dir% -j"
post-build = ""
install = "cmake --install %init_install_dir%"
# Dependencies
hexl = "hexl/1.2.3"

In the above example, the component name is library and the instance name is instance, which must be unique. This will create a directory in ~/.hekit/components of the structure library/instance/{fetch,build,install}. This allows users to have multiple instances of the same component on their system and to be able to link them in a flexible manner.

The example library also has a dependency listed as hexl = "hexl/1.2.3" which is used to back substitute the export_cmake value of that instance elsewhere in the recipe file.

The recipes directory contains default recipes for setting up a working environment.

Back substitution in recipe files

The value of the pair (key = "value") in the recipe file can be reused in other sections of the file. This can be achieved using the following options for back substitution

%key% : back substitute a value from within the same instance.

$component/instance/key$ : back substitutes the key from a specific instance.

!key! : back substitute a value defined from an external source. If --recipe_arg is not set, the user will be prompted to provide a value.

Examples

init

Although optional, the init command can be used to add hekit to the PATH variable and enable the tab completion feature. To initialize hekit for the first time run

cd <he-toolkit-root-directory>
./hekit init

Afterwards source your shell initialization file e.g. ~/.bashrc. Now you can run the hekit commands from anywhere.

Additionally, the init command can be executed with the --default-config flag. This will create the directory ~/.hekit in the user's home directory with the default.config and plugins/plugins.toml files. This directory will be used to store all components and third party plugins installed by hekit.

cd <he-toolkit-root-directory>
./hekit init --default-config

list

In order to check the installed components, execute the following command

hekit list

fetch, build and install

The install command can be used to fetch, build, and install the required libraries.

hekit install ./recipes/default.toml

Using the fetch and build commands, the user can direct hekit to perform specific actions up to the one specified. For example, for fetching libraries

hekit fetch ./recipes/examples.toml --recipe_arg "toolkit-path=~/he-toolkit"

By default, if actions such as build or install were executed successfully, the next time that the command is executed, they are going to be skipped. For re-executing actions such as build or install, the flag --force must be set

hekit build ./recipes/examples.toml --force

remove

In order to uninstall a specific instance, execute the remove command with the component and instance name

hekit remove hexl 1.2.3

For uninstalling all instances of a component, execute the remove command with only the component name

hekit remove hexl

Lastly, it is possible to uninstall all components using the following command

hekit remove --all

check-dependencies

To check system dependencies, execute

hekit check-dependencies dependencies.txt

new

The command new can be used to create a new project. When it is executed with the option -–based-on, it will create a copy of the base project, keeping its directory structure.

hekit new my-secure-query --based-on secure-query

However, when the command is executed without -–based-on

hekit new example

It will create the following directory structure:

Projects
└── example
      |- CMakeLists.txt
      |- README.md
      └── include
            └── example.h
      └── recipes
            └── example.toml
      └── src
            └── example.cpp

The following actions should be completed to build the new project:

  • Open the toml file inside the recipes directory and replace -DFLAG=TBD with the desired CMake flags for your project.

  • Open CMakeLists.txt and uncomment the statements for find_package and target_link_libraries of the required library. If other dependencies are needed, for instance Threads, the file must be updated to include and compile them.

  • Add and/or write the code of the new project in the .cpp and .h files created by the command.

Tab completion

As an optional feature, the user is able to enable tab completion using the argcomplete library.

As described in its documentation, the following actions are required to enable this functionality

  • Install argcomplete:

    pip install argcomplete

  • If you have used the hekit init command then you are ready to start using the feature. Otherwise, if you would like to set it manually add the following line to your shell initialization script e.g. .bashrc file

    eval "$(register-python-argcomplete hekit.py)"