diff --git a/tfhe/docs/README.md b/tfhe/docs/README.md index e511403311..8bb9cf27f6 100644 --- a/tfhe/docs/README.md +++ b/tfhe/docs/README.md @@ -22,18 +22,27 @@ layout: Learn the basics of TFHE-rs, set it up, and make it run with ease. -
What is TFHE-rs?Understand TFHE-rs library and basic cryptographic conceptsgetting_started.mdstart1.png
InstallationFollow the step by step guide to import TFHE-rs in your projectinstallation.mdstart2.png
Quick startSee a full example of using TFHE-rs to compute on encrypted dataquick_start.mdstart3.png
+
What is TFHE-rs?Understand TFHE-rs library and basic cryptographic conceptsgetting_startedstart1.png
InstallationFollow the step by step guide to import TFHE-rs in your projectinstallation.mdstart2.png
Quick startSee a full example of using TFHE-rs to compute on encrypted dataquick_start.mdstart3.png
## Build with TFHE-rs Start building with TFHE-rs by exploring its core features, discovering essential guides, and learning more with user-friendly tutorials. -
FundamentalsExplore the core features.build1.png
GuidesDeploy your project.build2.png
TutorialsLearn more with tutorials.build3.png
+
FHE ComputationsRun FHE computation on encrypted data.build1.png
ConfigurationAdvanced configuration for better performance.build2.png
IntegrationUse TFHE-rs in different contexts or platforms..build3.png
## 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. + +* [Homomorphic parity bit](tutorials/parity_bit.md): Learn how to implement a parity bit calculation over encrypted data +* [Homomorphic case changing on ASCII string](tutorials/ascii_fhe_string.md): See how to process string data securely by changing cases while keeping the data encrypted. +* [SHA256 with Boolean API](tutorials/sha256_bool.md): Delve into a more complex example: implementing the SHA256 hash function entirely on encrypted boolean values. +* [All tutorials](tutorials/see-all-tutorials.md): 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. @@ -56,8 +65,8 @@ Collaborate with us to advance the FHE spaces and drive innovation together. * [Contribute to TFHE-rs](dev/contributing.md) * [Check the latest release note](https://github.com/zama-ai/tfhe-rs/releases) -* [Request a feature](https://github.com/zama-ai/tfhe-rs/issues/new?assignees=\&labels=feature\_request\&projects=\&template=feature\_request.md\&title=) -* [Report a bug](https://github.com/zama-ai/tfhe-rs/issues/new?assignees=\&labels=triage\_required\&projects=\&template=bug\_report.md\&title=) +* [Request a feature](https://github.com/zama-ai/tfhe-rs/issues/new?assignees=\&labels=feature_request\&projects=\&template=feature_request.md\&title=) +* [Report a bug](https://github.com/zama-ai/tfhe-rs/issues/new?assignees=\&labels=triage_required\&projects=\&template=bug_report.md\&title=) *** diff --git a/tfhe/docs/SUMMARY.md b/tfhe/docs/SUMMARY.md index 92a92ddb08..cf15fbe64c 100644 --- a/tfhe/docs/SUMMARY.md +++ b/tfhe/docs/SUMMARY.md @@ -4,58 +4,73 @@ ## Get Started -* [What is TFHE-rs?](getting\_started/readme.md) -* [Installation](getting\_started/installation.md) -* [Quick start](getting\_started/quick\_start.md) -* [Types & Operations](getting\_started/operations.md) -* [Benchmarks](getting\_started/benchmarks/summary.md) - * [CPU Benchmarks](getting\_started/benchmarks/cpu\_benchmarks.md) - * [GPU Benchmarks](getting\_started/benchmarks/gpu\_benchmarks.md) +* [What is TFHE-rs?](getting_started/readme.md) +* [Installation](getting_started/installation.md) +* [Quick start](getting_started/quick_start.md) +* [Benchmarks](getting_started/benchmarks/summary.md) + * [CPU Benchmarks](getting_started/benchmarks/cpu_benchmarks.md) + * [GPU Benchmarks](getting_started/benchmarks/gpu_benchmarks.md) * [Zero-knowledge proof benchmarks](getting_started/benchmarks/zk_proof_benchmarks.md) -* [Security and cryptography](getting\_started/security\_and\_cryptography.md) - -## Fundamentals - -* [Configuration and key generation](fundamentals/configure-and-generate-keys.md) -* [Server key](fundamentals/set-the-server-key.md) -* [Encryption](fundamentals/encrypt-data.md) -* [Computation on encrypted data](fundamentals/compute.md) -* [Decryption](fundamentals/decrypt-data.md) -* [Encrypted pseudo random values](fundamentals/encrypted-prf.md) -* [Serialization/deserialization](fundamentals/serialization.md) -* [Compressing ciphertexts/keys](fundamentals/compress.md) -* [Debugging](fundamentals/debug.md) - -## Guides - -* [Rust configuration](guides/rust\_configuration.md) -* [GPU acceleration](guides/run\_on\_gpu.md) -* [Overflow detection](guides/overflow\_operations.md) -* [Data versioning](guides/data\_versioning.md) -* [Public key encryption](guides/public\_key.md) -* [Zero-knowledge proofs](guides/zk-pok.md) -* [Generic trait bounds](guides/trait\_bounds.md) -* [Parallelized PBS](guides/parallelized\_pbs.md) -* [High-level API in C](guides/c\_api.md) -* [JS on WASM API](guides/js\_on\_wasm\_api.md) -* [Multi-threading with Rayon crate](guides/rayon\_crate.md) -* [Trivial ciphertexts](guides/trivial\_ciphertext.md) -* [PBS statistics](guides/pbs-stats.md) -* [Array](guides/array.md) -* [Strings](guides/strings.md) +* [Security and cryptography](getting_started/security_and_cryptography.md) + +## FHE Computation + +* [Types](fhe-computation/types/README.md) + * [Integer](fhe-computation/types/integer.md) + * [Strings](fhe-computation/types/strings.md) + * [Array](fhe-computation/types/array.md) +* [Operations](fhe-computation/operations/README.md) + * [Arithmetic operations](fhe-computation/operations/arithmetic-operations.md) + * [Bitwise operations](fhe-computation/operations/bitwise-operations.md) + * [Comparison operations](fhe-computation/operations/comparison-operations.md) + * [Min/Max operations](fhe-computation/operations/min-max-operations.md) + * [Ternary conditional operations](fhe-computation/operations/ternary-conditional-operations.md) + * [Casting operations](fhe-computation/operations/casting-operations.md) + * [Boolean Operations](fhe-computation/operations/boolean-operations.md) +* [Core workflow](fhe-computation/compute/README.md) + * [Configuration and key generation](fhe-computation/compute/configure-and-generate-keys.md) + * [Server key](fhe-computation/compute/set-the-server-key.md) + * [Encryption](fhe-computation/compute/encrypt-data.md) + * [Decryption](fhe-computation/compute/decrypt-data.md) +* [Data handling](fhe-computation/data-handling/README.md) + * [Compressing ciphertexts/keys](fhe-computation/data-handling/compress.md) + * [Serialization/deserialization](fhe-computation/data-handling/serialization.md) + * [Data versioning](fhe-computation/data-handling/data_versioning.md) +* [Advanced features](fhe-computation/advanced-features/README.md) + * [Encrypted pseudo random values](fhe-computation/advanced-features/encrypted-prf.md) + * [Overflow detection](fhe-computation/advanced-features/overflow_operations.md) + * [Public key encryption](fhe-computation/advanced-features/public_key.md) + * [Trivial ciphertexts](fhe-computation/advanced-features/trivial_ciphertext.md) + * [Zero-knowledge proofs](fhe-computation/advanced-features/zk-pok.md) + * [Multi-threading with Rayon crate](fhe-computation/advanced-features/rayon_crate.md) +* [Tooling](fhe-computation/tooling/README.md) + * [PBS statistics](fhe-computation/tooling/pbs-stats.md) + * [Generic trait bounds](fhe-computation/tooling/trait_bounds.md) + * [Debugging](fhe-computation/tooling/debug.md) + +## Configuration + +* [Advanced Rust setup](configuration/rust_configuration.md) +* [GPU acceleration](configuration/run_on_gpu.md) +* [Parallelized PBS](configuration/parallelized_pbs.md) + +## Integration + +* [JS on WASM API](integration/js_on_wasm_api.md) +* [High-level API in C](integration/c_api.md) ## Tutorials +* [Homomorphic parity bit](tutorials/parity_bit.md) +* [Homomorphic case changing on Ascii string](tutorials/ascii_fhe_string.md) +* [SHA256 with Boolean API](tutorials/sha256_bool.md) * [All tutorials](tutorials/see-all-tutorials.md) -* [Homomorphic parity bit](tutorials/parity\_bit.md) -* [Homomorphic case changing on Ascii string](tutorials/ascii\_fhe\_string.md) -* [SHA256 with Boolean API](tutorials/sha256\_bool.md) ## References * [API references](https://docs.rs/tfhe/latest/tfhe/) * [Fine-grained APIs](references/fine-grained-apis/README.md) - * [Quick start](references/fine-grained-apis/quick\_start.md) + * [Quick start](references/fine-grained-apis/quick_start.md) * [Boolean](references/fine-grained-apis/boolean/README.md) * [Operations](references/fine-grained-apis/boolean/operations.md) * [Cryptographic parameters](references/fine-grained-apis/boolean/parameters.md) @@ -80,5 +95,5 @@ * [Contributing](dev/contributing.md) * [Release note](https://github.com/zama-ai/tfhe-rs/releases) -* [Feature request](https://github.com/zama-ai/tfhe-rs/issues/new?assignees=\&labels=feature\_request\&projects=\&template=feature\_request.md\&title=) -* [Bug report](https://github.com/zama-ai/tfhe-rs/issues/new?assignees=\&labels=triage\_required\&projects=\&template=bug\_report.md\&title=) +* [Feature request](https://github.com/zama-ai/tfhe-rs/issues/new?assignees=\&labels=feature_request\&projects=\&template=feature_request.md\&title=) +* [Bug report](https://github.com/zama-ai/tfhe-rs/issues/new?assignees=\&labels=triage_required\&projects=\&template=bug_report.md\&title=) diff --git a/tfhe/docs/guides/parallelized_pbs.md b/tfhe/docs/configuration/parallelized_pbs.md similarity index 93% rename from tfhe/docs/guides/parallelized_pbs.md rename to tfhe/docs/configuration/parallelized_pbs.md index 0be778cb47..93dea9cf62 100644 --- a/tfhe/docs/guides/parallelized_pbs.md +++ b/tfhe/docs/configuration/parallelized_pbs.md @@ -1,6 +1,6 @@ # Parallelized PBS -This document describes the implementation and benefits of parallelized [Programmable Bootstrapping](../getting\_started/security\_and\_cryptography.md) (PBS) in **TFHE-rs**, including code examples for using multi-bit PBS parameters and ensuring deterministic execution. +This document describes the implementation and benefits of parallelized [Programmable Bootstrapping](../getting_started/security_and_cryptography.md) (PBS) in **TFHE-rs**, including code examples for using multi-bit PBS parameters and ensuring deterministic execution. ## Parallelized Programmable Bootstrapping diff --git a/tfhe/docs/guides/run_on_gpu.md b/tfhe/docs/configuration/run_on_gpu.md similarity index 89% rename from tfhe/docs/guides/run_on_gpu.md rename to tfhe/docs/configuration/run_on_gpu.md index 231c2dcb47..6543eebaa3 100644 --- a/tfhe/docs/guides/run_on_gpu.md +++ b/tfhe/docs/configuration/run_on_gpu.md @@ -11,13 +11,12 @@ This guide explains how to update your existing program to leverage GPU accelera * [gcc](https://gcc.gnu.org/) >= 8.0 - check this [page](https://gist.github.com/ax3l/9489132) for more details about nvcc/gcc compatible versions * [cmake](https://cmake.org/) >= 3.24 * libclang, to match Rust bingen [requirements](https://rust-lang.github.io/rust-bindgen/requirements.html) >= 9.0 -* Rust version - check this [page](rust\_configuration.md) +* Rust version - check this [page](rust_configuration.md) ## Importing to your project To use the **TFHE-rs** GPU backend in your project, add the following dependency in your `Cargo.toml`. - ```toml tfhe = { version = "1.0.0", features = ["boolean", "shortint", "integer", "gpu"] } ``` @@ -31,7 +30,7 @@ For optimal performance when using **TFHE-rs**, run your code in release mode wi **TFHE-rs** GPU backend is supported on Linux (x86, aarch64). | OS | x86 | aarch64 | -|---------|-------------|---------------| +| ------- | ----------- | ------------- | | Linux | Supported | Supported\* | | macOS | Unsupported | Unsupported\* | | Windows | Unsupported | Unsupported | @@ -40,7 +39,7 @@ For optimal performance when using **TFHE-rs**, run your code in release mode wi ### Configuring and creating keys. -Comparing to the [CPU example](../getting\_started/quick\_start.md), GPU set up differs in the key creation, as detailed [here](run\_on\_gpu.md#Setting-the-keys) +Comparing to the [CPU example](../getting_started/quick_start.md), GPU set up differs in the key creation, as detailed [here](./run_on_gpu.md#setting-the-keys) Here is a full example (combining the client and server parts): @@ -77,9 +76,7 @@ fn main() { } ``` -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. +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 @@ -103,7 +100,7 @@ On the client-side, the method to encrypt the data is exactly the same than the 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 [CPU operations](../getting\_started/operations.md). +Then, homomorphic computations are performed using the same approach as the [CPU operations](../fhe-computation/operations/README.md). ```Rust //Server-side @@ -131,7 +128,7 @@ Finally, the client decrypts the results using: The GPU backend includes the following operations for both signed and unsigned encrypted integers: | name | symbol | `Enc`/`Enc` | `Enc`/ `Int` | -|-----------------------|----------------|----------------------------|----------------------------| +| --------------------- | -------------- | -------------------------- | -------------------------- | | Neg | `-` | :heavy\_check\_mark: | N/A | | Add | `+` | :heavy\_check\_mark: | :heavy\_check\_mark: | | Sub | `-` | :heavy\_check\_mark: | :heavy\_check\_mark: | @@ -157,31 +154,32 @@ The GPU backend includes the following operations for both signed and unsigned e | Cast (from src type) | `cast_from` | :heavy\_multiplication\_x: | N/A | | Ternary operator | `select` | :heavy\_check\_mark: | :heavy\_multiplication\_x: | - {% hint style="info" %} -All operations follow the same syntax than the one described in [here](../getting\_started/operations.md). +All operations follow the same syntax than the one described in [here](../fhe-computation/operations/README.md). {% endhint %} ## Multi-GPU support TFHE-rs supports platforms with multiple GPUs. There is **nothing to change in the code to execute on such platforms**. To keep the API as user-friendly as possible, the configuration is automatically set, i.e., the user has no fine-grained control over the number of GPUs to be used. -## Benchmark +## Benchmark + Please refer to the [GPU benchmarks](../getting_started/benchmarks/gpu_benchmarks.md) for detailed performance benchmark results. ## Warning + When measuring GPU times on your own on Linux, set the environment variable `CUDA_MODULE_LOADING=EAGER` to avoid CUDA API overheads during the first kernel execution. ## Compressing ciphertexts after some homomorphic computation on the GPU -You can compress ciphertexts using the GPU, even after computations, just like on the [CPU](../fundamentals/compress.md#compression-ciphertexts-after-some-homomorphic-computation). +You can compress ciphertexts using the GPU, even after computations, just like on the [CPU](../fhe-computation/data-handling/compress.md#compression-ciphertexts-after-some-homomorphic-computation). + +The way to do it 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: -The way to do it 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 +* One 32-bits integer +* One 64-bit integer +* One Boolean +* One 2-bit integer ```rust use tfhe::prelude::*; @@ -246,7 +244,8 @@ fn main() { ## Array types -It is possible to use array types on GPU, just as [on CPU](array.md). Here is an example showing how to do it: +It is possible to use array types on GPU, just as [on CPU](../fhe-computation/types/array.md). Here is an example showing how to do it: + ```rust use tfhe::{ConfigBuilder, set_server_key, ClearArray, ClientKey, CompressedServerKey}; use tfhe::array::GpuFheUint32Array; diff --git a/tfhe/docs/guides/rust_configuration.md b/tfhe/docs/configuration/rust_configuration.md similarity index 100% rename from tfhe/docs/guides/rust_configuration.md rename to tfhe/docs/configuration/rust_configuration.md diff --git a/tfhe/docs/fhe-computation/advanced-features/README.md b/tfhe/docs/fhe-computation/advanced-features/README.md new file mode 100644 index 0000000000..7c935bda53 --- /dev/null +++ b/tfhe/docs/fhe-computation/advanced-features/README.md @@ -0,0 +1 @@ +# Advanced features diff --git a/tfhe/docs/fundamentals/encrypted-prf.md b/tfhe/docs/fhe-computation/advanced-features/encrypted-prf.md similarity index 100% rename from tfhe/docs/fundamentals/encrypted-prf.md rename to tfhe/docs/fhe-computation/advanced-features/encrypted-prf.md diff --git a/tfhe/docs/guides/overflow_operations.md b/tfhe/docs/fhe-computation/advanced-features/overflow_operations.md similarity index 65% rename from tfhe/docs/guides/overflow_operations.md rename to tfhe/docs/fhe-computation/advanced-features/overflow_operations.md index 4e3bf61ede..f9276813dc 100644 --- a/tfhe/docs/guides/overflow_operations.md +++ b/tfhe/docs/fhe-computation/advanced-features/overflow_operations.md @@ -40,21 +40,3 @@ assert_eq!( ); assert!(overflowed.decrypt(&client_key)); ``` - -The following tables show the current benchmarks result. - -Unsigned homomorphic integers: - -| Operation\Size | FheUint8 | FheUint16 | FheUint32 | FheUint64 | FheUint128 | FheUint256 | -| -------------------------- | --------- | --------- | --------- | --------- | ---------- | ---------- | -| unsigned\_overflowing\_add | 63.67 ms | 84.11 ms | 107.95 ms | 120.8 ms | 147.38 ms | 191.28 ms | -| unsigned\_overflowing\_sub | 68.89 ms | 81.83 ms | 107.63 ms | 120.38 ms | 150.21 ms | 190.39 ms | -| unsigned\_overflowing\_mul | 140.76 ms | 191.85 ms | 272.65 ms | 510.61 ms | 1.34 s | 4.51 s | - -Signed homomorphic integers: - -| Operation\Size | FheInt8 | FheInt16 | FheInt32 | FheInt64 | FheInt128 | FheInt256 | -| ------------------------ | --------- | --------- | --------- | --------- | --------- | --------- | -| signed\_overflowing\_add | 76.54 ms | 84.78 ms | 104.23 ms | 134.38 ms | 162.99 ms | 202.56 ms | -| signed\_overflowing\_sub | 82.46 ms | 86.92 ms | 104.41 ms | 132.21 ms | 168.06 ms | 201.17 ms | -| signed\_overflowing\_mul | 277.91 ms | 365.67 ms | 571.22 ms | 1.21 s | 3.57 s | 12.84 s | diff --git a/tfhe/docs/guides/public_key.md b/tfhe/docs/fhe-computation/advanced-features/public_key.md similarity index 96% rename from tfhe/docs/guides/public_key.md rename to tfhe/docs/fhe-computation/advanced-features/public_key.md index 73771209d3..473fb18fa9 100644 --- a/tfhe/docs/guides/public_key.md +++ b/tfhe/docs/fhe-computation/advanced-features/public_key.md @@ -7,7 +7,7 @@ Public key encryption refers to the cryptographic paradigm where the encryption * **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.](https://eprint.iacr.org/2021/1402) * **Compact public key**: the second method is based on the paper [TFHE Public-Key Encryption Revisited](https://eprint.iacr.org/2023/603), allowing for significantly smaller key sizes compared to the first method. -Public keys can also be [compressed](../fundamentals/compress.md) to reduce size. +Public keys can also be [compressed](../data-handling/compress.md) to reduce size. ## Classical public key diff --git a/tfhe/docs/guides/rayon_crate.md b/tfhe/docs/fhe-computation/advanced-features/rayon_crate.md similarity index 100% rename from tfhe/docs/guides/rayon_crate.md rename to tfhe/docs/fhe-computation/advanced-features/rayon_crate.md diff --git a/tfhe/docs/guides/trivial_ciphertext.md b/tfhe/docs/fhe-computation/advanced-features/trivial_ciphertext.md similarity index 100% rename from tfhe/docs/guides/trivial_ciphertext.md rename to tfhe/docs/fhe-computation/advanced-features/trivial_ciphertext.md diff --git a/tfhe/docs/guides/zk-pok.md b/tfhe/docs/fhe-computation/advanced-features/zk-pok.md similarity index 94% rename from tfhe/docs/guides/zk-pok.md rename to tfhe/docs/fhe-computation/advanced-features/zk-pok.md index bbf00f09cb..3c8fefa7a9 100644 --- a/tfhe/docs/guides/zk-pok.md +++ b/tfhe/docs/fhe-computation/advanced-features/zk-pok.md @@ -74,25 +74,29 @@ pub fn main() -> Result<(), Box> { ``` Performance can be improved by setting `lto="fat"` in `Cargo.toml` + ```toml [profile.release] lto = "fat" ``` + 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`. {% hint style="info" %} -You can choose a more costly proof with `ZkComputeLoad::Proof`, which has a faster verification time. Alternatively, you can select `ZkComputeLoad::Verify` for a faster proof and slower verification. +You can choose a more costly proof with `ZkComputeLoad::Proof`, which has a faster verification time. Alternatively, you can select `ZkComputeLoad::Verify` for a faster proof and slower verification. {% endhint %} ## 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 [Libert](https://eprint.iacr.org/2023/800). -- ZKV2: Differing from the paper, this version provides better performance for provers and verifiers. +* ZKV1: This version is close to the original paper from [Libert](https://eprint.iacr.org/2023/800). +* 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: + ```rust use rand::prelude::*; use tfhe::prelude::*; @@ -150,5 +154,6 @@ pub fn main() -> Result<(), Box> { } ``` -## Benchmark -Please refer to the [Zero-knowledge proof benchmarks](../getting_started/benchmarks/zk_proof_benchmarks.md) for detailed performance benchmark results. +## Benchmark + +Please refer to the [Zero-knowledge proof benchmarks](../../getting_started/benchmarks/zk_proof_benchmarks.md) for detailed performance benchmark results. diff --git a/tfhe/docs/fundamentals/compute.md b/tfhe/docs/fhe-computation/compute/README.md similarity index 100% rename from tfhe/docs/fundamentals/compute.md rename to tfhe/docs/fhe-computation/compute/README.md diff --git a/tfhe/docs/fundamentals/configure-and-generate-keys.md b/tfhe/docs/fhe-computation/compute/configure-and-generate-keys.md similarity index 90% rename from tfhe/docs/fundamentals/configure-and-generate-keys.md rename to tfhe/docs/fhe-computation/compute/configure-and-generate-keys.md index 8654715a67..2ddb9e27b0 100644 --- a/tfhe/docs/fundamentals/configure-and-generate-keys.md +++ b/tfhe/docs/fhe-computation/compute/configure-and-generate-keys.md @@ -4,7 +4,7 @@ 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 [this page](../guides/rust\_configuration.md#homomorphic-types). +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 [this page](../../configuration/rust_configuration.md#homomorphic-types). 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. diff --git a/tfhe/docs/fundamentals/decrypt-data.md b/tfhe/docs/fhe-computation/compute/decrypt-data.md similarity index 100% rename from tfhe/docs/fundamentals/decrypt-data.md rename to tfhe/docs/fhe-computation/compute/decrypt-data.md diff --git a/tfhe/docs/fundamentals/encrypt-data.md b/tfhe/docs/fhe-computation/compute/encrypt-data.md similarity index 100% rename from tfhe/docs/fundamentals/encrypt-data.md rename to tfhe/docs/fhe-computation/compute/encrypt-data.md diff --git a/tfhe/docs/fundamentals/set-the-server-key.md b/tfhe/docs/fhe-computation/compute/set-the-server-key.md similarity index 100% rename from tfhe/docs/fundamentals/set-the-server-key.md rename to tfhe/docs/fhe-computation/compute/set-the-server-key.md diff --git a/tfhe/docs/fhe-computation/data-handling/README.md b/tfhe/docs/fhe-computation/data-handling/README.md new file mode 100644 index 0000000000..1d5f0edcbd --- /dev/null +++ b/tfhe/docs/fhe-computation/data-handling/README.md @@ -0,0 +1 @@ +# Data handling diff --git a/tfhe/docs/fundamentals/compress.md b/tfhe/docs/fhe-computation/data-handling/compress.md similarity index 100% rename from tfhe/docs/fundamentals/compress.md rename to tfhe/docs/fhe-computation/data-handling/compress.md diff --git a/tfhe/docs/guides/data_versioning.md b/tfhe/docs/fhe-computation/data-handling/data_versioning.md similarity index 100% rename from tfhe/docs/guides/data_versioning.md rename to tfhe/docs/fhe-computation/data-handling/data_versioning.md diff --git a/tfhe/docs/fundamentals/serialization.md b/tfhe/docs/fhe-computation/data-handling/serialization.md similarity index 96% rename from tfhe/docs/fundamentals/serialization.md rename to tfhe/docs/fhe-computation/data-handling/serialization.md index 74d6db6ff1..be2ba69f5a 100644 --- a/tfhe/docs/fundamentals/serialization.md +++ b/tfhe/docs/fhe-computation/data-handling/serialization.md @@ -7,6 +7,7 @@ This document explains the `serialization` and `deserialization` features that a When dealing with sensitive types, it's important to implement safe serialization and safe deserialization functions to prevent runtime errors and enhance security. **TFHE-rs** provide easy to use functions for this purpose, such as `safe_serialize`, `safe_deserialize` and `safe_deserialize_conformant`. Here is a basic example on how to use it: + ```rust // main.rs @@ -35,7 +36,7 @@ fn main() { The safe deserialization must take the output of a safe-serialization as input. During the process, the following validation occurs: * **Type match**: deserializing `type A` from a serialized `type B` raises an error indicating "On deserialization, expected type A, got type B". -* **Version compatibility**: data serialized in previous versions of **TFHE-rs** are automatically upgraded to the latest version using the [data versioning](../guides/data\_versioning.md) feature. +* **Version compatibility**: data serialized in previous versions of **TFHE-rs** are automatically upgraded to the latest version using the [data versioning](data_versioning.md) feature. * **Parameter compatibility**: deserializing an object of `type A` with one set of crypto parameters from an object of `type A` with another set of crypto parameters raises an error indicating "Deserialized object of type A not conformant with given parameter set" * If both parameter sets have the same LWE dimension for ciphertexts, a ciphertext from param 1 may not fail this deserialization check with param 2. * This check can't distinguish ciphertexts/server keys from independent client keys with the same parameters. @@ -120,8 +121,7 @@ fn main() { The safe serialization and deserialization use `bincode` internally. -To selectively disable some of the features of the safe serialization, you can use `SerializationConfig`/`DeserializationConfig` builders. -For example, it is possible to disable the data versioning: +To selectively disable some of the features of the safe serialization, you can use `SerializationConfig`/`DeserializationConfig` builders. For example, it is possible to disable the data versioning: ```rust // main.rs @@ -152,8 +152,7 @@ fn main() { **TFHE-rs** uses the [Serde](https://crates.io/crates/serde) framework and implements Serde's `Serialize` and `Deserialize` traits. -This allows you to serialize into any [data format](https://serde.rs/#data-formats) supported by serde. -However, this is a more bare bone approach as none of the checks described in the previous section will be performed for you. +This allows you to serialize into any [data format](https://serde.rs/#data-formats) supported by serde. However, this is a more bare bone approach as none of the checks described in the previous section will be performed for you. In the following example, we use [bincode](https://crates.io/crates/bincode) for its binary format: diff --git a/tfhe/docs/fhe-computation/operations/README.md b/tfhe/docs/fhe-computation/operations/README.md new file mode 100644 index 0000000000..184af05730 --- /dev/null +++ b/tfhe/docs/fhe-computation/operations/README.md @@ -0,0 +1,30 @@ +# Operations + +This document gives a high-level overview of various operations on encrypted integers supported by **TFHE-rs.** + +**TFHE-rs** supports various operations on encrypted integers (`Enc`) of any size between 1 and 256 bits. These operations can also work between encrypted integers and clear integers (`Int`). + +| 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: | +| Less than | `lt` | :heavy\_check\_mark: | :heavy\_check\_mark: | +| Less 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 | `select` | :heavy\_check\_mark: | :heavy\_multiplication\_x: | diff --git a/tfhe/docs/fhe-computation/operations/arithmetic-operations.md b/tfhe/docs/fhe-computation/operations/arithmetic-operations.md new file mode 100644 index 0000000000..e1f4633c31 --- /dev/null +++ b/tfhe/docs/fhe-computation/operations/arithmetic-operations.md @@ -0,0 +1,60 @@ +# Arithmetic operations + +This document details the arithmetic operations supported by **TFHE-rs**. + +Homomorphic integer types (`FheUint` and `FheInt`) support the following arithmetic operations: + +| 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 | + +Specifications for operations with zero: + +* **Division by zero**: returns modulus - 1. + * Example: for FheUint8 (modulus = $$2^8=256$$), dividing by zero returns an ecryption of 255. +* **Remainder operator**: returns the first input unchanged. + * Example: if `ct1 = FheUint8(63)` and `ct2 = FheUint8(0)`, then ct1 % ct2 returns FheUint8(63). + +The following example shows how to perform arithmetic operations: + +```rust +use tfhe::prelude::*; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8, FheUint8}; + +fn main() -> Result<(), Box> { + 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(()) +} +``` diff --git a/tfhe/docs/fhe-computation/operations/bitwise-operations.md b/tfhe/docs/fhe-computation/operations/bitwise-operations.md new file mode 100644 index 0000000000..c90a5bb2e0 --- /dev/null +++ b/tfhe/docs/fhe-computation/operations/bitwise-operations.md @@ -0,0 +1,39 @@ +# Bitwise operations + +This document details the bitwise operations supported by **TFHE-rs**. + +Homomorphic integer types support the following bitwise operations: + +
namesymboltype
Not!Unary
BitAnd&Binary
BitOr|Binary
BitXor^Binary
Shr>>Binary
Shl<<Binary
Rotate Rightrotate_rightBinary
Rotate Leftrotate_leftBinary
+ +The following example shows how to perform bitwise operations: + +```rust +use tfhe::prelude::*; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; + +fn main() -> Result<(), Box> { + 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(()) +} +``` diff --git a/tfhe/docs/fhe-computation/operations/boolean-operations.md b/tfhe/docs/fhe-computation/operations/boolean-operations.md new file mode 100644 index 0000000000..959a8b70c4 --- /dev/null +++ b/tfhe/docs/fhe-computation/operations/boolean-operations.md @@ -0,0 +1,12 @@ +# Boolean Operations + +This document details the Booleans operations supported by **TFHE-rs**. + +Native homomorphic Booleans support the following common Boolean operations: + +| 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/fhe-computation/operations/casting-operations.md b/tfhe/docs/fhe-computation/operations/casting-operations.md new file mode 100644 index 0000000000..521e862a1b --- /dev/null +++ b/tfhe/docs/fhe-computation/operations/casting-operations.md @@ -0,0 +1,63 @@ +# Casting operations + +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: + +```rust +use tfhe::prelude::*; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt16, FheUint8, FheUint32, FheUint16}; + +fn main() -> Result<(), Box> { + 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(()) +} +``` diff --git a/tfhe/docs/fhe-computation/operations/comparison-operations.md b/tfhe/docs/fhe-computation/operations/comparison-operations.md new file mode 100644 index 0000000000..6906ebe62f --- /dev/null +++ b/tfhe/docs/fhe-computation/operations/comparison-operations.md @@ -0,0 +1,58 @@ +# Comparison operations + +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](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) +* [PartialEq](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) + +Supported operations: + +| name | symbol | type | +| --------------------------------------------------------------------------- | ------ | ------ | +| [Equal](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) | `eq` | Binary | +| [Not Equal](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) | `ne` | Binary | +| [Greater Than](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) | `gt` | Binary | +| [Greater or Equal](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) | `ge` | Binary | +| [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 | + +The following example shows how to perform comparison operations: + +```rust +use tfhe::prelude::*; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8}; + +fn main() -> Result<(), Box> { + 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(()) +} +``` diff --git a/tfhe/docs/fhe-computation/operations/min-max-operations.md b/tfhe/docs/fhe-computation/operations/min-max-operations.md new file mode 100644 index 0000000000..86d9ae966b --- /dev/null +++ b/tfhe/docs/fhe-computation/operations/min-max-operations.md @@ -0,0 +1,40 @@ +# Min/Max operations + +This document details the min/max operations supported by **TFHE-rs**. + +Homomorphic integers support the min/max operations: + +| name | symbol | type | +| ---- | ------ | ------ | +| Min | `min` | Binary | +| Max | `max` | Binary | + +The following example shows how to perform min/max operations: + +```rust +use tfhe::prelude::*; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; + +fn main() -> Result<(), Box> { + 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(()) +} +``` diff --git a/tfhe/docs/fhe-computation/operations/ternary-conditional-operations.md b/tfhe/docs/fhe-computation/operations/ternary-conditional-operations.md new file mode 100644 index 0000000000..1652766770 --- /dev/null +++ b/tfhe/docs/fhe-computation/operations/ternary-conditional-operations.md @@ -0,0 +1,54 @@ +# Ternary conditional operations + +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 }`. + +| name | symbol | type | +| ---------------- | -------- | ------- | +| Ternary operator | `select` | Ternary | + +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: + +```rust +use tfhe::prelude::*; +use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt32}; + +fn main() -> Result<(), Box> { + // Basic configuration to use homomorphic integers + let config = ConfigBuilder::default().build(); + + // 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 = encrypted_comp.decrypt(&client_key); + assert_eq!(clear_res, clear_a > clear_b); + + // `encrypted_comp` is a FheBool, thus it encrypts a boolean value. + // This acts as a condition on which the + // `select` function can be applied on. + // Clear equivalent computations: + // if 32 > -45 {result = 32} else {result = -45} + let encrypted_res = &encrypted_comp.select(&encrypted_a, &encrypted_b); + + let clear_res: i32 = encrypted_res.decrypt(&client_key); + assert_eq!(clear_res, clear_a); + + Ok(()) +} +``` diff --git a/tfhe/docs/fhe-computation/tooling/README.md b/tfhe/docs/fhe-computation/tooling/README.md new file mode 100644 index 0000000000..a07e7c8bb9 --- /dev/null +++ b/tfhe/docs/fhe-computation/tooling/README.md @@ -0,0 +1 @@ +# Tooling diff --git a/tfhe/docs/fundamentals/debug.md b/tfhe/docs/fhe-computation/tooling/debug.md similarity index 86% rename from tfhe/docs/fundamentals/debug.md rename to tfhe/docs/fhe-computation/tooling/debug.md index 220f568fd5..893332cf49 100644 --- a/tfhe/docs/fundamentals/debug.md +++ b/tfhe/docs/fhe-computation/tooling/debug.md @@ -2,7 +2,7 @@ This document explains a feature to facilitate debugging. -Starting from **TFHE-rs 0.5**, [trivial ciphertexts](../guides/trivial\_ciphertext.md) 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. +Starting from **TFHE-rs 0.5**, [trivial ciphertexts](../advanced-features/trivial_ciphertext.md) 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. {% hint style="warning" %} Trivial ciphertexts are not secure. An application released/deployed in production must never receive trivial ciphertext from a client. diff --git a/tfhe/docs/guides/pbs-stats.md b/tfhe/docs/fhe-computation/tooling/pbs-stats.md similarity index 91% rename from tfhe/docs/guides/pbs-stats.md rename to tfhe/docs/fhe-computation/tooling/pbs-stats.md index 39575131d3..9a5fab63c4 100644 --- a/tfhe/docs/guides/pbs-stats.md +++ b/tfhe/docs/fhe-computation/tooling/pbs-stats.md @@ -6,7 +6,7 @@ The `shortint` API now includes a global counter to track the number of Programm 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 [`debug mode`](../fundamentals/debug.md), this feature allows for quick estimations during iterations on the FHE code. +When combined with the [`debug mode`](debug.md), this feature allows for quick estimations during iterations on the FHE code. Here is an example of how to use the PBS counter: diff --git a/tfhe/docs/guides/trait_bounds.md b/tfhe/docs/fhe-computation/tooling/trait_bounds.md similarity index 100% rename from tfhe/docs/guides/trait_bounds.md rename to tfhe/docs/fhe-computation/tooling/trait_bounds.md diff --git a/tfhe/docs/fhe-computation/types/README.md b/tfhe/docs/fhe-computation/types/README.md new file mode 100644 index 0000000000..f54cd23d3b --- /dev/null +++ b/tfhe/docs/fhe-computation/types/README.md @@ -0,0 +1 @@ +# Types diff --git a/tfhe/docs/guides/array.md b/tfhe/docs/fhe-computation/types/array.md similarity index 100% rename from tfhe/docs/guides/array.md rename to tfhe/docs/fhe-computation/types/array.md diff --git a/tfhe/docs/fhe-computation/types/integer.md b/tfhe/docs/fhe-computation/types/integer.md new file mode 100644 index 0000000000..d3d9fb88f9 --- /dev/null +++ b/tfhe/docs/fhe-computation/types/integer.md @@ -0,0 +1,23 @@ +# Integer + +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: + +```Rust + // 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)?; +``` diff --git a/tfhe/docs/guides/strings.md b/tfhe/docs/fhe-computation/types/strings.md similarity index 100% rename from tfhe/docs/guides/strings.md rename to tfhe/docs/fhe-computation/types/strings.md diff --git a/tfhe/docs/getting_started/benchmarks/cpu_benchmarks.md b/tfhe/docs/getting_started/benchmarks/cpu_benchmarks.md index 0b675c28a9..0827d056ad 100644 --- a/tfhe/docs/getting_started/benchmarks/cpu_benchmarks.md +++ b/tfhe/docs/getting_started/benchmarks/cpu_benchmarks.md @@ -22,7 +22,7 @@ The next table shows the operation timings on CPU when the left input is encrypt 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](../../references/fine-grained-apis/quick\_start.md), each balancing performance and correctness differently. For more details about parameters, see [here](../../references/fine-grained-apis/shortint/parameters.md). You can find the benchmark results on GPU for all these operations [here](../../guides/run\_on\_gpu.md#benchmarks). +You can minimize operational costs by selecting from 'unchecked', 'checked', or 'smart' modes from [the fine-grained APIs](../../references/fine-grained-apis/quick_start.md), each balancing performance and correctness differently. For more details about parameters, see [here](../../references/fine-grained-apis/shortint/parameters.md). You can find the benchmark results on GPU for all these operations [here](../../configuration/run_on_gpu.md#benchmarks). ## Programmable bootstrapping diff --git a/tfhe/docs/getting_started/benchmarks/zk_proof_benchmarks.md b/tfhe/docs/getting_started/benchmarks/zk_proof_benchmarks.md index d6836b20e3..232aab897b 100644 --- a/tfhe/docs/getting_started/benchmarks/zk_proof_benchmarks.md +++ b/tfhe/docs/getting_started/benchmarks/zk_proof_benchmarks.md @@ -1,7 +1,7 @@ # Zero-knowledge proof benchmarks -This document details the performance benchmarks of [zero-knowledge proofs](../../guides/zk-pok.md) for [compact public key encryption](../../guides/public_key.md) using **TFHE-rs**. +This document details the performance benchmarks of [zero-knowledge proofs](../../fhe-computation/advanced-features/zk-pok.md) for [compact public key encryption](../../fhe-computation/advanced-features/public_key.md) using **TFHE-rs**. -Benchmarks for the zero-knowledge proofs have been run on a `m6i.4xlarge` with 16 cores to simulate an usual client configuration. The verification are done on a `hpc7a.96xlarge` AWS instances to mimic a powerful server. +Benchmarks for the zero-knowledge proofs have been run on a `m6i.4xlarge` with 16 cores to simulate an usual client configuration. The verification are done on a `hpc7a.96xlarge` AWS instances to mimic a powerful server. {% embed url="https://docs.google.com/spreadsheets/d/1x12I7Tkdx63Q6sNllygg6urSd5KC1sj1wj4L9jWiET4/edit?usp=sharing" %} diff --git a/tfhe/docs/getting_started/operations.md b/tfhe/docs/getting_started/operations.md deleted file mode 100644 index 4f822fe797..0000000000 --- a/tfhe/docs/getting_started/operations.md +++ /dev/null @@ -1,384 +0,0 @@ -# Types & Operations - -This document explains the encryption types and operations supported by **TFHE-rs.** - -## Types - -**TFHE-rs** supports two main types of encrypted data: - -* `FheUint`: homomorphic equivalent of Rust unsigned integers `u8, u16, ...` -* `FheInt`: homomorphic equivalent of Rust signed integers `i8, i16, ...` - -### Integer - -**TFHE-rs** uses integers to encrypt all messages which are larger than 4 bits. - -Similar to Rust integers, you need to specify the bit size of data when declaring a variable: - -```Rust - // let clear_a: u64 = 7; - let mut a = FheUint64::try_encrypt(clear_a, &keys)?; - - // let clear_b: i8 = 3; - let mut b = FheInt8::try_encrypt(clear_b, &keys)?; - - // let clear_c: u128 = 2; - let mut c = FheUint128::try_encrypt(clear_c, &keys)?; -``` - -## Operations - -**TFHE-rs** supports various operations on encrypted integers (`Enc`) of any size between 1 and 256 bits. These operations can also work between encrypted integers and clear integers (`Int`). - -| 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: | -| Less than | `lt` | :heavy\_check\_mark: | :heavy\_check\_mark: | -| Less 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 | `select` | :heavy\_check\_mark: | :heavy\_multiplication\_x: | - -### Arithmetic operations - -Homomorphic integer types (`FheUint` and `FheInt`) support the following arithmetic operations: - -| 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 | - -Specifications for operations with zero: - -* **Division by zero**: returns modulus - 1. - * Example: for FheUint8 (modulus = $$2^8=256$$), dividing by zero returns an ecryption of 255. -* **Remainder operator**: returns the first input unchanged. - * Example: if `ct1 = FheUint8(63)` and `ct2 = FheUint8(0)`, then ct1 % ct2 returns FheUint8(63). - -The following example shows how to perform arithmetic operations: - -```rust -use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8, FheUint8}; - -fn main() -> Result<(), Box> { - 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(()) -} -``` - -### Bitwise operations - -Homomorphic integer types support the following bitwise operations: - -| name | symbol | type | -| ------------------------------------------------------------------------------------- | -------------- | ------ | -| [Not](https://doc.rust-lang.org/std/ops/trait.Not.html) | `!` | Unary | -| [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 | -| [Shr](https://doc.rust-lang.org/std/ops/trait.Shr.html) | `>>` | Binary | -| [Shl](https://doc.rust-lang.org/std/ops/trait.Shl.html) | `<<` | Binary | -| [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 | - -The following example shows how to perform bitwise operations: - -```rust -use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; - -fn main() -> Result<(), Box> { - 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(()) -} -``` - -### Comparison operations - -Homomorphic integers support comparison operations. However, due to Rust's limitations, you cannot overload comparison symbols. This is because Rust requires Boolean outputs from such operations, but homomorphic types return ciphertexts. Therefore, you should use the following methods, which conform to the naming conventions of Rust’s standard traits: - -* [PartialOrd](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) -* [PartialEq](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) - -Supported operations: - -| name | symbol | type | -| --------------------------------------------------------------------------- | ------ | ------ | -| [Equal](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) | `eq` | Binary | -| [Not Equal](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html) | `ne` | Binary | -| [Greater Than](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) | `gt` | Binary | -| [Greater or Equal](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) | `ge` | Binary | -| [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 | - -The following example shows how to perform comparison operations: - -```rust -use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt8}; - -fn main() -> Result<(), Box> { - 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(()) -} -``` - -### Min/Max operations - -Homomorphic integers support the min/max operations: - -| name | symbol | type | -| ---- | ------ | ------ | -| Min | `min` | Binary | -| Max | `max` | Binary | - -The following example shows how to perform min/max operations: - -```rust -use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheUint8}; - -fn main() -> Result<(), Box> { - 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(()) -} -``` - -### Ternary conditional operations - -The ternary conditional operator execute conditional instructions in the form `if cond { choice_if_true } else { choice_if_false }`. - -| name | symbol | type | -| ---------------- |----------| ------- | -| Ternary operator | `select` | Ternary | - -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: - -```rust -use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt32}; - -fn main() -> Result<(), Box> { - // Basic configuration to use homomorphic integers - let config = ConfigBuilder::default().build(); - - // 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 = encrypted_comp.decrypt(&client_key); - assert_eq!(clear_res, clear_a > clear_b); - - // `encrypted_comp` is a FheBool, thus it encrypts a boolean value. - // This acts as a condition on which the - // `select` function can be applied on. - // Clear equivalent computations: - // if 32 > -45 {result = 32} else {result = -45} - let encrypted_res = &encrypted_comp.select(&encrypted_a, &encrypted_b); - - let clear_res: i32 = encrypted_res.decrypt(&client_key); - assert_eq!(clear_res, clear_a); - - Ok(()) -} -``` - -### Casting operations - -You can cast between integer types using either the `cast_from` associated function or the `cast_into` method. - -The following example shows how to perform casting operations: - -```rust -use tfhe::prelude::*; -use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheInt16, FheUint8, FheUint32, FheUint16}; - -fn main() -> Result<(), Box> { - 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(()) -} -``` - -### Boolean Operations - -Native homomorphic Booleans support the following common Boolean operations: - -| 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/getting_started/quick_start.md b/tfhe/docs/getting_started/quick_start.md index fd8c8c550e..43aa3d0015 100644 --- a/tfhe/docs/getting_started/quick_start.md +++ b/tfhe/docs/getting_started/quick_start.md @@ -4,7 +4,7 @@ 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](#using-tfhe-rs-and-its-apis). +If you already know how to set up a Rust project, feel free to go directly to the next [section](quick_start.md#using-tfhe-rs-and-its-apis). 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](https://rust-lang.github.io/rustup/installation/other.html). @@ -79,11 +79,11 @@ If you are on a different platform please refer to the [installation documentati 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](../fundamentals/configure-and-generate-keys.md) -3. Client-side: [encrypt data](../fundamentals/encrypt-data.md) -4. Server-side: [set the server key](../fundamentals/set-the-server-key.md) -5. Server-side: [compute over encrypted data](../fundamentals/compute.md) -6. Client-side: [decrypt data](../fundamentals/decrypt-data.md) +2. Client-side: [configure and generate keys](../fhe-computation/compute/configure-and-generate-keys.md) +3. Client-side: [encrypt data](../fhe-computation/compute/encrypt-data.md) +4. Server-side: [set the server key](../fhe-computation/compute/set-the-server-key.md) +5. Server-side: [compute over encrypted data](../fhe-computation/compute/) +6. Client-side: [decrypt data](../fhe-computation/compute/decrypt-data.md) This example demonstrates the basic workflow combining the client and server parts: @@ -116,4 +116,4 @@ fn main() { } ``` -You can learn more about homomorphic types and associated compilation features in the [configuration documentation.](../guides/rust\_configuration.md) +You can learn more about homomorphic types and associated compilation features in the [configuration documentation.](../configuration/rust_configuration.md) diff --git a/tfhe/docs/guides/c_api.md b/tfhe/docs/integration/c_api.md similarity index 100% rename from tfhe/docs/guides/c_api.md rename to tfhe/docs/integration/c_api.md diff --git a/tfhe/docs/guides/js_on_wasm_api.md b/tfhe/docs/integration/js_on_wasm_api.md similarity index 100% rename from tfhe/docs/guides/js_on_wasm_api.md rename to tfhe/docs/integration/js_on_wasm_api.md diff --git a/tfhe/docs/tutorials/ascii_fhe_string.md b/tfhe/docs/tutorials/ascii_fhe_string.md index 979529481d..d9b8ce9bb3 100644 --- a/tfhe/docs/tutorials/ascii_fhe_string.md +++ b/tfhe/docs/tutorials/ascii_fhe_string.md @@ -3,10 +3,9 @@ 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. {% hint style="info" %} -Since version 0.11, **TFHE-rs** has introduced the `strings` feature, which provides an easy to use FHE strings API. See the [fhe strings guide](../guides/strings.md) for more information. +Since version 0.11, **TFHE-rs** has introduced the `strings` feature, which provides an easy to use FHE strings API. See the [fhe strings guide](../fhe-computation/types/strings.md) for more information. {% endhint %} - 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] @@ -159,9 +158,11 @@ fn main() { ``` ## 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` + ```toml # Cargo.toml @@ -170,6 +171,7 @@ tfhe = { version = "1.0.0", features = ["strings"] } ``` The `FheAsciiString` type allows to simply do homomorphic case changing of encrypted strings (and much more!): + ```rust use tfhe::prelude::*; use tfhe::{generate_keys, set_server_key, ConfigBuilder, FheAsciiString}; @@ -198,4 +200,4 @@ fn main() { } ``` -You can read more about this in the [FHE strings documentation](../guides/strings.md) +You can read more about this in the [FHE strings documentation](../fhe-computation/types/strings.md) diff --git a/tfhe/src/test_user_docs.rs b/tfhe/src/test_user_docs.rs index 257f98b163..6b07880567 100644 --- a/tfhe/src/test_user_docs.rs +++ b/tfhe/src/test_user_docs.rs @@ -5,66 +5,123 @@ mod test_cpu_doc { // README doctest!("../../README.md", readme); - // FUNDAMENTALS - doctest!("../docs/fundamentals/compress.md", fundamentals_compress); - doctest!("../docs/fundamentals/compute.md", fundamentals_compute); + // CONGFIGURATION doctest!( - "../docs/fundamentals/configure-and-generate-keys.md", - fundamentals_configure_and_generate_keys + "../docs/configuration/parallelized_pbs.md", + configuration_parallelized_pbs ); - doctest!("../docs/fundamentals/debug.md", fundamentals_debug); doctest!( - "../docs/fundamentals/decrypt-data.md", - fundamentals_decrypt_data + "../docs/configuration/rust_configuration.md", + configuration_rust_configuration + ); + + // FHE COMPUTATION + + // ADVANCED FEATURES + doctest!( + "../docs/fhe-computation/advanced-features/encrypted-prf.md", + advanced_features_encrypted_prf + ); + doctest!( + "../docs/fhe-computation/advanced-features/overflow_operations.md", + advanced_features_overflow_operations ); doctest!( - "../docs/fundamentals/encrypt-data.md", - fundamentals_encrypt_data + "../docs/fhe-computation/advanced-features/public_key.md", + advanced_features_public_key ); doctest!( - "../docs/fundamentals/encrypted-prf.md", - fundamentals_encrypted_prf + "../docs/fhe-computation/advanced-features/rayon_crate.md", + advanced_features_rayon_crate ); doctest!( - "../docs/fundamentals/serialization.md", - fundamentals_serialization + "../docs/fhe-computation/advanced-features/trivial_ciphertext.md", + advanced_features_trivial_ciphertext ); doctest!( - "../docs/fundamentals/set-the-server-key.md", - fundamentals_set_the_server_key + "../docs/fhe-computation/advanced-features/zk-pok.md", + advanced_features_zk_pok ); - // GETTING STARTED + // COMPUTE doctest!( - "../docs/getting_started/operations.md", - getting_started_operations + "../docs/fhe-computation/compute/configure-and-generate-keys.md", + compute_configure_and_generate_keys ); doctest!( - "../docs/getting_started/quick_start.md", - getting_started_quick_start + "../docs/fhe-computation/compute/decrypt-data.md", + compute_decrypt_data + ); + doctest!( + "../docs/fhe-computation/compute/encrypt-data.md", + compute_encrypt_data + ); + doctest!("../docs/fhe-computation/compute/README.md", compute_readme); + doctest!( + "../docs/fhe-computation/compute/set-the-server-key.md", + compute_set_the_server_key + ); + + // DATA HANDLING + doctest!( + "../docs/fhe-computation/data-handling/compress.md", + data_handling_compress + ); + doctest!( + "../docs/fhe-computation/data-handling/data_versioning.md", + data_handling_data_versioning + ); + doctest!( + "../docs/fhe-computation/data-handling/serialization.md", + data_handling_serialization ); - // GUIDES - doctest!("../docs/guides/array.md", array); + // OPERATIONS doctest!( - "../docs/guides/overflow_operations.md", - guides_overflow_operations + "../docs/fhe-computation/operations/arithmetic-operations.md", + operations_arithmetic_operations ); doctest!( - "../docs/guides/parallelized_pbs.md", - guides_parallelized_pbs + "../docs/fhe-computation/operations/bitwise-operations.md", + operations_bitwise_operations ); - doctest!("../docs/guides/pbs-stats.md", guides_pbs_stats); - doctest!("../docs/guides/public_key.md", guides_public_key); - doctest!("../docs/guides/rayon_crate.md", guides_rayon_crate); - doctest!("../docs/guides/strings.md", guides_strings); - doctest!("../docs/guides/trait_bounds.md", guides_trait_bounds); doctest!( - "../docs/guides/trivial_ciphertext.md", - guides_trivial_ciphertext + "../docs/fhe-computation/operations/casting-operations.md", + operations_casting_operations + ); + doctest!( + "../docs/fhe-computation/operations/comparison-operations.md", + operations_comparison_operations + ); + doctest!( + "../docs/fhe-computation/operations/min-max-operations.md", + operations_min_max_operations + ); + doctest!( + "../docs/fhe-computation/operations/ternary-conditional-operations.md", + operations_ternary_conditional_operations + ); + + // TOOLING + doctest!("../docs/fhe-computation/tooling/debug.md", tooling_debug); + doctest!( + "../docs/fhe-computation/tooling/pbs-stats.md", + tooling_pbs_stats + ); + doctest!( + "../docs/fhe-computation/tooling/trait_bounds.md", + tooling_trait_bounds + ); + + // TYPES + doctest!("../docs/fhe-computation/types/array.md", types_array); + doctest!("../docs/fhe-computation/types/strings.md", types_strings); + + // GETTING STARTED + doctest!( + "../docs/getting_started/quick_start.md", + getting_started_quick_start ); - doctest!("../docs/guides/zk-pok.md", guides_zk_pok); - doctest!("../docs/guides/data_versioning.md", guides_data_versioning); // REFERENCES @@ -146,5 +203,8 @@ mod test_cpu_doc { mod test_gpu_doc { use doc_comment::doctest; - doctest!("../docs/guides/run_on_gpu.md", guides_run_on_gpu); + doctest!( + "../docs/configuration/run_on_gpu.md", + configuration_run_on_gpu + ); }