From 4a00d25cb18c6580a0998f9d409f7c24cd7c06f2 Mon Sep 17 00:00:00 2001 From: J-B Orfila Date: Fri, 4 Aug 2023 19:00:32 +0200 Subject: [PATCH] doc: updating doc for v0.4 --- tfhe/docs/SUMMARY.md | 2 +- .../fine_grained_api/integer/operations.md | 14 +- tfhe/docs/fine_grained_api/integer/readme.md | 4 +- .../fine_grained_api/shortint/operations.md | 6 + tfhe/docs/fine_grained_api/shortint/readme.md | 2 +- tfhe/docs/getting_started/benchmarks.md | 129 ++-- tfhe/docs/getting_started/installation.md | 16 +- tfhe/docs/getting_started/operations.md | 587 ++++++++++-------- tfhe/docs/how_to/rust_configuration.md | 12 +- 9 files changed, 452 insertions(+), 320 deletions(-) diff --git a/tfhe/docs/SUMMARY.md b/tfhe/docs/SUMMARY.md index 801607b102..a5e50be7f8 100644 --- a/tfhe/docs/SUMMARY.md +++ b/tfhe/docs/SUMMARY.md @@ -5,7 +5,7 @@ ## Getting Started * [Installation](getting_started/installation.md) * [Quick Start](getting_started/quick_start.md) -* [Operations](getting_started/operations.md) +* [Types & Operations](getting_started/operations.md) * [Benchmarks](getting_started/benchmarks.md) * [Security and Cryptography](getting_started/security_and_cryptography.md) diff --git a/tfhe/docs/fine_grained_api/integer/operations.md b/tfhe/docs/fine_grained_api/integer/operations.md index 861e5781bc..fabb48868c 100644 --- a/tfhe/docs/fine_grained_api/integer/operations.md +++ b/tfhe/docs/fine_grained_api/integer/operations.md @@ -17,7 +17,7 @@ This crate implements two ways to represent an integer: The first possibility to represent a large integer is to use a Radix-based decomposition on the plaintexts. Let $$B \in \mathbb{N}$$ be a basis such that the size of $$B$$ is smaller than (or equal to) 4 bits. Then, an integer $$m \in \mathbb{N}$$ can be written as $$m = m_0 + m_1*B + m_2*B^2 + ...$$, where each $$m_i$$ is strictly smaller than $$B$$. Each $$m_i$$ is then independently encrypted. In the end, an Integer ciphertext is defined as a set of shortint ciphertexts. -The definition of an integer requires a basis and a number of blocks. This is done at key generation. Below, the keys are dedicated to unsigned integers encrypting messages over 8 bits, using a basis over 2 bits (i.e., $$B=2^2$$) and 4 blocks. +The definition of an integer requires a basis and a number of blocks. These parameters are chosen at key generation. Below, the keys are dedicated to integers encrypting messages over 8 bits, using a basis over 2 bits (i.e., $$B=2^2$$) and 4 blocks. ```rust use tfhe::integer::gen_keys_radix; @@ -93,6 +93,10 @@ Each operation may come in different 'flavors': Not all operations have these 4 flavors, as some of them are implemented in a way that the operation is always possible without ever exceeding the plaintext space capacity. +{% hint style="info" %} +If you don't know which flavor to use, you should use the `default` one. +{% endhint %} + ## How to use each operation type Let's try to do a circuit evaluation using the different flavors of already introduced operations. For a very small circuit, the `unchecked` flavor may be enough to do the computation correctly. Otherwise, `checked` and `smart` are the best options. @@ -211,6 +215,14 @@ fn main() { } ``` +{% hint style="warning" %} +You must avoid cloning the inputs when calling `smart` operations to preserve performance. For instance, you SHOULD NOT have these kind of patterns in the code: +```Rust +sks.smart_add(&mut a.clone(), &mut b.clone()); +``` +{% endhint %} + + The main advantage of the default flavor is to ensure predictable timings, as long as only this kind of operation is used. Only the parallelized version of the operations is provided. {% hint style="warning" %} diff --git a/tfhe/docs/fine_grained_api/integer/readme.md b/tfhe/docs/fine_grained_api/integer/readme.md index 17ab8c6931..625466f3bd 100644 --- a/tfhe/docs/fine_grained_api/integer/readme.md +++ b/tfhe/docs/fine_grained_api/integer/readme.md @@ -1,6 +1,6 @@ # Tutorial -`tfhe::integer` is dedicated to unsigned integers smaller than 256 bits. The steps to homomorphically evaluate an integer circuit are described here. +`tfhe::integer` is dedicated to integers smaller than 256 bits. The steps to homomorphically evaluate an integer circuit are described here. ## Key Types @@ -25,7 +25,7 @@ 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 an **8-bit** integer by using **4** shortint blocks that store **2** bits of message each. +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. ```rust use tfhe::integer::gen_keys_radix; diff --git a/tfhe/docs/fine_grained_api/shortint/operations.md b/tfhe/docs/fine_grained_api/shortint/operations.md index 93187930b9..64bdfc52b1 100644 --- a/tfhe/docs/fine_grained_api/shortint/operations.md +++ b/tfhe/docs/fine_grained_api/shortint/operations.md @@ -37,8 +37,14 @@ Each operation may come in different 'flavors': Not all operations have these 4 flavors, as some of them are implemented in a way that the operation is always possible without ever exceeding the plaintext space capacity. +{% hint style="info" %} +If you don't know which flavor to use, you should use the `default` one. +{% endhint %} + + ## How to use operation types + Let's try to do a circuit evaluation using the different flavors of operations that we have already introduced. For a very small circuit, the `unchecked` flavour may be enough to do the computation correctly. Otherwise,`checked` and `smart` are the best options. Let's do a scalar multiplication, a subtraction, and a multiplication. diff --git a/tfhe/docs/fine_grained_api/shortint/readme.md b/tfhe/docs/fine_grained_api/shortint/readme.md index d6bb603384..54f79f2ea8 100644 --- a/tfhe/docs/fine_grained_api/shortint/readme.md +++ b/tfhe/docs/fine_grained_api/shortint/readme.md @@ -1,6 +1,6 @@ # Tutorial -`tfhe::shortint` is dedicated to small unsigned integers smaller than 8 bits. The steps to homomorphically evaluate a circuit are described below. +`tfhe::shortint` is dedicated to unsigned integers smaller than 8 bits. The steps to homomorphically evaluate a circuit are described below. ## Key generation diff --git a/tfhe/docs/getting_started/benchmarks.md b/tfhe/docs/getting_started/benchmarks.md index 4aafd0c305..1432add67c 100644 --- a/tfhe/docs/getting_started/benchmarks.md +++ b/tfhe/docs/getting_started/benchmarks.md @@ -1,97 +1,106 @@ # Benchmarks -Due to their nature, homomorphic operations are naturally slower than their clear equivalent. Some timings are exposed for basic operations. For completeness, benchmarks for other libraries are also given. +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. {% hint style="info" %} All benchmarks were launched on an AWS m6i.metal with the following specifications: Intel(R) Xeon(R) Platinum 8375C CPU @ 2.90GHz and 512GB of RAM. {% endhint %} -## Boolean +## Integer -This measures the execution time of a single binary Boolean gate. +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. -### tfhe-rs::boolean. +| Operation \ Size | `FheUint8` | `FheUint16` | `FheUint32` | `FheUint64` | `FheUint128` | `FheUint256` | +|--------------------------------------------------------|------------|-------------|-------------|-------------|--------------|--------------| +| Negation (`-`) | 70.9 ms | 99.3 ms | 129 ms | 180 ms | 239 ms | 333 ms | +| Add / Sub (`+`,`-`) | 70.5 ms | 100 ms | 132 ms | 186 ms | 249 ms | 334 ms | +| Mul (`x`) | 144 ms | 216 ms | 333 ms | 832 ms | 2.50 s | 8.85 s | +| Equal / Not Equal (`eq`, `ne`) | 36.1 ms | 36.5 ms | 57.4 ms | 64.2 ms | 67.3 ms | 78.1 ms | +| Comparisons (`ge`, `gt`, `le`, `lt`) | 52.6 ms | 73.1 ms | 98.8 ms | 124 ms | 165 ms | 201 ms | +| Max / Min (`max`,`min`) | 76.2 ms | 102 ms | 135 ms | 171 ms | 212 ms | 301 ms | +| Bitwise operations (`&`, `\|`, `^`) | 19.4 ms | 20.3 ms | 21.0 ms | 27.2 ms | 31.6 ms | 40.2 ms | +| Div / Rem (`/`, `%`) | 729 ms | 1.93 s | 4.81 s | 12.2 s | 30.7 s | 89.6 s | +| Left / Right Shifts (`<<`, `>>`) | 99.4 ms | 129 ms | 180 ms | 243 ms | 372 ms | 762 ms | +| Left / Right Rotations (`left_rotate`, `right_rotate`) | 103 ms | 128 ms | 182 ms | 241 ms | 374 ms | 763 ms | -| Parameter set | Concrete FFT | Concrete FFT + AVX-512 | -| --------------------- | ------------ | ---------------------- | -| DEFAULT\_PARAMETERS | 8.8ms | 6.8ms | -| TFHE\_LIB\_PARAMETERS | 13.6ms | 10.9ms | -### tfhe-lib. - -| Parameter set | fftw | spqlios-fma | -| ------------------------------------------------ | ------ | ----------- | -| default\_128bit\_gate\_bootstrapping\_parameters | 28.9ms | 15.7ms | +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](../fine_grained_api/shortint/parameters.md)). +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`. -### OpenFHE. -| Parameter set | GINX | GINX (Intel HEXL) | -| ------------- | ----- | ----------------- | -| STD\_128 | 172ms | 78ms | -| MEDIUM | 113ms | 50.2ms | +## 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. -## Integer -This measures the execution time for some operation sets of tfhe-rs::integer. +This uses the Concrete FFT + AVX-512 configuration. -| Operation \ Size | `FheUint8` | `FheUint16` | `FheUint32` | ` FheUint64` | `FheUint128` | `FheUint256` | -|--------------------------------------------------------|------------|-------------|-------------|--------------|--------------|--------------| -| Negation (`-`) | 80.4 ms | 106 ms | 132 ms | 193 ms | 257 ms | 348 ms | -| Add / Sub (`+`,`-`) | 81.5 ms | 110 ms | 139 ms | 200 ms | 262 ms | 355 ms | -| Mul (`x`) | 150 ms | 221 ms | 361 ms | 928 ms | 2.90 s | 10.97 s | -| Equal / Not Equal (`eq`, `ne`) | 39.4 ms | 40.2 ms | 61.1 ms | 66.4 ms | 74.5 ms | 85.7 ms | -| Comparisons (`ge`, `gt`, `le`, `lt`) | 57.5 ms | 79.6 ms | 105 ms | 136 ms | 174 ms | 219 ms | -| Max / Min (`max`,`min`) | 100 ms | 130 ms | 163 ms | 204 ms | 245 ms | 338 ms | -| Bitwise operations (`&`, `|`, `^`) | 20.7 ms | 21.1 ms | 22.6 ms | 30.2 ms | 34.1 ms | 42.1 ms | -| Div / Rem (`/`, `%`) | 1.37 s | 3.50 s | 9.12 s | 23.9 s | 59.9 s | 149.2 s | -| Left / Right Shifts (`<<`, `>>`) | 106 ms | 140 ms | 202 ms | 262 ms | 403 ms | 827 ms | -| Left / Right Rotations (`left_rotate`, `right_rotate`) | 105 ms | 140 ms | 199 ms | 263 ms | 403 ms | 829 ms | +| Parameter set | PARAM\_MESSAGE\_1\_CARRY\_1 | PARAM\_MESSAGE\_2\_CARRY\_2 | PARAM\_MESSAGE\_3\_CARRY\_3 | PARAM\_MESSAGE\_4\_CARRY\_4 | +|------------------------------------|-----------------------------|-----------------------------|-----------------------------|-----------------------------| +| unchecked\_add | 348 ns | 413 ns | 2.95 µs | 12.1 µs | +| add | 7.59 ms | 17.0 ms | 121 ms | 835 ms | +| mul\_lsb | 8.13 ms | 16.8 ms | 121 ms | 827 ms | +| keyswitch\_programmable\_bootstrap | 7.28 ms | 16.6 ms | 121 ms | 811 ms | +## Boolean -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, more information about parameters can be found [here](../fine_grained_api/shortint/parameters.md)). -To ensure predictable timings, the operation flavor is the `default` one: the carry is propagated if needed. The operation costs could be reduced by using `unchecked`, `checked`, or `smart`. +This measures the execution time of a single binary Boolean gate. +### tfhe-rs::boolean. -## Shortint -This measures the execution time for some operations using various parameter sets of tfhe-rs::shortint. +| Parameter set | Concrete FFT + AVX-512 | +|------------------------------------------------------|------------------------| +| DEFAULT\_PARAMETERS\_KS\_PBS | 9.19 ms | +| PARAMETERS\_ERROR\_PROB\_2\_POW\_MINUS\_165\_KS\_PBS | 14.1 ms | +| TFHE\_LIB\_PARAMETERS | 10.0 ms | -This uses the Concrete FFT + AVX-512 configuration. -| Parameter set | unchecked\_add | unchecked\_mul\_lsb | keyswitch\_programmable\_bootstrap | -|-----------------------------|----------------|---------------------|------------------------------------| -| PARAM\_MESSAGE\_1\_CARRY\_1 | 338 ns | 8.3 ms | 8.1 ms | -| PARAM\_MESSAGE\_2\_CARRY\_2 | 406 ns | 18.4 ms | 18.4 ms | -| PARAM\_MESSAGE\_3\_CARRY\_3 | 3.06 µs | 134 ms | 129.4 ms | -| PARAM\_MESSAGE\_4\_CARRY\_4 | 11.7 µs | 854 ms | 828.1 ms | +### tfhe-lib. -Next, the timings for the operation flavor `default` are given. This flavor ensures predictable timings of an operation along the entire circuit by clearing the carry space after each operation. +Using the same m6i.metal machine as the one for tfhe-rs, the timings are: -| Parameter set | add | mul\_lsb | keyswitch\_programmable\_bootstrap | -| --------------------------- | -------------- | ------------------- | ---------------------------------- | -| PARAM\_MESSAGE\_1\_CARRY\_1 | 7.90 ms | 8.00 ms | 8.10 ms | -| PARAM\_MESSAGE\_2\_CARRY\_2 | 18.4 ms | 18.1 ms | 18.4 ms | -| PARAM\_MESSAGE\_3\_CARRY\_3 | 131.5 ms | 129.5 ms | 129.4 ms | -| PARAM\_MESSAGE\_4\_CARRY\_4 | 852.5 ms | 839.7 ms | 828.1 ms | +| Parameter set | spqlios-fma | +|--------------------------------------------------|-------------| +| default\_128bit\_gate\_bootstrapping\_parameters | 15.4 ms | -## How to reproduce benchmarks +### OpenFHE (v1.1.1). -TFHE-rs benchmarks can easily be reproduced from the [sources](https://github.com/zama-ai/tfhe-rs). +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 ..` -```shell -#Boolean benchmarks: -make bench_boolean +To use the HEXL library, the configuration used is as follows: +```bash +export CXX=clang++ +export CC=clang -#Integer benchmarks: -make bench_integer +scripts/configure.sh +Release -> y +hexl -> y -#Shortint benchmarks: -make bench_shortint +scripts/build-openfhe-development-hexl.sh ``` -If the host machine supports AVX-512, then the argument `AVX512_SUPPORT=ON' should be added, e.g.: +Using the same m6i.metal machine as the one for tfhe-rs, the timings are: + +| Parameter set | GINX | GINX w/ Intel HEXL | +|----------------------------------|---------|--------------------| +| FHEW\_BINGATE/STD128\_OR | 40.2 ms | 31.0 ms | +| FHEW\_BINGATE/STD128\_LMKCDEY_OR | 38.6 ms | 28.4 ms | + + +## How to reproduce TFHE-rs benchmarks + +TFHE-rs benchmarks can be easily reproduced from [source](https://github.com/zama-ai/tfhe-rs). ```shell +#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. diff --git a/tfhe/docs/getting_started/installation.md b/tfhe/docs/getting_started/installation.md index ad88de2a36..9ecb2d68a6 100644 --- a/tfhe/docs/getting_started/installation.md +++ b/tfhe/docs/getting_started/installation.md @@ -4,12 +4,22 @@ ## Importing into your project -To use `TFHE-rs` in your project, you first need to add it as a dependency in your `Cargo.toml`: +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: ```toml tfhe = { version = "0.4.0", features = [ "boolean", "shortint", "integer", "x86_64-unix" ] } ``` +If you are using an `ARM` machine: +```toml +tfhe = { version = "0.4.0", features = [ "boolean", "shortint", "integer", "aarch64-unix" ] } +``` + +{% hint style="info" %} +You need to use a Rust version >= 1.72 to compile TFHE-rs. +{% endhint %} + {% hint style="success" %} When running code that uses `TFHE-rs`, it is highly recommended to run in release mode with cargo's `--release` flag to have the best possible performance {% endhint %} @@ -25,7 +35,3 @@ TFHE-rs is supported on Linux (x86, aarch64), macOS (x86, aarch64) and Windows ( | Linux | `x86_64-unix` | `aarch64-unix`\* | | macOS | `x86_64-unix` | `aarch64-unix`\* | | Windows | `x86_64` | Unsupported | - -{% hint style="info" %} -Users who have ARM devices can compile TFHE-rs using a stable toolchain with version >= 1.72 (see [Configuration](../how_to/rust_configuration.md) for more details). -{% endhint %} diff --git a/tfhe/docs/getting_started/operations.md b/tfhe/docs/getting_started/operations.md index 4a41c5ea26..338438f2b7 100644 --- a/tfhe/docs/getting_started/operations.md +++ b/tfhe/docs/getting_started/operations.md @@ -1,97 +1,110 @@ -# Operations - -The table below contains an overview of the available operations in `TFHE-rs`. More details, and further examples, are given in the following sections. - -| name | symbol | FheUint/FheUint | FheUint/Uint | Uint/FheUint | -|-----------------------|-------------|--------------------|--------------------------|--------------------------| -| Neg | `-` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Add | `+` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Sub | `-` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Mul | `*` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Div | `/` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Rem | `%` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Not | `!` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| BitAnd | `&` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| BitOr | `\|` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| BitXor | `^` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Shr | `>>` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Shl | `<<` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Min | `min` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Max | `max` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Greater than | `gt` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Greater or equal than | `ge` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Lower than | `lt` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Lower or equal than | `le` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Equal | `eq` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | -| Cast (into dest type) | `cast_into` | :heavy_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | -| Cast (from src type) | `cast_from` | :heavy_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | +# Homomorphic Types and Operations -## Boolean Operations +## 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, ...` -Native homomorphic Booleans support common Boolean operations. +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: -The list of supported operations is: +```Rust + // let clear_a: u64 = 7; + let mut a = FheUint64::try_encrypt(clear_a, &keys)?; -| name | symbol | type | -| ------------------------------------------------------------- | ------ | ------ | -| [BitAnd](https://doc.rust-lang.org/std/ops/trait.BitAnd.html) | `&` | Binary | -| [BitOr](https://doc.rust-lang.org/std/ops/trait.BitOr.html) | `\|` | Binary | -| [BitXor](https://doc.rust-lang.org/std/ops/trait.BitXor.html) | `^` | Binary | -| [Not](https://doc.rust-lang.org/std/ops/trait.Not.html) | `!` | Unary | + // let clear_b: i8 = 3; + let mut b = FheInt8::try_encrypt(clear_b, &keys)?; -## ShortInt Operations + // let clear_c: u128 = 2; + let mut c = FheUint128::try_encrypt(clear_c, &keys)?; +``` -Native small homomorphic integer types (e.g., FheUint3 or FheUint4) easily compute various operations. In general, computing over encrypted data is as easy as computing over clear data, since the same operation symbol is used. The addition between two ciphertexts is done using the symbol `+` between two FheUint values. Many operations can be computed between a clear value (i.e. a scalar) and a ciphertext. +## 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. + +| name | symbol | `Enc`/`Enc` | `Enc`/ `Int` | +|-----------------------|----------------|--------------------|--------------------------| +| Neg | `-` | :heavy_check_mark: | :heavy_check_mark: | +| Add | `+` | :heavy_check_mark: | :heavy_check_mark: | +| Sub | `-` | :heavy_check_mark: | :heavy_check_mark: | +| Mul | `*` | :heavy_check_mark: | :heavy_check_mark: | +| Div | `/` | :heavy_check_mark: | :heavy_check_mark: | +| Rem | `%` | :heavy_check_mark: | :heavy_check_mark: | +| Not | `!` | :heavy_check_mark: | :heavy_check_mark: | +| BitAnd | `&` | :heavy_check_mark: | :heavy_check_mark: | +| BitOr | `\|` | :heavy_check_mark: | :heavy_check_mark: | +| BitXor | `^` | :heavy_check_mark: | :heavy_check_mark: | +| Shr | `>>` | :heavy_check_mark: | :heavy_check_mark: | +| Shl | `<<` | :heavy_check_mark: | :heavy_check_mark: | +| Min | `min` | :heavy_check_mark: | :heavy_check_mark: | +| Max | `max` | :heavy_check_mark: | :heavy_check_mark: | +| Greater than | `gt` | :heavy_check_mark: | :heavy_check_mark: | +| Greater or equal than | `ge` | :heavy_check_mark: | :heavy_check_mark: | +| Lower than | `lt` | :heavy_check_mark: | :heavy_check_mark: | +| Lower or equal than | `le` | :heavy_check_mark: | :heavy_check_mark: | +| Equal | `eq` | :heavy_check_mark: | :heavy_check_mark: | +| Cast (into dest type) | `cast_into` | :heavy_check_mark: | :heavy_multiplication_x: | +| Cast (from src type) | `cast_from` | :heavy_check_mark: | :heavy_multiplication_x: | +| Ternary operator | `if_then_else` | :heavy_check_mark: | :heavy_multiplication_x: | -In Rust, operations on native types are modular. For example, computations on `u8` are carried out modulo $$2^{8}$$. A similar idea applies for FheUintX, where operations are done modulo $$2^{X}$$. For FheUint3, operations are done modulo $$8 = 2^{3}$$. -### Arithmetic operations. +## Integer -Small homomorphic integer types support all common arithmetic operations, meaning `+`, `-`, `x`, `/`, `mod`. +In `TFHE-rs`, integers are used to encrypt all messages which are larger than 4 bits. All supported operations are listed below. -The division operation implements a subtlety: since data is encrypted, it is possible to compute a division by 0. In this case, the division is tweaked so that dividing by 0 returns the max possible value for the message. +### Arithmetic operations. + +Homomorphic integer types support arithmetic operations. The list of supported operations is: -| name | symbol | type | -| ------------------------------------------------------- | ------ | ------ | -| [Add](https://doc.rust-lang.org/std/ops/trait.Add.html) | `+` | Binary | -| [Sub](https://doc.rust-lang.org/std/ops/trait.Sub.html) | `-` | Binary | -| [Mul](https://doc.rust-lang.org/std/ops/trait.Mul.html) | `*` | Binary | -| [Div](https://doc.rust-lang.org/std/ops/trait.Div.html) | `/` | Binary | -| [Rem](https://doc.rust-lang.org/std/ops/trait.Rem.html) | `%` | Binary | -| [Neg](https://doc.rust-lang.org/std/ops/trait.Neg.html) | `-` | Unary | +| name | symbol | type | +|----------------------------------------------------------|--------|--------| +| [Neg](https://doc.rust-lang.org/std/ops/trait.Neg.html) | `-` | Unary | +| [Add](https://doc.rust-lang.org/std/ops/trait.Add.html) | `+` | Binary | +| [Sub](https://doc.rust-lang.org/std/ops/trait.Sub.html) | `-` | Binary | +| [Mul](https://doc.rust-lang.org/std/ops/trait.Mul.html) | `*` | Binary | +| [Div](https://doc.rust-lang.org/std/ops/trait.Div.html)* | `/` | Binary | +| [Rem](https://doc.rust-lang.org/std/ops/trait.Rem.html)* | `%` | Binary | + +For division by 0, the convention is to return `modulus - 1`. For instance, for `FheUint8`, the modulus is $$2^8=256$$, so a division by 0 will return an encryption of 255. +For the remainder operator, the convention is to return the first input without any modification. For instance, if `ct1 = FheUint8(63)` and `ct2 = FheUint8(0)` then `ct1 % ct2` will return `FheUint8(63)`. -A simple example on how to use these operations: +A simple example of how to use these operations: ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint3}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8, FheUint8}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled().enable_default_uint3().build(); + let config = ConfigBuilder::all_disabled().enable_default_integers().build(); let (keys, server_keys) = generate_keys(config); set_server_key(server_keys); - let clear_a = 7; - let clear_b = 3; - let clear_c = 2; + let clear_a = 15_u64; + let clear_b = 27_u64; + let clear_c = 43_u64; + let clear_d = -87_i64; - let mut a = FheUint3::try_encrypt(clear_a, &keys)?; - let mut b = FheUint3::try_encrypt(clear_b, &keys)?; - let mut c = FheUint3::try_encrypt(clear_c, &keys)?; + let mut a = FheUint8::try_encrypt(clear_a, &keys)?; + let mut b = FheUint8::try_encrypt(clear_b, &keys)?; + let mut c = FheUint8::try_encrypt(clear_c, &keys)?; + let mut d = FheInt8::try_encrypt(clear_d, &keys)?; - a = a * &b; // Clear equivalent computations: 7 * 3 mod 8 = 5 - b = &b + &c; // Clear equivalent computations: 3 + 2 mod 8 = 5 - b = b - 5; // Clear equivalent computations: 5 - 5 mod 8 = 0 + a = a * &b; // Clear equivalent computations: 15 * 27 mod 256 = 149 + b = &b + &c; // Clear equivalent computations: 27 + 43 mod 256 = 70 + b = b - 76u8; // Clear equivalent computations: 70 - 76 mod 256 = 250 + d = d - 13i8; // Clear equivalent computations: -87 - 13 = 100 in [-128, 128[ - let dec_a = a.decrypt(&keys); - let dec_b = b.decrypt(&keys); + let dec_a: u8 = a.decrypt(&keys); + let dec_b: u8 = b.decrypt(&keys); + let dec_d: i8 = d.decrypt(&keys); - // We homomorphically swapped values using bitwise operations - assert_eq!(dec_a, (clear_a * clear_b) % 8); - assert_eq!(dec_b, ((clear_b + clear_c) - 5) % 8); + 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(()) } @@ -99,7 +112,7 @@ fn main() -> Result<(), Box> { ### Bitwise operations. -Small homomorphic integer types support some bitwise operations. +Homomorphic integer types support some bitwise operations. The list of supported operations is: @@ -114,29 +127,29 @@ The list of supported operations is: | [Rotate Right](https://doc.rust-lang.org/std/primitive.u32.html#method.rotate_right) | `rotate_right` | Binary | | [Rotate Left](https://doc.rust-lang.org/std/primitive.u32.html#method.rotate_left) | `rotate_left` | Binary | -A simple example on how to use these operations: +A simple example of how to use these operations: ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint3}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled().enable_default_uint3().build(); + let config = ConfigBuilder::all_disabled().enable_default_integers().build(); let (keys, server_keys) = generate_keys(config); set_server_key(server_keys); - let clear_a = 7; - let clear_b = 3; + let clear_a = 164; + let clear_b = 212; - let mut a = FheUint3::try_encrypt(clear_a, &keys)?; - let mut b = FheUint3::try_encrypt(clear_b, &keys)?; + let mut a = FheUint8::try_encrypt(clear_a, &keys)?; + let mut b = FheUint8::try_encrypt(clear_b, &keys)?; a = a ^ &b; b = b ^ &a; a = a ^ &b; - let dec_a = a.decrypt(&keys); - let dec_b = b.decrypt(&keys); + 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); @@ -148,9 +161,9 @@ fn main() -> Result<(), Box> { ### Comparisons. -Small homomorphic integer types support comparison operations. +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. Rust expects to have a Boolean as an output, whereas a ciphertext is returned when using homomorphic types. +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: @@ -168,143 +181,256 @@ The list of supported operations is: | [Lower ](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) | `lt` | Binary | | [Lower or Equal ](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) | `le` | Binary | - -A simple example on how to use these operations: +A simple example of how to use these operations: ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint3}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled().enable_default_uint3().build(); + let config = ConfigBuilder::all_disabled().enable_default_integers().build(); let (keys, server_keys) = generate_keys(config); set_server_key(server_keys); - let clear_a = 7; - let clear_b = 3; + let clear_a: i8 = -121; + let clear_b: i8 = 87; - let mut a = FheUint3::try_encrypt(clear_a, &keys)?; - let mut b = FheUint3::try_encrypt(clear_b, &keys)?; + let mut a = FheInt8::try_encrypt(clear_a, &keys)?; + let mut b = FheInt8::try_encrypt(clear_b, &keys)?; - assert_eq!(a.gt(&b).decrypt(&keys) != 0, true); - assert_eq!(b.le(&a).decrypt(&keys) != 0, true); + 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: i8 = greater.decrypt(&keys); + let dec_ge: i8 = greater_or_equal.decrypt(&keys); + let dec_lt: i8 = lower.decrypt(&keys); + let dec_le: i8 = lower_or_equal.decrypt(&keys); + let dec_eq: i8 = equal.decrypt(&keys); + + // We homomorphically swapped values using bitwise operations + assert_eq!(dec_gt, (clear_a > clear_b ) as i8); + assert_eq!(dec_ge, (clear_a >= clear_b) as i8); + assert_eq!(dec_lt, (clear_a < clear_b ) as i8); + assert_eq!(dec_le, (clear_a <= clear_b) as i8); + assert_eq!(dec_eq, (clear_a == clear_b) as i8); Ok(()) } ``` -### Univariate function evaluation. +### Min/Max. -The shortint type also supports the computation of univariate functions, which make use of TFHE's _programmable bootstrapping_. +Homomorphic integers support the min/max operations. -A simple example on how to use these operations: +| name | symbol | type | +| ---- | ------ | ------ | +| Min | `min` | Binary | +| Max | `max` | Binary | + +A simple example of how to use these operations: ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint4}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled().enable_default_uint4().build(); + let config = ConfigBuilder::all_disabled().enable_default_integers().build(); let (keys, server_keys) = generate_keys(config); set_server_key(server_keys); - let pow_5 = |value: u64| { - value.pow(5) % FheUint4::MODULUS as u64 - }; + let clear_a:u8 = 164; + let clear_b:u8 = 212; - let clear_a = 12; - let a = FheUint4::try_encrypt(12, &keys)?; + let mut a = FheUint8::try_encrypt(clear_a, &keys)?; + let mut b = FheUint8::try_encrypt(clear_b, &keys)?; - let c = a.map(pow_5); - let decrypted = c.decrypt(&keys); - assert_eq!(decrypted, pow_5(clear_a) as u8); + let min = a.min(&b); + let max = a.max(&b); + + let dec_min : u8 = min.decrypt(&keys); + let dec_max : u8 = max.decrypt(&keys); + + // We homomorphically swapped values using bitwise operations + assert_eq!(dec_min, u8::min(clear_a, clear_b)); + assert_eq!(dec_max, u8::max(clear_a, clear_b)); Ok(()) } ``` -### Bivariate function evaluations. +### Ternary conditional operator. +The ternary conditional operator allows computing conditional instructions of the form `if cond { choice_if } else { choice_else }`. -Using the shortint type allows you to evaluate bivariate functions (i.e., functions that take two ciphertexts as input). +| name | symbol | type | +|------------------|----------------|---------| +| Ternary operator | `if_then_else` | Ternary | -A simple code example: +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. ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint2}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt32}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled().enable_default_uint2().build(); - let (keys, server_keys) = generate_keys(config); - set_server_key(server_keys); + // Basic configuration to use homomorphic integers + let config = ConfigBuilder::all_disabled() + .enable_default_integers() + .build(); - let clear_a = 1; - let clear_b = 3; - let a = FheUint2::try_encrypt(clear_a, &keys)?; - let b = FheUint2::try_encrypt(clear_b, &keys)?; + // Key generation + let (client_key, server_keys) = generate_keys(config); + + let clear_a = 32i32; + let clear_b = -45i32; + + // Encrypting the input data using the (private) client_key + // FheInt32: Encrypted equivalent to i32 + let encrypted_a = FheInt32::try_encrypt(clear_a, &client_key)?; + let encrypted_b = FheInt32::try_encrypt(clear_b, &client_key)?; + + // On the server side: + set_server_key(server_keys); + + // Clear equivalent computations: 32 > -45 + let encrypted_comp = &encrypted_a.gt(&encrypted_b); + let clear_res: i32 = encrypted_comp.decrypt(&client_key); + assert_eq!(clear_res, (clear_a > clear_b) as i32); + + // `encrypted_comp` contains the result of the comparison, i.e., + // a boolean value. This acts as a condition on which the + // `if_then_else` function can be applied on. + // Clear equivalent computations: + // if 32 > -45 {result = 32} else {result = -45} + let encrypted_res = &encrypted_comp.if_then_else(&encrypted_a, &encrypted_b); + + let clear_res: i32 = encrypted_res.decrypt(&client_key); + assert_eq!(clear_res, clear_a); + + Ok(()) +} +``` - let c = a.bivariate_function(&b, std::cmp::max); - let decrypted = c.decrypt(&keys); - assert_eq!(decrypted, std::cmp::max(clear_a, clear_b) as u8); +### Casting. +Casting between integer types is possible via the `cast_from` associated function +or the `cast_into` method. + +```rust +use tfhe::prelude::*; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt16, FheUint8, FheUint32, FheUint16}; + +fn main() -> Result<(), Box> { + let config = ConfigBuilder::all_disabled() + .enable_default_integers() + .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(()) } ``` -## Integer -In TFHE-rs, integers are used to encrypt any messages larger than 4 bits. All supported operations are listed below. -### Arithmetic operations. +## ShortInt Operations -Homomorphic integer types support arithmetic operations. +Native small homomorphic integer types (e.g., FheUint3 or FheUint4) can easily compute various operations. In general, computing over encrypted data in `TFHE-rs` is as easy as computing over clear data, since the same operation symbol is used. The addition between two ciphertexts is done using the symbol `+` between two FheUint values. Many operations can be computed between a clear value (i.e. a scalar) and a ciphertext. -The list of supported operations is: +In Rust, operations on native types are modular. For example, computations on `u8` are carried out modulo $$2^{8}$$. A similar idea applies for FheUintX, where operations are done modulo $$2^{X}$$. For FheUint3, operations are done modulo $$8 = 2^{3}$$. -| name | symbol | type | -|----------------------------------------------------------|--------|--------| -| [Neg](https://doc.rust-lang.org/std/ops/trait.Neg.html) | `-` | Unary | -| [Add](https://doc.rust-lang.org/std/ops/trait.Add.html) | `+` | Binary | -| [Sub](https://doc.rust-lang.org/std/ops/trait.Sub.html) | `-` | Binary | -| [Mul](https://doc.rust-lang.org/std/ops/trait.Mul.html) | `*` | Binary | -| [Div](https://doc.rust-lang.org/std/ops/trait.Div.html)* | `/` | Binary | -| [Rem](https://doc.rust-lang.org/std/ops/trait.Rem.html)* | `%` | Binary | +### Arithmetic operations. -For division by $$0$$, the convention is to return $$modulus - 1$$. For instance, for FheUint8, the modulus is $$2^8=256$$, so a division by $$0$$ will return an encryption of $$255$$. -For the remainder operator, the convention is to return the first input without any modification. For instance, for $$ct1 = FheUint8(63)$$ and $$ct2 = FheUint8(0)$$, then $$ct1 % ct2$$ will return $$FheUint8(63)$$. +Small homomorphic integer types support all common arithmetic operations, meaning `+`, `-`, `x`, `/`, `mod`. +The division operation presents a subtlety: since data is encrypted, it is possible to compute a division by 0. In this case, the division is tweaked so that dividing by 0 returns the maximum possible value for the message. +The list of supported operations is: -A simple example on how to use these operations: +| name | symbol | type | +| ------------------------------------------------------- | ------ | ------ | +| [Add](https://doc.rust-lang.org/std/ops/trait.Add.html) | `+` | Binary | +| [Sub](https://doc.rust-lang.org/std/ops/trait.Sub.html) | `-` | Binary | +| [Mul](https://doc.rust-lang.org/std/ops/trait.Mul.html) | `*` | Binary | +| [Div](https://doc.rust-lang.org/std/ops/trait.Div.html) | `/` | Binary | +| [Rem](https://doc.rust-lang.org/std/ops/trait.Rem.html) | `%` | Binary | +| [Neg](https://doc.rust-lang.org/std/ops/trait.Neg.html) | `-` | Unary | + +A simple example of how to use these operations: ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint3}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled().enable_default_integers().build(); + let config = ConfigBuilder::all_disabled().enable_default_uint3().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_a = 7; + let clear_b = 3; + let clear_c = 2; - let mut a = FheUint8::try_encrypt(clear_a, &keys)?; - let mut b = FheUint8::try_encrypt(clear_b, &keys)?; - let mut c = FheUint8::try_encrypt(clear_c, &keys)?; + let mut a = FheUint3::try_encrypt(clear_a, &keys)?; + let mut b = FheUint3::try_encrypt(clear_b, &keys)?; + let mut c = FheUint3::try_encrypt(clear_c, &keys)?; - a = a * &b; // Clear equivalent computations: 15 * 27 mod 256 = 149 - b = &b + &c; // Clear equivalent computations: 27 + 43 mod 256 = 70 - b = b - 76u8; // Clear equivalent computations: 70 - 76 mod 256 = 250 + a = a * &b; // Clear equivalent computations: 7 * 3 mod 8 = 5 + b = &b + &c; // Clear equivalent computations: 3 + 2 mod 8 = 5 + b = b - 5; // Clear equivalent computations: 5 - 5 mod 8 = 0 - let dec_a: u8 = a.decrypt(&keys); - let dec_b: u8 = b.decrypt(&keys); + let dec_a = a.decrypt(&keys); + let dec_b = b.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); + // We homomorphically swapped values using bitwise operations + assert_eq!(dec_a, (clear_a * clear_b) % 8); + assert_eq!(dec_b, ((clear_b + clear_c) - 5) % 8); Ok(()) } @@ -312,7 +438,7 @@ fn main() -> Result<(), Box> { ### Bitwise operations. -Homomorphic integer types support some bitwise operations. +Small homomorphic integer types support some bitwise operations. The list of supported operations is: @@ -327,29 +453,29 @@ The list of supported operations is: | [Rotate Right](https://doc.rust-lang.org/std/primitive.u32.html#method.rotate_right) | `rotate_right` | Binary | | [Rotate Left](https://doc.rust-lang.org/std/primitive.u32.html#method.rotate_left) | `rotate_left` | Binary | -A simple example on how to use these operations: +A simple example of how to use these operations: ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint3}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled().enable_default_integers().build(); + let config = ConfigBuilder::all_disabled().enable_default_uint3().build(); let (keys, server_keys) = generate_keys(config); set_server_key(server_keys); - let clear_a = 164; - let clear_b = 212; + let clear_a = 7; + let clear_b = 3; - let mut a = FheUint8::try_encrypt(clear_a, &keys)?; - let mut b = FheUint8::try_encrypt(clear_b, &keys)?; + let mut a = FheUint3::try_encrypt(clear_a, &keys)?; + let mut b = FheUint3::try_encrypt(clear_b, &keys)?; a = a ^ &b; b = b ^ &a; a = a ^ &b; - let dec_a: u8 = a.decrypt(&keys); - let dec_b: u8 = b.decrypt(&keys); + let dec_a = a.decrypt(&keys); + let dec_b = b.decrypt(&keys); // We homomorphically swapped values using bitwise operations assert_eq!(dec_a, clear_b); @@ -361,7 +487,14 @@ fn main() -> Result<(), Box> { ### Comparisons. -Homomorphic integers support comparison operations. Since Rust does not allow the overloading of these operations, a simple function has been associated to each one. +Small homomorphic integer types 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. 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: + +* [PartialOrd](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) +* [PartialEq](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) The list of supported operations is: @@ -374,135 +507,101 @@ The list of supported operations is: | [Lower ](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) | `lt` | Binary | | [Lower or Equal ](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) | `le` | Binary | -A simple example on how to use these operations: + +A simple example of how to use these operations: ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint3}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled().enable_default_integers().build(); + let config = ConfigBuilder::all_disabled().enable_default_uint3().build(); let (keys, server_keys) = generate_keys(config); set_server_key(server_keys); - let clear_a:u8 = 164; - let clear_b:u8 = 212; - - let mut a = FheUint8::try_encrypt(clear_a, &keys)?; - let mut b = FheUint8::try_encrypt(clear_b, &keys)?; - - let 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 clear_a = 7; + let clear_b = 3; - let dec_gt : u8 = greater.decrypt(&keys); - let dec_ge : u8 = greater_or_equal.decrypt(&keys); - let dec_lt : u8 = lower.decrypt(&keys); - let dec_le : u8 = lower_or_equal.decrypt(&keys); - let dec_eq : u8 = equal.decrypt(&keys); + let mut a = FheUint3::try_encrypt(clear_a, &keys)?; + let mut b = FheUint3::try_encrypt(clear_b, &keys)?; - // We homomorphically swapped values using bitwise operations - assert_eq!(dec_gt, (clear_a > clear_b ) as u8); - assert_eq!(dec_ge, (clear_a >= clear_b) as u8); - assert_eq!(dec_lt, (clear_a < clear_b ) as u8); - assert_eq!(dec_le, (clear_a <= clear_b) as u8); - assert_eq!(dec_eq, (clear_a == clear_b) as u8); + assert_eq!(a.gt(&b).decrypt(&keys) != 0, true); + assert_eq!(b.le(&a).decrypt(&keys) != 0, true); Ok(()) } ``` -### Min/Max. - -Homomorphic integers support the min/max operations. +### Univariate function evaluation. -| name | symbol | type | -| ---- | ------ | ------ | -| Min | `min` | Binary | -| Max | `max` | Binary | +The shortint type also supports the computation of univariate functions, which make use of TFHE's _programmable bootstrapping_. -A simple example on how to use these operations: +A simple example of how to use these operations: ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint4}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled().enable_default_integers().build(); + let config = ConfigBuilder::all_disabled().enable_default_uint4().build(); let (keys, server_keys) = generate_keys(config); set_server_key(server_keys); - let clear_a:u8 = 164; - let clear_b:u8 = 212; - - let mut a = FheUint8::try_encrypt(clear_a, &keys)?; - let mut b = FheUint8::try_encrypt(clear_b, &keys)?; - - let min = a.min(&b); - let max = a.max(&b); + let pow_5 = |value: u64| { + value.pow(5) % FheUint4::MODULUS as u64 + }; - let dec_min : u8 = min.decrypt(&keys); - let dec_max : u8 = max.decrypt(&keys); + let clear_a = 12; + let a = FheUint4::try_encrypt(12, &keys)?; - // We homomorphically swapped values using bitwise operations - assert_eq!(dec_min, u8::min(clear_a, clear_b)); - assert_eq!(dec_max, u8::max(clear_a, clear_b)); + let c = a.map(pow_5); + let decrypted = c.decrypt(&keys); + assert_eq!(decrypted, pow_5(clear_a) as u8); Ok(()) } ``` -### Casting. +### Bivariate function evaluations. -Casting between integer types is possible via the `cast_from` associated function -or the `cast_into` method. +Using the shortint type allows you to evaluate bivariate functions (i.e., functions that take two ciphertexts as input). + +A simple code example: ```rust use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8, FheUint32, FheUint16}; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint2}; fn main() -> Result<(), Box> { - let config = ConfigBuilder::all_disabled() - .enable_default_integers() - .build(); - let (client_key, server_key) = generate_keys(config); + let config = ConfigBuilder::all_disabled().enable_default_uint2().build(); + let (keys, server_keys) = generate_keys(config); + set_server_key(server_keys); - // Casting requires server_key to set - // (encryptions/decryptions do not need server_key to be set) - set_server_key(server_key); + let clear_a = 1; + let clear_b = 3; + let a = FheUint2::try_encrypt(clear_a, &keys)?; + let b = FheUint2::try_encrypt(clear_b, &keys)?; - { - 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); + let c = a.bivariate_function(&b, std::cmp::max); + let decrypted = c.decrypt(&keys); + assert_eq!(decrypted, std::cmp::max(clear_a, clear_b) as u8); - // Upcasting - let a: FheUint32 = a.cast_into(); - let da: u32 = a.decrypt(&client_key); - assert_eq!(da, (clear as u8) as u32); - } + Ok(()) +} +``` - { - 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); - } +## Boolean Operations - Ok(()) -} -``` +Native homomorphic Booleans support common Boolean operations. + +The list of supported operations is: + +| name | symbol | type | +| ------------------------------------------------------------- | ------ | ------ | +| [BitAnd](https://doc.rust-lang.org/std/ops/trait.BitAnd.html) | `&` | Binary | +| [BitOr](https://doc.rust-lang.org/std/ops/trait.BitOr.html) | `\|` | Binary | +| [BitXor](https://doc.rust-lang.org/std/ops/trait.BitXor.html) | `^` | Binary | +| [Not](https://doc.rust-lang.org/std/ops/trait.Not.html) | `!` | Unary | diff --git a/tfhe/docs/how_to/rust_configuration.md b/tfhe/docs/how_to/rust_configuration.md index ed4940f981..b42ee81957 100644 --- a/tfhe/docs/how_to/rust_configuration.md +++ b/tfhe/docs/how_to/rust_configuration.md @@ -1,6 +1,6 @@ # 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 for ARM devices) +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: ```shell @@ -52,11 +52,11 @@ rustup show 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: -| Kind | Features | Type(s) | -| --------- | ---------- | --------------------------------- | -| Booleans | `boolean` | Booleans | -| ShortInts | `shortint` | Short unsigned integers | -| Integers | `integer` | Arbitrary-sized unsigned integers | +| Kind | Features | Type(s) | +|-----------|------------|---------------------------| +| Booleans | `boolean` | Booleans | +| ShortInts | `shortint` | Short integers | +| Integers | `integer` | Arbitrary-sized integers | ## AVX-512