Intel:registered: HE Acceleration Library is an open-source library which provides efficient implementations of integer arithmetic on Galois fields. Such arithmetic is prevalent in cryptography, particularly in homomorphic encryption (HE) schemes. Intel HE Acceleration Library targets integer arithmetic with word-sized primes, typically 30-60 bits. Intel HE Acceleration Library provides an API for 64-bit unsigned integers and targets Intel CPUs. For more details on Intel HE Acceleration Library, see our whitepaper. For tips on best performance, see Performance.
- Intel Homomorphic Encryption (HE) Acceleration Library
- Community Adoption
- Documentation
- Contributing
- Citing Intel HE Acceleration Library
- Contributors
Many cryptographic applications, particularly homomorphic encryption (HE), rely
on integer polynomial arithmetic in a finite field. HE, which enables
computation on encrypted data, typically uses polynomials with degree N a
power of two roughly in the range N=[2^{10}, 2^{17}]. The coefficients of
these polynomials are in a finite field with a word-sized prime, q, up to
q~62 bits. More precisely, the polynomials live in the ring Z_q[X]/(X^N + 1). That is, when adding or multiplying two polynomials, each coefficient of
the result is reduced by the prime modulus q. When multiplying two
polynomials, the resulting polynomials of degree 2N is additionally reduced
by taking the remainder when dividing by X^N+1.
The primary bottleneck in many HE applications is polynomial-polynomial
multiplication in Z_q[X]/(X^N + 1). For efficient implementation, Intel HE
Acceleration Library implements the negacyclic number-theoretic transform
(NTT). To multiply two polynomials, q_1(x), q_2(x) using the NTT, we perform
the FwdNTT on the two input polynomials, then perform an element-wise modular
multiplication, and perform the InvNTT on the result.
Intel HE Acceleration Library implements the following functions:
- The forward and inverse negacyclic number-theoretic transform (NTT)
- Element-wise vector-vector modular multiplication
- Element-wise vector-scalar modular multiplication with optional addition
- Element-wise modular multiplication
For each function, the library implements one or several Intel(R) AVX-512
implementations, as well as a less performant, more readable native C++
implementation. Intel HE Acceleration Library will automatically choose the
best implementation for the given CPU Intel(R) AVX-512 feature set. In
particular, when the modulus q is less than 2^{50}, the AVX512IFMA
instruction set available on Intel IceLake server and IceLake client will
provide a more efficient implementation.
For additional functionality, see the public headers, located in include/hexl
Intel HE Acceleration Library can be built in several ways. Intel HE
Acceleration Library has been uploaded to the Microsoft
vcpkg C++ package manager, which supports
Linux, macOS, and Windows builds. See the vcpkg repository for instructions to
build Intel HE Acceleration Library with vcpkg, e.g. run vcpkg install hexl.
There may be some delay in uploading latest release ports to vcpkg. Intel HE
Acceleration Library provides port files to build the latest version with
vcpkg. For a static build, run vcpkg install hexl --overlay-ports=/path/to/hexl/port/hexl --head. For dynamic build, use the
custom triplet file and run vcpkg install hexl:hexl-dynamic-build --overlay-ports=/path/to/hexl/port/hexl --head --overlay-triplets=/path/to/hexl/port/hexl. For detailed explanation, see
instruction
for building vcpkg port using overlays and use of custom
triplet
provided by vcpkg.
Intel HE Acceleration Library also supports a build using the CMake build system. See below for the instructions to build Intel HE Acceleration Library from source using CMake.
We have tested Intel HE Acceleration Library on the following operating systems:
- Ubuntu 20.04
- macOS 10.15 Catalina
- Microsoft Windows 10
Intel HE Acceleration Library requires the following dependencies:
| Dependency | Version |
|---|---|
| CMake | >= 3.13 * |
| Compiler | gcc >= 7.0, clang++ >= 5.0, MSVC >= 2019 |
* For Windows 10, you must check whether the version on CMake you have can generate the necessary Visual Studio project files. For example, only from CMake 3.14 onwards can MSVC 2019 project files be generated.
In addition to the standard CMake build options, Intel HE Acceleration Library supports several compile-time flags to configure the build. For convenience, they are listed below:
| CMake option | Values | Default | |
|---|---|---|---|
| HEXL_BENCHMARK | ON / OFF | ON | Set to ON to enable benchmark suite via Google benchmark |
| HEXL_COVERAGE | ON / OFF | OFF | Set to ON to enable coverage report of unit-tests |
| HEXL_SHARED_LIB | ON / OFF | OFF | Set to ON to enable building shared library |
| HEXL_DOCS | ON / OFF | OFF | Set to ON to enable building of documentation |
| HEXL_TESTING | ON / OFF | ON | Set to ON to enable building of unit-tests |
| HEXL_TREAT_WARNING_AS_ERROR | ON / OFF | OFF | Set to ON to treat all warnings as error |
To compile Intel HE Acceleration Library from source code, first clone the repository and change directories to where the source has been cloned.
The instructions to build Intel HE Acceleration Library are common to Linux and MacOS.
Then, to configure the build, call
cmake -S . -B buildadding the desired compile-time options with a -D flag. For instance,
to use a non-standard installation directory, configure the build with
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/path/to/installOr, to build Intel HE Acceleration Library as a shared library, call
cmake -S . -B build -DHEXL_SHARED_LIB=ONThen, to build Intel HE Acceleration Library, call
cmake --build buildThis will build the Intel HE Acceleration Library library in the
build/hexl/lib/ directory.
To install Intel HE Acceleration Library to the installation directory, run
cmake --install buildTo compile Intel HE Acceleration Library on Windows using Visual Studio in Release mode, configure the build via
cmake -S . -B build -G "Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=Releaseadding the desired compile-time options with a -D flag (see Compile-time
options). For instance, to use a non-standard
installation directory, configure the build with
cmake -S . -B build -G "Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/path/to/installTo specify the desired build configuration, pass either --config Debug or
--config Release to the build step and install steps. For instance, to build
Intel HE Acceleration Library in Release mode, call
cmake --build build --config ReleaseThis will build the Intel HE Acceleration Library library in the
build/hexl/lib/ or build/hexl/Release/lib directory.
To install Intel HE Acceleration Library to the installation directory, run
cmake --build build --target install --config ReleaseFor best performance, we recommend using Intel HE Acceleration Library on a
Linux system with the clang++-12 compiler. We also recommend using a processor
with Intel AVX512DQ support, with best performance on processors supporting
Intel AVX512-IFMA52. To determine if your processor supports AVX512-IFMA52,
simply look for -- Setting HEXL_HAS_AVX512IFMA printed during the configure
step.
See the below table for setting the modulus q for best performance.
| Instruction Set | Bound on modulus q |
|---|---|
| AVX512-DQ | q < 2^30 |
| AVX512-IFMA52 | q < 2^50 |
Some speedup is still expected for moduli q > 2^30 using the AVX512-DQ instruction set.
To run a set of unit tests via
Googletest, configure and build Intel
HE Acceleration Library with -DHEXL_TESTING=ON (see Compile-time
options).
Then, run
cmake --build build --target unittestThe unit-test executable itself is located at build/test/unit-test on Linux
and Mac, and at build\test\Release\unit-test.exe or
build\test\Debug\unit-test.exe on Windows.
To run a set of benchmarks via Google
benchmark, configure and build Intel HE
Acceleration Library with -DHEXL_BENCHMARK=ON (see Compile-time
options).
Then, run
cmake --build build --target benchOn Windows, run
cmake --build build --target bench --config ReleaseThe benchmark executable itself is located at build/benchmark/bench_hexl on
Linux and Mac, and at build\benchmark\Debug\bench_hexl.exe or
build\benchmark\Release\bench_hexl.exe on Windows.
The example folder has an example of using Intel HE Acceleration Library in a
third-party project.
For optimal performance, Intel HE Acceleration Library does not perform input
validation. In many cases the time required for the validation would be longer
than the execution of the function itself. To debug Intel HE Acceleration
Library, configure and build Intel HE Acceleration Library with
-DCMAKE_BUILD_TYPE=Debug (see Compile-time options).
This will generate a debug version of the library, e.g. libhexl_debug.a, that
can be used to debug the execution. In Debug mode, Intel HE Acceleration
Library will also link against Address
Sanitizer.
Note, enabling CMAKE_BUILD_TYPE=Debug will result in a significant
runtime overhead.
To enable verbose logging for the benchmarks or unit-tests in a Debug build,
add the log level as a command-line argument, e.g. build/benchmark/bench_hexl --v=9. See easyloggingpp's
documentation
for more details.
Intel HE Acceleration Library is single-threaded and thread-safe.
Intel HE Acceleration Library has been integrated to the following homomorphic encryption libraries:
See also the Intel Homomorphic Encryption Toolkit for example uses cases using Intel HE Acceleration Library.
Please let us know if you are aware of any other uses of Intel HE Acceleration Library.
Intel HE Acceleration Library supports documentation via Doxygen. See https://intel.github.io/hexl for the latest Doxygen documentation.
To build documentation, first install doxygen and graphviz, e.g.
sudo apt-get install doxygen graphvizThen, configure Intel HE Acceleration Library with -DHEXL_DOCS=ON (see
Compile-time options).
To build Doxygen documentation, after configuring Intel HE Acceleration
Library with -DHEXL_DOCS=ON, run
cmake --build build --target docs
To view the generated Doxygen documentation, open the generated
docs/doxygen/html/index.html file in a web browser.
Intel HE Acceleration Library welcomes external contributions. To know more about contributing please go to CONTRIBUTING.md.
We encourage feedback and suggestions via Github Issues as well as discussion via Github Discussions.
Public headers reside in the hexl/include folder.
Private headers, e.g. those containing Intel(R) AVX-512 code should not be put
in this folder.
To cite Intel HE Acceleration Library, please use the following BibTeX entry.
@misc{IntelHEXL,
author={Boemer, Fabian and Kim, Sejun and Seifu, Gelila and de Souza, Fillipe DM and Gopal, Vinodh and others},
title = {{I}ntel {HEXL} (release 1.2)},
howpublished = {\url{https://github.com/intel/hexl}},
month = september,
year = 2021,
key = {Intel HEXL}
} @misc{IntelHEXL,
author={Boemer, Fabian and Kim, Sejun and Seifu, Gelila and de Souza, Fillipe DM and Gopal, Vinodh and others},
title = {{I}ntel {HEXL} (release 1.1)},
howpublished = {\url{https://github.com/intel/hexl}},
month = may,
year = 2021,
key = {Intel HEXL}
} @misc{IntelHEXL,
author={Boemer, Fabian and Kim, Sejun and Seifu, Gelila and de Souza, Fillipe DM and Gopal, Vinodh and others},
title = {{I}ntel {HEXL} (release 1.0)},
howpublished = {\url{https://github.com/intel/hexl}},
month = april,
year = 2021,
key = {Intel HEXL}
}The Intel contributors to this project, sorted by last name, are
- Paky Abu-Alam
- Flavio Bergamaschi
- Fabian Boemer
- Jeremy Bottleson
- Jack Crawford
- Fillipe D.M. de Souza
- Hamish Hunt
- Sergey Ivanov
- Akshaya Jagannadharao
- Jingyi Jin
- Sejun Kim
- Nir Peled
- Kylan Race
- Jose Rojas (lead)
- Gelila Seifu
In addition to the Intel contributors listed, we are also grateful to contributions to this project that are not reflected in the Git history: