Importing into your project

To use TFHE-rs in your project, you first need to add it as a dependency in your Cargo.toml.

If you are using an x86 machine:

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

If you are using an ARM machine:

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

Supported platforms

TFHE-rs is supported on Linux (x86, aarch64), macOS (x86, aarch64) and Windows (x86 with RDSEED instruction).

Quick Start

The basic steps for using the high-level API of TFHE-rs are:

1. Importing the TFHE-rs prelude;

2. Client-side: Configuring and creating keys;

3. Client-side: Encrypting data;

4. Server-side: Setting the server key;

5. Server-side: Computing over encrypted data;

6. Client-side: Decrypting data.

Here is a full example (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:

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

Configuration options for different platforms can be found here. Other rust and homomorphic types features can be found here.

Imports.

tfhe uses traits to have a consistent API for creating FHE types and enable users to write generic functions. To be able to use associated functions and methods of a trait, the trait has to be in scope.

To make it easier, the prelude 'pattern' is used. All of the important tfhe traits are in a prelude module that you can glob import. With this, there is no need to remember or know the traits that you want to import.

use tfhe::prelude::*;

1. Configuring and creating keys.

The first step is the creation of the configuration. The configuration is used to declare which type you will (or will not) use, as well as enabling you to use custom crypto-parameters for these types. Custom parameters should only be used for more advanced usage and/or testing.

A configuration can be created by using the ConfigBuilder type.

In this example, 8-bit unsigned integers with default parameters are used. The integers feature must also be enabled, as per the table on this page.

The config is generated by first creating a builder with all types deactivated. Then, the integer types with default parameters are activated, since we are going to use FheUint8 values.

use tfhe::{ConfigBuilder, generate_keys};

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


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

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

The client_key is meant to stay private and not leave the client, whereas the server_key can be made public and sent to a server for it to enable FHE computations.

2. Setting the server key.

The next step is to call set_server_key

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

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

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

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

    set_server_key(server_key);
}

3. Encrypting data.

Encrypting data is achieved via the encrypt associated function of the FheEncrypt trait.

Types exposed by this crate implement at least one of FheEncrypt or FheTryEncrypt to allow encryption.

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

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

4. Computation and decryption.

Computations should be as easy as normal Rust to write, thanks to the usage of operator overloading.

let result = a + b;

The decryption is achieved by using the decrypt method, which comes from the FheDecrypt trait.

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

let clear_result = clear_a + clear_b;

assert_eq!(decrypted_result, clear_result);

The goal of this tutorial is to build a data type that represents a ASCII string in FHE while implementing the to_lower and to_upper functions.

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

• The uppercase letters are in the range [65, 90]

• The lowercase letters are in the range [97, 122]

lower_case = upper_case + UP_LOW_DISTANCE <=> upper_case = lower_case - UP_LOW_DISTANCE

Where UP_LOW_DISTANCE = 32

Types and methods.

This type will hold the encrypted characters as a Vec<FheUint8> to implement the functions that change the case.

To use the FheUint8 type, the integer feature must be activated:

# Cargo.toml

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

Other configurations can be found here.

In the FheAsciiString::encrypt function, some data validation is done:

• The input string can only contain ascii characters.

It is not possible to branch on an encrypted value, however it is possible to evaluate a boolean condition and use it to get the desired result. Checking if the 'char' is an uppercase letter to modify it to a lowercase can be done without using a branch, like this:

pub const UP_LOW_DISTANCE: u8 = 32;

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

We can remove the branch this way:

pub const UP_LOW_DISTANCE: u8 = 32;

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

On an homomorphic integer, this gives

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

pub const UP_LOW_DISTANCE: u8 = 32;

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

The whole code is:

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

pub const UP_LOW_DISTANCE: u8 = 32;

struct FheAsciiString {
    bytes: Vec<FheUint8>,
}

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

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

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

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

        Self { bytes: fhe_bytes }
    }

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

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

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

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

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

    set_server_key(server_key);

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

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

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

