1 of 59

0.7 Get Started

Installation

This document provides instructions to set up TFHE-rs in your project.

Importing

First, add TFHE-rs as a dependency in your Cargo.toml.

For x86_64 machine running a Unix-like OS:

tfhe = { version = "0.7.5", features = [ "boolean", "shortint", "integer", "x86_64-unix" ] }

For ARM machine running a Unix-like OS:

tfhe = { version = "0.7.5", features = [ "boolean", "shortint", "integer", "aarch64-unix" ] }

tfhe = { version = "*", features = ["boolean", "shortint", "integer", "x86_64"] }

Rust version: a minimum Rust version of 1.73 is required to compile TFHE-rs.

Performance: for optimal performance, it is highly recommended to run code that uses TFHE-rs in release mode with cargo's --release flag.

Supported platforms

TFHE-rs currently supports the following platforms:

x86

aarch64

Linux

x86_64-unix

aarch64-unix*

macOS

x86_64-unix

aarch64-unix*

Windows

x86_64 with RDSEED instruction

Unsupported

Types & Operations

This document explains the encryption types and operations supported by TFHE-rs.

Types

TFHE-rs supports two main types of encrypted data:

FheUint: homomorphic equivalent of Rust unsigned integers u8, u16, ...
FheInt: homomorphic equivalent of Rust signed integers i8, i16, ...

Integer

TFHE-rs uses integers to encrypt all messages which are larger than 4 bits.

Similar to Rust integers, you need to specify the bit size of data when declaring a variable:

    // let clear_a: u64 = 7;
    let mut a = FheUint64::try_encrypt(clear_a, &keys)?;

    // let clear_b: i8 = 3;
    let mut b = FheInt8::try_encrypt(clear_b, &keys)?;

    // let clear_c: u128 = 2;
    let mut c = FheUint128::try_encrypt(clear_c, &keys)?;

Operations

TFHE-rs supports various operations on encrypted integers (Enc) of any size between 1 and 256 bits. These operations can also work between encrypted integers and clear integers (Int).

name

symbol

Enc/Enc

Enc/ Int

Neg

-

Add

+

Sub

-

Mul

*

Div

/

Rem

%

Not

!

BitAnd

&

BitOr

|

BitXor

^

Shr

>>

Shl

<<

Min

min

Max

max

Greater than

gt

Greater or equal than

ge

Less than

lt

Less or equal than

le

Equal

eq

Cast (into dest type)

cast_into

Cast (from src type)

cast_from

Ternary operator

select

Arithmetic operations

Homomorphic integer types (FheUint and FheInt) support the following arithmetic operations:

name

symbol

type

-

Unary

+

Binary

-

Binary

*

Binary

/

Binary

%

Binary

Specifications for operations with zero:

Division by zero: returns modulus - 1.
Remainder operator: returns the first input unchanged.
- Example: if ct1 = FheUint8(63) and ct2 = FheUint8(0), then ct1 % ct2 returns FheUint8(63).

The following example shows how to perform arithmetic operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8, FheUint8};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);

    let clear_a = 15_u64;
    let clear_b = 27_u64;
    let clear_c = 43_u64;
    let clear_d = -87_i64;

    let mut a = FheUint8::try_encrypt(clear_a, &keys)?;
    let mut b = FheUint8::try_encrypt(clear_b, &keys)?;
    let mut c = FheUint8::try_encrypt(clear_c, &keys)?;
    let mut d = FheInt8::try_encrypt(clear_d, &keys)?;


    a = a * &b;     // Clear equivalent computations: 15 * 27 mod 256 = 149
    b = &b + &c;    // Clear equivalent computations: 27 + 43 mod 256 = 70
    b = b - 76u8;   // Clear equivalent computations: 70 - 76 mod 256 = 250
    d = d - 13i8;   // Clear equivalent computations: -87 - 13 = 100 in [-128, 128[

    let dec_a: u8 = a.decrypt(&keys);
    let dec_b: u8 = b.decrypt(&keys);
    let dec_d: i8 = d.decrypt(&keys);

    assert_eq!(dec_a, ((clear_a * clear_b) % 256_u64) as u8);
    assert_eq!(dec_b, (((clear_b  + clear_c).wrapping_sub(76_u64)) % 256_u64) as u8);
    assert_eq!(dec_d, (clear_d - 13) as i8);

    Ok(())
}

Bitwise operations

Homomorphic integer types support the following bitwise operations:

name

symbol

type

!

Unary

&

Binary

|

Binary

^

Binary

>>

Binary

<<

Binary

rotate_right

Binary

rotate_left

Binary

The following example shows how to perform bitwise operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);

    let clear_a = 164;
    let clear_b = 212;

    let mut a = FheUint8::try_encrypt(clear_a, &keys)?;
    let mut b = FheUint8::try_encrypt(clear_b, &keys)?;

    a = a ^ &b;
    b = b ^ &a;
    a = a ^ &b;

    let dec_a: u8 = a.decrypt(&keys);
    let dec_b: u8 = b.decrypt(&keys);

    // We homomorphically swapped values using bitwise operations
    assert_eq!(dec_a, clear_b);
    assert_eq!(dec_b, clear_a);

    Ok(())
}

Comparison operations

Homomorphic integers support comparison operations. However, due to Rust's limitations, you cannot overload comparison symbols. This is because Rust requires Boolean outputs from such operations, but homomorphic types return ciphertexts. Therefore, you should use the following methods, which conform to the naming conventions of Rust’s standard traits:

Supported operations:

name

symbol

type

eq

Binary

ne

Binary

gt

Binary

ge

Binary

lt

Binary

le

Binary

The following example shows how to perform comparison operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);

    let clear_a: i8 = -121;
    let clear_b: i8 = 87;

    let mut a = FheInt8::try_encrypt(clear_a, &keys)?;
    let mut b = FheInt8::try_encrypt(clear_b, &keys)?;

    let greater = a.gt(&b);
    let greater_or_equal = a.ge(&b);
    let lower = a.lt(&b);
    let lower_or_equal = a.le(&b);
    let equal = a.eq(&b);

    let dec_gt = greater.decrypt(&keys);
    let dec_ge = greater_or_equal.decrypt(&keys);
    let dec_lt = lower.decrypt(&keys);
    let dec_le = lower_or_equal.decrypt(&keys);
    let dec_eq = equal.decrypt(&keys);

    assert_eq!(dec_gt, clear_a > clear_b);
    assert_eq!(dec_ge, clear_a >= clear_b);
    assert_eq!(dec_lt, clear_a < clear_b);
    assert_eq!(dec_le, clear_a <= clear_b);
    assert_eq!(dec_eq, clear_a == clear_b);

    Ok(())
}

Min/Max operations

Homomorphic integers support the min/max operations:

name

symbol

type

Min

min

Binary

Max

max

Binary

The following example shows how to perform min/max operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);

    let clear_a:u8 = 164;
    let clear_b:u8 = 212;

    let mut a = FheUint8::try_encrypt(clear_a, &keys)?;
    let mut b = FheUint8::try_encrypt(clear_b, &keys)?;

    let min = a.min(&b);
    let max = a.max(&b);

    let dec_min : u8 = min.decrypt(&keys);
    let dec_max : u8 = max.decrypt(&keys);

    assert_eq!(dec_min, u8::min(clear_a, clear_b));
    assert_eq!(dec_max, u8::max(clear_a, clear_b));

    Ok(())
}

Ternary conditional operations

The ternary conditional operator execute conditional instructions in the form if cond { choice_if_true } else { choice_if_false }.

name

symbol

type

Ternary operator

select

Ternary

The syntax is encrypted_condition.select(encrypted_choice_if_true, encrypted_choice_if_false). The valid encrypted_condition must be an encryption of 0 or 1.

The following example shows how to perform ternary conditional operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt32};

fn main() -> Result<(), Box<dyn std::error::Error>> {
   // Basic configuration to use homomorphic integers
    let config = ConfigBuilder::default().build();

	// Key generation
	let (client_key, server_keys) = generate_keys(config);
	
	let clear_a = 32i32;
	let clear_b = -45i32;
	
	// Encrypting the input data using the (private) client_key
	// FheInt32: Encrypted equivalent to i32
	let encrypted_a = FheInt32::try_encrypt(clear_a, &client_key)?;
	let encrypted_b = FheInt32::try_encrypt(clear_b, &client_key)?;
	
	// On the server side:
	set_server_key(server_keys);
	
	// Clear equivalent computations: 32 > -45
	let encrypted_comp = &encrypted_a.gt(&encrypted_b);
	let clear_res = encrypted_comp.decrypt(&client_key);
	assert_eq!(clear_res, clear_a > clear_b);
	
	// `encrypted_comp` is a FheBool, thus it encrypts a boolean value.
    // This acts as a condition on which the
	// `select` function can be applied on.
	// Clear equivalent computations:
	// if 32 > -45 {result = 32} else {result = -45}
	let encrypted_res = &encrypted_comp.select(&encrypted_a, &encrypted_b);
	
	let clear_res: i32 = encrypted_res.decrypt(&client_key);
	assert_eq!(clear_res, clear_a);
	
	Ok(())
}

Casting operations

You can cast between integer types using either the cast_from associated function or the cast_into method.

The following example shows how to perform casting operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt16, FheUint8, FheUint32, FheUint16};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (client_key, server_key) = generate_keys(config);

    // Casting requires server_key to set
    // (encryptions/decryptions do not need server_key to be set)
    set_server_key(server_key);

    {
        let clear = 12_837u16;
        let a = FheUint16::encrypt(clear, &client_key);

        // Downcasting
        let a: FheUint8 = a.cast_into();
        let da: u8 = a.decrypt(&client_key);
        assert_eq!(da, clear as u8);

        // Upcasting
        let a: FheUint32 = a.cast_into();
        let da: u32 = a.decrypt(&client_key);
        assert_eq!(da, (clear as u8) as u32);
    }

    {
        let clear = 12_837u16;
        let a = FheUint16::encrypt(clear, &client_key);

        // Upcasting
        let a = FheUint32::cast_from(a);
        let da: u32 = a.decrypt(&client_key);
        assert_eq!(da, clear as u32);

        // Downcasting
        let a = FheUint8::cast_from(a);
        let da: u8 = a.decrypt(&client_key);
        assert_eq!(da, (clear as u32) as u8);
    }

    {
        let clear = 12_837i16;
        let a = FheInt16::encrypt(clear, &client_key);

        // Casting from FheInt16 to FheUint16
        let a = FheUint16::cast_from(a);
        let da: u16 = a.decrypt(&client_key);
        assert_eq!(da, clear as u16);
    }

    Ok(())
}

Boolean Operations

Native homomorphic Booleans support the following common Boolean operations:

name

symbol

type

&

Binary

|

Binary

^

Binary

!

Unary

Benchmarks

This document details the performance benchmarks of homomorphic operations using TFHE-rs.

By their nature, homomorphic operations run slower than their cleartext equivalents. The following are the timings for basic operations, including benchmarks from other libraries for comparison.

All CPU benchmarks were launched on an AWS hpc7a.96xlarge instance equipped with an AMD EPYC 9R14 CPU @ 2.60GHz and 740GB of RAM.

Integer operations

The following tables benchmark the execution time of some operation sets using FheUint (unsigned integers). The FheInt (signed integers) performs similarly.

The next table shows the operation timings on CPU when all inputs are encrypted:

The next table shows the operation timings on CPU when the left input is encrypted and the right is a clear scalar of the same size:

All timings are based on parallelized Radix-based integer operations where each block is encrypted using the default parameters PARAM_MESSAGE_2_CARRY_2_KS_PBS. To ensure predictable timings, we perform operations in the default mode, which propagates the carry bit as needed. You can minimize operational costs by selecting from 'unchecked', 'checked', or 'smart' modes, each balancing performance and security differently.

Shortint operations

The next table shows the execution time of some operations using various parameter sets of tfhe-rs::shortint. Except for unchecked_add, we perform all the operations in the default mode. This mode ensures predictable timings along the entire circuit by clearing the carry space after each operation. The configuration is Concrete FFT + AVX-512.

Boolean operations

The next table shows the execution time of a single binary Boolean gate.

tfhe-rs::boolean

tfhe-lib

Using the same hpc7a.96xlarge machine as the one for tfhe-rs, the timings are as follows:

OpenFHE (v1.1.2)

Following the official instructions from OpenFHE, we use clang14 and the following command to setup the project: cmake -DNATIVE_SIZE=32 -DWITH_NATIVEOPT=ON -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DWITH_OPENMP=OFF ..

The following example shows how to initialize the configuration to use the HEXL library:

Using the same hpc7a.96xlarge machine as the one for tfhe-rs, the timings are as follows:

Reproducing TFHE-rs benchmarks

AVX512 is now enabled by default for benchmarks when available

The following example shows how to reproduce TFHE-rs benchmarks:

Security and cryptography

This document introduces the cryptographic concepts of the scheme of Fully Homomorphic Encryption over the Torus (TFHE) and the security considerations of TFHE-rs.

TFHE

TFHE-rs is a cryptographic library that implements Fully Homomorphic Encryption using the TFHE scheme. You should understand the basics of TFHE to consider its limitations, such as:

The precision: TFHE has limitations on the number of bits used to represent plaintext values.
The execution time: TFHE operations are slower than native operations due to their complexity.

LWE ciphertexts

TFHE-rs primarily utilizes Learning With Errors (LWE) ciphertexts. The LWE problem forms the basis of TFHE's security and is considered resistant to quantum attacks.

An LWE Ciphertext is a collection of 32-bit or 64-bit unsigned integers. Before encrypting a message in an LWE ciphertext, you first need to encode it as a plaintext by shifting the message to the most significant bits of the unsigned integer type used.

Then, you add a small random value called noise to the least significant bits. This noise is crucial in ensuring the security of the ciphertext.

To get a ciphertext from a plaintext, you must encrypt the plaintext using a secret key.

An LWE ciphertext is composed of two parts:

The mask of a fresh ciphertext (the result of an encryption, and not the result of operations such as ciphertext addition) is a list of n uniformly random values.

The body is computed as follows:

Now that the encryption scheme is defined, let's review the example of the addition between ciphertexts to illustrate why it is slower to compute over encrypted data.

To add two ciphertexts, we must add their $mask$ and $body$:

Programmable Bootstrapping, noise management, and carry bits

In FHE, two types of operations can be applied to ciphertexts:

Leveled operations, which increase the noise in the ciphertext
Bootstrapped operations, which reduce the noise in the ciphertext

Noise is critical in FHE because it can tamper with the message if not tracked and managed properly. Bootstrapping operations decrease noise within the ciphertexts and guarantee the correctness of computation. The rest of the operations do not need bootstrapping operations, thus they are called leveled operations and are usually very fast as a result.

The following sections explain the concept of noise and padding in ciphertexts.

Noise

To ensure security, LWE requires random noise to be added to the message during encryption.

TFHE scheme draws this random noise from a Centered Normal Distribution with a standard deviation parameter. The choice of standard deviation impacts the security level: increasing the standard deviation enhances security while keeping other factors constant.

TFHE-rs encodes the noise in the least significant bits of each plaintext. Each leveled computation increases the value of the noise. If too many computations are performed, the noise will eventually overflow into the message bits and lead to an incorrect result.

The following figure illustrates how the extra bit of noise is incurred during an addition operation.

TFHE-rs enables automatic noise management by performing bootstrapping operations to reset the noise.

Programmable BootStrapping (PBS)

The bootstrapping of TFHE is programmable. This allows any function to be homomorphically computed over an encrypted input, while also reducing the noise. These functions are represented by look-up tables.

In general, the computation of a PBS is preceded or followed by a keyswitch, an operation to change the encryption key. The output ciphertext is then encrypted with the same key as the input one. To do this, two (public) evaluation keys are required: a bootstrapping key and a keyswitching key.

Carry

Since encoded values have a fixed precision, operating on them can produce results that are outside of the original interval. To avoid losing precision or wrapping around the interval, TFHE-rs uses additional bits by defining bits of padding on the most significant bits.

For example, when adding two ciphertexts, the sum could exceed the range of either ciphertext, and thus necessitate a carry that would then be transferred onto the first padding bit. In the following figure, each plaintext over 32 bits has one bit of padding on its left (the most significant bit). After the addition, the padding bit gets consumed to accommodate the carry. We refer to this process as consuming bits of padding. Without any padding-left, further additions may not produce accurate results.

Security

The default parameters for the TFHE-rs library are chosen considering the IND-CPA security model, and are selected with a bootstrapping failure probability fixed at p_error = $2^{-40}$. In particular, it is assumed that the results of decrypted computations are not shared by the secret key owner with any third parties, as such an action can lead to leakage of the secret encryption key. If you are designing an application where decryptions must be shared, you will need to craft custom encryption parameters which are chosen in consideration of the IND-CPA^D security model [1].

Classical public key encryption.

Fundamentals

Guides

Tutorials

References

Explanations

Developers

Types & Operations

This document explains the encryption types and operations supported by TFHE-rs.

Types

TFHE-rs supports two main types of encrypted data:

FheUint: homomorphic equivalent of Rust unsigned integers u8, u16, ...
FheInt: homomorphic equivalent of Rust signed integers i8, i16, ...

Integer

TFHE-rs uses integers to encrypt all messages which are larger than 4 bits.

Similar to Rust integers, you need to specify the bit size of data when declaring a variable:

    // let clear_a: u64 = 7;
    let mut a = FheUint64::try_encrypt(clear_a, &keys)?;

    // let clear_b: i8 = 3;
    let mut b = FheInt8::try_encrypt(clear_b, &keys)?;

    // let clear_c: u128 = 2;
    let mut c = FheUint128::try_encrypt(clear_c, &keys)?;

Operations

TFHE-rs supports various operations on encrypted integers (Enc) of any size between 1 and 256 bits. These operations can also work between encrypted integers and clear integers (Int).

name

symbol

Enc/Enc

Enc/ Int

Neg

-

Add

+

Sub

-

Mul

*

Div

/

Rem

%

Not

!

BitAnd

&

BitOr

|

BitXor

^

Shr

>>

Shl

<<

Min

min

Max

max

Greater than

gt

Greater or equal than

ge

Less than

lt

Less or equal than

le

Equal

eq

Cast (into dest type)

cast_into

Cast (from src type)

cast_from

Ternary operator

select

Arithmetic operations

Homomorphic integer types (FheUint and FheInt) support the following arithmetic operations:

name

symbol

type

-

Unary

+

Binary

-

Binary

*

Binary

/

Binary

%

Binary

Specifications for operations with zero:

Division by zero: returns modulus - 1.
- Example: for FheUint8 (modulus = $2^8=256$ ), dividing by zero returns an ecryption of 255.
Remainder operator: returns the first input unchanged.
- Example: if ct1 = FheUint8(63) and ct2 = FheUint8(0), then ct1 % ct2 returns FheUint8(63).

The following example shows how to perform arithmetic operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8, FheUint8};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);

    let clear_a = 15_u64;
    let clear_b = 27_u64;
    let clear_c = 43_u64;
    let clear_d = -87_i64;

    let mut a = FheUint8::try_encrypt(clear_a, &keys)?;
    let mut b = FheUint8::try_encrypt(clear_b, &keys)?;
    let mut c = FheUint8::try_encrypt(clear_c, &keys)?;
    let mut d = FheInt8::try_encrypt(clear_d, &keys)?;


    a = a * &b;     // Clear equivalent computations: 15 * 27 mod 256 = 149
    b = &b + &c;    // Clear equivalent computations: 27 + 43 mod 256 = 70
    b = b - 76u8;   // Clear equivalent computations: 70 - 76 mod 256 = 250
    d = d - 13i8;   // Clear equivalent computations: -87 - 13 = 100 in [-128, 128[

    let dec_a: u8 = a.decrypt(&keys);
    let dec_b: u8 = b.decrypt(&keys);
    let dec_d: i8 = d.decrypt(&keys);

    assert_eq!(dec_a, ((clear_a * clear_b) % 256_u64) as u8);
    assert_eq!(dec_b, (((clear_b  + clear_c).wrapping_sub(76_u64)) % 256_u64) as u8);
    assert_eq!(dec_d, (clear_d - 13) as i8);

    Ok(())
}

Bitwise operations

Homomorphic integer types support the following bitwise operations:

name

symbol

type

!

Unary

&

Binary

|

Binary

^

Binary

>>

Binary

<<

Binary

rotate_right

Binary

rotate_left

Binary

The following example shows how to perform bitwise operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);

    let clear_a = 164;
    let clear_b = 212;

    let mut a = FheUint8::try_encrypt(clear_a, &keys)?;
    let mut b = FheUint8::try_encrypt(clear_b, &keys)?;

    a = a ^ &b;
    b = b ^ &a;
    a = a ^ &b;

    let dec_a: u8 = a.decrypt(&keys);
    let dec_b: u8 = b.decrypt(&keys);

    // We homomorphically swapped values using bitwise operations
    assert_eq!(dec_a, clear_b);
    assert_eq!(dec_b, clear_a);

    Ok(())
}

Comparison operations

Supported operations:

name

symbol

type

eq

Binary

ne

Binary

gt

Binary

ge

Binary

lt

Binary

le

Binary

The following example shows how to perform comparison operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);

    let clear_a: i8 = -121;
    let clear_b: i8 = 87;

    let mut a = FheInt8::try_encrypt(clear_a, &keys)?;
    let mut b = FheInt8::try_encrypt(clear_b, &keys)?;

    let greater = a.gt(&b);
    let greater_or_equal = a.ge(&b);
    let lower = a.lt(&b);
    let lower_or_equal = a.le(&b);
    let equal = a.eq(&b);

    let dec_gt = greater.decrypt(&keys);
    let dec_ge = greater_or_equal.decrypt(&keys);
    let dec_lt = lower.decrypt(&keys);
    let dec_le = lower_or_equal.decrypt(&keys);
    let dec_eq = equal.decrypt(&keys);

    assert_eq!(dec_gt, clear_a > clear_b);
    assert_eq!(dec_ge, clear_a >= clear_b);
    assert_eq!(dec_lt, clear_a < clear_b);
    assert_eq!(dec_le, clear_a <= clear_b);
    assert_eq!(dec_eq, clear_a == clear_b);

    Ok(())
}

Min/Max operations

Homomorphic integers support the min/max operations:

name

symbol

type

Min

min

Binary

Max

max

Binary

The following example shows how to perform min/max operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);

    let clear_a:u8 = 164;
    let clear_b:u8 = 212;

    let mut a = FheUint8::try_encrypt(clear_a, &keys)?;
    let mut b = FheUint8::try_encrypt(clear_b, &keys)?;

    let min = a.min(&b);
    let max = a.max(&b);

    let dec_min : u8 = min.decrypt(&keys);
    let dec_max : u8 = max.decrypt(&keys);

    assert_eq!(dec_min, u8::min(clear_a, clear_b));
    assert_eq!(dec_max, u8::max(clear_a, clear_b));

    Ok(())
}

Ternary conditional operations

The ternary conditional operator execute conditional instructions in the form if cond { choice_if_true } else { choice_if_false }.

name

symbol

type

Ternary operator

select

Ternary

The syntax is encrypted_condition.select(encrypted_choice_if_true, encrypted_choice_if_false). The valid encrypted_condition must be an encryption of 0 or 1.

The following example shows how to perform ternary conditional operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt32};

fn main() -> Result<(), Box<dyn std::error::Error>> {
   // Basic configuration to use homomorphic integers
    let config = ConfigBuilder::default().build();

	// Key generation
	let (client_key, server_keys) = generate_keys(config);
	
	let clear_a = 32i32;
	let clear_b = -45i32;
	
	// Encrypting the input data using the (private) client_key
	// FheInt32: Encrypted equivalent to i32
	let encrypted_a = FheInt32::try_encrypt(clear_a, &client_key)?;
	let encrypted_b = FheInt32::try_encrypt(clear_b, &client_key)?;
	
	// On the server side:
	set_server_key(server_keys);
	
	// Clear equivalent computations: 32 > -45
	let encrypted_comp = &encrypted_a.gt(&encrypted_b);
	let clear_res = encrypted_comp.decrypt(&client_key);
	assert_eq!(clear_res, clear_a > clear_b);
	
	// `encrypted_comp` is a FheBool, thus it encrypts a boolean value.
    // This acts as a condition on which the
	// `select` function can be applied on.
	// Clear equivalent computations:
	// if 32 > -45 {result = 32} else {result = -45}
	let encrypted_res = &encrypted_comp.select(&encrypted_a, &encrypted_b);
	
	let clear_res: i32 = encrypted_res.decrypt(&client_key);
	assert_eq!(clear_res, clear_a);
	
	Ok(())
}

Casting operations

You can cast between integer types using either the cast_from associated function or the cast_into method.

The following example shows how to perform casting operations:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt16, FheUint8, FheUint32, FheUint16};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default().build();
    let (client_key, server_key) = generate_keys(config);

    // Casting requires server_key to set
    // (encryptions/decryptions do not need server_key to be set)
    set_server_key(server_key);

    {
        let clear = 12_837u16;
        let a = FheUint16::encrypt(clear, &client_key);

        // Downcasting
        let a: FheUint8 = a.cast_into();
        let da: u8 = a.decrypt(&client_key);
        assert_eq!(da, clear as u8);

        // Upcasting
        let a: FheUint32 = a.cast_into();
        let da: u32 = a.decrypt(&client_key);
        assert_eq!(da, (clear as u8) as u32);
    }

    {
        let clear = 12_837u16;
        let a = FheUint16::encrypt(clear, &client_key);

        // Upcasting
        let a = FheUint32::cast_from(a);
        let da: u32 = a.decrypt(&client_key);
        assert_eq!(da, clear as u32);

        // Downcasting
        let a = FheUint8::cast_from(a);
        let da: u8 = a.decrypt(&client_key);
        assert_eq!(da, (clear as u32) as u8);
    }

    {
        let clear = 12_837i16;
        let a = FheInt16::encrypt(clear, &client_key);

        // Casting from FheInt16 to FheUint16
        let a = FheUint16::cast_from(a);
        let da: u16 = a.decrypt(&client_key);
        assert_eq!(da, clear as u16);
    }

    Ok(())
}

Boolean Operations

Native homomorphic Booleans support the following common Boolean operations:

name

symbol

type

&

Binary

|

Binary

^

Binary

!

Unary

Security and cryptography

This document introduces the cryptographic concepts of the scheme of Fully Homomorphic Encryption over the Torus (TFHE) and the security considerations of TFHE-rs.

TFHE

TFHE-rs is a cryptographic library that implements Fully Homomorphic Encryption using the TFHE scheme. You should understand the basics of TFHE to consider its limitations, such as:

The precision: TFHE has limitations on the number of bits used to represent plaintext values.
The execution time: TFHE operations are slower than native operations due to their complexity.

LWE ciphertexts

TFHE-rs primarily utilizes Learning With Errors (LWE) ciphertexts. The LWE problem forms the basis of TFHE's security and is considered resistant to quantum attacks.

Then, you add a small random value called noise to the least significant bits. This noise is crucial in ensuring the security of the ciphertext.

To get a ciphertext from a plaintext, you must encrypt the plaintext using a secret key.

An LWE secret key is a list of n random integers: . is called the

An LWE ciphertext is composed of two parts:

The mask
The body

The mask of a fresh ciphertext (the result of an encryption, and not the result of operations such as ciphertext addition) is a list of n uniformly random values.

The body is computed as follows:

Now that the encryption scheme is defined, let's review the example of the addition between ciphertexts to illustrate why it is slower to compute over encrypted data.

To add two ciphertexts, we must add their $mask$ and $body$:

ct_0 = (a_{0}, ..., a_{n-1}, b) \\ ct_1 = (a_{0}^{\prime}, ..., a_{n-1}^{\prime}, b^{\prime}) \\ ct_{2} = ct_0 + ct_1 \\ ct_{2} = (a_{0} + a_{0}^{\prime}, ..., a_{n-1} + a_{n-1}^{\prime}, b + b^{\prime})\\ b + b^{\prime} = (\sum_{i = 0}^{n-1}{a_i * s_i}) + plaintext + (\sum_{i = 0}^{n-1}{a_i^{\prime} * s_i}) + plaintext^{\prime}\\ b + b^{\prime} = (\sum_{i = 0}^{n-1}{(a_i + a_i^{\prime})* s_i}) + \Delta m + \Delta m^{\prime} + e + e^{\prime}\\

To add ciphertexts, it is necessary to add both their masks and bodies. The operation involves adding elements, rather than just adding two integers. This is an intuitive example to show how FHE computation is slower compared to plaintext computation. However, other operations are far more expensive (for example, the computation of a lookup table using Programmable Bootstrapping).

Programmable Bootstrapping, noise management, and carry bits

In FHE, two types of operations can be applied to ciphertexts:

Leveled operations, which increase the noise in the ciphertext
Bootstrapped operations, which reduce the noise in the ciphertext

The following sections explain the concept of noise and padding in ciphertexts.

Noise

To ensure security, LWE requires random noise to be added to the message during encryption.

The following figure illustrates how the extra bit of noise is incurred during an addition operation.

TFHE-rs enables automatic noise management by performing bootstrapping operations to reset the noise.

Programmable BootStrapping (PBS)

These operations are quite complex to describe in short, you can find more details about these operations (or about TFHE in general) in the .

Carry

Security

By default, the cryptographic parameters provided by TFHE-rs ensure at least 128 bits of security. The security has been evaluated using the latest versions of the Lattice Estimator () with red_cost_model = reduction.RC.BDGL16.

[1]

Classical public key encryption.

In classical public key encryption, the public key contains a given number of ciphertexts all encrypting the value 0. By setting the number of encryptions to 0 in the public key at , where is the LWE dimension, is the ciphertext modulus, and is the number of security bits. This construction is secure due to the leftover hash lemma, which relates to the impossibility of breaking the underlying multiple subset sum problem. This guarantees both a high-density subset sum and an exponentially large number of possible associated random vectors per LWE sample .

Example: for FheUint8 (modulus = $2^8=256$ ), dividing by zero returns an ecryption of 255.

ct_0 = (a_{0}, ..., a_{n-1}, b) \\ ct_1 = (a_{0}^{\prime}, ..., a_{n-1}^{\prime}, b^{\prime}) \\ ct_{2} = ct_0 + ct_1 \\ ct_{2} = (a_{0} + a_{0}^{\prime}, ..., a_{n-1} + a_{n-1}^{\prime}, b + b^{\prime})\\ b + b^{\prime} = (\sum_{i = 0}^{n-1}{a_i * s_i}) + plaintext + (\sum_{i = 0}^{n-1}{a_i^{\prime} * s_i}) + plaintext^{\prime}\\ b + b^{\prime} = (\sum_{i = 0}^{n-1}{(a_i + a_i^{\prime})* s_i}) + \Delta m + \Delta m^{\prime} + e + e^{\prime}\\

Server key

This document explains how to call the function set_server_key.

This function will move the server key to an internal state of the crate and manage the details for a simpler interface.

Here is an example:

use tfhe::{ConfigBuilder, generate_keys, set_server_key};

fn main() {
    let config = ConfigBuilder::default().build();

    let (client_key, server_key) = generate_keys(config);

    set_server_key(server_key);
}

Encryption

This document explains how to encrypt data.

To encrypt data, use the encrypt method from the FheEncrypt trait. This crate provides types that implement either FheEncrypt or FheTryEncrypt or both, to enable encryption.

Here is an example:

use tfhe::prelude::*;
use tfhe::{generate_keys, ConfigBuilder, FheUint8};

fn main() {
    let config = ConfigBuilder::default().build();

    let (client_key, server_key) = generate_keys(config);

    let clear_a = 27u8;
    let clear_b = 128u8;

    let a = FheUint8::encrypt(clear_a, &client_key);
    let b = FheUint8::encrypt(clear_b, &client_key);
}

Quick start

This document explains the basic steps of using the high-level API of TFHE-rs.

Workflow explanation

These are the steps to use the TFHE-rs high-level API:

This example demonstrates the basic workflow combining the client and server parts:

use tfhe::{ConfigBuilder, generate_keys, set_server_key, FheUint8};
use tfhe::prelude::*;

fn main() {
    let config = ConfigBuilder::default().build();

    // Client-side
    let (client_key, server_key) = generate_keys(config);

    let clear_a = 27u8;
    let clear_b = 128u8;

    let a = FheUint8::encrypt(clear_a, &client_key);
    let b = FheUint8::encrypt(clear_b, &client_key);

    //Server-side
    set_server_key(server_key);
    let result = a + b;

    //Client-side
    let decrypted_result: u8 = result.decrypt(&client_key);

    let clear_result = clear_a + clear_b;

    assert_eq!(decrypted_result, clear_result);
}

The default configuration for x86 Unix machines is as follows:

tfhe = { version = "0.7.5", features = ["integer", "x86_64-unix"]}

Step1: Importing

TFHE-rs uses traits to implement consistent APIs and generic functions. To use traits, they must be in scope.

The prelude pattern provides a convenient way to globally import all important TFHE-rs traits at once. This approach saves time and avoids confusion.

use tfhe::prelude::*;

Serialization/deserialization

This document explains the serialization and deserialization features that are useful to send data to a server to perform the computations.

Serialization/deserialization

Here is a full example:

# Cargo.toml

[dependencies]
# ...
tfhe = { version = "0.7.5", features = ["integer","x86_64-unix"]}
bincode = "1.3.3"

// main.rs

use bincode;
use std::io::Cursor;
use tfhe::{ConfigBuilder, ServerKey, generate_keys, set_server_key, FheUint8};
use tfhe::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>>{
    let config = ConfigBuilder::default().build();

    let ( client_key, server_key) = generate_keys(config);

    let msg1 = 1;
    let msg2 = 0;

    let value_1 = FheUint8::encrypt(msg1, &client_key);
    let value_2 = FheUint8::encrypt(msg2, &client_key);

    // Prepare to send data to the server
    // The ClientKey is _not_ sent
    let mut serialized_data = Vec::new();
    bincode::serialize_into(&mut serialized_data, &server_key)?;
    bincode::serialize_into(&mut serialized_data, &value_1)?;
    bincode::serialize_into(&mut serialized_data, &value_2)?;

    // Simulate sending serialized data to a server and getting
    // back the serialized result
    let serialized_result = server_function(&serialized_data)?;
    let result: FheUint8 = bincode::deserialize(&serialized_result)?;

    let output: u8 = result.decrypt(&client_key);
    assert_eq!(output, msg1 + msg2);
    Ok(())
}


fn server_function(serialized_data: &[u8]) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let mut serialized_data = Cursor::new(serialized_data);
    let server_key: ServerKey = bincode::deserialize_from(&mut serialized_data)?;
    let ct_1: FheUint8 = bincode::deserialize_from(&mut serialized_data)?;
    let ct_2: FheUint8 = bincode::deserialize_from(&mut serialized_data)?;

    set_server_key(server_key);

    let result = ct_1 + ct_2;

    let serialized_result = bincode::serialize(&result)?;

    Ok(serialized_result)
}

Safe serialization/deserialization

When dealing with sensitive types, it's important to implement safe serialization and safe deserialization functions to prevent runtime errors and enhance security. The safe serialization and deserialization use bincode internally.

The safe deserialization must take the output of a safe-serialization as input. During the process, the following validation occurs:

Type match: deserializing type A from a serialized type B raises an error indicating "On deserialization, expected type A, got type B".
Version compatibility: deserializing type A of a newer version (for example, version 0.2) from a serialized type A of an older version (for example, version 0.1) raises an error indicating "On deserialization, expected serialization version 0.2, got version 0.1".
Parameter compatibility: deserializing an object of type A with one set of crypto parameters from an object of type A with another set of crypto parameters raises an error indicating "Deserialized object of type A not conformant with given parameter set"
- If both parameter sets have the same LWE dimension for ciphertexts, a ciphertext from param 1 may not fail this deserialization check with param 2.
- This check can't distinguish ciphertexts/server keys from independent client keys with the same parameters.
- This check is meant to prevent runtime errors in server homomorphic operations by checking that server keys and ciphertexts are compatible with the same parameter set.
- You can use the standalone is_conformant method to check parameter compatibility. Besides, the safe_deserialize_conformant function includes the parameter compatibility check, and the safe_deserialize function does not include the compatibility check.
Size limit: both serialization and deserialization processes expect a size limit (measured in bytes) for the serialized data:
- On serialization, an error is raised if the serialized output exceeds the specific limit.
- On deserialization, an error is raised if the serialized input exceeds the specific limit.

This feature aims to gracefully return an error in case of an attacker trying to cause an out-of-memory error on deserialization.

Here is an example:

// main.rs

use tfhe::conformance::ParameterSetConformant;
use tfhe::integer::parameters::RadixCiphertextConformanceParams;
use tfhe::prelude::*;
use tfhe::safe_deserialization::{safe_deserialize_conformant, safe_serialize};
use tfhe::shortint::parameters::{PARAM_MESSAGE_2_CARRY_2_KS_PBS, PARAM_MESSAGE_2_CARRY_2_PBS_KS};
use tfhe::conformance::ListSizeConstraint;
use tfhe::{
    generate_keys, FheUint8, CompactCiphertextList, FheUint8ConformanceParams,
    CompactPublicKey, ConfigBuilder, CompactCiphertextListConformanceParams
};

fn main() {
    let config = ConfigBuilder::default().build();

    let params_1 = PARAM_MESSAGE_2_CARRY_2_KS_PBS;
    let params_2 = PARAM_MESSAGE_2_CARRY_2_PBS_KS;
    
    let (client_key, server_key) = generate_keys(
        ConfigBuilder::with_custom_parameters(params_1, None).build()
    );
    
    let conformance_params_1 = FheUint8ConformanceParams::from(params_1);
    let conformance_params_2 = FheUint8ConformanceParams::from(params_2);
    
    let public_key = CompactPublicKey::new(&client_key);

    let msg = 27u8;

    let ct = FheUint8::try_encrypt(msg, &client_key).unwrap();
    
    assert!(ct.is_conformant(&conformance_params_1));
    assert!(!ct.is_conformant(&conformance_params_2));

    let mut buffer = vec![];

    safe_serialize(&ct, &mut buffer, 1 << 40).unwrap();
    
    assert!(safe_deserialize_conformant::<FheUint8>(
        buffer.as_slice(),
        1 << 20,
        &conformance_params_2
    ).is_err());

    let ct2 = safe_deserialize_conformant::<FheUint8>(
        buffer.as_slice(),
        1 << 20,
        &conformance_params_1
    ).unwrap();

    let dec: u8 = ct2.decrypt(&client_key);
    assert_eq!(msg, dec);
    
    
    // Example with a compact list:
    let msgs = [27, 188u8];
    let mut builder = CompactCiphertextList::builder(&public_key);
    builder.extend(msgs.iter().copied());
    let compact_list = builder.build();

    let mut buffer = vec![];
    safe_serialize(&compact_list, &mut buffer, 1 << 40).unwrap();
    
    let conformance_params = CompactCiphertextListConformanceParams {
        shortint_params: params_1.to_shortint_conformance_param(),
        num_elements_constraint: ListSizeConstraint::exact_size(2),
    };
    assert!(safe_deserialize_conformant::<CompactCiphertextList>(
        buffer.as_slice(),
        1 << 20,
        &conformance_params
    ).is_ok());
}

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8};

fn main() {
    let config = ConfigBuilder::default().build();

    let (client_key, server_key) = generate_keys(config);

    set_server_key(server_key);

    let clear_a = 35u8;
    let clear_b = 7u8;

    // Encryption
    let a = FheUint8::encrypt(clear_a, &client_key);
    let b = FheUint8::encrypt(clear_b, &client_key);

    // Take a reference to avoid moving data when doing the computation
    let a = &a;
    let b = &b;

    // Computation using Rust's built-in operators
    let add = a + b;
    let sub = a - b;
    let mul = a * b;
    let div = a / b;
    let rem = a % b;
    let and = a & b;
    let or = a | b;
    let xor = a ^ b;
    let neg = -a;
    let not = !a;
    let shl = a << b;
    let shr = a >> b;

    // Comparison operations need to use specific functions as the definition of the operators in
    // rust require to return a boolean which we cannot do in FHE
    let eq = a.eq(b);
    let ne = a.ne(b);
    let gt = a.gt(b);
    let lt = a.lt(b);

    // Decryption and verification of proper execution
    let decrypted_add: u8 = add.decrypt(&client_key);

    let clear_add = clear_a + clear_b;
    assert_eq!(decrypted_add, clear_add);

    let decrypted_sub: u8 = sub.decrypt(&client_key);

    let clear_sub = clear_a - clear_b;
    assert_eq!(decrypted_sub, clear_sub);

    let decrypted_mul: u8 = mul.decrypt(&client_key);

    let clear_mul = clear_a * clear_b;
    assert_eq!(decrypted_mul, clear_mul);

    let decrypted_div: u8 = div.decrypt(&client_key);

    let clear_div = clear_a / clear_b;
    assert_eq!(decrypted_div, clear_div);

    let decrypted_rem: u8 = rem.decrypt(&client_key);

    let clear_rem = clear_a % clear_b;
    assert_eq!(decrypted_rem, clear_rem);

    let decrypted_and: u8 = and.decrypt(&client_key);

    let clear_and = clear_a & clear_b;
    assert_eq!(decrypted_and, clear_and);

    let decrypted_or: u8 = or.decrypt(&client_key);

    let clear_or = clear_a | clear_b;
    assert_eq!(decrypted_or, clear_or);

    let decrypted_xor: u8 = xor.decrypt(&client_key);

    let clear_xor = clear_a ^ clear_b;
    assert_eq!(decrypted_xor, clear_xor);

    let decrypted_neg: u8 = neg.decrypt(&client_key);

    let clear_neg = clear_a.wrapping_neg();
    assert_eq!(decrypted_neg, clear_neg);

    let decrypted_not: u8 = not.decrypt(&client_key);

    let clear_not = !clear_a;
    assert_eq!(decrypted_not, clear_not);

    let decrypted_shl: u8 = shl.decrypt(&client_key);

    let clear_shl = clear_a << clear_b;
    assert_eq!(decrypted_shl, clear_shl);

    let decrypted_shr: u8 = shr.decrypt(&client_key);

    let clear_shr = clear_a >> clear_b;
    assert_eq!(decrypted_shr, clear_shr);

    let decrypted_eq = eq.decrypt(&client_key);

    let eq = clear_a == clear_b;
    assert_eq!(decrypted_eq, eq);

    let decrypted_ne = ne.decrypt(&client_key);

    let ne = clear_a != clear_b;
    assert_eq!(decrypted_ne, ne);

    let decrypted_gt = gt.decrypt(&client_key);

    let gt = clear_a > clear_b;
    assert_eq!(decrypted_gt, gt);

    let decrypted_lt = lt.decrypt(&client_key);

    let lt = clear_a < clear_b;
    assert_eq!(decrypted_lt, lt);
}

Encrypted pseudo random values

This document gives an example of generating pseudo random values in FHE that are not known by the server.

use tfhe::prelude::FheDecrypt;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8, Seed};

pub fn main() {
    let config = ConfigBuilder::default().build();
    let (client_key, server_key) = generate_keys(config);

    set_server_key(server_key);

    let random_bits_count = 3;

    // You can pass a 128 bits Seed here
    // The generated values will always be the same for a given server key
    // The server cannot know what value was generated
    let ct_res = FheUint8::generate_oblivious_pseudo_random(Seed(0), random_bits_count);

    let dec_result: u8 = ct_res.decrypt(&client_key);
    assert!(dec_result < (1 << random_bits_count));
}

Rust configuration

This document provides basic instructions to configure the Rust toolchain and features for TFHE-rs.

TFHE-rs requires a nightly Rust toolchain to build the C API and utilize advanced SIMD instructions. However, for other uses, a stable toolchain (version 1.73 or later) is sufficient.

Follow the following instructions to install the necessary Rust toolchain:

# If you don't need the C API or the advanced still unstable SIMD instructions use this
rustup toolchain install stable
# Otherwise install a nightly toolchain
rustup toolchain install nightly

Setting the toolchain

You can set the toolchain using either of the following methods.

Manually specify the toolchain for each cargo command:

# By default the +stable should not be needed, but we add it here for completeness
cargo +stable build --release
cargo +stable test --release
# Or
cargo +nightly build --release
cargo +nightly test --release

Override the toolchain for the current project:

# This should not be necessary by default, but if you want to make sure your configuration is
# correct you can still set the overridden toolchain to stable
rustup override set stable
# cargo will use the `stable` toolchain.
cargo build --release
# Or
rustup override set nightly
# cargo will use the `nightly` toolchain.
cargo build --release

To verify the default toolchain used by Cargo, execute:

rustup show

Choosing your features

TFHE-rs provides various cargo features to customize the types and features used.

Homomorphic types

This crate provides 3 kinds of data types. Each kind is enabled by activating the corresponding feature in the TOML line and has multiple types:

Kind

Features

Type (s)

Booleans

boolean

Booleans

ShortInts

shortint

Short integers

Integers

integer

Arbitrary-sized integers

AVX-512

cargo +nightly build --release --features=nightly-avx512

Generic trait bounds

Operators such as +, *, >>, and so on are tied to traits in std:::ops. For instance, the + operator corresponds to std::ops::Add. When writing a generic function that uses the + operator, you need to specify std::ops::Add as a trait bound.

The trait bound varies slightly depending on whether the left-hand side / right-hand side is an owned value or a reference. The following table shows the different scenarios:

operation

trait bound

T $op T

T: $Op<T, Output=T>

T $op &T

T: for<'a> $Op<&'a T, Output=T>

&T $op T

for<'a> &'a T: $Op<T, Output=T>

&T $op &T

for<'a> &'a T: $Op<&'a T, Output=T>

Using generic functions allows for clearer input handling, which simplifies the debugging.

Example

use std::ops::{Add, Mul};
use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint32, FheUint64};

pub fn ex1<'a, FheType, ClearType>(ct: &'a FheType, pt: ClearType) -> FheType
    where
        &'a FheType: Add<ClearType, Output = FheType>,
{
    ct + pt
}

pub fn ex2<'a, FheType, ClearType>(a: &'a FheType, b: &'a FheType, pt: ClearType) -> FheType
    where
        &'a FheType: Mul<&'a FheType, Output = FheType>,
        FheType: Add<ClearType, Output = FheType>,
{
    (a * b) + pt
}

pub fn ex3<FheType, ClearType>(a: FheType, b: FheType, pt: ClearType) -> FheType
    where
            for<'a> &'a FheType: Add<&'a FheType, Output = FheType>,
            FheType: Add<FheType, Output = FheType> + Add<ClearType, Output = FheType>,
{
    let tmp = (&a + &b) + (&a + &b);
    tmp + pt
}

pub fn ex4<FheType, ClearType>(a: FheType, b: FheType, pt: ClearType) -> FheType
    where
        FheType: Clone + Add<FheType, Output = FheType> + Add<ClearType, Output = FheType>,
{
    let tmp = (a.clone() + b.clone()) + (a.clone() + b.clone());
    tmp + pt
}

fn main() {
    let config = ConfigBuilder::default()
        .build();

    let (client_key, server_keys) = generate_keys(config);

    set_server_key(server_keys);

    // Use FheUint32
    {
        let clear_a = 46546u32;
        let clear_b = 6469u32;
        let clear_c = 64u32;

        let a = FheUint32::try_encrypt(clear_a, &client_key).unwrap();
        let b = FheUint32::try_encrypt(clear_b, &client_key).unwrap();
        assert_eq!(
            ex1(&clear_a, clear_c),
            ex1(&a, clear_c).decrypt(&client_key)
        );
        assert_eq!(
            ex2(&clear_a, &clear_b, clear_c),
            ex2(&a, &b, clear_c).decrypt(&client_key)
        );
        assert_eq!(
            ex3(clear_a, clear_b, clear_c),
            ex3(a.clone(), b.clone(), clear_c).decrypt(&client_key)
        );
        assert_eq!(
            ex4(clear_a, clear_b, clear_c),
            ex4(a, b, clear_c).decrypt(&client_key)
        );
    }

    // Use FheUint64
    {
        let clear_a = 46544866u64;
        let clear_b = 6469446677u64;
        let clear_c = 647897u64;

        let a = FheUint64::try_encrypt(clear_a, &client_key).unwrap();
        let b = FheUint64::try_encrypt(clear_b, &client_key).unwrap();
        assert_eq!(
            ex1(&clear_a, clear_c),
            ex1(&a, clear_c).decrypt(&client_key)
        );
        assert_eq!(
            ex2(&clear_a, &clear_b, clear_c),
            ex2(&a, &b, clear_c).decrypt(&client_key)
        );
        assert_eq!(
            ex3(clear_a, clear_b, clear_c),
            ex3(a.clone(), b.clone(), clear_c).decrypt(&client_key)
        );
        assert_eq!(
            ex4(clear_a, clear_b, clear_c),
            ex4(a, b, clear_c).decrypt(&client_key)
        );
    }
}

What is TFHE-rs?

TFHE-rs is a pure Rust implementation of Fully Homomorphic Encryption over the Torus (TFHE) to perform Boolean and integer arithmetic on encrypted data.

TFHE-rs implements advanced TFHE features, empowering developers and researchers with fine-grained control over TFHE so that they can focus on high-level functionality without delving into low-level implementation.

TFHE-rs includes:

Rust API: the primary API for working with TFHE-rs in Rust projects.
C API: for developers who prefer to use C.
Client-side WASM API: to integrate TFHE-rs functionalities into WebAssembly applications.

Key cryptographic concepts

TFHE is a Fully Homomorphic Encryption (FHE) scheme based on Learning With Errors (LWE), which is a secure cryptographic primitive against even quantum computers. The TFHE-rs library implements Zama’s variant of TFHE.

Homomorphic Encryption Basics

The basic elements of cryptography:

Message (or Cleartext): raw values before encryption.
Plaintext: encoded messages.
Ciphertext: encrypted messages.

FHE allows to compute on ciphertexts without revealing the content of the messages. A scheme is fully homomorphic if it supports at least two of the following operations when evaluating any programs. ( $x$ is a plaintext and $E[x]$ is the corresponding ciphertext):

Homomorphic univariate function evaluation: $f(E[x]) = E[f(x)]$
Homomorphic addition: $E[x] + E[y] = E[x + y]$
Homomorphic multiplication: $E[x] * E[y] = E[x * y]$

Zama's variant of TFHE

Zama's variant of TFHE is a fully homomorphic scheme that takes fixed-precision numbers as messages. It implements all homomorphic operations needed, such as addition and function evaluation via Programmable Bootstrapping.

Using TFHE-rs in Rust includes the following steps:

Key generation: generate a pair of keys using secure parameters.
- Client key: used for encryption and decryption of data. This key must be kept secret.
- Server key (or Evaluation key): used for performing operations on encrypted data. This key could be public.
Encryption: encrypt plaintexts using the client key to produce ciphertexts.
Homomorphic operation: perform operations on ciphertexts using the server key.
Decryption: decrypt the resulting ciphertexts back to plaintexts using the client key.

Debugging

This document explains a feature to facilitate debugging.

Trivial ciphertexts are not secure. An application released/deployed in production must never receive trivial ciphertext from a client.

To use this feature, simply call your circuits/functions with trivially encrypted values that are created using encrypt_trivial(instead of real encryptions that are created using encrypt):

use tfhe::prelude::*;
use tfhe::{set_server_key, generate_keys, ConfigBuilder, FheUint128};


fn mul_all(a: &FheUint128, b: &FheUint128, c: &FheUint128) -> FheUint128 {
    // Use the debug format ('{:?}'), if you don't want to unwrap()
    // and panic if the value is not a trivial.
    println!(
        "a: {:?}, b: {:?}, c: {:?}", 
        a.try_decrypt_trivial::<u128>(),
        b.try_decrypt_trivial::<u128>(),
        c.try_decrypt_trivial::<u128>(),
    );
    let tmp = a * b;
    
    println!("a * b = {:?}", tmp.try_decrypt_trivial::<u128>());

    tmp * c
}


fn main() {
    let (cks, sks) = generate_keys(ConfigBuilder::default().build());
    
    set_server_key(sks);
    
    let a = FheUint128::encrypt_trivial(1234u128);
    let b = FheUint128::encrypt_trivial(4567u128);
    let c = FheUint128::encrypt_trivial(89101112u128);
    
    // since all inputs are trivially encrypted, this is going to be
    // much faster
    let result = mul_all(&a, &b, &c);
}

This example is going to print:

a: Ok(1234), b: Ok(4567), c: Ok(89101112)
a * b = Ok(5635678)

If any input to mul_all is not a trivial ciphertexts, the computations will be done 100% in FHE, and the program will output:

a: Err(NotTrivialCiphertextError), b: Err(NotTrivialCiphertextError), c: Err(NotTrivialCiphertextError)
a * b = Err(NotTrivialCiphertextError)

Using trivial encryptions as input, the example runs in 980 ms on a standard 12-core laptop, compared to 7.5 seconds on a 128-core machine using real encryptions.

Decryption

This document provides instructions on how to decrypt data.

To decrypt data, use the decrypt method from the FheDecrypt trait:

use tfhe::prelude::*;
use tfhe::{generate_keys, ConfigBuilder, FheUint8};

fn main() {
    let config = ConfigBuilder::default().build();

    let (client_key, server_key) = generate_keys(config);

    let clear_a = 27u8;
    let clear_b = 128u8;

    let a = FheUint8::encrypt(clear_a, &client_key);
    let b = FheUint8::encrypt(clear_b, &client_key);

    let decrypted_a: u8 = a.decrypt(&client_key);
    let decrypted_b: u8 = b.decrypt(&client_key);

    assert_eq!(decrypted_a, clear_a);
    assert_eq!(decrypted_b, clear_b);
}

Trivial ciphertexts

This document describes how to use trivial encryption in TFHE-rs to initialize server-side values.

Sometimes, the server side needs to initialize a value. For example, when computing the sum of a list of ciphertexts, you typically initialize the sum variable to 0.

Instead of asking the client to send an actual encrypted zero, the server can use a trivial encryption. A trivial encryption creates a ciphertext that contains the desired value but isn't securely encrypted - essentially anyone, any key can decrypt it.

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8};

let config = ConfigBuilder::default().build();
let (client_key, sks) = generate_keys(config);

set_server_key(sks);

let a = FheUint8::try_encrypt_trivial(234u8).unwrap();

let clear: u8 = a.decrypt(&client_key);
assert_eq!(clear, 234);

Note that when you want to do an operation that involves a ciphertext and a clear value (often called scalar operation), you should only use trivial encryption of the clear value if the scalar operations that you want to run are not supported.

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint32};

let config = ConfigBuilder::default().build();
let (client_key, sks) = generate_keys(config);

set_server_key(sks);

// This is going to be faster
let a = FheUint32::try_encrypt(2097152u32, &client_key).unwrap();
let shift = 1u32;
let shifted = a << shift;
let clear: u32 = shifted.decrypt(&client_key);
assert_eq!(clear, 2097152 << 1);

// This is going to be slower
let a = FheUint32::try_encrypt(2097152u32, &client_key).unwrap();
let shift = FheUint32::try_encrypt_trivial(1u32).unwrap();
let shifted = a << shift;
let clear: u32 = shifted.decrypt(&client_key);
assert_eq!(clear, 2097152 << 1);

JS on WASM API

This document outlines how to use the TFHE-rs WebAssembly (WASM) client API for key generation, encryption, and decryption, providing setup examples for Node.js and web browsers.

TFHE-rs supports WASM client API, which includes functionality for key generation, encryption, and decryption. However, it does not support FHE computations.

TFHE-rs supports 3 WASM targets:

Node.js: For use in Node.js applications or packages
Web: For use in web browsers
Web-parallel: For use in web browsers with multi-threading support

The core of the API remains the same, requiring only minor changes in the initialization functions.

Node.js

Example:


const {
    init_panic_hook,
    ShortintParametersName,
    ShortintParameters,
    TfheClientKey,
    TfheCompactPublicKey,
    TfheCompressedServerKey,
    TfheConfigBuilder,
    CompactFheUint32List
} = require("./pkg/tfhe.js");

function fhe_uint32_example() {
    // Makes it so that if a rust thread panics,
    // the error message will be displayed in the console
    init_panic_hook();

    const block_params = new ShortintParameters(ShortintParametersName.PARAM_SMALL_MESSAGE_2_CARRY_2_COMPACT_PK);
    let config = TfheConfigBuilder.default()
        .build();

    let clientKey = TfheClientKey.generate(config);
    let compressedServerKey = TfheCompressedServerKey.new(clientKey);
    let publicKey = TfheCompactPublicKey.new(clientKey);

    let values = [0, 1, 2394, U32_MAX];
    let compact_list = CompactFheUint32List.encrypt_with_compact_public_key(values, publicKey);

    let serialized_list = compact_list.serialize();
    let deserialized_list = CompactFheUint32List.deserialize(serialized_list);
    let encrypted_list = deserialized_list.expand();
    assert.deepStrictEqual(encrypted_list.length, values.length);

    for (let i = 0; i < values.length; i++)
    {
        let decrypted = encrypted_list[i].decrypt(clientKey);
        assert.deepStrictEqual(decrypted, values[i]);
    }
}

Web

When using the Web WASM target, you should call an additional init function. With parallelism enabled, you need to call another additional initThreadPool function.

Example:

import init, {
    initThreadPool, // only available with parallelism
    init_panic_hook,
    ShortintParametersName,
    ShortintParameters,
    TfheClientKey,
    TfhePublicKey,
} from "./pkg/tfhe.js";

async function example() {
    await init()
    await initThreadPool(navigator.hardwareConcurrency);
    await init_panic_hook();

    const block_params = new ShortintParameters(ShortintParametersName.PARAM_SMALL_MESSAGE_2_CARRY_2_COMPACT_PK);
    // ....
}

Compiling the WASM API

Use the provided Makefile in the TFHE-rs repository to compile for the desired target:

make build_node_js_api for the Node.js API
make build_web_js_api for the browser API
make build_web_js_api_parallel for the browser API with parallelism

The compiled WASM packages are located in tfhe/pkg.

The browser API and the Node.js API are available as npm packages. Using npm i tfhe for the browser API and npm i node-tfhe for the Node.js API.

Using the JS on WASM API

TFHE-rs uses WASM to provide a JavaScript (JS) binding to the client-side primitives, like key generation and encryption within the Boolean and shortint modules.

Currently, there are several limitations. Due to a lack of threading support in WASM, key generation can be too slow to be practical for bigger parameter sets.

Some parameter sets lead to the FHE keys exceeding the 2GB memory limit of WASM, making these parameter sets virtually unusable.

First steps using TFHE-rs JS on WASM API

Setting up TFHE-rs JS on WASM API for Node.js programs.

$ git clone https://github.com/zama-ai/tfhe-rs.git
Cloning into 'tfhe-rs'...
...
Resolving deltas: 100% (3866/3866), done.
$ cd tfhe-rs
$ cd tfhe
$ rustup run wasm-pack build --release --target=nodejs --features=boolean-client-js-wasm-api,shortint-client-js-wasm-api
[INFO]: Compiling to Wasm...
...
[INFO]: :-) Your wasm pkg is ready to publish at ...

The command above targets Node.js. To generate a binding for a web browser, use --target=web. However, this tutorial does not cover that particular use case.

Both Boolean and shortint features are enabled here, but it's possible to use them individually.

After the build, a new directory pkg is available in the tfhe directory.

$ ls pkg
LICENSE  index.html  package.json  tfhe.d.ts  tfhe.js  tfhe_bg.txt  tfhe_bg.wasm  tfhe_bg.wasm.d.ts
$

Commented code to generate keys for shortint and encrypt a ciphertext

Make sure to update the path of the required clause in the example below to match the location of the TFHE package that was just built.

// Here import assert to check the decryption went well and panic otherwise
const assert = require('node:assert').strict;
// Import the Shortint module from the TFHE-rs package generated earlier
const { Shortint } = require("/path/to/built/tfhe/pkg");

function shortint_example() {
    // Get pre-defined parameters from the shortint module to manage messages with 4 bits of useful
    // information in total (2 bits of "message" and 2 bits of "carry")
    let params = Shortint.get_parameters(2, 2);
    // Create a new secret ClientKey, this must not be shared
    console.log("Generating client keys...")
    let cks = Shortint.new_client_key(params);
    // Encrypt 3 in a ciphertext
    console.log("Encrypting 3...")
    let ct = Shortint.encrypt(cks, BigInt(3));

    // Demonstrate ClientKey serialization (for example saving it on disk on the user device)
    let serialized_cks = Shortint.serialize_client_key(cks);
    // Deserialization
    let deserialized_cks = Shortint.deserialize_client_key(serialized_cks);

    // Demonstrate ciphertext serialization to send over the network
    let serialized_ct = Shortint.serialize_ciphertext(ct);
    // Deserialize a ciphertext received over the network for example
    let deserialized_ct = Shortint.deserialize_ciphertext(serialized_ct);

    // Decrypt with the deserialized objects
    console.log("Decrypting ciphertext...")
    let decrypted = Shortint.decrypt(deserialized_cks, deserialized_ct);
    // Check decryption works as expected
    assert.deepStrictEqual(decrypted, BigInt(3));
    console.log("Decryption successful!")

    // Generate public evaluation keys, also called ServerKey
    console.log("Generating compressed ServerKey...")
    let sks = Shortint.new_compressed_server_key(cks);

    // Can be serialized to send over the network to the machine doing the evaluation
    let serialized_sks = Shortint.serialize_compressed_server_key(sks);
    let deserialized_sks = Shortint.deserialize_compressed_server_key(serialized_sks);
    console.log("All done!")
}

shortint_example();

$ node example.js
Generating client keys...
Encrypting 3...
Decrypting ciphertext...
Decryption successful!
Generating compressed ServerKey...
All done!
$

Zero-knowledge proofs

This document explains how to implement the zero-knowledge proofs function for compact public key encryption to verify the encryption process without revealing the encrypted information.

You can enable this feature using the flag: --features=zk-pok when building TFHE-rs.

Using this feature is straightforward: during encryption, the client generates the proof, and the server validates it before conducting any homomorphic computations. The following example demonstrates how a client can encrypt and prove a ciphertext, and how a server can verify the ciphertext and compute it:

use rand::prelude::*;
use tfhe::prelude::FheDecrypt;
use tfhe::set_server_key;
use tfhe::zk::{CompactPkeCrs, ZkComputeLoad};

pub fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut rng = thread_rng();

    let params =
        tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS_TUNIFORM_2M64;
    let config = tfhe::ConfigBuilder::with_custom_parameters(params, None);

    let client_key = tfhe::ClientKey::generate(config.clone());
    // This is done in an offline phase and the CRS is shared to all clients and the server
    let crs = CompactPkeCrs::from_config(config.into(), 64).unwrap();
    let public_zk_params = crs.public_params();
    let server_key = tfhe::ServerKey::new(&client_key);
    let public_key = tfhe::CompactPublicKey::try_new(&client_key).unwrap();

    let clear_a = rng.gen::<u64>();
    let clear_b = rng.gen::<u64>();
    
    let proven_compact_list = tfhe::ProvenCompactCiphertextList::builder(&public_key)
        .push(clear_a)
        .push(clear_b)
        .build_with_proof_packed(public_zk_params, ZkComputeLoad::Proof)?;

    // Server side
    let result = {
        set_server_key(server_key);

        // Verify the ciphertexts
        let mut expander = proven_compact_list.verify_and_expand(&public_zk_params, &public_key)?;
        let a: tfhe::FheUint64 = expander.get(0).unwrap()?;
        let b: tfhe::FheUint64 = expander.get(1).unwrap()?;

        a + b
    };

    // Back on the client side
    let a_plus_b: u64 = result.decrypt(&client_key);
    assert_eq!(a_plus_b, clear_a.wrapping_add(clear_b));

    Ok(())
}

Performance can be improved by setting lto="fat" in Cargo.toml

[profile.release]
lto = "fat"

and by building the code for the native CPU architecture and in release mode, e.g. by calling RUSTFLAGS="-C target-cpu=native" cargo run --release.

You can choose a more costly proof with ZkComputeLoad::Proof, which has a faster verification time. Alternatively, you can select ZkComputeLoad::Verify for a faster proof and slower verification.

Using dedicated Compact Public Key parameters

A first example

You can use dedicated parameters for the compact public key encryption to reduce the size of encrypted data and speed up the zero-knowledge proof computation.

This works essentially in the same way as before. Additionally, you need to indicate the dedicated parameters to use:

use rand::prelude::*;
use tfhe::prelude::FheDecrypt;
use tfhe::set_server_key;
use tfhe::zk::{CompactPkeCrs, ZkComputeLoad};

pub fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut rng = thread_rng();

    let params = tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS_TUNIFORM_2M64;
    // Indicate which parameters to use for the Compact Public Key encryption
    let cpk_params = tfhe::shortint::parameters::compact_public_key_only::PARAM_PKE_MESSAGE_2_CARRY_2_KS_PBS_TUNIFORM_2M64;
    // And parameters allowing to keyswitch/cast to the computation parameters.
    let casting_params = tfhe::shortint::parameters::key_switching::PARAM_KEYSWITCH_MESSAGE_2_CARRY_2_KS_PBS_TUNIFORM_2M64;
    // Enable the dedicated parameters on the config
    let config = tfhe::ConfigBuilder::with_custom_parameters(params, None)
        .use_dedicated_compact_public_key_parameters((cpk_params, casting_params));

    // Then use TFHE-rs as usual
    let client_key = tfhe::ClientKey::generate(config.clone());
    // This is done in an offline phase and the CRS is shared to all clients and the server
    let crs = CompactPkeCrs::from_config(config.into(), 64).unwrap();
    let public_zk_params = crs.public_params();
    let server_key = tfhe::ServerKey::new(&client_key);
    let public_key = tfhe::CompactPublicKey::try_new(&client_key).unwrap();

    let clear_a = rng.gen::<u64>();
    let clear_b = rng.gen::<u64>();

    let proven_compact_list = tfhe::ProvenCompactCiphertextList::builder(&public_key)
        .push(clear_a)
        .push(clear_b)
        .build_with_proof_packed(public_zk_params, ZkComputeLoad::Verify)?;

    // Server side
    let result = {
        set_server_key(server_key);

        // Verify the ciphertexts
        let mut expander = proven_compact_list.verify_and_expand(&public_zk_params, &public_key)?;
        let a: tfhe::FheUint64 = expander.get(0).unwrap()?;
        let b: tfhe::FheUint64 = expander.get(1).unwrap()?;

        a + b
    };

    // Back on the client side
    let a_plus_b: u64 = result.decrypt(&client_key);
    assert_eq!(a_plus_b, clear_a.wrapping_add(clear_b));

    Ok(())
}

Benchmarks

Benchmarks for the proofs have been run on a m6i.4xlarge with 16 cores to simulate an usual client configuration. The verification are done on a hpc7a.96xlarge AWS instances to mimic a powerful server.

Timings in the case where the workload is mainly on the prover, i.e., with the ZkComputeLoad::Proof option.

Inputs

Proving

Verifying

1xFheUint64

2.79s

197ms

10xFheUint64

3.68s

251ms

Timings in the case where the workload is mainly on the verifier, i.e., with the ZkComputeLoad::Verify option.

Inputs

Proving

Verifying

1xFheUint64

730ms

522ms

10xFheUint64

1.08s

682ms

Multi-threading with Rayon crate

This document describes how to use Rayon for parallel processing in TFHE-rs, detailing configurations for single and multi-client applications with code examples.

Single-client application

The problem

The high-level API requires to call set_server_key on each thread where computations need to be done. So a first attempt to use Rayon with TFHE-rs might look like this:

use rayon::prelude::*;
use tfhe::prelude::*;
use tfhe::{ConfigBuilder, set_server_key, FheUint8, generate_keys};

fn main() {
    let (cks, sks) = generate_keys(ConfigBuilder::default());
    
    let xs = [
        FheUint8::encrypt(1u8, &cks),
        FheUint8::encrypt(2u8, &cks),
    ];

    let ys = [
        FheUint8::encrypt(3u8, &cks),
        FheUint8::encrypt(4u8, &cks),
    ];


    // set_server_key in each closure as they might be
    // running in different threads
    let (a, b) = rayon::join(
      || {
          set_server_key(sks.clone());
          &xs[0] + &ys[0]
      },
      || {
          set_server_key(sks.clone());
          &xs[1] + &ys[1]
      }
    );
}

However, due to Rayon's work-stealing mechanism and TFHE-rs' internals, this may create BorrowMutError.

Working example

The correct way is to call rayon::broadcast as follows:

use rayon::prelude::*;
use tfhe::prelude::*;
use tfhe::{ConfigBuilder, set_server_key, FheUint8, generate_keys};

fn main() {
    let (cks, sks) = generate_keys(ConfigBuilder::default());
    
    // set the server key in all of the rayon's threads so that
    // we won't need to do it later
    rayon::broadcast(|_| set_server_key(sks.clone()));
    // Set the server key in the main thread
    set_server_key(sks);
    
    let xs = [
        FheUint8::encrypt(1u8, &cks),
        FheUint8::encrypt(2u8, &cks),
    ];

    let ys = [
        FheUint8::encrypt(3u8, &cks),
        FheUint8::encrypt(4u8, &cks),
    ];

    let (a, b) = rayon::join(
      || {
          &xs[0] + &ys[0]
      },
      || {
          &xs[1] + &ys[1]
      }
    );

    let a: u8 = a.decrypt(&cks);
    let b: u8 = b.decrypt(&cks);
    assert_eq!(a, 4u8);
    assert_eq!(b, 6u8);
}

Multi-client applications

For applications that need to operate concurrently on data from different clients and require each client to use multiple threads, you need to create separate Rayon thread pools:

use rayon::prelude::*;
use tfhe::prelude::*;
use tfhe::{ConfigBuilder, set_server_key, FheUint8, generate_keys};

fn main() {
    let (cks1, sks1) = generate_keys(ConfigBuilder::default());
    let xs1 = [
        FheUint8::encrypt(1u8, &cks1),
        FheUint8::encrypt(2u8, &cks1),
    ];

    let ys1 = [
        FheUint8::encrypt(3u8, &cks1),
        FheUint8::encrypt(4u8, &cks1),
    ];

    let (cks2, sks2) = generate_keys(ConfigBuilder::default());
    let xs2 = [
        FheUint8::encrypt(100u8, &cks2),
        FheUint8::encrypt(200u8, &cks2),
    ];

    let ys2 = [
        FheUint8::encrypt(103u8, &cks2),
        FheUint8::encrypt(204u8, &cks2),
    ];

    let client_1_pool = rayon::ThreadPoolBuilder::new().num_threads(4).build().unwrap();
    let client_2_pool = rayon::ThreadPoolBuilder::new().num_threads(2).build().unwrap();
    
    client_1_pool.broadcast(|_| set_server_key(sks1.clone()));
    client_2_pool.broadcast(|_| set_server_key(sks2.clone()));
    
    let ((a1, b1), (a2, b2)) = rayon::join(|| {
        client_1_pool.install(|| {
            rayon::join(
                || {
                    &xs1[0] + &ys1[0]
                },
                || {
                    &xs1[1] + &ys1[1]
                }
            )
        })
    }, || {
        client_2_pool.install(|| {
            rayon::join(
                || {
                    &xs2[0] + &ys2[0]
                },
                || {
                    &xs2[1] + &ys2[1]
                }
            )
        })
    });
    
    let a1: u8 = a1.decrypt(&cks1);
    let b1: u8 = b1.decrypt(&cks1);
    assert_eq!(a1, 4u8);
    assert_eq!(b1, 6u8);

    let a2: u8 = a2.decrypt(&cks2);
    let b2: u8 = b2.decrypt(&cks2);
    assert_eq!(a2, 203u8);
    assert_eq!(b2, 148u8);
}

This can be useful if you have some rust #[test], see the example below:

// Pseudo code
#[test]
fn test_1() {
    let pool = rayon::ThreadPoolBuilder::new().num_threads(4).build().unwrap();
    pool.broadcast(|_| set_server_key(sks1.clone()));
    pool.install(|| {
        let result = call_to_a_multithreaded_function(...);
        assert_eq!(result, expected_value);
    })
}

#[test]
fn test_2() {
    let pool = rayon::ThreadPoolBuilder::new().num_threads(4).build().unwrap();
    pool.broadcast(|_| set_server_key(sks1.clone()));
    pool.install(|| {
        let result = call_to_another_multithreaded_function(...);
        assert_eq!(result, expected_value);
    })
}

GPU acceleration

This guide explains how to update your existing program to leverage GPU acceleration, or to start a new program using GPU.

TFHE-rs now supports a GPU backend with CUDA implementation, enabling integer arithmetic operations on encrypted data.

Prerequisites

Cuda version >= 10
Compute Capability >= 3.0

Importing to your project

To use the TFHE-rs GPU backend in your project, add the following dependency in your Cargo.toml.

If you are using an x86 machine:

tfhe = { version = "0.7.5", features = [ "boolean", "shortint", "integer", "x86_64-unix", "gpu" ] }

If you are using an ARM machine:

tfhe = { version = "0.7.5", features = [ "boolean", "shortint", "integer", "aarch64-unix", "gpu" ] }

For optimal performance when using TFHE-rs, run your code in release mode with the --release flag.

Supported platforms

TFHE-rs GPU backend is supported on Linux (x86, aarch64).

x86

aarch64

Linux

x86_64-unix

aarch64-unix*

macOS

Unsupported

Unsupported*

Windows

Unsupported

A first example

Configuring and creating keys.

Here is a full example (combining the client and server parts):

use tfhe::{ConfigBuilder, set_server_key, FheUint8, ClientKey, CompressedServerKey};
use tfhe::prelude::*;

fn main() {

    let config = ConfigBuilder::default().build();

    let client_key= ClientKey::generate(config);
    let compressed_server_key = CompressedServerKey::new(&client_key);

    let gpu_key = compressed_server_key.decompress_to_gpu();

    let clear_a = 27u8;
    let clear_b = 128u8;

    let a = FheUint8::encrypt(clear_a, &client_key);
    let b = FheUint8::encrypt(clear_b, &client_key);

    //Server-side

    set_server_key(gpu_key);
    let result = a + b;

    //Client-side
    let decrypted_result: u8 = result.decrypt(&client_key);

    let clear_result = clear_a + clear_b;

    assert_eq!(decrypted_result, clear_result);
}

Setting the keys

The configuration of the key is different from the CPU. More precisely, if both client and server keys are still generated by the client (which is assumed to run on a CPU), the server key has then to be decompressed by the server to be converted into the right format. To do so, the server should run this function: decompressed_to_gpu().

Once decompressed, the operations between CPU and GPU are identical.

Encryption

On the client-side, the method to encrypt the data is exactly the same than the CPU one, as shown in the following example:

    let clear_a = 27u8;
    let clear_b = 128u8;
    
    let a = FheUint8::encrypt(clear_a, &client_key);
    let b = FheUint8::encrypt(clear_b, &client_key);

Computation

The server first need to set up its keys with set_server_key(gpu_key).

    //Server-side
    set_server_key(gpu_key);
    let result = a + b;

    //Client-side
    let decrypted_result: u8 = result.decrypt(&client_key);

    let clear_result = clear_a + clear_b;

    assert_eq!(decrypted_result, clear_result);

Decryption

Finally, the client decrypts the results using:

    let decrypted_result: u8 = result.decrypt(&client_key);

Improving performance

TFHE-rs allows to leverage the high number of threads given by a GPU. To maximize the number of GPU threads, update your configuration accordingly:

let config = ConfigBuilder::with_custom_parameters(PARAM_GPU_MULTI_BIT_MESSAGE_2_CARRY_2_GROUP_3_KS_PBS, None).build();

Here's the complete example:

use tfhe::{ConfigBuilder, set_server_key, FheUint8, ClientKey, CompressedServerKey};
use tfhe::prelude::*;
use tfhe::shortint::parameters::PARAM_GPU_MULTI_BIT_MESSAGE_2_CARRY_2_GROUP_3_KS_PBS;

fn main() {

    let config = ConfigBuilder::with_custom_parameters(PARAM_GPU_MULTI_BIT_MESSAGE_2_CARRY_2_GROUP_3_KS_PBS, None).build();

    let client_key= ClientKey::generate(config);
    let compressed_server_key = CompressedServerKey::new(&client_key);

    let gpu_key = compressed_server_key.decompress_to_gpu();

    let clear_a = 27u8;
    let clear_b = 128u8;

    let a = FheUint8::encrypt(clear_a, &client_key);
    let b = FheUint8::encrypt(clear_b, &client_key);

    //Server-side

    set_server_key(gpu_key);
    let result = a + b;

    //Client-side
    let decrypted_result: u8 = result.decrypt(&client_key);

    let clear_result = clear_a + clear_b;

    assert_eq!(decrypted_result, clear_result);
}

List of available operations

The GPU backend includes the following operations for both signed and unsigned encrypted integers:

name

symbol

Enc/Enc

Enc/ Int

Neg

-

N/A

Add

+

Sub

-

Mul

*

Div

/

Rem

%

Not

!

N/A

BitAnd

&

BitOr

|

BitXor

^

Shr

>>

Shl

<<

Rotate right

rotate_right

Rotate left

rotate_left

Min

min

Max

max

Greater than

gt

Greater or equal than

ge

Lower than

lt

Lower or equal than

le

Equal

eq

Cast (into dest type)

cast_into

N/A

Cast (from src type)

cast_from

N/A

Ternary operator

select

Multi-GPU support

TFHE-rs supports platforms with multiple GPUs with some restrictions at the moment: the platform should have NVLink support, and only GPUs that have peer access to GPU 0 via NVLink will be used for the computation. Depending on the platform, this can restrict the number of GPUs used to perform the computation.

There is nothing to change in the code to execute on multiple GPUs, when they are available and have peer access to GPU 0 via NVLink. To keep the API as user-friendly as possible, the configuration is automatically set, i.e., the user has no fine-grained control over the number of GPUs to be used.

Benchmarks

All GPU benchmarks presented here were obtained on H100 GPUs, and rely on the multithreaded PBS algorithm. The cryptographic parameters PARAM_GPU_MULTI_BIT_MESSAGE_2_CARRY_2_GROUP_3_KS_PBS were used.

1xH100

Below come the results for the execution on a single H100. The following table shows the performance when the inputs of the benchmarked operation are encrypted:

Operation \ Size

FheUint8

FheUint16

FheUint32

FheUint64

FheUint128

FheUint256

Negation (-)

18.6 ms

24.9 ms

34.9 ms

52.4 ms

101 ms

197 ms

Add / Sub (+,-)

18.7 ms

25.0 ms

35.0 ms

52.4 ms

101 ms

197 ms

Mul (x)

35.0 ms

59.7 ms

124 ms

378 ms

1.31 s

5.01 s

Equal / Not Equal (eq, ne)

10.5 ms

11.1 ms

17.2 ms

19.5 ms

27.9 ms

45.2 ms

Comparisons (ge, gt, le, lt)

19.8 ms

25.0 ms

31.3 ms

40.2 ms

53.2 ms

85.2 ms

Max / Min (max,min)

30.2 ms

37.1 ms

46.6 ms

61.4 ms

91.8 ms

154 ms

Bitwise operations (&, |, ^)

4.83 ms

5.3 ms

6.36 ms

8.26 ms

15.3 ms

25.4 ms

Div / Rem (/, %)

221 ms

528 ms

1.31 s

3.6 s

11.0 s

40.0 s

Left / Right Shifts (<<, >>)

30.4 ms

41.4 ms

60.0 ms

119 ms

221 ms

435 ms

Left / Right Rotations (left_rotate, right_rotate)

30.4 ms

41.4 ms

60.1 ms

119 ms

221 ms

435 ms

The following table shows the performance when the left input of the benchmarked operation is encrypted and the other is a clear scalar of the same size:

Operation \ Size

FheUint8

FheUint16

FheUint32

FheUint64

FheUint128

FheUint256

Add / Sub (+,-)

19.0 ms

25.0 ms

35.0 ms

52.4 ms

101 ms

197 ms

Mul (x)

28.1 ms

43.9 ms

75.4 ms

177 ms

544 ms

1.92 s

Equal / Not Equal (eq, ne)

11.5 ms

11.9 ms

12.5 ms

18.9 ms

21.7 ms

30.6 ms

Comparisons (ge, gt, le, lt)

12.5 ms

17.4 ms

22.7 ms

29.9 ms

39.1 ms

57.2 ms

Max / Min (max,min)

22.5 ms

28.9 ms

37.4 ms

50.6 ms

77.4 ms

126 ms

Bitwise operations (&, |, ^)

4.92 ms

5.51 ms

6.47 ms

8.37 ms

15.5 ms

25.6 ms

Div (/)

46.8 ms

70.0 ms

138 ms

354 ms

1.10 s

3.83 s

Rem (%)

90.0 ms

140 ms

250 ms

592 ms

1.75 s

6.06 s

Left / Right Shifts (<<, >>)

4.82 ms

5.36 ms

6.38 ms

8.26 ms

15.3 ms

25.4 ms

Left / Right Rotations (left_rotate, right_rotate)

4.81 ms

5.36 ms

6.30 ms

8.19 ms

15.3 ms

25.3 ms

2xH100

Below come the results for the execution on two H100's. The following table shows the performance when the inputs of the benchmarked operation are encrypted:

Operation \ Size

FheUint8

FheUint16

FheUint32

FheUint64

FheUint128

FheUint256

Negation (-)

16.1 ms

20.3 ms

27.7 ms

38.2 ms

54.7 ms

83.0 ms

Add / Sub (+,-)

16.1 ms

20.4 ms

27.8 ms

38.3 ms

54.9 ms

83.2 ms

Mul (x)

31.0 ms

49.6 ms

92.4 ms

267 ms

892 ms

3.45 s

Equal / Not Equal (eq, ne)

11.2 ms

12.9 ms

20.4 ms

27.3 ms

38.8 ms

67.0 ms

Max / Min (max,min)

53.4 ms

59.3 ms

70.4 ms

89.6 ms

120 ms

177 ms

Bitwise operations (&, |, ^)

4.16 ms

4.62 ms

5.61 ms

7.52 ms

10.2 ms

15.7 ms

Div / Rem (/, %)

299 ms

595 ms

1.36 s

3.12 s

7.8 s

21.1 s

Left / Right Shifts (<<, >>)

26.9 ms

34.5 ms

48.7 ms

70.2 ms

108 ms

220 ms

Left / Right Rotations (left_rotate, right_rotate)

26.8 ms

34.5 ms

48.7 ms

70.1 ms

108 ms

220 ms

The following table shows the performance when the left input of the benchmarked operation is encrypted and the other is a clear scalar of the same size:

Operation \ Size

FheUint8

FheUint16

FheUint32

FheUint64

FheUint128

FheUint256

Add / Sub (+,-)

16.4 ms

20.5 ms

28.0 ms

38.4 ms

54.9 ms

83.1 ms

Mul (x)

25.3 ms

36.8 ms

62.0 ms

130 ms

377 ms

1.35 s

Equal / Not Equal (eq, ne)

36.4 ms

36.5 ms

39.3 ms

47.1 ms

58.0 ms

78.0 ms

Max / Min (max,min)

53.6 ms

60.8 ms

71.9 ms

89.4 ms

119 ms

173 ms

Bitwise operations (&, |, ^)

4.33 ms

4.76 ms

6.4 ms

7.65 ms

10.4 ms

15.7 ms

Div (/)

40.9 ms

59.7 ms

109.0 ms

248.5 ms

806.1 ms

2.9 s

Rem (%)

80.6 ms

116.1 ms

199.9 ms

412.9 ms

1.2 s

4.3 s

Left / Right Shifts (<<, >>)

4.15 ms

4.57 ms

6.19 ms

7.48 ms

10.3 ms

15.7 ms

Left / Right Rotations (left_rotate, right_rotate)

4.15 ms

4.57 ms

6.18 ms

7.46 ms

10.2 ms

15.6 ms

Homomorphic parity bit

This tutorial shows how to build a small function that homomorphically computes a parity bit in 2 steps:

Write a non-generic function
Use generics to handle the case where the function inputs are both FheBools and clear bools.

The parity bit function processes two parameters:

A slice of Boolean
A mode (Odd or Even)

This function returns a Boolean (true or false) so that the total count of true values across the input and the result matches with the specified parity mode (Odd or Even).

Non-generic version

First, define the verification function.

The function initializes the parity bit to false, then applies the XOR operation across all bits, adding negation based on the requested mode.

The validation function also adds the number of the bits set in the input to the computed parity bit and checks whether the sum is even or odd, depending on the mode.

After configurations, call the function:

Generic version

To enable the compute_parity_bit function to operate with both encrypted FheBool and plain bool, we introduce generics. This approach allows for validation using clear data and facilitates debugging.

Writing generic functions that incorporate operator overloading for our Fully Homomorphic Encryption (FHE) types is more complex than usual because FHE types do not implement the Copy trait. Consequently, it is necessary to use references (&) with these types, unlike native types, which typically implement Copy.

This complicates generic bounds at first.

Writing the correct trait bounds

The function has the following signature:

To make it generic, the first steps is:

Next, define the generic bounds with the where clause.

In the function, you can use the following operators:

! (trait: Not)
^ (trait: BitXor)

Adding them to where, it gives:

However, the compiler will return an error:

fhe_bit is a reference to a BoolType (&BoolType), because BoolType is borrowed from the fhe_bits slice during iteration. To fix the error, the first approach could be changing the BitXor bounds to what the Compiler suggests, by requiring &BoolType to implement BitXor rather than BoolType.

However, this approach still leads to an error:

To fix this error, use Higher-Rank Trait Bounds:

The final code is as follows:

Here is a complete example that uses this function for both clear and FHE values:

use tfhe::FheBool;
use tfhe::prelude::*;

#[derive(Copy, Clone, Debug)]
enum ParityMode {
    // The sum bits of message + parity bit must an odd number
    Odd,
    // The sum bits of message + parity bit must an even number
    Even,
}

fn compute_parity_bit(fhe_bits: &[FheBool], mode: ParityMode) -> FheBool {
    let mut parity_bit = fhe_bits[0].clone();
    for fhe_bit in &fhe_bits[1..] {
        parity_bit = fhe_bit ^ parity_bit
    }

    match mode {
        ParityMode::Odd => !parity_bit,
        ParityMode::Even => parity_bit,
    }
}

fn is_even(n: u8) -> bool {
    (n & 1) == 0
}

fn is_odd(n: u8) -> bool {
    !is_even(n)
}

fn check_parity_bit_validity(bits: &[bool], mode: ParityMode, parity_bit: bool) -> bool {
    let num_bit_set = bits
        .iter()
        .map(|bit| *bit as u8)
        .fold(parity_bit as u8, |acc, bit| acc + bit);

    match mode {
        ParityMode::Even => is_even(num_bit_set),
        ParityMode::Odd => is_odd(num_bit_set),
    }
}

use tfhe::{FheBool, ConfigBuilder, generate_keys, set_server_key};
use tfhe::prelude::*;

#[derive(Copy, Clone, Debug)]
enum ParityMode {
    // The sum bits of message + parity bit must an odd number
    Odd,
    // The sum bits of message + parity bit must an even number
    Even,
}

fn compute_parity_bit(fhe_bits: &[FheBool], mode: ParityMode) -> FheBool {
    let mut parity_bit = fhe_bits[0].clone();
    for fhe_bit in &fhe_bits[1..] {
        parity_bit = fhe_bit ^ parity_bit
    }

    match mode {
        ParityMode::Odd => !parity_bit,
        ParityMode::Even => parity_bit,
    }
}

fn is_even(n: u8) -> bool {
    (n & 1) == 0
}

fn is_odd(n: u8) -> bool {
    !is_even(n)
}

fn check_parity_bit_validity(bits: &[bool], mode: ParityMode, parity_bit: bool) -> bool {
    let num_bit_set = bits
        .iter()
        .map(|bit| *bit as u8)
        .fold(parity_bit as u8, |acc, bit| acc + bit);

    match mode {
        ParityMode::Even => is_even(num_bit_set),
        ParityMode::Odd => is_odd(num_bit_set),
    }
}

fn main() {
    let config = ConfigBuilder::default().build();

    let (client_key, server_key) = generate_keys(config);

    set_server_key(server_key);

    let clear_bits = [0, 1, 0, 0, 0, 1, 1].map(|b| (b != 0) as bool);

    let fhe_bits = clear_bits
        .iter()
        .map(|bit| FheBool::encrypt(*bit, &client_key))
        .collect::<Vec<FheBool>>();

    let mode = ParityMode::Odd;
    let fhe_parity_bit = compute_parity_bit(&fhe_bits, mode);
    let decrypted_parity_bit = fhe_parity_bit.decrypt(&client_key);
    let is_parity_bit_valid = check_parity_bit_validity(&clear_bits, mode, decrypted_parity_bit);
    println!("Parity bit is set: {} for mode: {:?}", decrypted_parity_bit, mode);
    assert!(is_parity_bit_valid);

    let mode = ParityMode::Even;
    let fhe_parity_bit = compute_parity_bit(&fhe_bits, mode);
    let decrypted_parity_bit = fhe_parity_bit.decrypt(&client_key);
    let is_parity_bit_valid = check_parity_bit_validity(&clear_bits, mode, decrypted_parity_bit);
    println!("Parity bit is set: {} for mode: {:?}", decrypted_parity_bit, mode);
    assert!(is_parity_bit_valid);
}

---- src/user_doc_tests.rs - user_doc_tests (line 199) stdout ----
error[E0369]: no implementation for `&BoolType ^ BoolType`
--> src/user_doc_tests.rs:218:30
    |
21  | parity_bit = fhe_bit ^ parity_bit
    |              ------- ^ ---------- BoolType
    |             |
    |             &BoolType
    |
help: consider extending the `where` bound, but there might be an alternative better way to express this requirement
    |
17  | BoolType: BitXor<BoolType, Output=BoolType>, &BoolType: BitXor<BoolType>
    |                                                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
error: aborting due to previous error

---- src/user_doc_tests.rs - user_doc_tests (line 236) stdout ----
error[E0637]: `&` without an explicit lifetime name cannot be used here
  --> src/user_doc_tests.rs:251:5
   |
17 |     &BoolType: BitXor<BoolType, Output=BoolType>,
   |     ^ explicit lifetime name needed here

error[E0310]: the parameter type `BoolType` may not live long enough
  --> src/user_doc_tests.rs:251:16
   |
17 |     &BoolType: BitXor<BoolType, Output=BoolType>,
   |                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ...so that the reference type `&'static BoolType` does not outlive the data it points at
   |
help: consider adding an explicit lifetime bound...
   |
15 |     BoolType: Clone + Not<Output = BoolType> + 'static,
   |

use std::ops::{Not, BitXor};

#[derive(Copy, Clone, Debug)]
enum ParityMode {
    // The sum bits of message + parity bit must an odd number
    Odd,
    // The sum bits of message + parity bit must an even number
    Even,
}

fn compute_parity_bit<BoolType>(fhe_bits: &[BoolType], mode: ParityMode) -> BoolType
where
    BoolType: Clone + Not<Output = BoolType>,
    for<'a> &'a BoolType: BitXor<BoolType, Output = BoolType>,
{
    let mut parity_bit = fhe_bits[0].clone();
    for fhe_bit in &fhe_bits[1..] {
        parity_bit = fhe_bit ^ parity_bit
    }

    match mode {
        ParityMode::Odd => !parity_bit,
        ParityMode::Even => parity_bit,
    }
}

use tfhe::{FheBool, ConfigBuilder, generate_keys, set_server_key};
use tfhe::prelude::*;
use std::ops::{Not, BitXor};

#[derive(Copy, Clone, Debug)]
enum ParityMode {
    // The sum bits of message + parity bit must an odd number
    Odd,
    // The sum bits of message + parity bit must an even number
    Even,
}

fn compute_parity_bit<BoolType>(fhe_bits: &[BoolType], mode: ParityMode) -> BoolType
    where
        BoolType: Clone + Not<Output=BoolType>,
        for<'a> &'a BoolType: BitXor<BoolType, Output=BoolType>,
{
    let mut parity_bit = fhe_bits[0].clone();
    for fhe_bit in &fhe_bits[1..] {
        parity_bit = fhe_bit ^ parity_bit
    }

    match mode {
        ParityMode::Odd => !parity_bit,
        ParityMode::Even => parity_bit,
    }
}

fn is_even(n: u8) -> bool {
    (n & 1) == 0
}

fn is_odd(n: u8) -> bool {
    !is_even(n)
}

fn check_parity_bit_validity(bits: &[bool], mode: ParityMode, parity_bit: bool) -> bool {
    let num_bit_set = bits
        .iter()
        .map(|bit| *bit as u8)
        .fold(parity_bit as u8, |acc, bit| acc + bit);

    match mode {
        ParityMode::Even => is_even(num_bit_set),
        ParityMode::Odd => is_odd(num_bit_set),
    }
}

fn main() {
    let config = ConfigBuilder::default().build();

    let ( client_key, server_key) = generate_keys(config);

    set_server_key(server_key);

    let clear_bits = [0, 1, 0, 0, 0, 1, 1].map(|b| (b != 0) as bool);

    let fhe_bits = clear_bits
        .iter()
        .map(|bit| FheBool::encrypt(*bit, &client_key))
        .collect::<Vec<FheBool>>();

    let mode = ParityMode::Odd;
    let clear_parity_bit = compute_parity_bit(&clear_bits, mode);
    let fhe_parity_bit = compute_parity_bit(&fhe_bits, mode);
    let decrypted_parity_bit = fhe_parity_bit.decrypt(&client_key);
    let is_parity_bit_valid = check_parity_bit_validity(&clear_bits, mode, decrypted_parity_bit);
    println!("Parity bit is set: {} for mode: {:?}", decrypted_parity_bit, mode);
    assert!(is_parity_bit_valid);
    assert_eq!(decrypted_parity_bit, clear_parity_bit);

    let mode = ParityMode::Even;
    let clear_parity_bit = compute_parity_bit(&clear_bits, mode);
    let fhe_parity_bit = compute_parity_bit(&fhe_bits, mode);
    let decrypted_parity_bit = fhe_parity_bit.decrypt(&client_key);
    let is_parity_bit_valid = check_parity_bit_validity(&clear_bits, mode, decrypted_parity_bit);
    println!("Parity bit is set: {} for mode: {:?}", decrypted_parity_bit, mode);
    assert!(is_parity_bit_valid);
    assert_eq!(decrypted_parity_bit, clear_parity_bit);
}

project(my-project)

cmake_minimum_required(VERSION 3.16)

set(TFHE_C_API "/path/to/tfhe-rs/target/release")

include_directories(${TFHE_C_API})
include_directories(${TFHE_C_API}/deps)
add_library(tfhe STATIC IMPORTED)
set_target_properties(tfhe PROPERTIES IMPORTED_LOCATION ${TFHE_C_API}/libtfhe.a)
add_library(tfheDynamicBuffer STATIC IMPORTED)
set_target_properties(tfheDynamicBuffer PROPERTIES IMPORTED_LOCATION ${TFHE_C_API}/deps/libtfhe_c_api_dynamic_buffer.a)

if(APPLE)
    find_library(SECURITY_FRAMEWORK Security)
    if (NOT SECURITY_FRAMEWORK)
        message(FATAL_ERROR "Security framework not found")
    endif()
endif()

