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

Setting up a Rust project

If you already know how to set up a Rust project, feel free to go directly to the next section.

First, install the Rust programming language tools. Visit https://rustup.rs/ and follow the instructions. For alternative installation methods, refer to the official Rust installation page.

After installing Rust, you can call the build and package manager Cargo:

$ cargo --version
cargo 1.81.0 (2dbb1af80 2024-08-20)

Your version may differ depending on when you installed Rust. To update your installation, invoke rustup update.

Now you can invoke Cargo and create a new default Rust project:

$ cargo new tfhe-example
    Creating binary (application) `tfhe-example` package
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

This will create a tfhe-example directory and populate it with the following:

$ tree tfhe-example/
tfhe-example/
├── Cargo.toml
└── src
    └── main.rs

1 directory, 2 files

You now have a minimal Rust project.

In the next section, we'll explain how to add TFHE-rs as a dependency to the project and start using it to perform FHE computations.

Using TFHE-rs and its APIs

To use TFHE-rs, you need to add it as a dependency to tfhe-example.

The Cargo.toml file is located at the root of the project. Initially, the file is minimal and doesn't contain any dependencies:

[package]
name = "tfhe-example"
version = "0.1.0"
edition = "2021"

[dependencies]

For x86 Unix systems, add the following configuration to include TFHE-rs:

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

Your updated Cargo.toml file should look like this:

[package]
name = "tfhe-example"
version = "0.1.0"
edition = "2021"

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

If you are on a different platform please refer to the installation documentation for configuration options of other supported platforms.

Now that the project has TFHE-rs as a dependency here are the detailed steps to use its high-level API:

1. Import the TFHE-rs prelude with the following Rust code: use tfhe::prelude::*;

2. Client-side: configure and generate keys

3. Client-side: encrypt data

4. Server-side: set the server key

5. Server-side: compute over encrypted data

6. Client-side: decrypt data

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);
}

You can learn more about homomorphic types and associated compilation features in the configuration documentation.

This document summarizes the timings of some homomorphic operations over 64-bit encrypted integers, depending on the hardware. More details are given for the CPU, the GPU, or zeros-knowledge proofs.

You can get the parameters used for benchmarks by cloning the repository and checking out the commit you want to use (starting with the v0.8.3 release) and run the following make command:

make print_doc_bench_parameters

Operation time (ms) over FheUint 64

This document details the CPU 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.

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 ensures that the input and output encoding are similar (i.e., the carries are always emptied).

You can minimize operational costs by selecting from 'unchecked', 'checked', or 'smart' modes from the fine-grained APIs, each balancing performance and correctness differently. For more details about parameters, see here. You can find the benchmark results on GPU for all these operations here.

Programmable bootstrapping

The next table shows the execution time of a keyswitch followed by a programmable bootstrapping depending on the precision of the input message. The associated parameter set is given. The configuration is Concrete FFT + AVX-512.

Reproducing TFHE-rs benchmarks

TFHE-rs benchmarks can be easily reproduced from the source.

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

#Boolean benchmarks:
make bench_boolean

#Integer benchmarks:
make bench_integer

#Shortint benchmarks:
make bench_shortint

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.8.7", features = [ "boolean", "shortint", "integer", "x86_64-unix" ] }

For ARM machine running a Unix-like OS:

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

For x86_64 machines with the rdseed instruction running Windows:

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

Supported platforms

TFHE-rs currently supports the following platforms:

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.

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.

Refer to the the preliminary whitepaper for more details.

Using TFHE-rs in Rust includes the following steps:

1. 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.

2. Encryption: encrypt plaintexts using the client key to produce ciphertexts.

3. Homomorphic operation: perform operations on ciphertexts using the server key.

4. Decryption: decrypt the resulting ciphertexts back to plaintexts using the client key.

To understand more about FHE applications, see the 6-minute introduction to homomorphic encryption.

Get started

Learn the basics of TFHE-rs, set it up, and make it run with ease.

Build with TFHE-rs

Start building with TFHE-rs by exploring its core features, discovering essential guides, and learning more with user-friendly tutorials.

Explore more

Access to additional resources and join the Zama community.

References & Explanations

Take a deep dive into TFHE-rs, exploring APIs from the highest to the lowest level of abstraction and accessing additional resources for in-depth explanations.

• Rust API reference: High-level API that abstracts cryptographic complexities and simplifies the development and more

• Fine-grained APIs: Mid-level APIs that enable evaluation of Boolean, short integer, and integer circuits

• Core crypto API: Low-level API with the primitive functions and types of the TFHE scheme

• TFHE deep dive: Resources that explain the Fully Homomorphic Encryption scheme - TFHE

Support channels

Ask technical questions and discuss with the community. Our team of experts usually answers within 24 hours during working days.

• Community forum

• Discord channel

Developers

Collaborate with us to advance the FHE spaces and drive innovation together.

• Contribute to TFHE-rs

• Check the latest release note

• Request a feature

• Report a bug

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:

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).

Arithmetic operations

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

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:

Bitwise operations

Homomorphic integer types support the following bitwise operations:

The following example shows how to perform bitwise operations:

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:

The following example shows how to perform comparison operations:

Min/Max operations

Homomorphic integers support the min/max operations:

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

Ternary conditional operations

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

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:

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:

Boolean Operations

Native homomorphic Booleans support the following common Boolean operations:

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:

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

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:

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:

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:

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:

Programmable bootstrapping

The next table shows the execution time of a keyswitch followed by a programmable bootstrapping depending on the precision of the input message. The associated parameter set is given.

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

Benchmarks for the zero-knowledge 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.

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.

To create a configuration, use the ConfigBuilder type. The following example shows the setup using 8-bit unsigned integers with default parameters. Additionally, ensure the integers feature is enabled, as indicated in the table on .

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.

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.

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.

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);
}

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);
}