Due to their nature, homomorphic operations are naturally slower than their cleartext equivalents. Some timings are exposed for basic operations. For completeness, benchmarks for other libraries are also given.

Integer

This measures the execution time for some operation sets of tfhe-rs::integer (the unsigned version). Note that the timings for FheInt (i.e., the signed integers) are similar.

The table below reports the timing when the inputs of the benchmarked operation are encrypted.

The table below reports the timing when the left input of the benchmarked operation is encrypted and the other is a clear scalar of the same size.

All timings are related to parallelized Radix-based integer operations, where each block is encrypted using the default parameters (i.e., PARAM_MESSAGE_2_CARRY_2_KS_PBS, more information about parameters can be found here). To ensure predictable timings, the operation flavor is the default one: the carry is propagated if needed. The operation costs may be reduced by using unchecked, checked, or smart.

Shortint

This measures the execution time for some operations using various parameter sets of tfhe-rs::shortint. Except for unchecked_add, all timings are related to the default operations. This flavor ensures predictable timings for an operation along the entire circuit by clearing the carry space after each operation.

This uses the Concrete FFT + AVX-512 configuration.

Boolean

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

OpenFHE (v1.1.2).

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

To use the HEXL library, the configuration used is as follows:

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:

How to reproduce TFHE-rs benchmarks

TFHE-rs benchmarks can be easily reproduced from source.

#Boolean benchmarks:
make AVX512_SUPPORT=ON bench_boolean

#Integer benchmarks:
make AVX512_SUPPORT=ON bench_integer

#Shortint benchmarks:
make AVX512_SUPPORT=ON bench_shortint

If the host machine does not support AVX512, then turning on AVX512_SUPPORT will not provide any speed-up.

In what follows, the process to manage data when upgrading the TFHE-rs version (starting from the 0.5.5 release) is given. This page details the methods to make data, which have initially been generated with an older version of TFHE-rs, usable with a newer version.

Forward Compatibility Strategy

The current strategy that has been adopted for TFHE-rs is the following:

• TFHE-rs has a global SERIALIZATION_VERSION constant;

• When breaking serialization changes are introduced, this global version is bumped;

• Safe serialization primitives check this constant upon deserialization, if the data is incompatible, these primitives return an error.

To be able to use older serialized data with newer versions, the following is done on new major TFHE-rs releases:

• A minor update is done to the previously released branch to add the new release as an optional dependency;

• Conversion code is added to the previous branch to be able to load old data and convert it to the new data format.

In practice, if we take the 0.6 release as a concrete example, here is what will happen:

• 0.6.0 is released with breaking changes to the serialization;

• 0.5.5 has tfhe@0.6.0 as optional dependency gated by the forward_compatibility feature;

• Conversion code is added to 0.5.5, if possible without any user input, but some data migration will likely require some information to be provided by the developer writing the migration code;

• 0.5.5 is released.

What it means from a developer perspective

A set of generic tooling is given to allow migrating data by using several workflows. The data migration is considered to be an application/protocol layer concern to avoid imposing design choices.

Examples to migrate data:

An Application uses TFHE-rs 0.5.3 and needs/wants to upgrade to 0.6.0 to benefit from various improvements.

Example timeline of the data migration or Bulk Data Migration:

• A new transition version of the Application is compiled with the 0.5.5 release of TFHE-rs;

• The transition version of the Application adds code to read previously stored data, convert it to the proper format for 0.6.0 and save it back to disk;

• The service enters a maintenance period (if relevant);

• Migration of data from 0.5.5 to 0.6.0 is done with the transition version of the Application, note that depending on the volume of data this transition can take a significant amount of time;

• The updated version of the Application is compiled with the 0.6.0 release of TFHE-rs and put in production;

• Service is resumed with the updated Application (if relevant).

The above case is describing a simple use case, where only a single version of data has to be managed. Moreover, the above strategy is not relevant in the case where the data is so large that migrating it in one go is not doable, or if the service cannot suffer any interruption.

In order to manage more complicated cases, another method called Migrate On Read can be used.

Here is an example timeline where data is migrated only as needed with the Migrate On Read approach:

• A new version of the Application is compiled, it has tfhe@0.5.5 as dependency (the dependency will have to be renamed to avoid conflicts, a possible name is to use the major version like tfhe_0_5) and tfhe@0.6.0 which will not be renamed and can be accessed as tfhe

• Code to manage reading the data is added to the Application:

• The code determines whether the data was saved with the 0.5 Application or the 0.6 Application, if the data is already up to date with the 0.6 format it can be loaded right away, if it's in the 0.5 format the Application can check if an updated version of the data is already available in the 0.6 format and loads that if it's available, otherwise it converts the data to 0.6, saves the converted data to avoid having to convert it every time it is accessed and continue processing with the 0.6 data

The above is more complicated to manage as data will be present on disk with several versions, however it allows to run the service continuously or near-continuously once the new Application is deployed (it will require careful routing or error handling as nodes with outdated Application won't be able to process the 0.6 data).

Also, if required, several version of TFHE-rs can be "chained" to upgrade very old data to newer formats. The above pattern can be extended to have tfhe_0_5 (tfhe@0.5.5 renamed), tfhe_0_6 (tfhe@0.6.0 renamed) and tfhe being tfhe@0.7.0, this will require special handling from the developers so that their protocol can handle data from 0.5.5, 0.6.0 and 0.7.0 using all the conversion tooling from the relevant version.

E.g., if some computation requires data from version 0.5.5 a conversion function could be called upgrade_data_from_0_5_to_0_7 and do:

• read data from 0.5.5

• convert to 0.6.0 format using tfhe_0_6

• convert to 0.7.0 format using tfhe_0_7

• save to disk in 0.7.0 format

• process 0.7.0 data with tfhe which is tfhe@0.7.0

TFHE-rs includes a list of specific operations to detect overflows. The overall idea is to have a specific ciphertext encrypting a flag reflecting the status of the computations. When an overflow occurs, this flag is set to true. Since the server is not able to evaluate this value (since it is encrypted), the client has to check the flag value when decrypting to determine if an overflow has happened. These operations might be slower than their equivalent which do not detect overflow, so they are not enabled by default (see the table below). In order to use them, specific operators must be called. At the moment, only additions, subtractions, multiplications are supported. Missing operations will be added soon.

The list of operations along with their symbol is:

These operations are then used exactly in the same way than the usual ones. The only difference lies into the decryption, as shown in following example:

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

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

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

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

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

The current benchmarks are given in the following tables (the first one for unsigned homomorphic integers and the second one for the signed integers):

📁 Github | 💛 Community support | 🟨 Zama Bounty Program

TFHE-rs is a pure Rust implementation of TFHE for Boolean and integer arithmetics over encrypted data. It includes a Rust and C API, as well as a client-side WASM API.

TFHE-rs is meant for developers and researchers who want full control over what they can do with TFHE, while not worrying about the low level implementation.

The goal is to have a stable, simple, high-performance, and production-ready library for all the advanced features of TFHE.

Key cryptographic concepts

The TFHE-rs library implements Zama’s variant of Fully Homomorphic Encryption over the Torus (TFHE). TFHE is based on Learning With Errors (LWE), a well-studied cryptographic primitive believed to be secure even against quantum computers.

In cryptography, a raw value is called a message (also sometimes called a cleartext), while an encoded message is called a plaintext and an encrypted plaintext is called a ciphertext.

Zama's variant of TFHE is fully homomorphic and deals with fixed-precision numbers as messages. It implements all needed homomorphic operations, such as addition and function evaluation via Programmable Bootstrapping. You can read more about Zama's TFHE variant in the preliminary whitepaper.

Using FHE in a Rust program with TFHE-rs consists in:

• generating a client key and a server key using secure parameters:

  • a client key encrypts/decrypts data and must be kept secret

  • a server key is used to perform operations on encrypted data and could be public (also called an evaluation key)

• encrypting plaintexts using the client key to produce ciphertexts

• operating homomorphically on ciphertexts with the server key

• decrypting the resulting ciphertexts into plaintexts using the client key

If you would like to know more about the problems that FHE solves, we suggest you review our 6 minute introduction to homomorphic encryption.

Serialization/Deserialization

As explained in the Introduction, most types are meant to be shared with the server that performs the computations.

The easiest way to send these data to a server is to use the serialization and deserialization features. tfhe uses the framework. Serde's Serialize and Deserialize functions are implemented on TFHE's types.

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

Safe Serialization/Deserialization

For some types, safe serialization and deserialization functions are available. Bincode is used internally.

Safe-deserialization must take as input the output of a safe-serialization. On this condition, validation of the following is done:

• type: trying to deserialize type A from a serialized type B raises an error along the lines of On deserialization, expected type A, got type B instead of a generic deserialization error (or less likely a meaningless result of type A)

• version: trying to deserialize type A (version 0.2) from a serialized type A (incompatible version 0.1) raises an error along the lines of On deserialization, expected serialization version 0.2, got version 0.1 instead of a generic deserialization error (or less likely a meaningless result of type A (version 0.2))

• parameter compatibility: trying to deserialize into an object of type A with some crypto parameters from a an object of type A with other crypto parameters raises an error along the lines of Deserialized object of type A not conformant with given parameter set. If both parameters sets 1 and 2 have the same lwe dimension for ciphertexts, a ciphertext from param 1 may not fail this deserialization check with param 2 even if doing this deserialization may not make sense. Also, this check can't distinguish ciphertexts/server keys from independant client keys with the same parameters (which makes no sense combining to do homomorphic operations). 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.

Moreover, a size limit (in number of bytes) for the serialized data is expected on both serialization and deserialization. On serialization, an error is raised if the serialized output would be bigger than the given limit. On deserialization, an error is raised if the serialized input is bigger than the given limit. It is meant to gracefully return an error in case of an attacker trying to cause an out of memory error on deserialization.

A standalone is_conformant method is also available on those types to do a parameter compatibility check.

Parameter compatibility check is done by safe_deserialize_conformant function but a safe_deserialize function without this check is also available.

TFHE

TFHE-rs is a cryptographic library dedicated to Fully Homomorphic Encryption. As its name suggests, it is based on the TFHE scheme.

It is necessary to understand some basics about TFHE in order to consider the limitations. Of particular importance are the precision (number of bits used to represent plaintext values) and execution time (why TFHE operations are slower than native operations).

LWE ciphertexts

Although there are many kinds of ciphertexts in TFHE, all of the encrypted values in TFHE-rs are mainly stored as LWE ciphertexts.

The security of TFHE relies on the LWE problem, which stands for Learning With Errors. The problem is believed to be secure against quantum attacks.

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

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

To go from a plaintext to a ciphertext, one must encrypt the plaintext using a secret key.

An LWE ciphertext is composed of two parts:

The mask of a fresh ciphertext (one that is the result of an encryption, and not of an operation 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, there are two types of operations that can be applied to ciphertexts:

• leveled operations, which increase the noise in the ciphertext

• bootstrapped operations, which reduce the noise in the ciphertext

In FHE, noise must be tracked and managed to guarantee the correctness of the computation.

Bootstrapping operations are used across the computation to decrease noise within the ciphertexts, preventing it from tampering with the message. The rest of the operations are called leveled because they do not need bootstrapping operations and are usually very fast as a result.

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

Noise.

For it to be secure, LWE requires random noise to be added to the message at encryption time.

In TFHE, this random noise is drawn from a Centered Normal Distribution, parameterized by a standard deviation. The chosen standard deviation has an impact on the security level. With everything else fixed, increasing the standard deviation will lead to an increase in the security level.

In TFHE-rs, noise is encoded 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 figure below illustrates this problem in the case of an addition, where an extra bit of noise is incurred as a result.

TFHE-rs offers the ability to automatically manage noise by performing bootstrapping operations to reset the noise.

Programmable BootStrapping (PBS)

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.

As an example, consider adding two ciphertexts. Adding two values could end up outside the range of either ciphertext, and thus necessitate a carry, which would then be carried onto the first padding bit. In the figure below, each plaintext over 32 bits has one bit of padding on its left (i.e., the most significant bit). After the addition, the padding bit is no longer available, as it has been used in order for the carry. This is referred to as consuming bits of padding. Since no padding is left, there is no guarantee that further additions would yield correct results.

Security.

Classical public key encryption.

TFHE-rs includes features to reduce the size of both keys and ciphertexts, by compressing them. Most TFHE-rs entities contain random numbers generated by a Pseudo Random Number Generator (PRNG). A PRNG is deterministic, therefore storing only the random seed used to generate those numbers is enough to keep all the required information: using the same PRNG and the same seed, the full chain of random values can be reconstructed when decompressing the entity.

In the library, entities that can be compressed are prefixed by Compressed. For instance, the type of a compressed FheUint256 is CompressedFheUint256.

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

Compressed ciphertexts

This example shows how to compress a ciphertext encypting messages over 16 bits.

Compressed server keys

This example shows how to compress the server keys.

Compressed public keys

This example shows how to compress the classical public keys.

Compressed compact public key

This example shows how to use compressed compact public keys.

This example is dedicated to the building of a small function that homomorphically computes a parity bit.

First, a non-generic function is written. Then, generics are used to handle the case where the function inputs are both FheBools and clear bools.

The parity bit function takes as input two parameters:

• A slice of Boolean

• A mode (Odd or Even)

This function returns a Boolean that will be either true or false so that the sum of Booleans (in the input and the returned one) is either an Odd or Even number, depending on the requested mode.

Non-generic version.

Other configurations can be found .

function definition

First, the verification function is defined.

The way to find the parity bit is to initialize it to false, then XOR it with all the bits, one after the other, adding negation depending on the requested mode.

A validation function is also defined to sum together the number of the bit set within the input with the computed parity bit and check that the sum is an even or odd number, depending on the mode.

final code

After the mandatory configuration steps, the function is called:

Generic version.

To make the compute_parity_bit function compatible with both FheBool and bool, generics have to be used.

Writing a generic function that accepts FHE types as well as clear types can help test the function to see if it is correct. If the function is generic, it can run with clear data, allowing the use of print-debugging or a debugger to spot errors.

Writing generic functions that use operator overloading for our FHE types can be trickier than normal, since FHE types are not copy. So using the reference & is mandatory, even though this is not the case when using native types, which are all Copy.

This will make the generic bounds trickier at first.

writing the correct trait bounds

The function has the following signature:

To make it generic, the first step is:

Next, the generic bounds have to be defined with the where clause.

In the function, the following operators are used:

• ! (trait: Not)

• ^ (trait: BitXor)

By adding them to where, this gives:

However, the compiler will complain:

fhe_bit is a reference to a BoolType (&BoolType) since it is borrowed from the fhe_bits slice when iterating over its elements. The first try is to change the BitXor bounds to what the Compiler suggests by requiring &BoolType to implement BitXor and not BoolType.

The Compiler is still not happy:

The way to fix this is to use Higher-Rank Trait Bounds:

The final code will look like this:

final code

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

Using the right toolchain for TFHE-rs.

TFHE-rs only requires a nightly toolchain for building the C API and using advanced SIMD instructions, otherwise you can use a stable toolchain (with version >= 1.72) Install the needed Rust toolchain:

Then, you can either:

• Manually specify the toolchain to use in each of the cargo commands:

• Or override the toolchain to use for the current project:

To check the toolchain that Cargo will use by default, you can use the following command:

Choosing your features

TFHE-rs exposes different cargo features to customize the types and features used.

Homomorphic Types.

This crate exposes two kinds of data types. Each kind is enabled by activating its corresponding feature in the TOML line. Each kind may have multiple types:

AVX-512

TFHE-rs now includes a GPU backend, featuring a CUDA implementation for performing integer arithmetics on encrypted data. In what follows, a simple tutorial is introduced: it shows how to update your existing program to use GPU acceleration, or how to start a new one using GPU.

Prerequisites

• Cuda version >= 10

• Compute Capability >= 3.0

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

• >= 3.24

• Rust version - check this

Importing to your project

To use the TFHE-rs GPU backend in your project, you first need to add it as a dependency in your Cargo.toml.

If you are using an x86 machine:

If you are using an ARM machine:

Supported platforms

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

A first example

Configuring and creating keys.

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

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(). From then on, there is no difference between the CPU and the GPU.

Encrypting data

On the client-side, the method to encrypt the data is exactly the same than the CPU one, i.e.:

Computation.

Decryption.

Finally, the client gets the decrypted results by computing:

Improving performance.

TFHE-rs includes the possibility to leverage the high number of threads given by a GPU. To do so, the configuration should be updated with Rust let config = ConfigBuilder::with_custom_parameters(PARAM_MULTI_BIT_MESSAGE_2_CARRY_2_GROUP_3_KS_PBS, None).build(); The complete example becomes:

List of available operations

The GPU backend includes the following operations:

Benchmarks

The tables below contain benchmarks for homomorphic operations running on a single V100 from AWS (p3.2xlarge machines), with the default parameters:

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 usual case where the same secret key is used to encrypt and decrypt the data. In TFHE-rs, there exists two methods for public key encryptions. First, the usual one, where the public key contains ma y encryption of zeroes. More details can be found in . The second method is based on the paper entitled . The main advantage of the latter method in comparison with the former lies into the key sizes, which are drastically reduced.

Note that public keys can be

classical public key

This example shows how to use public keys.

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.

Types

TFHE-rs includes two main types to represent encrypted data:

• FheUint: this is the homomorphic equivalent of Rust unsigned integers u8, u16, ...

• FheInt: this is the homomorphic equivalent of Rust (signed) integers i8, i16, ...

In the same manner as many programming languages, the number of bits used to represent the data must be chosen when declaring a variable. For instance:

Operation list

The table below contains an overview of the available operations in TFHE-rs. The notation Enc (for Encypted) either refers to FheInt or FheUint, for any size between 1 and 256-bits.

More details, and further examples, are given in the following sections.

Integer

In TFHE-rs, integers are used to encrypt all messages which are larger than 4 bits. All supported operations are listed below.

Arithmetic operations.

Homomorphic integer types support arithmetic operations.

The list of supported operations is:

A simple example of how to use these operations:

Bitwise operations.

Homomorphic integer types support some bitwise operations.

The list of supported operations is:

A simple example of how to use these operations:

Comparisons.

Homomorphic integers support comparison operations.

Due to some Rust limitations, it is not possible to overload the comparison symbols because of the inner definition of the operations. This is because Rust expects to have a Boolean as an output, whereas a ciphertext is returned when using homomorphic types.

You will need to use different methods instead of using symbols for the comparisons. These methods follow the same naming conventions as the two standard Rust traits:

The list of supported operations is:

A simple example of how to use these operations:

Min/Max.

Homomorphic integers support the min/max operations.

A simple example of how to use these operations:

Ternary conditional operator.

The ternary conditional operator allows computing conditional instructions of the form if cond { choice_if } else { choice_else }.

The syntax is encrypted_condition.if_then_else(encrypted_choice_if, encrypted_choice_else). The encrypted_condition should be an encryption of 0 or 1 in order to be valid.

Casting.

Casting between integer types is possible via the cast_from associated function or the cast_into method.

Boolean Operations

Native homomorphic Booleans support common Boolean operations.

The list of supported operations is:

is a popular crate to easily write multi-threaded code in Rust.

It is possible to use rayon to write multi-threaded TFHE-rs code. However due to internal details of rayon and TFHE-rs, there is some special setup that needs to be done.

Single Client Application

The Problem

The high level api requires to call set_server_key on each thread where computations needs to be done. So a first attempt at using rayon with TFHE-rs might look like this:

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

Working Example

The correct way is to call rayon::broadcast

Multi-Client Applications

If your application needs to operate on data from different clients concurrently, and that you want each client to use multiple threads, you will need to create different rayon thread pools

This can be useful if you have some rust #[test]