set(EXECUTABLE_NAME my-executable)
add_executable(${EXECUTABLE_NAME} main.c)
target_include_directories(${EXECUTABLE_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
target_link_libraries(${EXECUTABLE_NAME} LINK_PUBLIC tfhe tfheDynamicBuffer m pthread dl)
if(APPLE)
    target_link_libraries(${EXECUTABLE_NAME} LINK_PUBLIC ${SECURITY_FRAMEWORK})
endif()
target_compile_options(${EXECUTABLE_NAME} PRIVATE -Werror)

# /!\ Be sure to update CMakeLists.txt to give the absolute path to the compiled tfhe library
$ ls
CMakeLists.txt  main.c
$ mkdir build && cd build
$ cmake .. -DCMAKE_BUILD_TYPE=RELEASE
...
$ make
...
$ ./my-executable
FHE computation successful!
$


#include "tfhe.h"
#include <assert.h>
#include <stdio.h>

int main(void)
{
    int ok = 0;
    // Prepare the config builder for the high level API and choose which types to enable
    ConfigBuilder *builder;
    Config *config;

    // Put the builder in a default state without any types enabled
    config_builder_default(&builder);
    // Use the small LWE key for encryption
    config_builder_default_with_small_encryption(&builder);
    // Populate the config
    config_builder_build(builder, &config);

    ClientKey *client_key = NULL;
    ServerKey *server_key = NULL;

    // Generate the keys using the config
    generate_keys(config, &client_key, &server_key);
    // Set the server key for the current thread
    set_server_key(server_key);

    FheUint128 *lhs = NULL;
    FheUint128 *rhs = NULL;
    FheUint128 *result = NULL;
    // A 128-bit unsigned integer containing value: 20 << 64 | 10
    U128 clear_lhs = { .w0 = 10, .w1 = 20 };
    // A 128-bit unsigned integer containing value: 2 << 64 | 1
    U128 clear_rhs = { .w0 = 1, .w1 = 2 };

    ok = fhe_uint128_try_encrypt_with_client_key_u128(clear_lhs, client_key, &lhs);
    assert(ok == 0);

    ok = fhe_uint128_try_encrypt_with_client_key_u128(clear_rhs, client_key, &rhs);
    assert(ok == 0);

    // Compute the subtraction
    ok = fhe_uint128_sub(lhs, rhs, &result);
    assert(ok == 0);

    U128 clear_result;
    // Decrypt
    ok = fhe_uint128_decrypt(result, client_key, &clear_result);
    assert(ok == 0);

    // Here the subtraction allows us to compare each word
    assert(clear_result.w0 == 9);
    assert(clear_result.w1 == 18);

    // Destroy the ciphertexts
    fhe_uint128_destroy(lhs);
    fhe_uint128_destroy(rhs);
    fhe_uint128_destroy(result);

    // Destroy the keys
    client_key_destroy(client_key);
    server_key_destroy(server_key);

    printf("FHE computation successful!\n");
    return EXIT_SUCCESS;
}

Compressing ciphertexts/keys

This document explains the mechanism and steps to compress ciphertext and keys to reduce the storage needed as well as transmission times.

Most TFHE-rs entities contain random numbers generated by a Pseudo Random Number Generator (PRNG). Since the implemented PRNG is deterministic, storing only the random seed used to generate those numbers preserves all necessary information. When decompressing the entity, using the same PRNG and the same seed will reconstruct the full chain of random values.

In TFHE-rs, compressible entities are prefixed with Compressed. For instance, a compressed FheUint256 is declared as CompressedFheUint256.

In the following example code, we use the bincode crate dependency to serialize in a binary format and compare serialized sizes.

Compressing Ciphertexts

Compressing ciphertexts at encryption time

This example shows how to compress a ciphertext encrypting messages over 16 bits:

use tfhe::prelude::*;
use tfhe::{ConfigBuilder, generate_keys, set_server_key, CompressedFheUint16};

fn main() {
    let config = ConfigBuilder::default().build();
    let (client_key, _) = generate_keys(config);

    let clear = 12_837u16;
    let compressed = CompressedFheUint16::try_encrypt(clear, &client_key).unwrap();
    println!(
        "compressed size  : {}",
        bincode::serialize(&compressed).unwrap().len()
    );
    
    let decompressed = compressed.decompress();
    
    println!(
        "decompressed size: {}",
        bincode::serialize(&decompressed).unwrap().len()
    );

    let clear_decompressed: u16 = decompressed.decrypt(&client_key);
    assert_eq!(clear_decompressed, clear);
}

Compression ciphertexts after some homomorphic computation

You can compress ciphertexts at any time, even after performing multiple homomorphic operations.

To do so, you need to build a list containing all the ciphertexts that have to be compressed. This list might contain ciphertexts of different types, e.g., FheBool, FheUint32, FheInt64,... There is no constraint regarding the size of the list.

There are two possible approaches:

Single list: Compressing several ciphertexts into a single list. This generally yields a better compression ratio between output and input sizes;
Multiple lists: Using multiple lists. This offers more flexibility, since compression might happen at different times in the code, but could lead to larger outputs.

In more details, the optimal ratio is achieved with a list whose size is equal to the lwe_per_glwe field from the CompressionParameters.

The following example shows how to compress and decompress a list containing 4 messages: one 32-bits integer, one 64-bit integer, one boolean, and one 2-bit integer.

use tfhe::prelude::*;
use tfhe::shortint::parameters::{COMP_PARAM_MESSAGE_2_CARRY_2, PARAM_MESSAGE_2_CARRY_2};
use tfhe::{
    set_server_key, CompressedCiphertextList, CompressedCiphertextListBuilder, FheBool,
    FheInt64, FheUint16, FheUint2, FheUint32,
};

fn main() {
    let config = tfhe::ConfigBuilder::with_custom_parameters(PARAM_MESSAGE_2_CARRY_2, None)
        .enable_compression(COMP_PARAM_MESSAGE_2_CARRY_2)
        .build();

    let ck = tfhe::ClientKey::generate(config);
    let sk = tfhe::ServerKey::new(&ck);

    set_server_key(sk);

    let ct1 = FheUint32::encrypt(17_u32, &ck);

    let ct2 = FheInt64::encrypt(-1i64, &ck);

    let ct3 = FheBool::encrypt(false, &ck);

    let ct4 = FheUint2::encrypt(3u8, &ck);

    let compressed_list = CompressedCiphertextListBuilder::new()
        .push(ct1)
        .push(ct2)
        .push(ct3)
        .push(ct4)
        .build()
        .unwrap();

    let serialized = bincode::serialize(&compressed_list).unwrap();

    println!("Serialized size: {} bytes", serialized.len());

    let compressed_list: CompressedCiphertextList = bincode::deserialize(&serialized).unwrap();

    
    let a: FheUint32 = compressed_list.get(0).unwrap().unwrap();
    let b: FheInt64 = compressed_list.get(1).unwrap().unwrap();
    let c: FheBool = compressed_list.get(2).unwrap().unwrap();
    let d: FheUint2 = compressed_list.get(3).unwrap().unwrap();

    let a: u32 = a.decrypt(&ck);
    assert_eq!(a, 17);
    let b: i64 = b.decrypt(&ck);
    assert_eq!(b, -1);
    let c = c.decrypt(&ck);
    assert!(!c);
    let d: u8 = d.decrypt(&ck);
    assert_eq!(d, 3);

    // Out of bound index 
    assert!(compressed_list.get::<FheBool>(4).unwrap().is_none());

    // Incorrect type
    assert!(compressed_list.get::<FheInt64>(0).is_err());

    // Correct type but wrong number of bits
    assert!(compressed_list.get::<FheUint16>(0).is_err());
}

Compressing keys

Compressing server keys

This example shows how to compress the server keys:

use tfhe::prelude::*;
use tfhe::{
    generate_keys, set_server_key, ClientKey, CompressedServerKey, ConfigBuilder, FheUint8,
};

fn main() {
    let config = ConfigBuilder::default().build();

    let cks = ClientKey::generate(config);
    let compressed_sks = CompressedServerKey::new(&cks);

    println!(
        "compressed size  : {}",
        bincode::serialize(&compressed_sks).unwrap().len()
    );

    let sks = compressed_sks.decompress();

    println!(
        "decompressed size: {}",
        bincode::serialize(&sks).unwrap().len()
    );

    set_server_key(sks);

    let clear_a = 12u8;
    let a = FheUint8::try_encrypt(clear_a, &cks).unwrap();

    let c = a + 234u8;
    let decrypted: u8 = c.decrypt(&cks);
    assert_eq!(decrypted, clear_a.wrapping_add(234));
}

Compressed public keys

This example shows how to compress the classical public keys:

It is not currently recommended to use the CompressedPublicKey to encrypt ciphertexts without first decompressing them. If the resulting PublicKey is too large to fit in memory, it may result in significant slowdowns.

This issue has been identified and will be addressed in future releases.

use tfhe::prelude::*;
use tfhe::{ConfigBuilder, generate_keys, set_server_key, FheUint8, CompressedPublicKey};

fn main() {
    let config = ConfigBuilder::default().build();
    let (client_key, _) = generate_keys(config);

    let compressed_public_key = CompressedPublicKey::new(&client_key);

    println!("compressed size  : {}", bincode::serialize(&compressed_public_key).unwrap().len());

    let public_key = compressed_public_key.decompress();

    println!("decompressed size: {}", bincode::serialize(&public_key).unwrap().len());


    let a = FheUint8::try_encrypt(213u8, &public_key).unwrap();
    let clear: u8 = a.decrypt(&client_key);
    assert_eq!(clear, 213u8);
}

Compressed compact public key

This example shows how to use compressed compact public keys:

use tfhe::prelude::*;
use tfhe::{
    generate_keys, set_server_key, CompactCiphertextList, CompressedCompactPublicKey,
    ConfigBuilder, FheUint8,
};

fn main() {
    let config = ConfigBuilder::default()
        .use_custom_parameters(
            tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_COMPACT_PK_KS_PBS,
            None,
        )
        .build();
    let (client_key, _) = generate_keys(config);

    let public_key_compressed = CompressedCompactPublicKey::new(&client_key);

    println!(
        "compressed size  : {}",
        bincode::serialize(&public_key_compressed).unwrap().len()
    );

    let public_key = public_key_compressed.decompress();

    println!(
        "decompressed size: {}",
        bincode::serialize(&public_key).unwrap().len()
    );

    let compact_list = CompactCiphertextList::builder(&public_key)
        .push(255u8)
        .build();
    let expanded = compact_list.expand().unwrap();
    let a: FheUint8 = expanded.get(0).unwrap().unwrap();

    let clear: u8 = a.decrypt(&client_key);
    assert_eq!(clear, 255u8);
}

Overflow detection

This document explains how TFHE-rs implements specific operations to detect overflows in computations.

The mechanism of detecting overflow consists in returning an encrypted flag with a specific ciphertext that reflects the state of the computation. When an overflow occurs, this flag is set to true. Since the server is not able to evaluate this encrypted value, the client has to check the flag value when decrypting to determine if an overflow has happened.

These operations might be slower than their non-overflow-detecting equivalent, so they are not enabled by default. To use them, you must explicitly call specific operators. At the moment, only additions, subtractions, and multiplications are supported. We plan to add more operations in future releases.

Here's the list of operations supported along with their symbol:

name

symbol

type

overflow_add

Binary

overflow_sub

Binary

overflow_mul

Binary

The usage of these operations is similar to the standard ones. The key difference is in the decryption process, as shown in following example:

/// Adds two [FheUint] and returns a boolean indicating overflow.
///
/// * The operation is modular, i.e on overflow the result wraps around.
/// * On overflow the [FheBool] is true, otherwise false

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint16};

let (client_key, server_key) = generate_keys(ConfigBuilder::default());
set_server_key(server_key);

let a = FheUint16::encrypt(u16::MAX, &client_key);
let b = FheUint16::encrypt(1u16, &client_key);

let (result, overflowed) = (&a).overflowing_add(&b);
let result: u16 = result.decrypt(&client_key);
assert_eq!(result, u16::MAX.wrapping_add(1u16));
assert_eq!(
	overflowed.decrypt(&client_key),
	u16::MAX.overflowing_add(1u16).1
);
assert_eq!(overflowed.decrypt(&client_key), true);

The following tables show the current benchmarks result.

Unsigned homomorphic integers:

Operation\Size

FheUint8

FheUint16

FheUint32

FheUint64

FheUint128

FheUint256

unsigned_overflowing_add

63.67 ms

84.11 ms

107.95 ms

120.8 ms

147.38 ms

191.28 ms

unsigned_overflowing_sub

68.89 ms

81.83 ms

107.63 ms

120.38 ms

150.21 ms

190.39 ms

unsigned_overflowing_mul

140.76 ms

191.85 ms

272.65 ms

510.61 ms

1.34 s

4.51 s

Signed homomorphic integers:

Operation\Size

FheInt8

FheInt16

FheInt32

FheInt64

FheInt128

FheInt256

signed_overflowing_add

76.54 ms

84.78 ms

104.23 ms

134.38 ms

162.99 ms

202.56 ms

signed_overflowing_sub

82.46 ms

86.92 ms

104.41 ms

132.21 ms

168.06 ms

201.17 ms

signed_overflowing_mul

277.91 ms

365.67 ms

571.22 ms

1.21 s

3.57 s

12.84 s

Homomorphic case changing on Ascii string

This tutorial demonstrates how to build a data type that represents an ASCII string in Fully Homomorphic Encryption (FHE) by implementing to_lower and to_upper functions.

An ASCII character is stored in 7 bits. To store an encrypted ASCII, we use the FheUint8:

The uppercase letters are in the range [65, 90]
The lowercase letters are in the range [97, 122]

The relationship between uppercase and lowercase letters is defined as follows:

lower_case = upper_case + UP_LOW_DISTANCE
upper_case = lower_case - UP_LOW_DISTANCE

Where UP_LOW_DISTANCE = 32

Types and methods

This type stores the encrypted characters as a Vec<FheUint8> to implement case conversion functions.

To use the FheUint8 type, enable the integer feature:

# Cargo.toml

[dependencies]
# Default configuration for x86 Unix machines:
tfhe = { version = "0.7.5", features = ["integer", "x86_64-unix"]}

The FheAsciiString::encrypt function performs data validation to ensure the input string contains only ASCII characters.

In FHE operations, direct branching on encrypted values is not possible. However, you can evaluate a boolean condition to obtain the desired outcome. Here is an example to check and convert the 'char' to a lowercase without using a branch:

pub const UP_LOW_DISTANCE: u8 = 32;

fn to_lower(c: u8) -> u8 {
    if c > 64 && c < 91 {
        c + UP_LOW_DISTANCE
    } else {
        c
    }
}

You can remove the branch this way:

pub const UP_LOW_DISTANCE: u8 = 32;

fn to_lower(c: u8) -> u8 {
    c + ((c > 64) as u8 & (c < 91) as u8) * UP_LOW_DISTANCE
}

This method can adapt to operations on homomorphic integers:

use tfhe::prelude::*;
use tfhe::FheUint8;

pub const UP_LOW_DISTANCE: u8 = 32;

fn to_lower(c: &FheUint8) -> FheUint8 {
    c + FheUint8::cast_from(c.gt(64) & c.lt(91)) * UP_LOW_DISTANCE
}

Full example:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ClientKey, ConfigBuilder, FheUint8};

pub const UP_LOW_DISTANCE: u8 = 32;

struct FheAsciiString {
    bytes: Vec<FheUint8>,
}

fn to_upper(c: &FheUint8) -> FheUint8 {
    c - FheUint8::cast_from(c.gt(96) & c.lt(123)) * UP_LOW_DISTANCE
}

fn to_lower(c: &FheUint8) -> FheUint8 {
    c + FheUint8::cast_from(c.gt(64) & c.lt(91)) * UP_LOW_DISTANCE
}

impl FheAsciiString {
    fn encrypt(string: &str, client_key: &ClientKey) -> Self {
        assert!(
            string.chars().all(|char| char.is_ascii()),
            "The input string must only contain ascii letters"
        );

        let fhe_bytes: Vec<FheUint8> = string
            .bytes()
            .map(|b| FheUint8::encrypt(b, client_key))
            .collect();

        Self { bytes: fhe_bytes }
    }

    fn decrypt(&self, client_key: &ClientKey) -> String {
        let ascii_bytes: Vec<u8> = self
            .bytes
            .iter()
            .map(|fhe_b| fhe_b.decrypt(client_key))
            .collect();
        String::from_utf8(ascii_bytes).unwrap()
    }

    fn to_upper(&self) -> Self {
        Self {
            bytes: self.bytes.iter().map(to_upper).collect(),
        }
    }

    fn to_lower(&self) -> Self {
        Self {
            bytes: self.bytes.iter().map(to_lower).collect(),
        }
    }
}

fn main() {
    let config = ConfigBuilder::default()
        .build();

    let (client_key, server_key) = generate_keys(config);

    set_server_key(server_key);

    let my_string = FheAsciiString::encrypt("Hello Zama, how is it going?", &client_key);
    let verif_string = my_string.decrypt(&client_key);
    println!("Start string: {verif_string}");

    let my_string_upper = my_string.to_upper();
    let verif_string = my_string_upper.decrypt(&client_key);
    println!("Upper string: {verif_string}");
    assert_eq!(verif_string, "HELLO ZAMA, HOW IS IT GOING?");

    let my_string_lower = my_string_upper.to_lower();
    let verif_string = my_string_lower.decrypt(&client_key);
    println!("Lower string: {verif_string}");
    assert_eq!(verif_string, "hello zama, how is it going?");
}

Cryptographic parameters

Default parameters

Some cryptographic parameters will require tuning to ensure both the correctness of the result and the security of the computation.

To make it simpler, we've provided two sets of parameters, which ensure correct computations for a certain probability with the standard security of 128 bits. There exists an error probability due to the probabilistic nature of the encryption, which requires adding randomness (noise) following a Gaussian distribution. If this noise is too large, the decryption will not give a correct result. There is a trade-off between efficiency and correctness: generally, using a less efficient parameter set (in terms of computation time) leads to a smaller risk of having an error during homomorphic evaluation.

The following array summarizes this:

Parameter set

Error probability

DEFAULT_PARAMETERS

TFHE_LIB_PARAMETERS

User-defined parameters

You can also create your own set of parameters. This is an unsafe operation as failing to properly fix the parameters will result in an incorrect and/or insecure computation:

use tfhe::boolean::prelude::*;

fn main() {
// WARNING: might be insecure and/or incorrect
// You can create your own set of parameters
    let parameters = unsafe {
        BooleanParameters::new(
            LweDimension(586),
            GlweDimension(2),
            PolynomialSize(512),
            DynamicDistribution::new_gaussian_from_std_dev(
                StandardDev(0.00008976167396834998),
            ),
            DynamicDistribution::new_gaussian_from_std_dev(
                StandardDev(0.00000002989040792967434),
            ),
            DecompositionBaseLog(8),
            DecompositionLevelCount(2),
            DecompositionBaseLog(2),
            DecompositionLevelCount(5),
            EncryptionKeyChoice::Small,
        )
    };
}

Configuration and key generation

This document explains how to initialize the configuration and generate keys.

The configuration specifies the selected data types and their custom crypto-parameters. You should only use custom parameters for advanced usage and/or testing.

The configuration is initialized by creating a builder with all types deactivated. Then, the integer types with default parameters are activated, for using FheUint8 values.

use tfhe::{ConfigBuilder, generate_keys};

fn main() {
    let config = ConfigBuilder::default().build();


    let (client_key, server_key) = generate_keys(config);
}

The generate_keys command returns a client key and a server key:

Client_key: this key should remain private and never leave the client.
Server_key: this key can be public and sent to a server to enable FHE computations.

Public key encryption

This document explains public key encryption and provides instructions for 2 methods.

Public key encryption refers to the cryptographic paradigm where the encryption key can be publicly distributed, whereas the decryption key remains secret to the owner. This differs from the usual case where the same secret key is used to encrypt and decrypt the data. In TFHE-rs, there are two methods for public key encryptions:

Classical public key

This example shows how to use classical public keys.

use tfhe::prelude::*;
use tfhe::{ConfigBuilder, generate_keys, set_server_key, FheUint8, PublicKey};

fn main() {
    let config = ConfigBuilder::default().build();
    let (client_key, _) = generate_keys(config);

    let public_key = PublicKey::new(&client_key);

    let a = FheUint8::try_encrypt(255u8, &public_key).unwrap();
    let clear: u8 = a.decrypt(&client_key);
    assert_eq!(clear, 255u8);
}

Compact public key

This example shows how to use compact public keys. The main difference is in the ConfigBuilder where the parameter set has been changed.

use tfhe::prelude::*;
use tfhe::{
    generate_keys, set_server_key, CompactCiphertextList, CompactPublicKey, ConfigBuilder, FheUint8,
};


fn main() {
     let config = ConfigBuilder::default()
        .use_custom_parameters(
            tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_COMPACT_PK_KS_PBS,
            None,
        )
        .build();
    let (client_key, _) = generate_keys(config);

    let public_key = CompactPublicKey::new(&client_key);
    let compact_list = CompactCiphertextList::builder(&public_key)
        .push(255u8)
        .build();
    let expanded = compact_list.expand().unwrap();
    let a: FheUint8 = expanded.get(0).unwrap().unwrap();

    let clear: u8 = a.decrypt(&client_key);
    assert_eq!(clear, 255u8);
}

Data versioning

Data versioning and backward compatibility

This document explains how to save and load versioned data using the data versioning feature.

Starting from v0.6.4, TFHE-rs supports versioned data types. This allows you to store data and load it in the future without compatibility concerns. This feature is done by the tfhe-versionable crate.

Saving and loading versioned data

To use the versioning feature, wrap your types in their versioned equivalents before serialization using the versionize method. You can load serialized data with the unversionize function, even in newer versions of TFHE-rs where the data types might evolve. The unversionize function manages any necessary data type upgrades, ensuring compatibility.

# Cargo.toml

[dependencies]
# ...
tfhe = { version = "0.7.5", features = ["integer","x86_64-unix"]}
tfhe-versionable = "0.2.0"
bincode = "1.3.3"

// main.rs

use bincode;
use std::io::Cursor;
use tfhe::prelude::{FheDecrypt, FheEncrypt};
use tfhe::{ClientKey, ConfigBuilder, FheUint8};
use tfhe_versionable::{Unversionize, Versionize};

fn main() {
    let config = ConfigBuilder::default().build();

    let client_key = ClientKey::generate(config);

    let msg = 1;
    let ct = FheUint8::encrypt(msg, &client_key);

    // Versionize the data and store it
    let mut serialized_data = Vec::new();
    let versioned_client_key = client_key.versionize();
    let versioned_ct = ct.versionize();
    bincode::serialize_into(&mut serialized_data, &versioned_client_key).unwrap();
    bincode::serialize_into(&mut serialized_data, &versioned_ct).unwrap();

    // Load the data. This can be done in the future with a more recent version of tfhe-rs
    let mut serialized_data = Cursor::new(serialized_data);
    let versioned_client_key = bincode::deserialize_from(&mut serialized_data).unwrap();
    let versioned_ct = bincode::deserialize_from(&mut serialized_data).unwrap();
    let loaded_client_key =
        ClientKey::unversionize(versioned_client_key).unwrap();
    let loaded_ct =
        FheUint8::unversionize(versioned_ct).unwrap();

    let output: u8 = loaded_ct.decrypt(&loaded_client_key);
    assert_eq!(msg, output);
}

Versionize

Calling .versionize() on a value will add versioning tags. This is done recursively so all the subtypes that compose it are versioned too. Under the hood, it converts the value into an enum where each version of a type is represented by a new variant. The returned object can be serialized using serde:

    let versioned_client_key = client_key.versionize();
    bincode::serialize_into(&mut serialized_data, &versioned_client_key).unwrap();

Unversionize

The Type::unversionize() function takes a versioned value, upgrades it to the latest version of its type and removes the version tags. To do that, it matches the version in the versioned enum and eventually apply a conversion function that upgrades it to the most recent version. The resulting value can then be used inside TFHE-rs

    let versioned_client_key = bincode::deserialize_from(&mut serialized_data).unwrap();
    let loaded_client_key =
        ClientKey::unversionize(versioned_client_key).unwrap();

Breaking changes

When possible, data will be upgraded automatically without any kind of interraction. However, some changes might need information that are only known by the user of the library. These are called data breaking changes. In these occasions, TFHE-rs provides a way to upgrade these types manually.

You will find below a list of breaking changes and how to upgrade them.

0.6 -> 0.7

tfhe::integer::ciphertext::CompactCiphertextList: in 0.6, these lists of ciphertext were statically typed and homogenous. Since 0.7, they are heterogeneous. The new version stores for each element an information about its type (Signed, Unsigned or Boolean). Since this information were not stored before, the list is set to be made of Unsigned integers by default. If that is not the case, you can set its type using the following snippet:

use std::io::Cursor;
use tfhe::integer::ciphertext::{
    CompactCiphertextList, DataKind, IntegerCompactCiphertextListCastingMode,
    IntegerCompactCiphertextListUnpackingMode, SignedRadixCiphertext,
};
use tfhe::integer::{ClientKey, CompactPublicKey};
use tfhe::shortint::parameters::classic::compact_pk::PARAM_MESSAGE_2_CARRY_2_COMPACT_PK_KS_PBS;
use tfhe_versionable::{Unversionize, Versionize};

pub fn main() {
    let fhe_params = PARAM_MESSAGE_2_CARRY_2_COMPACT_PK_KS_PBS;
    let num_blocks = 4usize;

    let serialized_data = {
        let client_key = ClientKey::new(fhe_params);
        let pk = CompactPublicKey::new(&client_key);

        // Encrypt a negative value
        let compact_ct = CompactCiphertextList::builder(&pk).push(u8::MAX).build();

        // Versionize the data and store it
        let mut serialized_data = Vec::new();
        let versioned_client_key = client_key.versionize();
        let versioned_ct = compact_ct.versionize();
        bincode::serialize_into(&mut serialized_data, &versioned_client_key).unwrap();
        bincode::serialize_into(&mut serialized_data, &versioned_ct).unwrap();
        serialized_data
    };

    // Now load the data, after potential breaking changes in the data format
    let mut serialized_data = Cursor::new(serialized_data);
    let versioned_client_key = bincode::deserialize_from(&mut serialized_data).unwrap();
    let versioned_ct = bincode::deserialize_from(&mut serialized_data).unwrap();
    let client_key = ClientKey::unversionize(versioned_client_key).unwrap();
    let mut compact_ct = CompactCiphertextList::unversionize(versioned_ct).unwrap();

    // Reinterpret the data as needed after the load, here we simulate the need to load Unsigned
    // data
    compact_ct
        .reinterpret_data(&[DataKind::Signed(num_blocks)])
        .unwrap();
    let expander = compact_ct
        .expand(
            IntegerCompactCiphertextListUnpackingMode::NoUnpacking,
            IntegerCompactCiphertextListCastingMode::NoCasting,
        )
        .unwrap();
    let expanded = expander.get::<SignedRadixCiphertext>(0).unwrap().unwrap();
    let decrypted: i8 = client_key.decrypt_signed_radix(&expanded);
    // -1i8 == u8::MAX
    assert_eq!(-1i8, decrypted);
}