This document describes how to perform computation on encrypted data.

With TFHE-rs, the program can be as straightforward as conventional Rust coding by using operator overloading.

The following example illustrates the complete process of encryption, computation using Rust’s built-in operators, and decryption:

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);
}

This document explains the mechanism and steps to generate an oblivious encrypted random value using only server keys.

The goal is to give to the server the possibility to generate a random value, which will be obtained in an encrypted format and will remain unknown to the server. The implementation is based on this article.

This is possible through two methods on FheUint and FheInt:

• generate_oblivious_pseudo_random which return an integer taken uniformly in the full integer range ([0; 2^N[ for a FheUintN and [-2^(N-1); 2^(N-1)[ for a FheIntN).

• generate_oblivious_pseudo_random_bounded which return an integer taken uniformly in [0; 2^random_bits_count[. For a FheUintN, we must have random_bits_count <= N. For a FheIntN, we must have random_bits_count <= N - 1.

Both methods functions take a seed Seed as input, which could be any u128 value. They both rely on the use of the usual server key. The output is reproducible, i.e., the function is deterministic from the inputs: assuming the same hardware, seed and server key, this function outputs the same random encrypted value.

Here is an example of the usage:

use tfhe::prelude::FheDecrypt;
use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8, FheInt8, 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;

    let ct_res = FheUint8::generate_oblivious_pseudo_random(Seed(0));

    let dec_result: u8 = ct_res.decrypt(&client_key);

    let ct_res = FheUint8::generate_oblivious_pseudo_random_bounded(Seed(0), random_bits_count);

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

    let ct_res = FheInt8::generate_oblivious_pseudo_random(Seed(0));
    
    let dec_result: i8 = ct_res.decrypt(&client_key);
    
    let ct_res = FheInt8::generate_oblivious_pseudo_random_bounded(Seed(0), random_bits_count);

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

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

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. TFHE-rs provide easy to use functions for this purpose, such as safe_serialize, safe_deserialize and safe_deserialize_conformant.

Here is a basic example on how to use it:

// main.rs

use tfhe::safe_serialization::{safe_deserialize_conformant, safe_serialize};
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;
use tfhe::ServerKey;
use tfhe::{generate_keys, ConfigBuilder};

fn main() {
    let params_1 = PARAM_MESSAGE_2_CARRY_2_KS_PBS;

    let config = ConfigBuilder::with_custom_parameters(params_1).build();

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

    let mut buffer = vec![];

	// The last argument is the max allowed size for the serialized buffer
    safe_serialize(&server_key, &mut buffer, 1 << 30).unwrap();

    let _server_key_deser: ServerKey =
        safe_deserialize_conformant(buffer.as_slice(), 1 << 30, &config.into()).unwrap();
}

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: data serialized in previous versions of TFHE-rs are automatically upgraded to the latest version using the data versioning feature.

• 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 a more complete example:

// main.rs

use tfhe::conformance::ParameterSetConformant;
use tfhe::prelude::*;
use tfhe::safe_serialization::{safe_serialize, safe_deserialize_conformant};
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 params_1 = PARAM_MESSAGE_2_CARRY_2_KS_PBS;
    let params_2 = PARAM_MESSAGE_2_CARRY_2_PBS_KS;

    let config = ConfigBuilder::with_custom_parameters(params_1).build();

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

    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 << 20).unwrap();

    assert!(safe_deserialize_conformant::<FheUint8>(buffer.as_slice(), 1 << 20, &conformance_params_2)
        .is_err());

    let ct2: FheUint8 = safe_deserialize_conformant(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 << 20).unwrap();

    let conformance_params = CompactCiphertextListConformanceParams {
        shortint_params: params_1.to_shortint_conformance_param(),
        num_elements_constraint: ListSizeConstraint::exact_size(2),
    };
    safe_deserialize_conformant::<CompactCiphertextList>(buffer.as_slice(), 1 << 20, &conformance_params)
        .unwrap();
}

The safe serialization and deserialization use bincode internally.

To selectively disable some of the features of the safe serialization, you can use SerializationConfig/DeserializationConfig builders. For example, it is possible to disable the data versioning:

// main.rs

use tfhe::safe_serialization::{safe_deserialize_conformant, SerializationConfig};
use tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS;
use tfhe::ServerKey;
use tfhe::{generate_keys, ConfigBuilder};

fn main() {
    let params_1 = PARAM_MESSAGE_2_CARRY_2_KS_PBS;

    let config = ConfigBuilder::with_custom_parameters(params_1).build();

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

    let mut buffer = vec![];

    SerializationConfig::new(1 << 30).disable_versioning().serialize_into(&server_key, &mut buffer).unwrap();

    // You will still be able to load this item with `safe_deserialize_conformant`, but only using the current version of TFHE-rs
    let _server_key_deser: ServerKey =
        safe_deserialize_conformant(buffer.as_slice(), 1 << 30, &config.into()).unwrap();
}

Serialization/deserialization using serde

TFHE-rs uses the Serde framework and implements Serde's Serialize and Deserialize traits.

This allows you to serialize into any data format supported by serde. However, this is a more bare bone approach as none of the checks described in the previous section will be performed for you.

In the following example, we use bincode for its binary format:

# Cargo.toml

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

// main.rs

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)
}

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, 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_KS_PBS_TUNIFORM_2M64, PARAM_MESSAGE_2_CARRY_2_KS_PBS_TUNIFORM_2M64,
};
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_KS_PBS_TUNIFORM_2M64)
            .enable_compression(COMP_PARAM_MESSAGE_2_CARRY_2_KS_PBS_TUNIFORM_2M64)
            .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::{
    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));
}