PROJECT NOT UNDER ACTIVE MANAGEMENT

This project will no longer be maintained by Intel.
Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project.
Intel no longer accepts patches to this project.
If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the open source software community, please create your own fork of this project.

Python bindings and wrapper for Intel Paillier Cryptosystem Library

Intel Paillier Cryptosystem Library is an open-source library which provides accelerated performance of a partial homomorphic encryption (HE), named Paillier cryptosystem, by utilizing Intel® IPP-Crypto technologies on Intel CPUs supporting the AVX512IFMA instructions and Intel® Quickassist Technology. The library is written in modern standard C++ and provides the essential API for the Paillier cryptosystem scheme. Intel Paillier Cryptosystem Library - Python is a Python extension package intended for Python based privacy preserving machine learning solutions which utilizes the partial HE scheme for increased data and model protection. Intel Paillier Cryptosystem Library - Python is certified for ISO compliance.

Contents

• Python bindings and wrapper for Intel Paillier Cryptosystem Library
  • Contents
  • Introduction
  • Installing the package
    • Prerequisites
    • Dependencies
    • Installation
  • Usage
    • General
    • Using with QAT
    • Note: For more information of using the module, please refer to the example code available in the example folder.
    • Benchmark
• Standardization
• Contributors

Introduction

Paillier cryptosystem is a probabilistic asymmetric algorithm for public key cryptography and a partial homomorphic encryption scheme which allows two types of computation:

• addition of two ciphertexts
• addition and multiplication of a ciphertext by a plaintext number

As a public key encryption scheme, Paillier cryptosystem has three stages:

• Generate public-private key pair
• Encryption with public key
• Decryption with private key

For increased security, typically the key length is at least 1024 bits, but recommendation is 2048 bits or larger. To handle such large size integers, conventional implementations of the Paillier cryptosystem utilizes the GNU Multiple Precision Arithmetic Library (GMP). The essential computation of the scheme relies on the modular exponentiation, and our library takes advantage of the multi-buffer modular exponentiation function (mbx_exp_mb8) of IPP-Crypto library, which is enabled in AVX512IFMA instruction sets supporting SKUs, such as Intel Icelake Xeon CPUs.

The Python extension package allows ease of use of the C++ backend library. The extension provides seamless conversion from Python integer and floating point objects, which are theoretically infinite precision limited by memory size, to C++ BigNumber type. It also allows easier handling of arrays in numpy.ndarray or list format, for encryption, decryption and HE computations.

Installing the package

Prerequisites

For best performance, especially due to the multi-buffer modular exponentiation function, the Python extension is to be used on AVX512IFMA enabled systems, as listed below in Intel CPU codenames:

• Intel Cannon Lake
• Intel Ice Lake

The extension module can be used without AVX512IFMA - if the instruction set is not detected on the system, it will automatically switch to non multi-buffer modular exponentiation.

The following operating systems have been tested and deemed to be fully functional.

• Ubuntu 18.04 and higher
• Red Hat Enterprise Linux 8.1 and higher

We will keep working on adding more supported operating systems.

Dependencies

Must have dependencies include:

cmake >=3.15.1
git
pthread
g++ >= 7.0 or clang >= 10.0

The following libraries and tools are also required,

Python >= 3.8
pip >= 22.0.1
OpenSSL >= 1.1.0
numa >= 2.0.12
gmp >= 5.0.0
mpfr >= 3.1.0
mpc >= 1.1.0

which can be installed by:

# Ubuntu 20.04 or higher
$ sudo apt install python3-dev python3-pip libssl-dev libnuma-dev libgmp-dev libmpfr-dev libmpc-dev

# Fedora (RHEL 8, CentOS 8)
$ sudo dnf install python3-devel python3-pip openssl-devel numactl-devel gmp-devel mpfr-devel libmpc-devel

The following is also required

nasm >= 2.15

For Ubuntu 20.04 or lower and RHEL/CentOS, please refer to the Netwide Assembler webpage for download and installation details.

For more details regarding the C++ backend, refer to the Intel Paillier Cryptosystem Library.

Installation

Compiling and installing the package can be done by:

python setup.py install

or

pip install .

For building a distributable wheel package of the Intel Paillier Cryptosystem Library - Python,

python setup.py bdist_wheel

and the wheel package can be found under {PROJECT_ROOT}/dist.

To test the installed module,

python setup.py test

and the unit-test will be executed.

Usage

General

The module can be imported by:

import ipcl_python

First, the key pair needs to be generated - public key for encryption and private key for decryption.

from ipcl_python import PaillierKeypair
pubkey, prikey = PaillierKeypair.generate_keypair(2048, True)

For encryption and decryption, and the result verification:

a = np.random.rand(100)
ct_a = pubkey.encrypt(a)

de_a = prikey.decrypt(ct_a)
print(np.allclose(a, de_a))

Paillier cryptosystem supports ciphertext addition and plaintext addition/multiplcation.

# ciphertext addition
b = np.random.rand(100)
ct_b = pubkey.encrypt(b)
ct_c = ct_a + ct_b

de_c = prikey.decrypt(ct_c)
print(np.allclose(a + b, de_c))

# plaintext addition
ct_c = ct_a + b

de_c = prikey.decrypt(ct_c)
print(np.allclose(a + b, de_c))

# plaintext multiplication
ct_d = ct_a * b

de_d = prikey.decrypt(ct_d)
print(np.allclose(a * b, de_d))

Using with QAT

Before running the Python module with Quickassist Technology enabled, it is essential to trigger the QAT engine before running any workload and release it upon completion. Below is a simple code piece including how to initialize and release the QAT engine.

from ipcl_python import context, PaillierKeypair

# Reserve QAT engine
context.initializeContext("QAT")

# Sample Paillier HE operations
pubkey, prikey = PaillierKeypair.generate_keypair(2048, True)
a = np.random.rand(100)
ct_a = pubkey.encrypt(a)
de_a = prikey.decrypt(ct_a)
print(np.allclose(a, de_a))

# On completion - release QAT engine
context.terminateContext()

Note: For more information of using the module, please refer to the example code available in the example folder.

Benchmark

We provide a benchmark tool, located under the folder bench. In order to run the benchmark, please install the Google Benchmark via,

pip install google-benchmark>=1.6.1

Standardization

This library is certified for ISO compliance with the homomorphic encryption standards ISO/IEC 18033-6 by Dekra.

Contributors

Main contributors to this project, sorted by alphabetical order of last name are:

• Xiaojun Huang
• Sejun Kim (lead)
• Bin Wang
• Pengfei Zhao