tfhe::{CompactFheInt, CompactFheUint, CompactFheIntList, CompactFheUintList}: The types have been deprecated, they are only kept in TFHE-rs for backward compatibility. They can now be accessed using the tfhe::high_level_api::backward_compatibility::integers module. The only functionality that is still supported is to unversionize them and expand them into regular FheInt, FheUint, Vec<FehInt> and Vec<FheUint>:

    let loaded_ct = CompactFheUint8::unversionize(versioned_ct).unwrap();
    let ct = loaded_ct.expand();

Starting with v0.7, this compact list functionality is provided by the tfhe::CompactCiphertextList type.

Boolean

In tfhe::boolean, the available operations are mainly related to their equivalent Boolean gates (i.e., AND, OR... etc). What follows are examples of a unary gate (NOT) and a binary gate (XOR). The last one is about the ternary MUX gate, which allows homomorphic computation of conditional statements of the form If..Then..Else.

This library is meant to be used both on the server side and the client side. The typical use case should follow the subsequent steps:

On the client side, generate the client and server keys.
Send the server key to the server.
Then any number of times:
- On the client side, encrypt the input data with the client key.
- Transmit the encrypted input to the server.
- On the server side, perform homomorphic computation with the server key.
- Transmit the encrypted output to the client.
- On the client side, decrypt the output data with the client key.

Setup

In the first step, the client creates two keys, the client key and the server key, with the tfhe::boolean::gen_keys function:

use tfhe::boolean::prelude::*;

fn main() {

// We generate the client key and the server key,
// using the default parameters:
    let (client_key, server_key): (ClientKey, ServerKey) = gen_keys();
}

The client_key is of type ClientKey. It is secret and must never be transmitted. This key will only be used to encrypt and decrypt data.
The server_key is of type ServerKey. It is a public key and can be shared with any party. This key has to be sent to the server because it is required for homomorphic computation.

Note that both the client_key and server_key implement the Serialize and Deserialize traits. This way you can use any compatible serializer to store/send the data. To store the server_key in a binary file, you can use the bincode library:

use std::fs::{File, create_dir_all};
use std::io::{Write, Read};
use tfhe::boolean::prelude::*;

fn main() {

//---------------------------- CLIENT SIDE ----------------------------

// We generate a client key and a server key, using the default parameters:
    let (client_key, server_key) = gen_keys();

// We serialize the server key to bytes, and store them in a file:
    let encoded: Vec<u8> = bincode::serialize(&server_key).unwrap();

// Create a tmp dir with the current user name to avoid cluttering the /tmp dir
    let user = std::env::var("USER").unwrap_or_else(|_| "unknown_user".to_string());
    let tmp_dir_for_user = &format!("/tmp/{user}");

    create_dir_all(tmp_dir_for_user).unwrap();

    let server_key_file = &format!("{tmp_dir_for_user}/tutorial_server_key.bin");

// We write the server key to a file:
    let mut file = File::create(server_key_file)
        .expect("failed to create server key file");
    file.write_all(encoded.as_slice()).expect("failed to write key to file");

// ...
// We send the key to server side
// ...


//---------------------------- SERVER SIDE ----------------------------

// We read the file:
    let mut file = File::open(server_key_file)
        .expect("failed to open server key file");
    let mut encoded: Vec<u8> = Vec::new();
    file.read_to_end(&mut encoded).expect("failed to read key");

// We deserialize the server key:
    let key: ServerKey = bincode::deserialize(&encoded[..])
        .expect("failed to deserialize");
}

Encrypting inputs

Once the server key is available on the server side, it is possible to perform some homomorphic computations. The client needs to encrypt some data and send it to the server. Again, the Ciphertext type implements the Serialize and the Deserialize traits, so that any serializer and communication tool suiting your use case can be employed:

use tfhe::boolean::prelude::*;

fn main() {
    // Don't consider the following line; you should follow the procedure above.
    let (client_key, _) = gen_keys();

//---------------------------- CLIENT SIDE

// We use the client key to encrypt the messages:
    let ct_1 = client_key.encrypt(true);
    let ct_2 = client_key.encrypt(false);

// We serialize the ciphertexts:
    let encoded_1: Vec<u8> = bincode::serialize(&ct_1).unwrap();
    let encoded_2: Vec<u8> = bincode::serialize(&ct_2).unwrap();

// ...
// And we send them to the server somehow
// ...
}

Encrypting inputs using a public key

Anyone (the server or a third party) with the public key can also encrypt some (or all) of the inputs. The public key can only be used to encrypt, not to decrypt.

use tfhe::boolean::prelude::*;

fn main() {
    // Don't consider the following line; you should follow the procedure above.
    let (client_key, _) = gen_keys();
    let public_key = PublicKey::new(&client_key);

//---------------------------- SERVER or THIRD_PARTY SIDE

// We use the public key to encrypt the messages:
    let ct_1 = public_key.encrypt(true);
    let ct_2 = public_key.encrypt(false);

// We serialize the ciphertexts (if not on the server already):
    let encoded_1: Vec<u8> = bincode::serialize(&ct_1).unwrap();
    let encoded_2: Vec<u8> = bincode::serialize(&ct_2).unwrap();

// ...
// And we send them to the server to be deserialized (if not on the server already)
// ...
}

Executing a Boolean circuit

Once the encrypted inputs are on the server side, the server_key can be used to homomorphically execute the desired Boolean circuit:

use std::fs::File;
use std::io::{Write, Read};
use tfhe::boolean::prelude::*;

fn main() {
    // Don't consider the following lines; you should follow the procedure above.
    let (client_key, server_key) = gen_keys();
    let ct_1 = client_key.encrypt(true);
    let ct_2 = client_key.encrypt(false);
    let encoded_1: Vec<u8> = bincode::serialize(&ct_1).unwrap();
    let encoded_2: Vec<u8> = bincode::serialize(&ct_2).unwrap();

//---------------------------- ON SERVER SIDE ----------------------------

// We deserialize the ciphertexts:
    let ct_1: Ciphertext = bincode::deserialize(&encoded_1[..])
        .expect("failed to deserialize");
    let ct_2: Ciphertext = bincode::deserialize(&encoded_2[..])
        .expect("failed to deserialize");

// We use the server key to execute the boolean circuit:
// if ((NOT ct_2) NAND (ct_1 AND ct_2)) then (NOT ct_2) else (ct_1 AND ct_2)
    let ct_3 = server_key.not(&ct_2);
    let ct_4 = server_key.and(&ct_1, &ct_2);
    let ct_5 = server_key.nand(&ct_3, &ct_4);
    let ct_6 = server_key.mux(&ct_5, &ct_3, &ct_4);

// Then we serialize the output of the circuit:
    let encoded_output: Vec<u8> = bincode::serialize(&ct_6)
        .expect("failed to serialize output");

// ...
// And we send the output to the client
// ...
}

Decrypting the output

Once the encrypted output is on the client side, the client_key can be used to decrypt it:

use std::fs::File;
use std::io::{Write, Read};
use tfhe::boolean::prelude::*;

fn main() {
    // Don't consider the following lines; you should follow the procedure above.
    let (client_key, server_key) = gen_keys();
    let ct_6 = client_key.encrypt(true);
    let encoded_output: Vec<u8> = bincode::serialize(&ct_6).unwrap();

//---------------------------- ON CLIENT SIDE

// We deserialize the output ciphertext:
    let output: Ciphertext = bincode::deserialize(&encoded_output[..])
        .expect("failed to deserialize");

// Finally, we decrypt the output:
    let output = client_key.decrypt(&output);

// And check that the result is the expected one:
    assert_eq!(output, true);
}

Integer

tfhe::integer is dedicated to integers smaller than 256 bits. The steps to homomorphically evaluate an integer circuit are described here.

Key Types

integer provides 3 basic key types:

ClientKey
ServerKey
PublicKey

The ClientKey is the key that encrypts and decrypts messages, thus this key is meant to be kept private and should never be shared. This key is created from parameter values that will dictate both the security and efficiency of computations. The parameters also set the maximum number of bits of message encrypted in a ciphertext.

The ServerKey is the key that is used to actually do the FHE computations. It contains a bootstrapping key and a keyswitching key. This key is created from a ClientKey that needs to be shared to the server, so it is not meant to be kept private. A user with a ServerKey can compute on the encrypted data sent by the owner of the associated ClientKey.

To reflect this, computation/operation methods are tied to the ServerKey type.

The PublicKey is a key used to encrypt messages. It can be publicly shared to allow users to encrypt data such that only the ClientKey holder will be able to decrypt. Encrypting with the PublicKey does not alter the homomorphic capabilities associated to the ServerKey.

1. Key Generation

To generate the keys, a user needs two parameters:

A set of shortint cryptographic parameters.
The number of ciphertexts used to encrypt an integer (we call them "shortint blocks").

We are now going to build a pair of keys that can encrypt 8-bit integers (signed or unsigned) by using 4 shortint blocks that store 2 bits of message each.

use tfhe::integer::gen_keys_radix;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let num_block = 4;
    let (client_key, server_key) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);
}

2. Encrypting values

Once we have our keys, we can encrypt values:

use tfhe::integer::gen_keys_radix;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let num_block = 4;
    let (client_key, server_key) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);

    let msg1 = 128u64;
    let msg2 = 13u64;

    // We use the client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);
}

3. Encrypting values with the public key

Once the client key is generated, the public key can be derived and used to encrypt data.

use tfhe::integer::gen_keys_radix;
use tfhe::integer::PublicKey;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let num_block = 4;
    let (client_key, _) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);

    //We generate the public key from the secret client key:
    let public_key = PublicKey::new(&client_key);

    //encryption
    let msg1 = 128u64;
    let msg2 = 13u64;

    // We use the public key to encrypt two messages:
    let ct_1 = public_key.encrypt_radix(msg1, num_block);
    let ct_2 = public_key.encrypt_radix(msg2, num_block);
}

4. Computing and decrypting

With our server_key, and encrypted values, we can now do an addition and then decrypt the result.

use tfhe::integer::gen_keys_radix;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let num_block = 4;
    let (client_key, server_key) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);

    let msg1 = 128;
    let msg2 = 13;

    // message_modulus^vec_length
    let modulus = client_key.parameters().message_modulus().0.pow(num_block as u32) as u64;

    // We use the client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    // We use the server public key to execute an integer circuit:
    let ct_3 = server_key.add_parallelized(&ct_1, &ct_2);

    // We use the client key to decrypt the output of the circuit:
    let output: u64 = client_key.decrypt(&ct_3);

    assert_eq!(output, (msg1 + msg2) % modulus);
}

Serialization/Deserialization

As explained in the introduction, some types (Serverkey, Ciphertext) are meant to be shared with the server that performs the computations.

# Cargo.toml

[dependencies]
# ...
bincode = "1.3.3"

// main.rs

use bincode;
use std::io::Cursor;
use tfhe::shortint::prelude::*;


fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 1;
    let msg2 = 0;

    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    let mut serialized_data = Vec::new();
    bincode::serialize_into(&mut serialized_data, &server_key)?;
    bincode::serialize_into(&mut serialized_data, &ct_1)?;
    bincode::serialize_into(&mut serialized_data, &ct_2)?;

    // Simulate sending serialized data to a server and getting
    // back the serialized result
    let serialized_result = server_function(&serialized_data)?;
    let result: Ciphertext = bincode::deserialize(&serialized_result)?;

    let output = client_key.decrypt(&result);
    assert_eq!(output, msg1 + msg2);
    Ok(())
}


fn server_function(serialized_data: &[u8]) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let mut serialized_data = Cursor::new(serialized_data);
    let server_key: ServerKey = bincode::deserialize_from(&mut serialized_data)?;
    let ct_1: Ciphertext = bincode::deserialize_from(&mut serialized_data)?;
    let ct_2: Ciphertext = bincode::deserialize_from(&mut serialized_data)?;

    let result = server_key.unchecked_add(&ct_1, &ct_2);

    let serialized_result = bincode::serialize(&result)?;

    Ok(serialized_result)
}

Parallelized PBS

Parallelized Programmable Bootstrapping

TFHE-rs can already perform parallel execution of integer homomorphic operations. Activating this feature can lead to performance improvements, particularly in the case of high core-count CPUs when enough cores are available, or when dealing with operations that require small input message precision.

The following example shows how to use parallelized bootstrapping by choosing multi-bit PBS parameters:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint32};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default()
        .use_custom_parameters(
           tfhe::shortint::parameters::PARAM_MULTI_BIT_MESSAGE_2_CARRY_2_GROUP_3_KS_PBS,
           None,
        )
        .build();
        
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);
    
    let clear_a = 673u32;
    let clear_b = 6u32;
    let a = FheUint32::try_encrypt(clear_a, &keys)?;
    let b = FheUint32::try_encrypt(clear_b, &keys)?;

    let c = &a >> &b;
    let decrypted: u32 = c.decrypt(&keys);
    assert_eq!(decrypted, clear_a >> clear_b);

    Ok(())
}

Deterministic parallelized Programmable Bootstrapping

By nature, the parallelized PBS might not be deterministic: while the resulting ciphertext will always decrypt to the correct plaintext, the order of the operations could vary, resulting in different output ciphertext. To ensure a consistent ciphertext output regardless of execution order, add the with_deterministic_execution() suffix to the parameters.

Here's an example:

use tfhe::prelude::*;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint32};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ConfigBuilder::default()
        .use_custom_parameters(
           tfhe::shortint::parameters::PARAM_MULTI_BIT_MESSAGE_2_CARRY_2_GROUP_3_KS_PBS.with_deterministic_execution(),
           None,
        )
        .build();
        
    let (keys, server_keys) = generate_keys(config);
    set_server_key(server_keys);
    
    let clear_a = 673u32;
    let clear_b = 6u32;
    let a = FheUint32::try_encrypt(clear_a, &keys)?;
    let b = FheUint32::try_encrypt(clear_b, &keys)?;

    let c = &a >> &b;
    let decrypted: u32 = c.decrypt(&keys);
    assert_eq!(decrypted, clear_a >> clear_b);

    Ok(())
}

PBS statistics

This document explains how to use the PBS statistics feature in TFHE-rs' shortint API to assess the overall computational intensity in FHE applications.

The shortint API now includes a global counter to track the number of Programmable Bootstrapping (PBS) executed with the pbs-stats feature. This feature enables precise tracking of PBS executions in a circuit. It helps to estimate the overall compute intensity of FHE code using either the shortint, integer, or High-Level APIs.

To know how many PBSes were executed, call get_pbs_count. To reset the PBS count, call reset_pbs_count. You can combine two functions to understand how many PBSes were executed in each part of your code.

Here is an example of how to use the PBS counter:

use tfhe::prelude::*;
use tfhe::*;

pub fn main() {
    // Config and key generation
    let config = ConfigBuilder::default().build();

    let (cks, sks) = generate_keys(config);

    // Encryption
    let a = FheUint32::encrypt(42u32, &cks);
    let b = FheUint32::encrypt(16u32, &cks);

    // Set the server key
    set_server_key(sks);

    // Compute and get the PBS count for the 32 bits multiplication
    let c = &a * &b;
    let mul_32_count = get_pbs_count();

    // Reset the PBS count, and get the PBS count for a 32 bits bitwise AND
    reset_pbs_count();
    let d = &a & &b;
    let and_32_count = get_pbs_count();

    // Display the result
    println!("mul_32_count: {mul_32_count}");
    println!("and_32_count: {and_32_count}");
}

SHA256 with Boolean API

This tutorial guides you to convert a regular SHA-256 function to its homomorphic version, with considerations of optimal performances. You will learn:

The basics of the SHA-256 function.
The steps to implement SHA-256 homomorphically.

SHA-256 basics

Padding

The SHA-256 function processes the input data in blocks or chunks of 512 bits. Before performing the hash computations, prepare the data as follows:

Append a single "1" bit
Append "0" bits until exactly 64 bits remain to make the message length a multiple of 512
Append the last 64 bits as a binary encoding of the original input length

In this diagram, the numbers on the top represent the length of the padded input at each position. The formula L+1+k+64 ensures that the length reaches a multiple of 512, matching the required length of the padded input.

Operations and functions

We will use bitwise AND, XOR, NOT, addition modulo 2^32, the Rotate Right (ROTR) and Shift Right (SHR) operations as building blocks for functions inside the SHA-256 computation. These operations all use 32-bit words and produce new words.

We combine these operations inside the sigma (with 4 variations), Ch, and Maj functions. When changing SHA-256 to the homomorphic computation, we will mainly change the code of each operation.

Here is the definition of each function:

Ch(x, y, z) = (x AND y) XOR ((NOT x) AND z)
Maj(x, y, z) = (x AND y) XOR (x AND z) XOR (y AND z)

Σ0(x) = ROTR-2(x) XOR ROTR-13(x) XOR ROTR-22(x)
Σ1(x) = ROTR-6(x) XOR ROTR-11(x) XOR ROTR-25(x)
σ0(x) = ROTR-7(x) XOR ROTR-18(x) XOR SHR-3(x)
σ1(x) = ROTR-17(x) XOR ROTR-19(x) XOR SHR-10(x)

We simplify Maj using the Boolean distributive law: (x AND y) XOR (x AND z) = x AND (y XOR z), as shown below:

Maj(x, y, z) = (x AND (y XOR z)) XOR (y AND z)

We simplify Ch using a single bitwise multiplexer. Here's the truth table of the Ch expression.

Result

This table shows that the result equals to z when x = 0, and the result equals to y when x = 1, which means if x {y} else {z}. Hence we can replace the 4 bitwise operations of Ch by a single bitwise multiplexer.

All these operations can be evaluated homomorphically:

ROTR and SHR: They can be evaluated by changing the index of each ecrypted bit of the word without using any homomorphic operation.
Bitwise AND, XOR and multiplexer: They can be computed homomorphically
Addition modulo 2^32: It can be broken down into boolean homomorphic operations.

SHA-256 computation

The SHA-256 function processes data in 512-bit chunks. Here is what happens during computation:

The 512-bit chunk is computed into 16 words, each containing 32 bits.
Another 48 words are computed using the previous function.
After computing the 64 words, within the same chunk, a compression loop will compute a hash value (8 32-bit words) using the previous functions and some constants to mix everything up.
This entire process iterate through each 512-bit chunk of your data.
When we finish the last chunk iteration, the resulting hash values will be the output of the SHA-256 function.

Here is an example of this function using arrays of 32 bools to represent words:

fn sha256(padded_input: Vec<bool>) -> [bool; 256] {

    // Initialize hash values with constant values
    let mut hash: [[bool; 32]; 8] = [
        hex_to_bools(0x6a09e667), hex_to_bools(0xbb67ae85),
        hex_to_bools(0x3c6ef372), hex_to_bools(0xa54ff53a),
        hex_to_bools(0x510e527f), hex_to_bools(0x9b05688c),
        hex_to_bools(0x1f83d9ab), hex_to_bools(0x5be0cd19),
    ];

    let chunks = padded_input.chunks(512);

    for chunk in chunks {
        let mut w = [[false; 32]; 64];

        // Copy first 16 words from current chunk
        for i in 0..16 {
            w[i].copy_from_slice(&chunk[i * 32..(i + 1) * 32]);
        }

        // Compute the other 48 words
        for i in 16..64 {
            w[i] = add(add(add(sigma1(&w[i - 2]), w[i - 7]), sigma0(&w[i - 15])), w[i - 16]);
        }

        let mut a = hash[0];
        let mut b = hash[1];
        let mut c = hash[2];
        let mut d = hash[3];
        let mut e = hash[4];
        let mut f = hash[5];
        let mut g = hash[6];
        let mut h = hash[7];

        // Compression loop, each iteration uses a specific constant from K
        for i in 0..64 {
            let temp1 = add(add(add(add(h, ch(&e, &f, &g)), w[i]), hex_to_bools(K[i])), sigma_upper_case_1(&e));
            let temp2 = add(sigma_upper_case_0(&a), maj(&a, &b, &c));
            h = g;
            g = f;
            f = e;
            e = add(d, temp1);
            d = c;
            c = b;
            b = a;
            a = add(temp1, temp2);
        }

        hash[0] = add(hash[0], a);
        hash[1] = add(hash[1], b);
        hash[2] = add(hash[2], c);
        hash[3] = add(hash[3], d);
        hash[4] = add(hash[4], e);
        hash[5] = add(hash[5], f);
        hash[6] = add(hash[6], g);
        hash[7] = add(hash[7], h);
    }

    // Concatenate the final hash values to produce a 256-bit hash
    let mut output = [false; 256];
    for i in 0..8 {
        output[i * 32..(i + 1) * 32].copy_from_slice(&hash[i]);
    }
    output
}

Homomorphic SHA-256 on encrypted data

To convert SHA-256 to a homomorphic version, you can replace each bit of padded_input with a fully homomorphic encryption of the same bit value and operate on the encrypted value using homomorphic operations.

While the structure of the SHA-256 function remains the same, there are some important considerations in the code:

The function signature and the borrowing rules should adapt to the ciphertext type (representing the encrypted bits).
Implementing SHA-256 operations with homomorphic encryption uses homomorphic boolean operations internally.

Homomorphic operations on encrypted data can be very expensive. Consider these options for better speed:

Remove unnecessary use of homomorphic operations and maximize parallelization.
Simplify the code with Rayon crate that parallelizes iterators and manages threads efficiently.

Now let's dive into details of each SHA256 operation.

Rotate Right and Shift Right

Rotate Right and Shift Right can be evaluated by changing the position of each encrypted bit in the word, requiring no homomorphic operations. Here is the implementation:

fn rotate_right(x: &[Ciphertext; 32], n: usize) -> [Ciphertext; 32] {
    let mut result = x.clone();
    result.rotate_right(n);
    result
}

fn shift_right(x: &[Ciphertext; 32], n: usize, sk: &ServerKey) -> [Ciphertext; 32] {
    let mut result = x.clone();
    result.rotate_right(n);
    result[..n].fill_with(|| sk.trivial_encrypt(false));
    result
}

Bitwise XOR, AND, Multiplexer

To implement these operations, we will use the xor, and mux methods from the TFHE-rs library to perform each boolean operation homomorphically.

For better efficiency, we can parallelize the homomorphic computations because we operate bitwise. It means that we can homomorphically XOR the bits at index 0 of two words using one thread while XORing the bits at index 1 using another thread, and so on. This approach allows for the computation of bitwise operations using up to 32 concurrent threads, corresponding to the 32-bit words used.

Here is the implementation of the bitwise homomorphic XOR operation. The par_iter and par_iter_mut methods create a parallel iterator that we use to compute each XOR efficiently. The other two bitwise operations are implemented in the same way.

fn xor(a: &[Ciphertext; 32], b: &[Ciphertext; 32], sk: &ServerKey) -> [Ciphertext; 32] {
    let mut result = a.clone();
    result.par_iter_mut()
        .zip(a.par_iter().zip(b.par_iter()))
        .for_each(|(dst, (lhs, rhs))| *dst = sk.xor(lhs, rhs));
    result
}

Addition modulo 2^32

This might be the trickiest operation to efficiently implement in a homomorphic manner. A naive implementation could use the Ripple Carry Adder algorithm, which is straightforward but cannot be parallelized because each step depends on the previous one.

A better choice is to use Carry Lookahead Adder, which allows us to use the parallelized AND and XOR bitwise operations. With this design, our adder is around 50% faster than the Ripple Carry Adder.

pub fn add(a: &[Ciphertext; 32], b: &[Ciphertext; 32], sk: &ServerKey) -> [Ciphertext; 32] {
    let propagate = xor(a, b, sk); // Parallelized bitwise XOR
    let generate = and(a, b, sk); // Parallelized bitwise AND

    let carry = compute_carry(&propagate, &generate, sk);
    let sum = xor(&propagate, &carry, sk); // Parallelized bitwise XOR

    sum
}

fn compute_carry(propagate: &[Ciphertext; 32], generate: &[Ciphertext; 32], sk: &ServerKey) -> [Ciphertext; 32] {
    let mut carry = trivial_bools(&[false; 32], sk);
    carry[31] = sk.trivial_encrypt(false);

    for i in (0..31).rev() {
        carry[i] = sk.or(&generate[i + 1], &sk.and(&propagate[i + 1], &carry[i + 1]));
    }

    carry
}

