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.

Refer to 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.

Tutorials

Explore step-by-step guides that walk you through real-world uses of TFHE-rs.

• : Learn how to implement a parity bit calculation over encrypted data

• : See how to process string data securely by changing cases while keeping the data encrypted.

• : Delve into a more complex example: implementing the SHA256 hash function entirely on encrypted boolean values.

• : A complete list of all available tutorials in one place.tutorials: A complete list of all available tutorials in one place.

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.

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

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

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

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

• : Document describing algorithms implemented in TFHE-rs

Support channels

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

Developers

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

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

Importing

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

Supported platforms

TFHE-rs currently supports the following platforms:

By default, TFHE-rs makes the assumption that hardware AES features are enabled on the target CPU. The required CPU features are:

• x86_64: sse2, aesni

• aarch64: aes, neon

To add support for older CPU, import TFHE-rs with the software-prng feature in your Cargo.toml:

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 details the performance benchmarks of zero-knowledge proofs for compact public key encryption using TFHE-rs.

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

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

By their nature, homomorphic operations run slower than their cleartext equivalents.

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

By their nature, homomorphic operations run slower than their cleartext equivalents.

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

The cryptographic parameters HPU_PARAM_MESSAGE_2_CARRY_2_KS32_PBS_TUNIFORM_2M64 were used.

1xHPU

Below are the results for the execution on a single Alveo v80 board. 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:

Reproducing TFHE-rs benchmarks

TFHE-rs benchmarks can be easily reproduced from the .

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

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

Please refer to the for detailed performance benchmark results.

integer does not come with its own set of parameters. Instead, it relies on parameters from shortint. Currently, parameter sets having the same space dedicated to the message and the carry (i.e. PARAM_MESSAGE_{X}_CARRY_{X} with X in [1,4]) are recommended. See for more details about cryptographic parameters, and to see how to properly instantiate integers depending on the chosen representation.

This document describes the main integer types of encrypted data in TFHE-rs and explains how to specify bit sizes for encryption.

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

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

This document details the casting operations supported by TFHE-rs.

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

This document details the min/max operations supported by TFHE-rs.

Homomorphic integers support the min/max operations:

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 a = FheUint8::try_encrypt(clear_a, &keys)?;
    let 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(())
}

This document details the dot product operations supported by TFHE-rs.

Currently, the dot product supports the following case:

• One operand is a slice of FheBool

• The other operand is a slice of clear values (e.g., u64)

• Both slices must be of the same length

The following example shows how to perform dot product:

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

fn main() {
    let (client_key, server_key) = generate_keys(ConfigBuilder::default());
    set_server_key(server_key);
  
    let a = [true, false, true]
     .into_iter()
     .map(|b| FheBool::encrypt(b, &client_key))
     .collect::<Vec<_>>();
   
    let b = [2u8, 3u8, 4u8];
   
    let result = FheUint8::dot_product(&a, &b);
    let decrypted: u8 = result.decrypt(&client_key);
    assert_eq!(decrypted, 6u8);
}

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 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 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, 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, CompactCiphertextList, CompactPublicKey, ConfigBuilder, FheUint8,
};


fn main() {
     let config = ConfigBuilder::default()
        .use_custom_parameters(
            tfhe::shortint::parameters::PARAM_MESSAGE_2_CARRY_2_KS_PBS_GAUSSIAN_2M128,
        )
        .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 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);

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

Start here

• Homomorphic parity bit

• Homomorphic case changing on Ascii string

• SHA 256 with Boolean API

Go further

Blog tutorials and articles

• Dark Market with TFHE-rs - July 7, 2023

• Regular Expression Engine with TFHE-rs - June 30, 2023

Video tutorials

• Implement GPU acceleration on homomorphic computation using TFHE-rs - May 2024

• Implement signed integers using TFHE-rs - Nov 8, 2023

• Quick start

• Boolean

• Shortint

• Integer

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

By their nature, homomorphic operations run slower than their cleartext equivalents.

• Integer operations

Please refer to the HPU benchmarks for detailed performance benchmark results.

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, the HPU or zeros-knowledge proofs.

The cryptographic parameters used for benchmarking follow a tweaked uniform (TUniform) noise distribution instead of a Gaussian. The main advantage of this distribution is to be bounded, whereas the usual Gaussian one is not. In some practical cases, this can simplify the use of homomorphic computation. See the noise section of the Security and cryptography documentation page for more information on the noise distributions.

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.0 release) and run the following make command:

make print_doc_bench_parameters

Operation time over FheUint 64

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

By their nature, homomorphic operations run slower than their cleartext equivalents.

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

Pfail: $2^{-64}$

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:

Pfail: $2^{-128}$

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 on GPU here and on HPU here.

Reproducing TFHE-rs benchmarks

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

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

#Integer benchmarks:
make bench_integer

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

The cryptographic parameters PARAM_GPU_MULTI_BIT_GROUP_4_MESSAGE_2_CARRY_2_KS_PBS were used.

Pfail: $2^{-128}$

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:

Reproducing TFHE-rs benchmarks

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

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

#Integer benchmarks:
make bench_integer_gpu

This document details the GPU performance benchmarks of programmable bootstrapping and keyswitch operations using TFHE-rs.

P-fail: $2^{-40}$

P-fail: $2^{-64}$

P-fail: $2^{-128}$

Reproducing TFHE-rs benchmarks

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

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

#PBS benchmarks:
make bench_pbs_gpu

#KS-PBS benchmarks:
make bench_ks_pbs_gpu

This document details the Booleans operations supported by TFHE-rs.

Native homomorphic Booleans support the following common Boolean operations:

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:

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!(overflowed.decrypt(&client_key));

This document details the CPU performance benchmarks of programmable bootstrapping and keyswitch operations using TFHE-rs.

The next tables show the execution time of a single programmable bootstrapping as well as keyswitch followed by a programmable bootstrapping depending on the precision of the input message. The associated parameters set are given. The configuration is tfhe-fft + AVX-512.

Note that these benchmarks use Gaussian parameters. MB-PBS stands for multi-bit programmable bootstrapping.

P-fail:

P-fail:

P-fail:

Reproducing TFHE-rs benchmarks

TFHE-rs benchmarks can be easily reproduced from the .

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

This document details the ternary operations supported by TFHE-rs.

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:

This document explains how the choice of cryptographic parameters impacts both the security and efficiency of FHE algorithms. The chosen parameters determine the error probability (sometimes referred to failure probability) and overall performance of computations using fully homomorphic encryption. This error probability is due to the noisy nature of FHE computations (see for more details about the encryption process).

All parameter sets provide at least 128-bits of security according to the .

Default parameters

Currently, the default parameters use blocks that contain 2 bits of message and 2 bits of carry - a tweaked uniform (TUniform, defined ) noise distribution, and have a bootstrapping failure probability . These are particularly suitable for applications that need to be secure in the IND-CPA^D model (see for more details). The GPU backend still uses an error probability smaller than by default. Those will be updated soon.

When using the high-level API of TFHE-rs, you can create a key pair using the default recommended set of parameters. For example:

Parameters versioning and naming scheme

Parameter sets are versioned for backward compatibility. This means that each set of parameters can be tied to a specific version of TFHE-rs, so that they remain unchanged and compatible after an upgrade.

All parameter sets are stored as variables inside the tfhe::shortint::parameters module, with submodules named after the versions of TFHE-rs in which these parameters where added. For example, parameters added in TFHE-rs v1.0 can be found inside tfhe::shortint::parameters::v1_0.

The naming convention of these parameters indicates their capabilities. Taking tfhe::parameters::v1_0::V1_0_PARAM_MESSAGE_2_CARRY_2_KS_PBS_TUNIFORM_2M128 as an example:

• V1_0: these parameters were introduced in TFHE-rs v1.0

• MESSAGE_2: LWE blocks include 2 bits of message

• CARRY_2: LWE blocks include 2 bits of carry

• KS_PBS: the keyswitch is computed before the bootstrap

• TUNIFORM: the tweaked uniform noise distribution is used

• 2M128: the probability of failure for the bootstrap is

For convenience, aliases are provided for the most used sets of parameters and stored in the module tfhe::shortint::parameters::aliases. Note, however, that these parameters are not stable over time and are always updated to the latest TFHE-rs version. For this reason, they should only be used for prototyping and are not suitable for production use cases.

How to choose the parameter sets

You can override the default parameters with the with_custom_parameters(block_parameters) method of the Config object. For example, to use a Gaussian distribution instead of the TUniform one, you can modify your configuration as follows:

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.

When combined with the , this feature allows for quick estimations during iterations on the FHE code.

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

This document explains a feature to facilitate debugging.

Starting from TFHE-rs 0.5, 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):

This example is going to print:

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

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.

This document explains how to compress ciphertexts using the GPU - even after homomorphic computations - just like on the .

Compressing ciphertexts after computation using GPU is very similar to how it's done on the CPU. The following example shows how to compress and decompress a list containing 4 messages:

• One 32-bits integer

• One 64-bit integer

• One Boolean

• One 2-bit integer

This document explains how to use array types on GPU, just as .

Here is an example:

This contains the operations available in tfhe::boolean, along with code examples.

The NOT unary gate

Binary gates

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:

This example shows how to use the MUX ternary gate:

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.

To be able to serialize our data, a needs to be picked. Here, is a good choice, mainly because it is binary format.

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]

Then add the following configuration to include TFHE-rs:

tfhe = { version = "~1.2.0", features = ["integer"] }

Your updated Cargo.toml file should look like this:

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

[dependencies]
tfhe = { version = "~1.2.0", features = ["integer"] }

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 explains the FheAsciiString type for handling encrypted strings in TFHE-rs.

TFHE-rs has supports for ASCII strings with the type FheAsciiString. You can enable this feature using the flag: --features=strings

Supported Operations

A variety of common operations are supported for FheAsciiString. These include:

• Comparisons: eq, ne, lt, le, gt, ge, eq_ignore_case

• Case conversion: to_lowercase / to_uppercase

• String checks: starts_with / ends_with / contains

• Trimming: trim_start / trim_end / trim

• Prefix/suffix operations: strip_prefix / strip_suffix

• Search: find / rfind

When encrypting strings, you can add padding to hide the actual length of strings. The null character (b'\0') is used as the padding. Here is an example:

# Cargo.toml

[dependencies]
tfhe = { version = "~1.2.0", features = ["integer", "strings"] }

use tfhe::{ConfigBuilder, generate_keys, set_server_key, FheAsciiString, FheStringLen, ClearString};
use tfhe::prelude::*;
use tfhe::safe_serialization::safe_serialize;


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

    set_server_key(sks);

    let r = FheAsciiString::try_encrypt("café is french for coffee", &cks);
    // As the input string is not strictly ASCII, it is not compatible
    assert!(r.is_err());

    let string = FheAsciiString::try_encrypt("tfhe-rs", &cks).unwrap();
    // This adds 3 chars of padding to the chars of the input string
    let padded_string = FheAsciiString::try_encrypt_with_padding("tfhe-rs", 3, &cks).unwrap();
    // This makes it so the string has 10 chars (adds padding or truncates input as necessary)
    let other_string = FheAsciiString::try_encrypt_with_fixed_sized("tfhe", 10, &cks).unwrap();

    let mut buffer1 = vec![];
    safe_serialize(&padded_string, &mut buffer1, 1 << 30).unwrap();
    let mut buffer2 = vec![];
    safe_serialize(&other_string, &mut buffer2, 1 << 30).unwrap();
    // The two strings created with padding, have the same
    // memory/disk footprint, even though the lengths are not the same
    assert_eq!(buffer1.len(), buffer2.len());

    // When a string has no padding, its length is known in clear
    let len = string.len();
    assert!(matches!(len, FheStringLen::NoPadding(7)));
    // When a string has padding, its length is only known as an encrypted value
    let FheStringLen::Padding(encrypted_len) = padded_string.len() else {
        panic!("Expected len to be encrypted");
    };
    let padded_string_len: u16 = encrypted_len.decrypt(&cks);
    assert_eq!(padded_string_len, 7); // Note padding chars are not counted
    // The enum resulting of a len() / is_empty() call can be transformed 
    // to a FheUint16 using `into_ciphertext`
    assert!(string.len().into_ciphertext().is_trivial());
    assert!(!padded_string.len().into_ciphertext().is_trivial());
    let other_string_len: u16 = other_string.len().into_ciphertext().decrypt(&cks);
    assert_eq!(other_string_len, 4);

    // Padded and un-padded strings are equal if the content is
    assert!(padded_string.eq(&string).decrypt(&cks));

    let prefix = ClearString::new("tfhe".to_string());
    let (stripped_string, has_been_stripped) = string.strip_prefix(&prefix);
    // Notice that stripping, makes the string as being considered as padded
    // as it is not possible to homomorphically remove chars
    let FheStringLen::Padding(encrypted_len) = stripped_string.len() else {
        panic!("Expected len to be encrypted");
    };
    let stripped_string_len: u16 = encrypted_len.decrypt(&cks);
    assert_eq!(stripped_string_len, 3);
    let decrypted = stripped_string.decrypt(&cks);
    assert_eq!(decrypted, "-rs");
    assert!(has_been_stripped.decrypt(&cks));
}

This document describes the array types provided by the High-level API.

This new encrypted types allow you to easily perform array and tensor operations on encrypted data, taking care of the iteration and shape logic for you.

It also implements efficient algorithms in some cases, like summing elements of an array.

The following example shows a complete workflow of working with encrypted arrays, including:

• Generating keys

• Encrypting arrays of integers

• Performing operations such as:

  • slicing arrays

  • computing on a sub array, adding encrypted data to it

  • computing on a sub array, adding clear data to it

• Decrypting the result, getting back a Rust Vec of decrypted values

# Cargo.toml

[dependencies]
tfhe = { version = "~1.2.0", features = ["integer"] }

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

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

    set_server_key(sks);

    let num_elems = 4 * 4;
    let clear_xs = (0..num_elems as u32).collect::<Vec<_>>();
    let clear_ys = vec![1u32; num_elems];

    // Encrypted 2D array with values
    // [[  0,  1,  2,  3]
    //  [  4,  5,  6,  7]
    //  [  8,  9, 10, 11]
    //  [ 12, 13, 14, 15]]
    let xs = CpuFheUint32Array::try_encrypt((clear_xs.as_slice(), vec![4, 4]), &cks).unwrap();
    // Encrypted 2D array with values
    // [[  1,  1,  1,  1]
    //  [  1,  1,  1,  1]
    //  [  1,  1,  1,  1]
    //  [  1,  1,  1,  1]]
    let ys = CpuFheUint32Array::try_encrypt((clear_ys.as_slice(), vec![4, 4]), &cks).unwrap();

    assert_eq!(xs.num_dim(), 2);
    assert_eq!(xs.shape(), &[4, 4]);
    assert_eq!(ys.num_dim(), 2);
    assert_eq!(ys.shape(), &[4, 4]);

    // Take a sub slice
    //  [[ 10, 11]
    //   [ 14, 15]]
    let xss = xs.slice(&[2..4, 2..4]);
    // Take a sub slice
    //  [[  1,  1]
    //   [  1,  1]]
    let yss = ys.slice(&[2..4, 2..4]);

    assert_eq!(xss.num_dim(), 2);
    assert_eq!(xss.shape(), &[2, 2]);
    assert_eq!(yss.num_dim(), 2);
    assert_eq!(yss.shape(), &[2, 2]);

    let r = &xss + &yss;

    // Result is
    //  [[ 11, 12]
    //   [ 15, 16]]
    let result: Vec<u32> = r.decrypt(&cks);
    assert_eq!(result, vec![11, 12, 15, 16]);

    // Clear 2D array with values
    //  [[  10,  20]
    //   [  30,  40]]
    let clear_array = ClearArray::new(vec![10u32, 20u32, 30u32, 40u32], vec![2, 2]);
    let r = &xss + &clear_array;

    // Result is
    //  [[ 20, 31]
    //   [ 44, 55]]
    let r: Vec<u32> = r.decrypt(&cks);
    assert_eq!(r, vec![20, 31, 44, 55]);
}

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

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 = "~1.2.0", features = ["integer"] }
tfhe-versionable = "0.5.0"
bincode = "1.3.3"

// main.rs

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.

Since the ServerKey and ClientKey types both implement the Serialize andDeserialize 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!(!loaded_client_key.decrypt(&ct_1));
}

This document details the arithmetic operations supported by TFHE-rs.

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 encryption 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 c = FheUint8::try_encrypt(clear_c, &keys)?;
    let mut d = FheInt8::try_encrypt(clear_d, &keys)?;


    a *= &b;     // Clear equivalent computations: 15 * 27 mod 256 = 149
    b = &b + &c;    // Clear equivalent computations: 27 + 43 mod 256 = 70
    b -= 76u8;   // Clear equivalent computations: 70 - 76 mod 256 = 250
    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(())
}

This document details the bitwise operations supported by TFHE-rs.

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 ^= &b;
    b ^= &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(())
}

This document details the comparison operations supported by TFHE-rs.

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 a = FheInt8::try_encrypt(clear_a, &keys)?;
    let 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(())
}

Default parameters

The TFHE cryptographic scheme relies on a variant of Regev cryptosystem and is based on a problem so difficult that it is even post-quantum resistant.

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.

In the two proposed sets of parameters, the only difference lies in this error probability. The default parameter set ensures an error probability of at most $2^{-64}$ when computing a programmable bootstrapping (i.e., any gates but the not). The other one is closer to the error probability claimed in the original TFHE paper, namely $2^{-165}$, but it is up-to-date regarding security requirements.

The following array summarizes this:

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

TFHE is a fully homomorphic encryption scheme that enables fast homomorphic operations on booleans, integers and reals.

By enabling both leveled and bootstrapped operations, TFHE can be used for a wide range of usecases, from homomorphic boolean circuits to homomorphic neural networks.

Here are a series of articles that guide you to go deeper into the understanding of the scheme:

• TFHE Deep Dive - Part I - Ciphertext types

• TFHE Deep Dive - Part II - Encodings and linear leveled operations

• TFHE Deep Dive - Part III - Key switching and leveled multiplications

• TFHE Deep Dive - Part IV - Programmable Bootstrapping

The article Guide to Fully Homomorphic Encryption over the Discretized Torus gives more mathematical details about the TFHE scheme.

You can also watch the video record of the original talk by Ilaria Chillotti for FHE.org:

This document serves as a practical reference for implementing generic functions in Rust that use operators across mixed references and values. The following explanations help you to understand the trait necessary to handle such operations.

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:

Example

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

• >= 8.0 - check this for more details about nvcc/gcc compatible versions

• >= 3.24

• libclang, to match Rust bingen >= 9.0

• Rust version - check this

Importing to your project

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

Supported platforms

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

A first example

Configuring and creating keys.

Comparing to the , GPU set up differs in the key creation, as detailed

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

Beware that when the GPU feature is activated, when calling: let config = ConfigBuilder::default().build();, the cryptographic parameters differ from the CPU ones, used when the GPU feature is not activated. Indeed, TFHE-rs uses dedicated parameters for the GPU in order to achieve better performance.

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:

Computation

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

Then, homomorphic computations are performed using the same approach as the .

Decryption

Finally, the client decrypts the results using:

All parameter sets provide at least 128-bits of security according to the , with an error probability equal to when using programmable bootstrapping. This error probability is due to the randomness added at each encryption (see for more details about the encryption process).

Parameters and message precision

shortint comes with sets of parameters that permit the use of the library functionalities securely and efficiently. Each parameter set is associated to the message and carry precisions. Therefore, each key pair is entangled to precision.

The user is allowed to choose which set of parameters to use when creating the pair of keys.

The difference between the parameter sets is the total amount of space dedicated to the plaintext, how it is split between the message buffer and the carry buffer, and the order in which the keyswitch (KS) and bootstrap (PBS) are computed. The syntax chosen for the name of a parameter is: PARAM_MESSAGE_{number of message bits}_CARRY_{number of carry bits}_{KS_PBS | PBS_KS}. For example, the set of parameters for a message buffer of 5 bits, a carry buffer of 2 bits and where the keyswitch is computed before the bootstrap is PARAM_MESSAGE_5_CARRY_2_KS_PBS.

Note that the KS_PBS order should have better performance at the expense of ciphertext size, PBS_KS is the opposite.

This example contains keys that are generated to have messages encoded over 2 bits (i.e., computations are done modulus ) with 2 bits of carry.

The PARAM_MESSAGE_2_CARRY_2_KS_PBS parameter set is the default shortint parameter set that you can also use through the tfhe::shortint::prelude::DEFAULT_PARAMETERS constant.

Impact of parameters on the operations

As shown , the choice of the parameter set impacts the operations available and their efficiency.

Generic bi-variate functions.

The computations of bi-variate functions is based on a trick: concatenating two ciphertexts into one. Where the carry buffer is not at least as large as the message buffer, this trick no longer works. In this case, many bi-variate operations, such as comparisons, cannot be correctly computed. The only exception concerns multiplication.

Multiplication.

In the case of multiplication, two algorithms are implemented: the first one relies on the bi-variate function trick, where the other one is based on the . To correctly compute a multiplication, the only requirement is to have at least one bit of carry (i.e., using parameter sets PARAM_MESSAGE_X_CARRY_Y with Y>=1). This method is slower than using the other one. Using the smart version of the multiplication automatically chooses which algorithm is used depending on the chosen parameters.

User-defined parameter sets

It is possible to define new parameter sets. To do so, it is sufficient to use the function new() or to manually fill the ClassicPBSParameters structure fields.

For instance:

This document describes the implementation and benefits of parallelized (PBS) in TFHE-rs, including code examples for using multi-bit PBS parameters and ensuring deterministic execution.

Parallelized Programmable Bootstrapping

Programmable Bootstrapping is inherently a sequential operation. However, some showed that introducing parallelism is feasible at the expense of larger keys, thereby enhancing the performance of PBS. This new PBS is called a multi-bit PBS.

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:

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:

The core_crypto module from TFHE-rs is dedicated to the implementation of the cryptographic tools related to TFHE. To construct an FHE application, the and/or modules (based on core_crypto) are recommended.

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 element of LWE mask.

For instance, the code to encrypt and then decrypt a message looks like:

This tutorial demonstrates how to build your own 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. In this tutorial, we use the FheUint8 to store an encrypted ASCII:

• 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]
tfhe = { version = "~1.2.0", features = ["integer"] }

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

#![allow(dead_code)]

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:

#![allow(dead_code)]

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:

#![allow(dead_code)]

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

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

const UP_LOW_DISTANCE: u8 = 32;

