SEAL/README.md

647 строки
28 KiB
Markdown
Исходник Обычный вид История

2019-01-30 10:03:51 +03:00
# Microsoft SEAL
2018-11-09 21:39:54 +03:00
2019-10-01 06:39:21 +03:00
Microsoft SEAL is an easy-to-use open-source ([MIT licensed](LICENSE)) homomorphic
encryption library developed by the Cryptography and Privacy Research group at
2020-01-29 04:30:20 +03:00
Microsoft. Microsoft SEAL is written in modern standard C++ and is easy to compile
and run in many different environments. For more information about the Microsoft SEAL
project, see
2019-10-01 06:39:21 +03:00
[sealcrypto.org](https://www.microsoft.com/en-us/research/project/microsoft-seal).
2018-11-09 21:39:54 +03:00
2020-01-24 08:48:47 +03:00
This document pertains to Microsoft SEAL version 3.5. Users of previous versions
2019-10-01 06:39:21 +03:00
of the library should look at the [list of changes](Changes.md).
2018-11-09 21:39:54 +03:00
2019-01-30 07:46:42 +03:00
# Contents
2019-07-17 02:03:28 +03:00
2019-05-24 09:00:03 +03:00
- [Introduction](#introduction)
2019-05-24 19:30:41 +03:00
- [Core Concepts](#core-concepts)
2019-05-24 09:00:03 +03:00
- [Homomorphic Encryption](#homomorphic-encryption)
2019-05-24 19:30:41 +03:00
- [Microsoft SEAL](#microsoft-seal-1)
2019-05-24 09:00:03 +03:00
- [Installing Microsoft SEAL](#installing-microsoft-seal)
2019-01-30 07:46:42 +03:00
- [Windows](#windows)
2019-01-30 19:44:19 +03:00
- [Linux and macOS](#linux-and-macos)
- [From NuGet package](#from-nuget-package)
2019-10-06 11:21:27 +03:00
- [Enabling Optional Dependencies](#enabling-optional-dependencies)
2019-10-01 06:39:21 +03:00
- [Microsoft GSL](#microsoft-gsl)
- [ZLIB](#zlib)
2019-10-06 11:21:27 +03:00
- [Building Microsoft SEAL for .NET](#building-microsoft-seal-for-net)
2019-01-30 07:46:42 +03:00
- [Windows](#windows-1)
2019-01-30 19:44:19 +03:00
- [Linux and macOS](#linux-and-macos-1)
2019-05-31 03:24:25 +03:00
- [Getting Started](#getting-started)
- [Contributing](#contributing)
2019-02-21 03:17:53 +03:00
- [Citing Microsoft SEAL](#citing-microsoft-seal)
2019-01-30 07:46:42 +03:00
2019-05-24 09:00:03 +03:00
# Introduction
2019-07-17 02:03:28 +03:00
2019-05-24 19:30:41 +03:00
## Core Concepts
2019-07-17 02:03:28 +03:00
2019-10-01 06:39:21 +03:00
Most encryption schemes consist of three functionalities: key generation, encryption,
and decryption. Symmetric-key encryption schemes use the same secret key for both
encryption and decryption; public-key encryption schemes use separately a public
key for encryption and a secret key for decryption. Therefore, public-key encryption
schemes allow anyone who knows the public key to encrypt data, but only those who
know the secret key can decrypt and read the data. Symmetric-key encryption can be
used for efficiently encrypting very large amounts of data, and enables secure
outsourced cloud storage. Public-key encryption is a fundamental concept that
enables secure online communication today, but is typically much less efficient
than symmetric-key encryption.
While traditional symmetric- and public-key encryption can be used for secure storage
and communication, any outsourced computation will necessarily require such encryption
layers to be removed before computation can take place. Therefore, cloud services
providing outsourced computation capabilities must have access to the secret keys,
and implement access policies to prevent unauthorized employees from getting access
to these keys.
2019-05-24 19:30:41 +03:00
2019-05-24 09:00:03 +03:00
## Homomorphic Encryption
2019-07-17 02:03:28 +03:00
2019-10-01 06:39:21 +03:00
Homomorphic encryption refers to encryption schemes that allow the cloud to compute
directly on the encrypted data, without requiring the data to be decrypted first.
The results of such encrypted computations remain encrypted, and can be only decrypted
with the secret key (by the data owner). Multiple homomorphic encryption schemes
with different capabilities and trade-offs have been invented over the past decade;
most of these are public-key encryption schemes, although the public-key functionality
may not always be needed.
Homomorphic encryption is not a generic technology: only some computations on
encrypted data are possible. It also comes with a substantial performance overhead,
so computations that are already very costly to perform on unencrypted data are
likely to be infeasible on encrypted data. Moreover, data encrypted with homomorphic
encryption is many times larger than unencrypted data, so it may not make sense to
encrypt, e.g., entire large databases, with this technology. Instead, meaningful
use-cases are in scenarios where strict privacy requirements prohibit unencrypted
cloud computation altogether, but the computations themselves are fairly lightweight.
Typically, homomorphic encryption schemes have a single secret key which is held
by the data owner. For scenarios where multiple different private data owners wish
to engage in collaborative computation, homomorphic encryption is probably not
a reasonable solution.
Homomorphic encryption cannot be used to enable data scientist to circumvent GDPR.
For example, there is no way for a cloud service to use homomorphic encryption to
draw insights from encrypted customer data. Instead, results of encrypted computations
remain encrypted and can only be decrypted by the owner of the data, e.g., a cloud
service customer.
2019-05-24 09:00:03 +03:00
2019-05-24 19:30:41 +03:00
## Microsoft SEAL
2019-07-17 02:03:28 +03:00
2019-10-01 06:39:21 +03:00
Microsoft SEAL is a homomorphic encryption library that allows additions and
multiplications to be performed on encrypted integers or real numbers. Other
operations, such as encrypted comparison, sorting, or regular expressions, are
in most cases not feasible to evaluate on encrypted data using this technology.
Therefore, only specific privacy-critical cloud computation parts of programs
should be implemented with Microsoft SEAL.
It is not always easy or straightfoward to translate an unencrypted computation
into a computation on encrypted data, for example, it is not possible to branch
on encrypted data. Microsoft SEAL itself has a steep learning curve and requires
the user to understand many homomorphic encryption specific concepts, even though
in the end the API is not too complicated. Even if a user is able to program and
run a specific computation using Microsoft SEAL, the difference between efficient
and inefficient implementations can be several orders of magnitude, and it can be
hard for new users to know how to improve the performance of their computation.
Microsoft SEAL comes with two different homomorphic encryption schemes with very
different properties. The BFV scheme allows modular arithmetic to be performed on
encrypted integers. The CKKS scheme allows additions and multiplications on encrypted
real or complex numbers, but yields only approximate results. In applications such
as summing up encrypted real numbers, evaluating machine learning models on encrypted
data, or computing distances of encrypted locations CKKS is going to be by far the
best choice. For applications where exact values are necessary, the BFV scheme is
the only choice.
2019-05-24 09:00:03 +03:00
# Installing Microsoft SEAL
2018-12-01 04:41:23 +03:00
## Windows
2019-10-01 06:39:21 +03:00
Microsoft SEAL comes with a Microsoft Visual Studio 2019 solution file `SEAL.sln`
that can be used to conveniently build the library, examples, and unit tests. Visual
2019-10-06 21:59:09 +03:00
Studio 2017 version 15.3 or newer is required to build Microsoft SEAL.
#### Platform
2019-10-01 06:39:21 +03:00
The Visual Studio solution `SEAL.sln` is configured to build Microsoft SEAL both
for `Win32` and `x64` platforms. Please choose the right platform before building
Microsoft SEAL. The `SEALNetNative` project or the .NET wrapper library `SEALNet`
can only be built for `x64`.
2018-12-01 04:41:23 +03:00
2019-01-30 03:12:43 +03:00
#### Debug and Release builds
2018-12-01 04:41:23 +03:00
2019-10-01 06:39:21 +03:00
You can easily switch from Visual Studio build configuration menu whether Microsoft
SEAL should be built in `Debug` mode (no optimizations) or in `Release` mode. Please
note that `Debug` mode should not be used except for debugging Microsoft SEAL itself,
as the performance will be orders of magnitude worse than in `Release` mode.
2018-12-01 04:41:23 +03:00
2019-10-06 21:59:09 +03:00
#### Building Microsoft SEAL
2018-12-01 04:41:23 +03:00
2019-10-01 06:39:21 +03:00
Build the SEAL project `native\src\SEAL.vcxproj` from `SEAL.sln`. This results in
the static library `seal.lib` to be created in `native\lib\$(Platform)\$(Configuration)`.
When linking with applications, you need to add `native\src\` (full path) as an
include directory for Microsoft SEAL header files.
2018-12-01 04:41:23 +03:00
2019-10-06 21:59:09 +03:00
#### Building Examples
2018-12-01 04:41:23 +03:00
Build the SEALExamples project `native\examples\SEALExamples.vcxproj` from `SEAL.sln`.
This results in an executable `sealexamples.exe` to be created in
`native\bin\$(Platform)\$(Configuration)`.
2018-12-01 04:41:23 +03:00
2019-10-06 21:59:09 +03:00
#### Building Unit Tests
2018-12-01 04:41:23 +03:00
2019-05-24 09:00:03 +03:00
The unit tests require the Google Test framework to be installed. The appropriate
2019-10-01 06:39:21 +03:00
NuGet package is already listed in `native\tests\packages.config`, so once you
attempt to build the SEALTest project `native\tests\SEALTest.vcxproj` from `SEAL.sln`
Visual Studio will automatically download and install it for you.
2018-12-01 04:41:23 +03:00
## Linux and macOS
2018-12-01 04:41:23 +03:00
2019-10-01 06:39:21 +03:00
Microsoft SEAL is very easy to configure and build in Linux and macOS using CMake
(>= 3.12). A modern version of GNU G++ (>= 6.0) or Clang++ (>= 5.0) is needed. In macOS
the Xcode toolchain (>= 9.3) will work.
2018-12-01 04:41:23 +03:00
2019-05-24 09:00:03 +03:00
In macOS you will need CMake with command line tools. For this, you can either
2018-12-01 04:41:23 +03:00
1. install the cmake package with [Homebrew](https://brew.sh), or
2019-10-06 21:59:09 +03:00
2. download CMake directly from [cmake.org/download](https://cmake.org/download) and
[enable command line tools](https://stackoverflow.com/questions/30668601/installing-cmake-command-line-tools-on-a-mac).
2018-12-01 04:41:23 +03:00
Below we give instructions for how to configure, build, and install Microsoft SEAL either
2018-12-01 04:41:23 +03:00
system-wide (global install), or for a single user (local install). A system-wide
install requires elevated (root) privileges.
2019-10-06 11:21:27 +03:00
#### Debug and Release Modes
2018-12-01 04:41:23 +03:00
You can easily switch from CMake configuration options whether Microsoft SEAL should be
built in `Debug` mode (no optimizations) or in `Release` mode. Please note that `Debug`
mode should not be used except for debugging Microsoft SEAL itself, as the performance
will be orders of magnitude worse than in `Release` mode.
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
#### Building Microsoft SEAL
2018-12-01 04:41:23 +03:00
We assume that Microsoft SEAL has been cloned into a directory called `SEAL` and all
commands presented below are assumed to be executed in the directory `SEAL`.
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
You can build Microsoft SEAL for your machine by executing the following commands:
2018-12-01 04:46:17 +03:00
````
cd native/src
2018-12-01 04:46:17 +03:00
cmake .
make
cd ../..
2018-12-01 04:46:17 +03:00
````
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
#### Building Examples
After building Microsoft SEAL, you can build the examples as follows:
2018-12-01 04:46:17 +03:00
````
cd native/examples
2018-12-01 04:46:17 +03:00
cmake .
make
cd ../..
2018-12-01 04:46:17 +03:00
````
2019-10-06 11:21:27 +03:00
The `sealexamples` executable can now be found in `native/bin/`.
2018-12-01 04:41:23 +03:00
2019-10-06 21:59:09 +03:00
#### Building Unit Tests
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
To build the unit tests you will need the [GoogleTest](https://github.com/google/googletest)
framework, which is included in Microsoft SEAL as a git submodule. To download the GoogleTest
source files, do:
````
git submodule update --init
````
2019-10-06 11:21:27 +03:00
This needs to be executed only once, and can be skipped if Microsoft SEAL was cloned with
`git --recurse-submodules`. To build the tests, do:
2018-12-01 04:46:17 +03:00
````
cd native/tests
2018-12-01 04:46:17 +03:00
cmake .
make
cd ../..
2018-12-01 04:46:17 +03:00
````
2019-10-06 11:21:27 +03:00
The `sealtest` executable can now be found in `native/bin/`. All unit tests should pass
successfully.
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
### Installing Microsoft SEAL
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
If you have root access to the system you can install Microsoft SEAL system-wide as follows:
````
cd native/src
cmake .
make
sudo make install
cd ../..
````
To instead install Microsoft SEAL locally, e.g., to `~/mylibs/`, do the following:
2018-12-01 04:46:17 +03:00
````
cd native/src
2019-10-06 11:21:27 +03:00
cmake . -DCMAKE_INSTALL_PREFIX=~/mylibs
2018-12-01 04:46:17 +03:00
make
make install
cd ../..
2018-12-01 04:46:17 +03:00
````
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
### Linking with Microsoft SEAL through CMake
2018-12-01 04:41:23 +03:00
It is very easy to link your own applications and libraries with Microsoft SEAL if
you use CMake. Simply add the following to your `CMakeLists.txt`:
2018-12-01 04:46:17 +03:00
````
find_package(SEAL 3.4 REQUIRED)
2019-10-06 11:21:27 +03:00
target_link_libraries(<your target> SEAL::seal)
````
If Microsoft SEAL was installed globally, the above `find_package` command will likely
find the library automatically. To link with a locally installed Microsoft SEAL, e.g.,
installed in `~/mylibs` as described above, you may need to tell CMake where to look for
Microsoft SEAL when you configure your application by running:
2019-10-06 11:21:27 +03:00
````
cd <directory containing your CMakeLists.txt>
cmake . -DCMAKE_PREFIX_PATH=~/mylibs
2018-12-01 04:46:17 +03:00
````
2018-12-01 04:41:23 +03:00
## From NuGet package
For .NET developers the easiest way of installing Microsoft SEAL is by using the
multi-platform NuGet package available at
[NuGet.org](https://www.nuget.org/packages/Microsoft.Research.SEALNet). Simply add
this package into your .NET project as a dependency and you are ready to go.
# Enabling Optional Dependencies
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
Microsoft SEAL has no required dependencies, but certain optional features can be
enabled if it is compiled with support for specific third-party libraries.
## Microsoft GSL
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
Microsoft GSL (Guidelines Support Library) is a header-only library that implements
two convenient (templated) data types: `gsl::span` and `gsl::multi_span`. These
are *view types* that provide safe (bounds-checked) array access to memory. For
example, if Microsoft GSL is available, Microsoft SEAL can allow `BatchEncoder`
2019-10-06 11:21:27 +03:00
and `CKKSEncoder` to encode from and decode to a `gsl::span` instead of `std::vector`,
which can have significant benefit in performance. Additionally, `BatchEncoder` allows
2019-10-06 11:21:27 +03:00
access to the slot data alternatively through a two-dimensional `gsl::multi_span`,
reflecting the batching slot structure. Also the `Ciphertext` class allows the
ciphertext data to be accessed hierarchically through a `gsl::multi_span`.
#### Microsoft GSL in Windows
To build Microsoft SEAL with support for Microsoft GSL, clone first the Microsoft GSL
library from [GitHub.com/Microsoft/GSL](https://GitHub.com/Microsoft/GSL) to some
convenient directory, e.g., `C:\MyLibs\GSL` in this example.
Next, you will need to signal Microsoft SEAL to enable Microsoft GSL support by
creating a new Windows environment variable `MSGSL_ROOT`, and setting its value to
`C:\MyLibs\GSL\include`. Restart Visual Studio at this point if you had it open,
otherwise it will not have captured the newly created environment variable.
2019-10-06 11:21:27 +03:00
Rebuilding Microsoft SEAL should now automatically detect that Microsoft GSL is
available, and enable both `gsl::span` and `gsl::multi_span` support. To disable
Microsoft GSL support, delete the `MSGSL_ROOT` environment variable, restart Visual
Studio, and rebuild Microsoft SEAL.
If Microsoft SEAL is built with Microsoft GSL support, any programs or libraries
consuming Microsoft SEAL will need access to the Microsoft GSL header files, so you
need to add `$(MSGSL_ROOT)` to *Additional Include Directories* under the *C/C++* tab
in your Visual Studio project properties. Note that in the Microsoft SEAL projects
this has already been set for you, so all projects in `SEAL.sln` should work without
change.
2019-10-06 11:21:27 +03:00
#### Microsoft GSL in Linux and macOS
On some Linux distributions Microsoft GSL can be conveniently obtained through
a package manager, e.g., on Ubuntu it suffices to install the package `libmsgsl-dev`.
Alternatively, you can simply clone it from
[GitHub.com/Microsoft/GSL](https://github.com/Microsoft/GSL). When installed with
a package manager, CMake will likely detect the Microsoft GSL location automatically.
Otherwise, if Microsoft GSL is cloned to `~/mylibs/GSL`, you need to provide CMake
with this location when building Microsoft SEAL as follows:
2018-12-01 04:46:17 +03:00
````
2019-10-06 11:21:27 +03:00
cd native/src
cmake . -DMSGSL_ROOT=~/mylibs/GSL/include
2018-12-01 04:46:17 +03:00
make
````
Note that you may need to give the same `-DMSGSL_ROOT=~/mylibs/GSL/include` hint
2019-10-06 11:21:27 +03:00
to CMake when configuring your own applications linking with Microsoft SEAL.
## ZLIB
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
ZLIB is a widely used compression library that implements the DEFLATE compression
algorithm. Microsoft SEAL can use ZLIB (if present) to automatically compress data
2019-10-06 11:21:27 +03:00
that is serialized. For example, in some cases `Ciphertext` objects consist of a large
number of integers modulo specific prime numbers (`coeff_modulus` primes). When using
the CKKS scheme, although these prime numbers can often be quite small (e.g., 30 bits),
the numbers are nevertheless serialized as 64-bit integers. In this case, more than
half of data in a ciphertext are zeros that can be compressed away with a compression
library, such as ZLIB. The BFV scheme benefits typically less from this technique, because
the prime numbers used for the `coeff_modulus` encryption parameter tend to be larger,
and integers modulo these prime numbers fill more of each 64-bit word. The compression is
2019-10-06 11:21:27 +03:00
not only applied to `Ciphertext` objects, but to every serializable Microsoft SEAL object.
If ZLIB is detected by CMake, it will be automatically used for serialization (see
`Serialization::compr_mode_default` in `native/src/seal/serialization.h`. However, it is
2019-10-06 11:21:27 +03:00
always possible to explicitly pass `compr_mode_type::none` to serialization methods to
disable compression.
**WARNING:** The compression rate for a `SecretKey` can (in theory at least) reveal
2019-10-06 11:21:27 +03:00
information about the key. In most common applications of Microsoft SEAL the size of
a `SecretKey` would not be deliberately revealed to untrusted parties. If this is
a concern, one can always save the `SecretKey` in an uncompressed form by passing
`compr_mode_type::none` to `SecretKey::save`.
2018-12-01 04:41:23 +03:00
2019-10-06 11:21:27 +03:00
#### ZLIB in Windows
ZLIB is usually not found on a typical Windows system. You can clone it from
[GitHub.com/madler/zlib](https://github.com/madler/zlib) to some convenient directory,
e.g., `C:\MyLibs\zlib` in this example. You need to build ZLIB first by opening
*Developer Command Prompt for VS 2019*, go to `C:\MyLibs\zlib`, and run
2019-10-06 11:21:27 +03:00
````
cmake .
cmake --build . --config Release
````
Next, you will need to signal Microsoft SEAL to enable ZLIB support by creating a new
Windows environment variable `ZLIB_ROOT`, and setting its value to `C:\MyLibs\zlib`.
Restart Visual Studio at this point if you had it open, otherwise it will not have
captured the newly created environment variable. Rebuilding Microsoft SEAL should now
automatically detect that ZLIB is available, and enable support for
`compr_mode_type::deflate`. To disable ZLIB support, delete the `ZLIB_ROOT` environment
variable, restart Visual Studio, and rebuild Microsoft SEAL.
2019-10-06 11:21:27 +03:00
#### ZLIB in Linux and macOS
The ZLIB (development package) can be conveniently obtained through a package manager
on most Linux distributions, e.g., on Ubuntu it suffices to install the package
`zlib1g-dev`. Alternatively, clone from [GitHub.com/madler/zlib](GitHub.com/madler/zlib)
and build it yourself. For example, suppose you have cloned ZLIB to `~/mylibs/zlib`.
To build ZLIB, simply execute:
2019-10-06 11:21:27 +03:00
````
cd ~/mylibs/zlib
cmake .
make
````
If ZLIB was installed with a package manager, CMake will likely detect the location
of ZLIB automatically. Otherwise, if ZLIB was built in `~/mylibs/zlib`, you need
to provide CMake with this location when building Microsoft SEAL as follows:
2019-10-06 11:21:27 +03:00
````
cd native/src
cmake . -DZLIB_ROOT=~/mylibs/zlib
make
````
# Building Microsoft SEAL for .NET
Microsoft SEAL provides a .NET Standard library that wraps the functionality in
Microsoft SEAL for use in .NET development.
## Windows
The Microsoft Visual Studio 2019 solution file `SEAL.sln` contains the projects necessary
to build the .NET assembly, a backing native shared library, .NET examples, and unit
tests.
#### Native library
Microsoft SEAL for .NET requires a native library that is invoked by the managed .NET
library. Build the SEALNetNative project `dotnet\native\SEALNetNative.vcxproj` from
`SEAL.sln`. Building SEALNetNative results in the dynamic library `sealnetnative.dll`
to be created in `dotnet\lib\$(Platform)\$(Configuration)`. This library is meant to
be used only by the .NET library, not by end users, and needs to be present in the same
directory as your executable when running a .NET application.
2019-01-30 03:12:43 +03:00
#### .NET library
2019-05-24 09:00:03 +03:00
Once you have built the shared native library (see above), build the SEALNet project
`dotnet\src\SEALNet.csproj` from `SEAL.sln`. Building SEALNet results in the assembly
`SEALNet.dll` to be created in `dotnet\lib\$(Configuration)\netstandard2.0`. This
is the assembly you can reference in your application.
2019-01-30 03:12:43 +03:00
#### .NET examples
Build the SEALNetExamples project `dotnet\examples\SEALNetExamples.csproj` from
`SEAL.sln`. This results in the assembly `SEALNetExamples.dll` to be created in
`dotnet\bin\$(Configuration)\netcoreapp2.1`. The project takes care of copying the
native SEALNetNative library to the output directory.
2019-01-30 03:12:43 +03:00
#### .NET unit tests
Build the SEALNet Test project `dotnet\tests\SEALNetTest.csproj` from `SEAL.sln`. This
results in the `SEALNetTest.dll` assembly to be created in
`dotnet\lib\$(Configuration)\netcoreapp2.1`. The project takes care of copying the
native SEALNetNative library to the output directory.
2019-10-30 20:20:52 +03:00
#### Using Microsoft SEAL for .NET in your own application
2019-01-30 03:12:43 +03:00
To use Microsoft SEAL for .NET in your own application you need to:
1. add a reference in your project to `SEALNet.dll`;
2. ensure `sealnetnative.dll` is available for your application when run. The easiest
way to ensure this is to copy `sealnetnative.dll` to the same directory where your
application's executable is located.
2019-10-30 20:20:52 +03:00
#### Building your own NuGet package
You can build your own NuGet package for Microsoft SEAL by following the instructions
in [NUGET.md](dotnet/nuget/NUGET.md).
2019-01-31 01:42:46 +03:00
## Linux and macOS
Microsoft SEAL for .NET relies on a native shared library that can be easily
configured and built using CMake (>= 3.12) and a modern version of GNU G++ (>= 6.0)
or Clang++ (>= 5.0). In macOS the Xcode toolchain (>= 9.3) will work.
For compiling .NET code you will need to install a .NET Core SDK (>= 2.1). You can
follow these
[instructions for installing in Linux](https://dotnet.microsoft.com/download?initial-os=linux),
or for [installing in macOS](https://dotnet.microsoft.com/download?initial-os=macos).
2019-10-30 20:20:52 +03:00
#### Native library
2019-05-24 09:00:03 +03:00
If you only intend to run the examples and unit tests provided with Microsoft SEAL,
you do not need to install the native shared library, you only need to compile it.
The SEALNetExamples and SEALNetTest projects take care of copying the native shared
library to the appropriate assembly output directory.
To compile the native shared library you will need to:
1. Compile Microsoft SEAL as a static or shared library with Position-Independent Code (PIC);
2. Compile native shared library.
2019-10-06 11:21:27 +03:00
The instructions for compiling Microsoft SEAL are similar to the instructions described, but
in addition you need to ensure that the CMake configuration option `SEAL_LIB_BUILD_TYPE` is
set to either `Static_PIC` (default) or `Shared`. Assuming Microsoft SEAL was built using
the default CMake configuration options, we can immediately use it to compile the shared
native library required for .NET:
````
cd dotnet/native
cmake .
make
cd ../..
````
2019-10-30 20:20:52 +03:00
#### .NET library
To build the .NET Standard library, do the following:
````
cd dotnet/src
2019-10-30 20:20:52 +03:00
dotnet build --configuration <Debug|Release>
cd ../..
````
2019-05-31 03:24:25 +03:00
You can use the `dotnet` parameter `--configuration <Debug|Release>` to build either
a `Debug` or `Release` version of the assembly. This will result in a `SEALNet.dll`
assembly to be created in `dotnet/lib/$(Configuration)/netstandard2.0`. This assembly
is the one you will want to reference in your own projects.
2019-10-30 20:20:52 +03:00
#### .NET examples
To build and run the .NET examples, do:
````
cd dotnet/examples
dotnet run
cd ../..
````
2019-05-24 09:00:03 +03:00
As mentioned before, the .NET project will copy the shared native library to the assembly
output directory. You can use the `dotnet` parameter `--configuration <Debug|Release>` to
run either `Debug` or `Release` versions of the examples.
2019-10-30 20:20:52 +03:00
#### .NET unit tests
To build and run the .NET unit tests, do:
````
cd dotnet/tests
dotnet test
cd ../..
````
2019-05-31 03:24:25 +03:00
All unit tests should pass. You can use the `dotnet` parameter `--configuration <Debug|Release>`
to run `Debug` or `Relase` unit tests, and you can use `--verbosity detailed` to print the list
of unit tests that are being run.
2019-10-30 20:20:52 +03:00
#### Using Microsoft SEAL for .NET in your own application
2019-01-30 03:12:43 +03:00
To use Microsoft SEAL for .NET in your own application you need to:
1. add a reference in your project to `SEALNet.dll`;
2019-10-06 21:59:09 +03:00
2. ensure the native shared library is available for your application when run. The easiest way
to ensure this is to copy `libsealnetnative.so` to the same directory where your application's
executable is located.
2019-05-24 09:00:03 +03:00
In Linux or macOS, if you have root access to the system, you have the option to install the
native shared library globally. Then your application will always be able to find and load it.
2019-05-24 09:00:03 +03:00
Assuming Microsoft SEAL is build and installed globally, you can install the shared native
library globally as follows:
````
cd dotnet/native
cmake .
make
sudo make install
cd ../..
````
2019-05-31 03:24:25 +03:00
# Getting Started
2019-10-01 06:39:21 +03:00
2019-05-31 03:24:25 +03:00
Using Microsoft SEAL will require the user to invest some time in learning fundamental
concepts in homomorphic encryption. The code comes with heavily commented examples that
2019-05-31 03:57:50 +03:00
are designed to gradually teach such concepts as well as to demonstrate much of the API.
2019-05-31 03:24:25 +03:00
The code examples are available (and identical) in C++ and C#, and are divided into
several source files in `native/examples/` (C++) and `dotnet/examples/` (C#), as follows:
|C++ |C# |Description |
|-------------------|------------------|----------------------------------------------------------------------------|
|`examples.cpp` |`Examples.cs` |The example runner application |
|`1_bfv_basics.cpp` |`1_BFV_Basics.cs` |Encrypted modular arithmetic using the BFV scheme |
|`2_encoders.cpp` |`2_Encoders.cs` |Encoding more complex data into Microsoft SEAL plaintext objects |
|`3_levels.cpp` |`3_Levels.cs` |Introduces the concept of levels; prerequisite for using the CKKS scheme |
|`4_ckks_basics.cpp`|`4_CKKS_Basics.cs`|Encrypted real number arithmetic using the CKKS scheme |
|`5_rotation.cpp` |`5_Rotation.cs` |Performing cyclic rotations on encrypted vectors in the BFV and CKKS schemes|
|`6_performance.cpp`|`6_Performance.cs`|Performance tests for Microsoft SEAL |
It is recommeded to read the comments and the code snippets along with command line printout
from running an example. For easier navigation, command line printout provides the line number
in the associated source file where the associated code snippets start.
2019-05-31 03:57:50 +03:00
**WARNING: It is impossible to use Microsoft SEAL correctly without reading all examples
or by simply re-using the code from examples. Any developer attempting to do so
will inevitably produce code that is *vulnerable*, *malfunctioning*, or *extremely slow*.**
2019-06-11 03:01:17 +03:00
# Contributing
2019-05-24 09:00:03 +03:00
This project welcomes contributions and suggestions. Most contributions require you
2019-02-08 05:54:40 +03:00
to agree to a Contributor License Agreement (CLA) declaring that you have the right to,
2019-05-24 09:00:03 +03:00
and actually do, grant us the rights to use your contribution. For details, visit
2019-02-08 05:54:40 +03:00
https://cla.microsoft.com.
2019-05-24 09:00:03 +03:00
When you submit a pull request, a CLA-bot will automatically determine whether you need
to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow
the instructions provided by the bot. You will only need to do this once across all
2019-02-08 05:54:40 +03:00
repos using our CLA.
Pull requests must be submitted to the branch called *contrib*.
2019-02-08 05:54:40 +03:00
2019-05-24 09:00:03 +03:00
This project has adopted the
2019-02-08 05:54:40 +03:00
[Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
2019-05-24 09:00:03 +03:00
For more information see the
[Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional
2019-02-08 05:54:40 +03:00
questions or comments.
2019-02-21 03:17:53 +03:00
# Pull Requests
For contributing to Microsoft SEAL, please see [CONTRIBUTING.md](CONTRIBUTING.md).
2019-02-21 03:17:53 +03:00
# Citing Microsoft SEAL
To cite Microsoft SEAL in academic papers, please use the following BibTeX entries.
2020-01-24 08:48:47 +03:00
### Version 3.5
@misc{sealcrypto,
title = {{M}icrosoft {SEAL} (release 3.5)},
howpublished = {\url{https://github.com/Microsoft/SEAL}},
month = ???,
year = 2020,
note = {Microsoft Research, Redmond, WA.},
key = {SEAL}
}
### Version 3.4
@misc{sealcrypto,
title = {{M}icrosoft {SEAL} (release 3.4)},
howpublished = {\url{https://github.com/Microsoft/SEAL}},
month = oct,
year = 2019,
note = {Microsoft Research, Redmond, WA.},
key = {SEAL}
}
### Version 3.3
2019-06-11 03:01:17 +03:00
@misc{sealcrypto,
title = {{M}icrosoft {SEAL} (release 3.3)},
2019-06-11 03:01:17 +03:00
howpublished = {\url{https://github.com/Microsoft/SEAL}},
month = june,
year = 2019,
note = {Microsoft Research, Redmond, WA.},
key = {SEAL}
}
2019-02-21 03:17:53 +03:00
### Version 3.2
2019-06-11 03:01:17 +03:00
@misc{sealcrypto,
2019-02-21 03:17:53 +03:00
title = {{M}icrosoft {SEAL} (release 3.2)},
2019-06-11 03:01:17 +03:00
howpublished = {\url{https://github.com/Microsoft/SEAL}},
month = feb,
year = 2019,
note = {Microsoft Research, Redmond, WA.},
key = {SEAL}
}
2019-02-21 03:17:53 +03:00
### Version 3.1
2019-06-11 03:01:17 +03:00
@misc{sealcrypto,
2019-02-21 03:17:53 +03:00
title = {{M}icrosoft {SEAL} (release 3.1)},
2019-06-11 03:01:17 +03:00
howpublished = {\url{https://github.com/Microsoft/SEAL}},
month = dec,
year = 2018,
note = {Microsoft Research, Redmond, WA.},
key = {SEAL}
}
2019-02-21 03:17:53 +03:00
### Version 3.0
2019-06-11 03:01:17 +03:00
2019-02-21 03:17:53 +03:00
@misc{sealcrypto,
2019-06-11 03:01:17 +03:00
title = {{M}icrosoft {SEAL} (release 3.0)},
howpublished = {\url{http://sealcrypto.org}},
month = oct,
year = 2018,
note = {Microsoft Research, Redmond, WA.},
key = {SEAL}
2019-06-07 03:08:06 +03:00
}