To further optimize performance, we use parallel prefix algorithms to parallelize the function that computes the carry signals. These algorithms involve more (homomorphic) boolean operations and their parallel nature speeds up the processing. We have implemented the Brent-Kung and Ladner-Fischer algorithms with different tradeoffs:

Brent-Kung has the least amount of boolean operations we could find (140 when using grey cells, for 32-bit numbers), which makes it suitable when we can't process many operations concurrently and fast. Our results confirm that it's indeed faster than both the sequential algorithm and Ladner-Fischer when run on regular computers.
On the other hand, Ladner-Fischer performs more boolean operations (209 using grey cells) than Brent-Kung, but they are performed in larger batches. Hence we can compute more operations in parallel and finish earlier, but we need more fast threads available or they will slow down the carry signals computation. Ladner-Fischer can be suitable when using cloud-based computing services, which offer many high-speed threads.

Our implementation uses Brent-Kung by default, but you can enable Ladner-Fischer by using the --ladner-fischer command line argument.

Finally, with all these SHA-256 operations working homomorphically, our functions will be homomomorphic as well along with the whole SHA-256 function (after adapting the code to work with the Ciphertext type).

More parallel processing

Let's talk about other performance improvements we can make before we finish.

In the main sha256_fhe, you can perform some functions in parallel. For example, in the compression loop, temp1 and temp2 can be computed in parallel by using the rayon::join() function when there is a CPU available. The two temporary values in the compression loop are the result of multiple additions, so you can use nested calls to rayon::join() to parallelize more operations.

Another way to speed up consecutive additions would be using the Carry Save Adder, a very efficient adder that takes 3 numbers and returns a sum and a carry sequence. If our inputs are A, B, and C, we can construct a CSA with our previously implemented Maj function and the bitwise XOR operation as follows:

Carry = Maj(A, B, C)
Sum = A XOR B XOR C

By chaining CSAs, we can input the sum and carry from a preceding stage along with another number into a new CSA. Finally, to get the result of the additions we add the sum and carry sequences using a conventional adder. In the end, we are performing the same number of additions, but some of them are now CSAs, speeding up the process. Below is the illustration of this process in the temp1 and temp2 computations.

let (temp1, temp2) = rayon::join(
    || {
        let ((sum, carry), s1) = rayon::join(
            || {
                let ((sum, carry), ch) = rayon::join(
                    || csa(&h, &w[i], &trivial_bools(&hex_to_bools(K[i]), sk), sk),
                    || ch(&e, &f, &g, sk),
                );
                csa(&sum, &carry, &ch, sk)
            },
            || sigma_upper_case_1(&e, sk)
        );

        let (sum, carry) = csa(&sum, &carry, &s1, sk);
        add(&sum, &carry, sk)
    },
    || {
        add(&sigma_upper_case_0(&a, sk), &maj(&a, &b, &c, sk), sk)
    },
);

The first closure of the outer call to join will return temp1 and the second temp2.

Inside the first outer closure, we call join recursively until we add the value h, the current word w[i], and the current constant K[i] by using the CSA, while potentially computing the ch function in parallel. Then we take the sum, carry, and ch values and add them again using the CSA.

All this is done while potentially computing the sigma_upper_case_1 function. Finally we input the previous sum, carry, and sigma values to the CSA and perform the final addition with add. Once again, this is done while potentially computing sigma_upper_case_0 and maj and adding them to get temp2, in the second outer closure.

With these types of changes, we finally get a homomorphic SHA256 function that doesn't leave unused computational resources.

How to use SHA256_bool

First, use the --release flag when running the program. Considering the implementation of encrypt_bools and decrypt_bools, the use of SHA-256 will be as follows:

fn main() {
    let matches = Command::new("Homomorphic sha256")
        .arg(Arg::new("ladner_fischer")
            .long("ladner-fischer")
            .help("Use the Ladner Fischer parallel prefix algorithm for additions")
            .action(ArgAction::SetTrue))
        .get_matches();

    // If set using the command line flag "--ladner-fischer" this algorithm will be used in additions
    let ladner_fischer: bool = matches.get_flag("ladner_fischer");

    // INTRODUCE INPUT FROM STDIN

    let mut input = String::new();
    println!("Write input to hash:");

    io::stdin()
        .read_line(&mut input)
        .expect("Failed to read line");

    input = input.trim_end_matches('\n').to_string();

    println!("You entered: \"{}\"", input);

    // CLIENT PADS DATA AND ENCRYPTS IT

    let (ck, sk) = gen_keys();

    let padded_input = pad_sha256_input(&input);
    let encrypted_input = encrypt_bools(&padded_input, &ck);

    // SERVER COMPUTES OVER THE ENCRYPTED PADDED DATA

    println!("Computing the hash");
    let encrypted_output = sha256_fhe(encrypted_input, ladner_fischer, &sk);

    // CLIENT DECRYPTS THE OUTPUT

    let output = decrypt_bools(&encrypted_output, &ck);
    let outhex = bools_to_hex(output);

    println!("{}", outhex);
}

We can supply the data to hash using a file instead of the command line by using stdin . For example, if the file input.txt is in the same directory as the project, we can use the following shell command after building with cargo build --release:

./target/release/examples/sha256_bool < input.txt

The program accepts hexadecimal inputs. The input must start with "0x" and contain only valid hex digits, otherwise it will be interpreted as text.

Finally， padding is performed on the client side. This has the advantage of hiding the exact length of the input content from the server, thus avoiding the server extracting information from the length, even though the content is fully encrypted.

It is also feasible to perform padding on the server side. The padding function would take the encrypted input and pad it with trivial bit encryptions. We can then integrate the padding function into the sha256_fhe function computed by the server.

Operations

The structure and operations related to integers are described in this section.

How an integer is represented

In integer, the encrypted data is split amongst many ciphertexts encrypted with the shortint library. Below is a scheme representing an integer composed by k shortint ciphertexts.

This crate implements two ways to represent an integer:

the Radix representation
the CRT (Chinese Reminder Theorem) representation

Radix-based integers.

The first possibility to represent a large integer is to use a Radix-based decomposition on the plaintexts. Let $B \in \mathbb{N}$ be a basis such that the size of $B$ is smaller than (or equal to) 4 bits. Then, an integer $m \in \mathbb{N}$ can be written as $m = m_0 + m_1*B + m_2*B^2 + ...$ , where each $m_i$ is strictly smaller than $B$ . Each $m_i$ is then independently encrypted. In the end, an Integer ciphertext is defined as a set of shortint ciphertexts.

The definition of an integer requires a basis and a number of blocks. These parameters are chosen at key generation. Below, the keys are dedicated to integers encrypting messages over 8 bits, using a basis over 2 bits (i.e., $B=2^2$ ) and 4 blocks.

use tfhe::integer::gen_keys_radix;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let num_block = 4;
    let (client_key, server_key) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);
}

In this representation, the correctness of operations requires the carries to be propagated throughout the ciphertext. This operation is costly, since it relies on the computation of many programmable bootstrapping operations over shortints.

CRT-based integers.

The second approach to represent large integers is based on the Chinese Remainder Theorem. In this case, the basis $B$ is composed of several integers $b_i$ , such that there are pairwise coprime, and each $b\_i$ has a size smaller than 4 bits. The CRT-based integer are defined modulus $\prod b_i$ . For an integer $m$ , its CRT decomposition is simply defined as $m \bmod{b_0}, m \bmod{b_1}, ...$ . Each part is then encrypted as a shortint ciphertext. In the end, an Integer ciphertext is defined as a set of shortint ciphertexts.

In the following example, the chosen basis is $B = [2, 3, 5]$ . The integer is defined modulus $2*3*5 = 30$ . There is no need to pre-size the number of blocks since it is determined from the number of values composing the basis. Here, the integer is split over three blocks.

use tfhe::integer::CrtClientKey;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    let basis = vec![2, 3, 5];
    let cks = CrtClientKey::new(PARAM_MESSAGE_2_CARRY_2_KS_PBS, basis);
}

This representation has many advantages: no carry propagation is required, cleaning the carry buffer of each ciphertext block is enough. This implies that operations can easily be parallelized. It also allows the efficient computation of PBS in the case where the function is CRT-compliant.

A variant of the CRT is proposed where each block might be associated to a different key couple. Here, a keychain to the computations is required, but this may result in a performance improvement.

List of available operations

The list of operations available in integer depends on the type of representation:

Operation name

Radix-based

CRT-based

Negation

Addition

Scalar Addition

Subtraction

Scalar Subtraction

Multiplication

Scalar Multiplication

Bitwise OR, AND, XOR

Equality

Left/Right Shift

Comparisons <,<=,>, >=

Min, Max

Types of operations

Much like shortint, the operations available via a ServerKey may come in different variants:

operations that take their inputs as encrypted values.
scalar operations take at least one non-encrypted value as input.

For example, the addition has both variants:

ServerKey::unchecked_add, which takes two encrypted values and adds them.
ServerKey::unchecked_scalar_add, which takes an encrypted value and a clear value (the so-called scalar) and adds them.

Each operation may come in different 'flavors':

unchecked: always does the operation, without checking if the result may exceed the capacity of the plaintext space.
checked: checks are done before computing the operation, returning an error if operation cannot be done safely.
smart: always does the operation, if the operation cannot be computed safely, the smart operation will propagate the carry buffer to make the operation possible. Some of those will require a mutable reference as input: this is because the inputs' carry might be cleaned, but this will not change the underlying encrypted value.
default: always compute the operation and always clear the carry. Could be slower than smart, but ensure that the timings are consistent from one call to another.

Not all operations have these 4 flavors, as some of them are implemented in a way that the operation is always possible without ever exceeding the plaintext space capacity.

If you don't know which flavor to use, you should use the default one.

How to use each operation type

Let's try to do a circuit evaluation using the different flavors of already introduced operations. For a very small circuit, the unchecked flavor may be enough to do the computation correctly. Otherwise, checked and smart are the best options.

As an example, let's do a scalar multiplication, a subtraction, and an addition.

use tfhe::integer::gen_keys_radix;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    let num_block = 4;
    let (client_key, server_key) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);

    let msg1 = 12u64;
    let msg2 = 11u64;
    let msg3 = 9u64;
    let scalar = 3u64;

    // message_modulus^vec_length
    let modulus = client_key.parameters().message_modulus().0.pow(num_block as u32) as u64;

    // We use the client key to encrypt two messages:
    let mut ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);
    let ct_3 = client_key.encrypt(msg2);

    server_key.unchecked_small_scalar_mul_assign(&mut ct_1, scalar);

    server_key.unchecked_sub_assign(&mut ct_1, &ct_2);

    server_key.unchecked_add_assign(&mut ct_1, &ct_3);

    // We use the client key to decrypt the output of the circuit:
    let output: u64 = client_key.decrypt(&ct_1);
    // The carry buffer has been overflowed, the result is not correct
    assert_ne!(output, ((msg1 * scalar as u64 - msg2) + msg3) % modulus as u64);
}

During this computation the carry buffer has been overflowed, and the output may be incorrect as all the operations were unchecked.

If the same circuit is done but using the checked flavor, a panic will occur:

use tfhe::integer::gen_keys_radix;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    let num_block = 2;
    let (client_key, server_key) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);

    let msg1 = 12u64;
    let msg2 = 11u64;
    let msg3 = 9u64;
    let scalar = 3u64;

    // message_modulus^vec_length
    let modulus = client_key.parameters().message_modulus().0.pow(num_block as u32) as u64;

    // We use the client key to encrypt two messages:
    let mut ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);
    let ct_3 = client_key.encrypt(msg3);

    server_key.checked_small_scalar_mul_assign(&mut ct_1, scalar).unwrap();
    
    server_key.checked_sub_assign(&mut ct_1, &ct_2).unwrap();
    
    let result = server_key.checked_add_assign(&mut ct_1, &ct_3);
    assert!(result.is_err());

    // We use the client key to decrypt the output of the circuit:
    // Only the scalar multiplication could be done
    let output: u64 = client_key.decrypt(&ct_1);
    assert_eq!(output, ((msg1 * scalar) - msg2) % modulus as u64);
}

The checked flavor permits the manual management of the overflow of the carry buffer by raising an error if correctness is not guaranteed.

Using the smart flavor will output the correct result all the time. However, the computation may be slower as the carry buffer may be propagated during the computations.

use tfhe::integer::gen_keys_radix;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    let num_block = 4;
    let (client_key, server_key) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);

    let msg1 = 12u64;
    let msg2 = 11u64;
    let msg3 = 9u64;
    let scalar = 3u64;

    // message_modulus^vec_length
    let modulus = client_key.parameters().message_modulus().0.pow(num_block as u32) as u64;

    // We use the client key to encrypt two messages:
    let mut ct_1 = client_key.encrypt(msg1);
    let mut ct_2 = client_key.encrypt(msg2);
    let mut ct_3 = client_key.encrypt(msg3);

    server_key.smart_scalar_mul_assign(&mut ct_1, scalar);

    server_key.smart_sub_assign(&mut ct_1, &mut ct_2);

    server_key.smart_add_assign(&mut ct_1, &mut ct_3);

    // We use the client key to decrypt the output of the circuit:
    let output: u64 = client_key.decrypt(&ct_1);
    assert_eq!(output, ((msg1 * scalar as u64 - msg2) + msg3) % modulus as u64);
}

You must avoid cloning the inputs when calling smart operations to preserve performance. For instance, you SHOULD NOT have these kind of patterns in the code:

sks.smart_add(&mut a.clone(), &mut b.clone());

The main advantage of the default flavor is to ensure predictable timings, as long as only this kind of operation is used. Only the parallelized version of the operations is provided.

Using default could slow down computations.

use tfhe::integer::gen_keys_radix;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;

fn main() {
    let num_block = 4;
    let (client_key, server_key) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);

    let msg1 = 12u64;
    let msg2 = 11u64;
    let msg3 = 9u64;
    let scalar = 3u64;

    // message_modulus^vec_length
    let modulus = client_key.parameters().message_modulus().0.pow(num_block as u32) as u64;

    // We use the client key to encrypt two messages:
    let mut ct_1 = client_key.encrypt(msg1);
    let mut ct_2 = client_key.encrypt(msg2);
    let mut ct_3 = client_key.encrypt(msg3);

    server_key.scalar_mul_assign_parallelized(&mut ct_1, scalar);

    server_key.sub_assign_parallelized(&mut ct_1, &mut ct_2);

    server_key.add_assign_parallelized(&mut ct_1, &mut ct_3);

    // We use the client key to decrypt the output of the circuit:
    let output: u64 = client_key.decrypt(&ct_1);
    assert_eq!(output, ((msg1 * scalar as u64 - msg2) + msg3) % modulus as u64);
}

Quick start

This library makes it possible to execute homomorphic operations over encrypted data, where the data are either Booleans, short integers (named shortint in the rest of this documentation), or integers up to 256 bits. It allows you to execute a circuit on an untrusted server because both circuit inputs and outputs are kept private. Data are indeed encrypted on the client side, before being sent to the server. On the server side, every computation is performed on ciphertexts.

The server, however, has to know the circuit to be evaluated. At the end of the computation, the server returns the encryption of the result to the user. Then the user can decrypt it with the secret key.

General method to write an homomorphic circuit program

The overall process to write an homomorphic program is the same for all types. The basic steps for using the TFHE-rs library are the following:

Choose a data type (Boolean, shortint, integer)
Import the library
Create client and server keys
Encrypt data with the client key
Compute over encrypted data using the server key
Decrypt data with the client key

API levels.

This library has different modules, with different levels of abstraction.

There is the core_crypto module, which is the lowest level API with the primitive functions and types of the TFHE scheme.

Above the core_crypto module, there are the Boolean, shortint, and integer modules, which contain easy to use APIs enabling evaluation of Boolean, short integer, and integer circuits.

Finally, there is the high-level module built on top of the Boolean, shortint, integer modules. This module is meant to abstract cryptographic complexities: no cryptographical knowledge is required to start developing an FHE application. Another benefit of the high-level module is the drastically simplified development process compared to lower level modules.

high-level API

TFHE-rs exposes a high-level API by default that includes datatypes that try to match Rust's native types by having overloaded operators (+, -, ...).

Here is an example of how the high-level API is used:

Use the --release flag to run this example (eg: cargo run --release)

Boolean example

Here is an example of how the library can be used to evaluate a Boolean circuit:

Use the --release flag to run this example (eg: cargo run --release)

shortint example

Here is a full example using shortint:

Use the --release flag to run this example (eg: cargo run --release)

integer example

Use the --release flag to run this example (eg: cargo run --release)

use tfhe::{ConfigBuilder, generate_keys, set_server_key, FheUint8};
use tfhe::prelude::*;

fn main() {
    let config = ConfigBuilder::default()
        .build();

    let (client_key, server_key) = generate_keys(config);

    set_server_key(server_key);

    let clear_a = 27u8;
    let clear_b = 128u8;

    let a = FheUint8::encrypt(clear_a, &client_key);
    let b = FheUint8::encrypt(clear_b, &client_key);

    let result = a + b;

    let decrypted_result: u8 = result.decrypt(&client_key);

    let clear_result = clear_a + clear_b;

    assert_eq!(decrypted_result, clear_result);
}

use tfhe::boolean::prelude::*;

fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let (client_key, server_key) = gen_keys();

    // We use the client secret key to encrypt two messages:
    let ct_1 = client_key.encrypt(true);
    let ct_2 = client_key.encrypt(false);

    // We use the server public key to execute a boolean circuit:
    // if ((NOT ct_2) NAND (ct_1 AND ct_2)) then (NOT ct_2) else (ct_1 AND ct_2)
    let ct_3 = server_key.not(&ct_2);
    let ct_4 = server_key.and(&ct_1, &ct_2);
    let ct_5 = server_key.nand(&ct_3, &ct_4);
    let ct_6 = server_key.mux(&ct_5, &ct_3, &ct_4);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_6);
    assert_eq!(output, true);
}

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys
    // using parameters with 2 bits of message and 2 bits of carry
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2);

    let msg1 = 1;
    let msg2 = 0;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    // We use the server public key to execute an integer circuit:
    let ct_3 = server_key.add(&ct_1, &ct_2);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_3);
    assert_eq!(output, (msg1 + msg2) % modulus as u64);
}

use tfhe::integer::gen_keys_radix;
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2;

fn main() {
    // We generate keys to encrypt 16 bits radix-encoded integers
    // using 8 blocks of 2 bits
    let (cks, sks) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2, 8);

    let clear_a = 2382u16;
    let clear_b = 29374u16;

    let mut a = cks.encrypt(clear_a as u64);
    let mut b = cks.encrypt(clear_b as u64);

    let encrypted_max = sks.smart_max_parallelized(&mut a, &mut b);
    let decrypted_max: u64 = cks.decrypt(&encrypted_max);

    assert_eq!(decrypted_max as u16, clear_a.max(clear_b))
}

Serialization/Deserialization

Since the ServerKey and ClientKey types both implement the Serialize and Deserialize traits, you are free to use any serializer that suits you to save and load the keys to disk.

Here is an example using the bincode serialization library, which serializes to a binary format:

use std::fs::{File, create_dir_all};
use std::io::{Write, Read};
use tfhe::boolean::prelude::*;

fn main() {
// We generate a set of client/server keys, using the default parameters:
    let (client_key, server_key) = gen_keys();

// We serialize the keys to bytes:
    let encoded_server_key: Vec<u8> = bincode::serialize(&server_key).unwrap();
    let encoded_client_key: Vec<u8> = bincode::serialize(&client_key).unwrap();

// Create a tmp dir with the current user name to avoid cluttering the /tmp dir
    let user = std::env::var("USER").unwrap_or_else(|_| "unknown_user".to_string());
    let tmp_dir_for_user = &format!("/tmp/{user}");

    create_dir_all(tmp_dir_for_user).unwrap();

    let server_key_file = &format!("{tmp_dir_for_user}/ser_example_server_key.bin");
    let client_key_file = &format!("{tmp_dir_for_user}/ser_example_client_key.bin");

// We write the keys to files:
    let mut file = File::create(server_key_file)
        .expect("failed to create server key file");
    file.write_all(encoded_server_key.as_slice()).expect("failed to write key to file");
    let mut file = File::create(client_key_file)
        .expect("failed to create client key file");
    file.write_all(encoded_client_key.as_slice()).expect("failed to write key to file");

// We retrieve the keys:
    let mut file = File::open(server_key_file)
        .expect("failed to open server key file");
    let mut encoded_server_key: Vec<u8> = Vec::new();
    file.read_to_end(&mut encoded_server_key).expect("failed to read the key");

    let mut file = File::open(client_key_file)
        .expect("failed to open client key file");
    let mut encoded_client_key: Vec<u8> = Vec::new();
    file.read_to_end(&mut encoded_client_key).expect("failed to read the key");

// We deserialize the keys:
    let loaded_server_key: ServerKey = bincode::deserialize(&encoded_server_key[..])
        .expect("failed to deserialize");
    let loaded_client_key: ClientKey = bincode::deserialize(&encoded_client_key[..])
        .expect("failed to deserialize");


    let ct_1 = client_key.encrypt(false);

// We check for equality:
    assert_eq!(false, loaded_client_key.decrypt(&ct_1));
}

Shortint

tfhe::shortint is dedicated to unsigned integers smaller than 8 bits. The steps to homomorphically evaluate a circuit are described below.

Key generation

tfhe::shortint provides 3 key types:

ClientKey
ServerKey
PublicKey

The ClientKey is the key that encrypts and decrypts messages (integer values up to 8 bits here). It is meant to be kept private and should never be shared. This key is created from parameter values that will dictate both the security and efficiency of computations. The parameters also set the maximum number of bits of message encrypted in a ciphertext.

The ServerKey is the key that is used to evaluate the FHE computations. Most importantly, it contains a bootstrapping key and a keyswitching key. This key is created from a ClientKey that needs to be shared to the server (it is not meant to be kept private). A user with a ServerKey can compute on the encrypted data sent by the owner of the associated ClientKey.

Computation/operation methods are tied to the ServerKey type.

The PublicKey is the key used to encrypt messages. It can be publicly shared to allow users to encrypt data such that only the ClientKey holder will be able to decrypt. Encrypting with the PublicKey does not alter the homomorphic capabilities associated to the ServerKey.

use tfhe::shortint::prelude::*;

fn main()  {
    // We generate a set of client/server keys
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);
}

Encrypting values

Once the keys have been generated, the client key is used to encrypt data:

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys
   let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 1;
    let msg2 = 0;

    // We use the client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);
}

Encrypting values using a public key

Once the keys have been generated, the client key is used to encrypt data:

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys
   let (client_key, _) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);
   let public_key = PublicKey::new(&client_key);

    let msg1 = 1;
    let msg2 = 0;

    // We use the client key to encrypt two messages:
    let ct_1 = public_key.encrypt(msg1);
    let ct_2 = public_key.encrypt(msg2);
}

Computing and decrypting

Using the server_key, addition is possible over encrypted values. The resulting plaintext is recovered after the decryption via the secret client key.

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 1;
    let msg2 = 0;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    // We use the server public key to execute an integer circuit:
    let ct_3 = server_key.add(&ct_1, &ct_2);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_3);
    assert_eq!(output, (msg1 + msg2) % modulus as u64);
}

Operations

This contains the operations available in tfhe::boolean, along with code examples.

The NOT unary gate

use tfhe::boolean::prelude::*;

fn main() {
// We generate a set of client/server keys, using the default parameters:
    let (client_key, server_key) = gen_keys();

// We use the client secret key to encrypt a message:
    let ct_1 = client_key.encrypt(true);

// We use the server public key to execute the NOT gate:
    let ct_not = server_key.not(&ct_1);

// We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_not);
    assert_eq!(output, false);
}

Binary gates

use tfhe::boolean::prelude::*;

fn main() {
// We generate a set of client/server keys, using the default parameters:
    let (client_key, server_key) = gen_keys();

// We use the client secret key to encrypt a message:
    let ct_1 = client_key.encrypt(true);
    let ct_2 = client_key.encrypt(false);

// We use the server public key to execute the XOR gate:
    let ct_xor = server_key.xor(&ct_1, &ct_2);

// We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_xor);
    assert_eq!(output, true^false);
}

The MUX ternary gate

Let ct_1, ct_2, ct_3 be three Boolean ciphertexts. Then, the MUX gate (abbreviation of MUltipleXer) is equivalent to the operation:

if ct_1 {
    return ct_2
} else {
    return ct_3
}

This example shows how to use the MUX ternary gate:

use tfhe::boolean::prelude::*;

