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" ] }

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:

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:

1. Import the TFHE-rs 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);
}

The default configuration for x86 Unix machines is as follows:

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

Refer to the installation documentation for configuration options of different platforms.Learn more about homomorphic types features in the configuration documentation.

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::*;

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

We value your feedback! Take a 5-question developer survey to improve the TFHE-rs library and the documentation and help other developers use FHE.

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.

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.

$plaintext = (\Delta * m) + e$

$m \in \mathbb{Z}_p$

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.

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

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

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 (repository) with red_cost_model = reduction.RC.BDGL16.

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

[1] Li, Baiyu, et al. "Securing approximate homomorphic encryption using differential privacy." Annual International Cryptology Conference. Cham: Springer Nature Switzerland, 2022.

Classical public key encryption.

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.

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.

For more details about parameters, see here. You can find the benchmark results on GPU for all these operations here.

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:

export CXX=clang++
export CC=clang

scripts/configure.sh
Release -> y
hexl -> y

scripts/build-openfhe-development-hexl.sh

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

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 gives an example of generating pseudo random values in FHE that are not known by the server.

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:

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 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:

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 a feature to facilitate debugging.

Starting from TFHE-rs 0.5, trivial ciphertexts introduce a new feature to facilitate debugging. This feature supports a debugger, print statements, and faster execution, significantly reducing waiting time and enhancing the development pace of FHE applications.

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.

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.

This versioning scheme is compatible with all the data formats supported by serde.

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.

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: the first method involves the public key containing many encryptions of zero, as detailed in Guide to Fully Homomorphic Encryption over the [Discretized] Torus, Appendix A.

• Compact public key: the second method is based on the paper TFHE Public-Key Encryption Revisited, allowing for significantly smaller key sizes compared to the first method.

Public keys can also be compressed to reduce size.

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.

For more information on using compact public keys to encrypt data and generate a zero-knowledge proof of correct encryption at the same time, see the guide on ZK proofs.

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

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

Serialization/deserialization

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

To serialize the data, you need to choose a data format. In the following example, we use bincode for its binary format.

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

You can combine this serialization/deserialization feature with the data versioning feature by using the safe_serialize_versioned and safe_deserialize_conformant_versioned functions.

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:

AVX-512

While the library generally selects automatically the best instruction sets available by the host, in the case of 'AVX-512', you have to choose it explicitly. This requires to use a nightly toolchain with the feature nightly-avx512.

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

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

Arithmetic operations

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

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:

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:

• PartialOrd

• PartialEq

Supported operations:

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