struct MyFheString {
    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 MyFheString {
    fn encrypt(string: &str, client_key: &ClientKey) -> Self {
        assert!(
            string.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 = MyFheString::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?");
}

Using TFHE-rs strings feature

This code can be greatly simplified by using the strings feature from TFHE-rs.

First, add the feature in your Cargo.toml

# Cargo.toml

[dependencies]
tfhe = { version = "~1.2.0", features = ["strings"] }

The FheAsciiString type allows to simply do homomorphic case changing of encrypted strings (and much more!):

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

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

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

    set_server_key(server_key);

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

    let my_string_upper = my_string.to_uppercase();
    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_lowercase();
    let verif_string = my_string_lower.decrypt(&client_key);
    println!("Lower string: {verif_string}");
    assert_eq!(verif_string, "hello zama, how is it going?");
}

You can read more about this in the FHE strings documentation

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

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

tfhe::shortint is dedicated to the manipulation of small unsigned integers that fit in a single LWE ciphertext. The actual size depends on the chosen parameters, but is always smaller than 8 bits. For example, with the PARAM_MESSAGE_2_CARRY_2_KS_PBS parameters, you can encode messages of 2 bits inside a shortint.

The integer and high-level API leverage shortints to allow homomorphic computations over larger integers.

The steps to homomorphically evaluate a shortint 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 (small integer values). 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);
}

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.

TFHE-rs can generate zero-knowledge proofs to verify that the compact public key encryption process is correct. In other words, TFHE-rs generates the proof without revealing any information other than the already known range of the encrypted message. This technique is derived from .

To use this feature, you must first generate a CRS (Common Reference String). The CRS is a piece of cryptographic data that is necessary to ensure the security of zero-knowledge proofs. The CRS should be generated in advance and shared between all the clients and the server. A CRS can be reused for multiple encryptions with the same parameters.

Once the CRS is generated, using zero-knowledge proofs is straightforward: during encryption, the client generates the proof, and the server validates it before performing any homomorphic computations.

Note that you need to use dedicated parameters for the compact public key encryption. This helps to reduce the size of encrypted data and speed up the zero-knowledge proof computation.

The following example shows how a client can encrypt and prove a ciphertext, and how a server can verify and compute the ciphertext:

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

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.

Scheme version

The ZK scheme used to generate and verify proofs is available in two versions:

• ZKV1: This version is close to the original paper from .

• ZKV2: Differing from the paper, this version provides better performance for provers and verifiers.

TFHE-rs selects automatically the scheme to use based on the encryption parameters during the CRS generation. With default parameters, ZKV2 is selected.

The following example shows how to generate a CRS and proofs for ZKV1. Compared to the previous example, only the parameters are changed:

Benchmark

Please refer to the for detailed performance benchmark results.

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

is a popular Rust crate that simplifies writing multi-threaded code. You can use Rayon to write multi-threaded TFHE-rs code. However, due to the specifications of Rayon and TFHE-rs, certain setups are necessary.

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:

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:

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:

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

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:

1. Choose a data type (Boolean, shortint, integer)

2. Import the library

3. Create client and server keys

4. Encrypt data with the client key

5. Compute over encrypted data using the server key

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

Boolean example

Here is an example of how the library can be used to evaluate a Boolean circuit:

shortint example

Here is a full example using shortint:

integer example

The library is simple to use and can evaluate homomorphic circuits of arbitrary length. The description of the algorithms can be found in the paper (also available as ).

This document describes the C bindings to the TFHE-rs high-level primitives for creating Fully Homomorphic Encryption (FHE) programs.

Setting up TFHE-rs C API for C programming.

You can build TFHE-rs C API using the following command:

Locate files in the right path:

• In ${REPO\_ROOT}/target/release/, you can find:

  • The tfhe.h header

  • The static (.a) and dynamic (.so) libtfhe binaries

• In ${REPO\_ROOT}/target/release/deps/, you can find:

  • The tfhe-c-api-dynamic-buffer.h header

  • The static (.a) and dynamic (.so) libraries