fn main() {
// We generate a set of client/server keys, using the default parameters:
    let (client_key, server_key) = gen_keys();

    let bool1 = true;
    let bool2 = false;
    let bool3 = true;

// We use the client secret key to encrypt a message:
    let ct_1 = client_key.encrypt(true);
    let ct_2 = client_key.encrypt(false);
    let ct_3 = client_key.encrypt(false);


// We use the server public key to execute the NOT gate:
    let ct_xor = server_key.mux(&ct_1, &ct_2, &ct_3);

// We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_xor);
    assert_eq!(output, if bool1 {bool2} else {bool3});
}

Serialization/Deserialization

As explained in the introduction, some types (Serverkey, Ciphertext) are meant to be shared with the server that does the computations.

The easiest way to send these data to a server is to use the serialization and deserialization features. TFHE-rs uses the serde framework, so serde's Serialize and Deserialize are implemented.

# Cargo.toml

[dependencies]
# ...
bincode = "1.3.3"

// main.rs

use bincode;
use std::io::Cursor;
use tfhe::integer::{gen_keys_radix, ServerKey, RadixCiphertext};
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;


fn main() -> Result<(), Box<dyn std::error::Error>> {
    // We generate a set of client/server keys, using the default parameters:
    let num_block = 4;
    let (client_key, server_key) = gen_keys_radix(PARAM_MESSAGE_2_CARRY_2_KS_PBS, num_block);

    let msg1 = 201;
    let msg2 = 12;

    // message_modulus^vec_length
    let modulus = client_key.parameters().message_modulus().0.pow(num_block as u32) as u64;
    
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    let mut serialized_data = Vec::new();
    bincode::serialize_into(&mut serialized_data, &server_key)?;
    bincode::serialize_into(&mut serialized_data, &ct_1)?;
    bincode::serialize_into(&mut serialized_data, &ct_2)?;

    // Simulate sending serialized data to a server and getting
    // back the serialized result
    let serialized_result = server_function(&serialized_data)?;
    let result: RadixCiphertext = bincode::deserialize(&serialized_result)?;

    let output: u64 = client_key.decrypt(&result);
    assert_eq!(output, (msg1 + msg2) % modulus);
    Ok(())
}


fn server_function(serialized_data: &[u8]) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let mut serialized_data = Cursor::new(serialized_data);
    let server_key: ServerKey = bincode::deserialize_from(&mut serialized_data)?;
    let ct_1: RadixCiphertext = bincode::deserialize_from(&mut serialized_data)?;
    let ct_2: RadixCiphertext = bincode::deserialize_from(&mut serialized_data)?;

    let result = server_key.unchecked_add(&ct_1, &ct_2);

    let serialized_result = bincode::serialize(&result)?;

    Ok(serialized_result)
}

Quick start

The core_crypto module offers an API to low-level cryptographic primitives and objects, like lwe_encryption or rlwe_ciphertext. The goal is to propose an easy-to-use API for cryptographers.

The overall code architecture is split in two parts: one for entity definitions and another focused on algorithms. The entities contain the definition of useful types, like LWE ciphertext or bootstrapping keys. The algorithms are then naturally defined to work using these entities.

The API is convenient to add or modify existing algorithms, or to have direct access to the raw data. Even if the LWE ciphertext object is defined, along with functions giving access to the body, it is also possible to bypass these to get directly the $i^{th}$ element of LWE mask.

For instance, the code to encrypt and then decrypt a message looks like:

use tfhe::core_crypto::prelude::*;

// DISCLAIMER: these toy example parameters are not guaranteed to be secure or yield correct
// computations
// Define parameters for LweCiphertext creation
let lwe_dimension = LweDimension(742);
let lwe_noise_distribution =
    Gaussian::from_dispersion_parameter(StandardDev(0.000007069849454709433), 0.0);
let ciphertext_modulus = CiphertextModulus::new_native();

// Create the PRNG
let mut seeder = new_seeder();
let seeder = seeder.as_mut();
let mut encryption_generator =
    EncryptionRandomGenerator::<ActivatedRandomGenerator>::new(seeder.seed(), seeder);
let mut secret_generator =
    SecretRandomGenerator::<ActivatedRandomGenerator>::new(seeder.seed());

// Create the LweSecretKey
let lwe_secret_key =
    allocate_and_generate_new_binary_lwe_secret_key(lwe_dimension, &mut secret_generator);

// Create the plaintext
let msg = 3u64;
let plaintext = Plaintext(msg << 60);

// Create a new LweCiphertext
let mut lwe = LweCiphertext::new(0u64, lwe_dimension.to_lwe_size(), ciphertext_modulus);

encrypt_lwe_ciphertext(
    &lwe_secret_key,
    &mut lwe,
    plaintext,
    lwe_noise_distribution,
    &mut encryption_generator,
);

let decrypted_plaintext = decrypt_lwe_ciphertext(&lwe_secret_key, &lwe);

// Round and remove encoding
// First create a decomposer working on the high 4 bits corresponding to our encoding.
let decomposer = SignedDecomposer::new(DecompositionBaseLog(4), DecompositionLevelCount(1));
let rounded = decomposer.closest_representable(decrypted_plaintext.0);

// Remove the encoding
let cleartext = rounded >> 60;

// Check we recovered the original message
assert_eq!(cleartext, msg);

Operations

The structure and operations related to short integers are described in this section.

How a shortint is represented

In shortint, the encrypted data is stored in an LWE ciphertext.

Conceptually, the message stored in an LWE ciphertext is divided into a carry buffer and a message buffer.

The message buffer is the space where the actual message is stored. This represents the modulus of the input messages (denoted by MessageModulus in the code). When doing computations on a ciphertext, the encrypted message can overflow the message modulus. The part of the message which exceeds the message modulus is stored in the carry buffer. The size of the carry buffer is defined by another modulus, called CarryModulus.

Together, the message modulus and the carry modulus form the plaintext space that is available in a ciphertext. This space cannot be overflowed, otherwise the computation may result in an incorrect output.

In order to ensure the correctness of the computation, we track the maximum value encrypted in a ciphertext via an associated attribute called the degree. When the degree reaches a defined threshold, the carry buffer may be emptied to safely resume the computations. In shortint the carry modulus is considered useful as a means to do more computations.

Types of operations

The operations available via a ServerKey may come in different variants:

operations that take their inputs as encrypted values
scalar operations that take at least one non-encrypted value as input

For example, the addition has two variants:

ServerKey::unchecked_add, which takes two encrypted values and adds them.
ServerKey::unchecked_scalar_add, which takes an encrypted value and a clear value (a so-called scalar) and adds them.

Each operation may come in different 'flavors':

unchecked: always does the operation, without checking if the result may exceed the capacity of the plaintext space. Using this operation might have an impact on the correctness of the following operations;
checked: checks are done before computing the operation, returning an error if operation cannot be done safely;
smart: always does the operation. If the operation cannot be computed safely, the smart operation will clear the carry to make the operation possible. Some of those will require a mutable reference as input: this is to allow the modification of the carry, but this will not change the underlying encrypted value;
default: always does the operation and always clears the carry. Could be slower than smart, but it ensures that the timings are consistent from one call to another.

Not all operations have these 4 flavors, as some of them are implemented in a way that the operation is always possible without ever exceeding the plaintext space capacity.

If you don't know which flavor to use, you should use the default one.

How to use operation types

Let's try to do a circuit evaluation using the different flavors of operations that we have already introduced. For a very small circuit, the unchecked flavour may be enough to do the computation correctly. Otherwise,checked and smart are the best options.

Let's do a scalar multiplication, a subtraction, and a multiplication.

During this computation, the carry buffer has been overflowed and, as all the operations were unchecked, the output may be incorrect.

If we redo this same circuit with the checked flavor, a panic will occur:

The checked flavor permits manual management of the overflow of the carry buffer by raising an error if correctness is not guaranteed.

Using the smart flavor will output the correct result all the time. However, the computation may be slower as the carry buffer may be cleaned during the computations.

The main advantage of the default flavor is to ensure predictable timings as long as this is the only kind of operation which is used.

Using default could slow-down computations.

#List of available operations

Certain operations can only be used if the parameter set chosen is compatible with the bivariate programmable bootstrapping, meaning the carry buffer is larger than or equal to the message buffer. These operations are marked with a star (*).

The list of implemented operations for shortint is:

addition between two ciphertexts
addition between a ciphertext and an unencrypted scalar
comparisons <, <=, >, >=, ==, != between a ciphertext and an unencrypted scalar
division of a ciphertext by an unencrypted scalar
LSB multiplication between two ciphertexts returning the result truncated to fit in the message buffer
multiplication of a ciphertext by an unencrypted scalar
bitwise shift <<, >>
subtraction of a ciphertext by another ciphertext
subtraction of a ciphertext by an unencrypted scalar
negation of a ciphertext
bitwise and, or and xor (*)
comparisons <, <=, >, >=, ==, != between two ciphertexts (*)
division between two ciphertexts (*)
MSB multiplication between two ciphertexts returning the part overflowing the message buffer (*)

Public key encryption.

TFHE-rs supports both private and public key encryption methods. The only difference between both lies in the encryption step: in this case, the encryption method is called using public_key instead of client_key.

Here is a small example on how to use public encryption:

Arithmetic operations.

Classical arithmetic operations are supported by shortint:

bitwise operations

Short homomorphic integer types support some bitwise operations.

A simple example on how to use these operations:

comparisons

Short homomorphic integer types support comparison operations.

A simple example on how to use these operations:

univariate function evaluations

A simple example on how to use this operation to homomorphically compute the hamming weight (i.e., the number of bits equal to one) of an encrypted number.

bi-variate function evaluations

Using the shortint types offers the possibility to evaluate bi-variate functions, or functions that take two ciphertexts as input. This requires choosing a parameter set such that the carry buffer size is at least as large as the message (i.e., PARAM_MESSAGE_X_CARRY_Y with X <= Y).

Here is a simple code example:

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys, using the default parameters:
   let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 3;
    let msg2 = 2;

    // We use the client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);
}

use tfhe::shortint::prelude::*;
use tfhe::shortint::parameters::DynamicDistribution;

fn main() {
    let param = unsafe {
        ClassicPBSParameters::new(
            LweDimension(656),
            GlweDimension(2),
            PolynomialSize(512),
            DynamicDistribution::new_gaussian_from_std_dev(
                StandardDev(0.000034119201269311964),
            ),
            DynamicDistribution::new_gaussian_from_std_dev(
                StandardDev(0.00000004053919869756513),
            ),
            DecompositionBaseLog(8),
            DecompositionLevelCount(2),
            DecompositionBaseLog(3),
            DecompositionLevelCount(4),
            MessageModulus(4),
            CarryModulus(1),
            MaxNoiseLevel::new(2),
            2.0f64.powi(-40),
            CiphertextModulus::new_native(),
            EncryptionKeyChoice::Big,
        )
    };
}

use tfhe::core_crypto::prelude::*;

pub fn main() {
    // DISCLAIMER: these toy example parameters are not guaranteed to be secure or yield correct
    // computations
    // Define the parameters for a 4 bits message able to hold the doubled 2 bits message
    let small_lwe_dimension = LweDimension(742);
    let glwe_dimension = GlweDimension(1);
    let polynomial_size = PolynomialSize(2048);
    let lwe_noise_distribution =
        Gaussian::from_dispersion_parameter(StandardDev(0.000007069849454709433), 0.0);
    let glwe_noise_distribution =
        Gaussian::from_dispersion_parameter(StandardDev(0.00000000000000029403601535432533), 0.0);
    let pbs_base_log = DecompositionBaseLog(23);
    let pbs_level = DecompositionLevelCount(1);
    let ciphertext_modulus = CiphertextModulus::new_native();

    // Request the best seeder possible, starting with hardware entropy sources and falling back to
    // /dev/random on Unix systems if enabled via cargo features
    let mut boxed_seeder = new_seeder();
    // Get a mutable reference to the seeder as a trait object from the Box returned by new_seeder
    let seeder = boxed_seeder.as_mut();

    // Create a generator which uses a CSPRNG to generate secret keys
    let mut secret_generator =
        SecretRandomGenerator::<ActivatedRandomGenerator>::new(seeder.seed());

    // Create a generator which uses two CSPRNGs to generate public masks and secret encryption
    // noise
    let mut encryption_generator =
        EncryptionRandomGenerator::<ActivatedRandomGenerator>::new(seeder.seed(), seeder);

    println!("Generating keys...");

    // Generate an LweSecretKey with binary coefficients
    let small_lwe_sk =
        LweSecretKey::generate_new_binary(small_lwe_dimension, &mut secret_generator);

    // Generate a GlweSecretKey with binary coefficients
    let glwe_sk =
        GlweSecretKey::generate_new_binary(glwe_dimension, polynomial_size, &mut secret_generator);

    // Create a copy of the GlweSecretKey re-interpreted as an LweSecretKey
    let big_lwe_sk = glwe_sk.clone().into_lwe_secret_key();

    // Generate the bootstrapping key, we use the parallel variant for performance reason
    let std_bootstrapping_key = par_allocate_and_generate_new_lwe_bootstrap_key(
        &small_lwe_sk,
        &glwe_sk,
        pbs_base_log,
        pbs_level,
        glwe_noise_distribution,
        ciphertext_modulus,
        &mut encryption_generator,
    );

    // Create the empty bootstrapping key in the Fourier domain
    let mut fourier_bsk = FourierLweBootstrapKey::new(
        std_bootstrapping_key.input_lwe_dimension(),
        std_bootstrapping_key.glwe_size(),
        std_bootstrapping_key.polynomial_size(),
        std_bootstrapping_key.decomposition_base_log(),
        std_bootstrapping_key.decomposition_level_count(),
    );

    // Use the conversion function (a memory optimized version also exists but is more complicated
    // to use) to convert the standard bootstrapping key to the Fourier domain
    convert_standard_lwe_bootstrap_key_to_fourier(&std_bootstrapping_key, &mut fourier_bsk);
    // We don't need the standard bootstrapping key anymore
    drop(std_bootstrapping_key);

    // Our 4 bits message space
    let message_modulus = 1u64 << 4;

    // Our input message
    let input_message = 3u64;

    // Delta used to encode 4 bits of message + a bit of padding on u64
    let delta = (1_u64 << 63) / message_modulus;

    // Apply our encoding
    let plaintext = Plaintext(input_message * delta);

    // Allocate a new LweCiphertext and encrypt our plaintext
    let lwe_ciphertext_in: LweCiphertextOwned<u64> = allocate_and_encrypt_new_lwe_ciphertext(
        &small_lwe_sk,
        plaintext,
        lwe_noise_distribution,
        ciphertext_modulus,
        &mut encryption_generator,
    );

    // Compute a cleartext multiplication by 2
    let mut cleartext_multiplication_ct = lwe_ciphertext_in.clone();
    println!("Performing cleartext multiplication...");
    lwe_ciphertext_cleartext_mul(
        &mut cleartext_multiplication_ct,
        &lwe_ciphertext_in,
        Cleartext(2),
    );

    // Decrypt the cleartext multiplication result
    let cleartext_multiplication_plaintext: Plaintext<u64> =
        decrypt_lwe_ciphertext(&small_lwe_sk, &cleartext_multiplication_ct);

    // Create a SignedDecomposer to perform the rounding of the decrypted plaintext
    // We pass a DecompositionBaseLog of 5 and a DecompositionLevelCount of 1 indicating we want to
    // round the 5 MSB, 1 bit of padding plus our 4 bits of message
    let signed_decomposer =
        SignedDecomposer::new(DecompositionBaseLog(5), DecompositionLevelCount(1));

    // Round and remove our encoding
    let cleartext_multiplication_result: u64 =
        signed_decomposer.closest_representable(cleartext_multiplication_plaintext.0) / delta;

    println!("Checking result...");
    assert_eq!(6, cleartext_multiplication_result);
    println!(
        "Cleartext multiplication result is correct! \
        Expected 6, got {cleartext_multiplication_result}"
    );

    // Now we will use a PBS to compute the same multiplication, it is NOT the recommended way of
    // doing this operation in terms of performance as it's much more costly than a multiplication
    // with a cleartext, however it resets the noise in a ciphertext to a nominal level and allows
    // to evaluate arbitrary functions so depending on your use case it can be a better fit.

    // Generate the accumulator for our multiplication by 2 using a simple closure
    let accumulator: GlweCiphertextOwned<u64> = generate_programmable_bootstrap_glwe_lut(
        polynomial_size,
        glwe_dimension.to_glwe_size(),
        message_modulus as usize,
        ciphertext_modulus,
        delta,
        |x: u64| 2 * x,
    );

    // Allocate the LweCiphertext to store the result of the PBS
    let mut pbs_multiplication_ct = LweCiphertext::new(
        0u64,
        big_lwe_sk.lwe_dimension().to_lwe_size(),
        ciphertext_modulus,
    );
    println!("Computing PBS...");
    programmable_bootstrap_lwe_ciphertext(
        &lwe_ciphertext_in,
        &mut pbs_multiplication_ct,
        &accumulator,
        &fourier_bsk,
    );

    // Decrypt the PBS multiplication result
    let pbs_multiplication_plaintext: Plaintext<u64> =
        decrypt_lwe_ciphertext(&big_lwe_sk, &pbs_multiplication_ct);

    // Round and remove our encoding
    let pbs_multiplication_result: u64 =
        signed_decomposer.closest_representable(pbs_multiplication_plaintext.0) / delta;

    println!("Checking result...");
    assert_eq!(6, pbs_multiplication_result);
    println!(
        "Multiplication via PBS result is correct! Expected 6, got {pbs_multiplication_result}"
    );
}

use tfhe::shortint::prelude::*;


fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 3;
    let msg2 = 3;
    let scalar = 4;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the client key to encrypt two messages:
    let mut ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    server_key.unchecked_scalar_mul_assign(&mut ct_1, scalar);
    server_key.unchecked_sub_assign(&mut ct_1, &ct_2);
    server_key.unchecked_mul_lsb_assign(&mut ct_1, &ct_2);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_1);
    println!("expected {}, found {}", ((msg1 * scalar as u64 - msg2) * msg2) % modulus as u64, output);
}

use tfhe::shortint::prelude::*;
use std::error::Error;

fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 3;
    let msg2 = 3;
    let scalar = 4;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the client key to encrypt two messages:
    let mut ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    let mut ops = || -> Result<(), Box<dyn Error>> {
        server_key.checked_scalar_mul_assign(&mut ct_1, scalar)?;
        server_key.checked_sub_assign(&mut ct_1, &ct_2)?;
        server_key.checked_mul_lsb_assign(&mut ct_1, &ct_2)?;
        Ok(())
    };

    match ops() {
        Ok(_) => (),
        Err(e) => {
            println!("correctness of operations is not guaranteed due to error: {}", e);
            return;
        },
    }

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_1);
    assert_eq!(output, ((msg1 * scalar as u64 - msg2) * msg2) % modulus as u64);
}

use tfhe::shortint::prelude::*;


fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 3;
    let msg2 = 3;
    let scalar = 4;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the client key to encrypt two messages:
    let mut ct_1 = client_key.encrypt(msg1);
    let mut ct_2 = client_key.encrypt(msg2);

    server_key.smart_scalar_mul_assign(&mut ct_1, scalar);
    server_key.smart_sub_assign(&mut ct_1, &mut ct_2);
    server_key.smart_mul_lsb_assign(&mut ct_1, &mut ct_2);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_1);
    assert_eq!(output, ((msg1 * scalar as u64 - msg2) * msg2) % modulus as u64);
}

use tfhe::shortint::prelude::*;


fn main() {
    // We generate a set of client/server keys, using the default parameters:
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 3;
    let msg2 = 3;
    let scalar = 4;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the client key to encrypt two messages:
    let mut ct_1 = client_key.encrypt(msg1);
    let mut ct_2 = client_key.encrypt(msg2);

    server_key.scalar_mul_assign(&mut ct_1, scalar);
    server_key.sub_assign(&mut ct_1, &mut ct_2);
    server_key.mul_lsb_assign(&mut ct_1, &mut ct_2);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_1);
    assert_eq!(output, ((msg1 * scalar as u64 - msg2) * msg2) % modulus as u64);
}

use tfhe::shortint::prelude::*;

fn main() {
    // Generate the client key and the server key:
    let (cks, _) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);
    let pks = PublicKey::new(&cks);

    let msg = 2;
    // Encryption of one message:
    let ct = pks.encrypt(msg);
    // Decryption:
    let dec = cks.decrypt(&ct);
    assert_eq!(dec, msg);
}

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys to compute over Z/2^2Z, with 2 carry bits
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 2;
    let msg2 = 1;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the private client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    // We use the server public key to execute an integer circuit:
    let ct_3 = server_key.unchecked_add(&ct_1, &ct_2);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_3);
    assert_eq!(output, (msg1 + msg2) % modulus as u64);
}

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys to compute over Z/2^2Z, with 2 carry bits
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 2;
    let msg2 = 1;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the private client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    // We use the server public key to homomorphically compute a bitwise AND:
    let ct_3 = server_key.unchecked_bitand(&ct_1, &ct_2);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_3);
    assert_eq!(output, (msg1 & msg2) % modulus as u64);
}

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys to compute over Z/2^2Z, with 2 carry bits
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 2;
    let msg2 = 1;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the private client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    // We use the server public key to execute an integer circuit:
    let ct_3 = server_key.unchecked_greater_or_equal(&ct_1, &ct_2);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_3);
    assert_eq!(output, (msg1 >= msg2) as u64 % modulus as u64);
}

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys to compute over Z/2^2Z, with 2 carry bits
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 3;

    let modulus = client_key.parameters.message_modulus().0;

    // We use the private client key to encrypt a message:
    let ct_1 = client_key.encrypt(msg1);

    // Compute the lookup table for the univariate function:
    let acc = server_key.generate_lookup_table(|n| n.count_ones().into());

    // Apply the table lookup on the input message:
    let ct_res = server_key.apply_lookup_table(&ct_1, &acc);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_res);
    assert_eq!(output, msg1.count_ones() as u64);
}

use tfhe::shortint::prelude::*;

fn main() {
    // We generate a set of client/server keys to compute over Z/2^2Z, with 2 carry bits
    let (client_key, server_key) = gen_keys(PARAM_MESSAGE_2_CARRY_2_KS_PBS);

    let msg1 = 3;
    let msg2 = 2;

    let modulus = client_key.parameters.message_modulus().0 as u64;

    // We use the private client key to encrypt two messages:
    let ct_1 = client_key.encrypt(msg1);
    let ct_2 = client_key.encrypt(msg2);

    // Compute the lookup table for the bivariate functions
    let acc = server_key.generate_lookup_table_bivariate(|x,y| (x.count_ones()
        + y.count_ones()) as u64 % modulus );

    let ct_res = server_key.apply_lookup_table_bivariate(&ct_1, &ct_2, &acc);

    // We use the client key to decrypt the output of the circuit:
    let output = client_key.decrypt(&ct_res);
    assert_eq!(output, (msg1.count_ones() as u64 + msg2.count_ones() as u64) % modulus);
}

0.7

Get Started

Installation

Importing

Supported platforms

Types & Operations

Types

Integer

Operations

Arithmetic operations

Bitwise operations

Comparison operations

Min/Max operations

Ternary conditional operations

Casting operations

Boolean Operations

Benchmarks

Integer operations

Shortint operations

Boolean operations

tfhe-rs::boolean

tfhe-lib

OpenFHE (v1.1.2)

Reproducing TFHE-rs benchmarks

Security and cryptography

TFHE

LWE ciphertexts

Programmable Bootstrapping, noise management, and carry bits

Noise

Programmable BootStrapping (PBS)

Carry

Security

Classical public key encryption.

Fundamentals

Guides

Tutorials

References

Explanations

Developers

Installation

Importing

Supported platforms

Types & Operations

Types

Integer

Operations

Arithmetic operations

Bitwise operations

Comparison operations

Min/Max operations

Ternary conditional operations

Casting operations

Boolean Operations

Security and cryptography

TFHE

LWE ciphertexts

Programmable Bootstrapping, noise management, and carry bits

Noise

Programmable BootStrapping (PBS)

Carry

Security

Classical public key encryption.

Benchmarks

Integer operations

Shortint operations

Boolean operations

tfhe-rs::boolean

tfhe-lib

OpenFHE (v1.1.2)

Reproducing TFHE-rs benchmarks

Server key

Encryption

Quick start

Workflow explanation

Step1: Importing

Welcome to TFHE-rs

Get started

Build with TFHE-rs

Explore more

References & Explanations

Commented code of a uint128 subtraction using `TFHE-rs C API`.