Theme: 

1. Introduction

This documentation is also available online.

1.1. About TFHE-Java

TFHE-Java is a comprehensive Java library that provides high-level bindings to TFHE-rs, leveraging Java’s Foreign Function & Memory (FFM) API to deliver fully homomorphic encryption capabilities to the JVM ecosystem.
The project enables developers to perform computations on encrypted data without decrypting it, maintaining data privacy and security throughout the entire computation lifecycle.

Built on top of the battle-tested TFHE-rs native library from Zama, TFHE-Java brings the power of fully homomorphic encryption to Java applications while maintaining type safety, memory safety, and idiomatic Java programming patterns.

1.2. Understanding the TFHE Scheme

TFHE (Torus Fully Homomorphic Encryption) is a fully homomorphic encryption scheme that enables fast homomorphic operations on encrypted data.
The scheme is based on the Learning With Errors problem, which is considered resistant to quantum attacks, making it a future-proof cryptographic solution.

1.2.1. Core Cryptographic Concepts

The TFHE scheme operates on several fundamental concepts:

1.2.2. Key Types and Their Roles

TFHE employs multiple key types, each serving a specific purpose in the encryption workflow:

  • Client Key: The secret key used for encryption and decryption.
    This key must remain private and secure on the client side.
    It serves as the root of trust for all cryptographic operations.

  • Server Key: A public evaluation key that enables homomorphic operations on encrypted data.
    The server can perform computations without being able to decrypt the data, ensuring privacy.

  • Public Key: An optional key derived from the client key that allows third parties to encrypt data without possessing the secret key.
    Useful for scenarios where multiple parties need to encrypt data for a single recipient.

  • Bootstrapping Key and Key Switching Key: Specialized evaluation keys required for advanced operations like programmable bootstrapping and keyswitch operations.

1.2.3. Security Foundation

The security of TFHE rests on the computational hardness of the Learning With Errors problem.
The scheme provides:

  • Quantum Resistance: The LWE problem is believed to be resistant to attacks by quantum computers, unlike traditional RSA or elliptic curve cryptography.

  • Semantic Security: Ciphertexts reveal no information about the underlying plaintext, even when multiple ciphertexts of the same value are observed.

  • Configurable Security Levels: Parameters like LWE dimension and noise distribution allow users to tune the security level versus performance trade-off.

Additional security features include zero-knowledge proofs for verifying computation correctness without revealing sensitive information, as detailed in the TFHE Deep Dive series.

1.3. Main Features

TFHE-Java provides a rich set of features for building privacy-preserving applications:

1.3.1. Comprehensive Type System

  • Boolean Operations: Native FHE boolean type supporting all logical operations (AND, OR, XOR, NOT)

  • Integer Types: Full spectrum of signed and unsigned integers

    • Signed integers: FheInt2 through FheInt2048 (2, 4, 6, 8, 10, 12, 14, 16, 32, 64, 128, 160, 256, 512, 1024, 2048 bits)

    • Unsigned integers: FheUint2 through FheUint2048 (same bit sizes as signed)

  • Array Types: Homomorphic arrays for batch operations on multiple encrypted values

  • High Precision: Support for arbitrary-precision arithmetic using BigInteger for types beyond 64 bits

1.3.2. Rich Operation Set

  • Arithmetic Operations: Addition, subtraction, multiplication, division, modulo, and negation

  • Bitwise Operations: AND, OR, XOR, NOT, shifts (left/right, logical/arithmetic), and rotations

  • Comparison Operations: Equal, not equal, less than, greater than, less than or equal, greater than or equal

  • Conditional Operations: Ternary conditional (if-then-else), min/max operations

  • Type Conversions: Casting between different integer types and bit widths

1.3.3. Advanced Capabilities

  • Compressed Representations: Compact storage format for ciphertexts and keys to reduce memory footprint and transmission costs

  • Serialization/Deserialization: Full support for persisting and transmitting encrypted data and keys

  • Public Key Encryption: Enable third-party encryption without sharing the secret key

  • Trivial Ciphertexts: Efficient mixing of encrypted and plaintext values in computations

  • Zero-Knowledge Proofs: Verify computation correctness without revealing sensitive information

  • Configurable Parameters: Fine-grained control over security levels, performance characteristics, and noise distributions

1.3.4. Integration Features

  • Foreign Function & Memory API: Direct memory access to native TFHE-rs library using Java’s modern FFM API (no JNI overhead)

  • Type Safety: Strong Java type system prevents common cryptographic implementation errors

  • Memory Safety: Automatic resource management using Java’s try-with-resources and AutoCloseable patterns

  • Comprehensive Testing: Extensive test suite with BDD-style living documentation

  • Cross-Platform Support: Native libraries for macOS (ARM64/x86_64), Linux, and Windows

1.4. Data Structures and TFHE Workflows

1.4.1. Core Data Structures

Ciphertexts and Keys

The fundamental data structures in TFHE-Java mirror the underlying cryptographic primitives:

  • FHE Value Types (FheBool, FheInt*, FheUint*): Wrapper classes representing encrypted values.
    Each instance encapsulates an LWE ciphertext and provides type-safe operations.

  • Compressed Types (CompressedFheBool, CompressedFheInt*, CompressedFheUint*): Space-efficient representations that reduce storage and transmission overhead.
    Must be decompressed before performing homomorphic operations.

  • Array Types (FheBoolArray, FheInt*Array, FheUint*Array): Collections of encrypted values supporting batch operations and element-wise computations.

  • Key Objects:

    • ClientKey: Encapsulates the client key for encryption/decryption

    • ServerKey: Encapsulates the server key for homomorphic operations

    • PublicKey: Encapsulates the public key for third-party encryption

    • CompressedServerKey / CompressedPublicKey: Compressed key representations

Configuration Objects

  • ConfigBuilder: Fluent API for constructing TFHE configurations with custom parameters

  • Parameter Objects: Encapsulate cryptographic parameters like LWE dimension, polynomial sizes, noise distribution, and security levels

  • Noise Distributions: TUniform and centered normal distributions for controlling the random noise characteristics

1.4.2. Standard TFHE Workflow

A typical TFHE computation follows this workflow:

1. Configuration and Key Generation
// Create configuration (client-side)
Config config = new ConfigBuilder().build();

// Generate keys
KeySet keys = config.generateKeys();
ClientKey clientKey = keys.clientKey();
ServerKey serverKey = keys.serverKey();

The configuration defines the cryptographic parameters.
The key generation produces both the private client key and the public server key.

2. Data Encryption (Client-Side)
// Encrypt data using client key
FheUint32 encryptedValue = FheUint32.encrypt(42, clientKey);

// Or use public key for third-party encryption
PublicKey publicKey = PublicKey.newWith(clientKey);
FheUint32 encryptedValue2 = FheUint32.encrypt(100, publicKey);

Plaintext data is encrypted into ciphertexts that can be safely transmitted to untrusted servers.

3. Secure Transmission
// Serialize encrypted data for transmission
Buffer serializedData = encryptedValue.serialize();

// Serialize server key for computation
Buffer serializedServerKey = serverKey.serialize();

// Send to server...

Encrypted data and the server key are serialized and transmitted to the computation server.
The client key never leaves the client.

4. Homomorphic Computation (Server-Side)
// Deserialize on server
ServerKey serverKey = ServerKey.deserialize(serializedServerKey);
FheUint32 value1 = FheUint32.deserialize(serializedData1);
FheUint32 value2 = FheUint32.deserialize(serializedData2);

// Set server key for operations
serverKey.setAsKey();

// Perform homomorphic operations
FheUint32 sum = value1.add(value2);
FheUint32 product = sum.mul(value1);
FheUint32 result = product.bitwiseAnd(value2);

The server performs homomorphic operations on encrypted data using the server key.
The server cannot decrypt the data but can compute on it.
Operations like addition, multiplication, and bitwise operations are performed without revealing the underlying values.

5. Result Decryption (Client-Side)
// Serialize result for transmission back to client
Buffer serializedResult = result.serialize();

// Deserialize and decrypt on client
FheUint32 encryptedResult = FheUint32.deserialize(serializedResult);
int plainResult = encryptedResult.decrypt(clientKey);

The encrypted result is sent back to the client, where it is decrypted using the client key to obtain the final plaintext result.

1.4.3. Advanced Workflows

Compressed Ciphertext Workflow

For bandwidth-constrained environments:

// Client compresses before transmission
CompressedFheUint32 compressed = encryptedValue.compress();
Buffer serialized = compressed.serialize();

// Server decompresses before computation
CompressedFheUint32 compressedReceived = CompressedFheUint32.deserialize(serialized);
FheUint32 decompressed = compressedReceived.decompress();
serverKey.setAsKey();
FheUint32 result = decompressed.add(otherValue);

Ciphertexts can be compressed to reduce transmission size, then decompressed on the server before computation.

Trivial Ciphertext Workflow

For mixing encrypted and public constants:

// Create trivial ciphertext from public value
FheUint32 trivial = FheUint32.tryEncryptTrivial(42);

// Mix with encrypted values
serverKey.setAsKey();
FheUint32 result = encryptedValue.add(trivial);

Trivial ciphertexts allow efficient mixing of public constants with encrypted data without the overhead of full encryption.

Noise Management

Noise accumulates during operations and must be managed:

  • Leveled Operations: Fast operations that increase noise (additions, subtractions, bitwise operations)

  • Programmable Bootstrapping: Reduces noise while computing functions (multiplications, comparisons, non-linear operations)

  • Padding Bits: Reserve space in the most significant bits to handle carries and prevent overflow

The TFHE-rs library automatically manages bootstrapping and key switching operations to maintain correctness, abstracting away much of the complexity from the developer.

1.5. Additional Resources

For deeper understanding of TFHE concepts and implementations, refer to:

For terminology clarification, please consult the Glossary.
All referenced materials are listed in the Bibliography.

2. Summary

Scenarios Steps Features: 2

Passed

Failed

Total

Passed

Failed

Skipped

Pending

Undefined

Missing

Total

Duration

Status

Glossary

1

0

1

0

0

0

0

0

0

0

000ms

passed

Bibliography

1

0

1

0

0

0

0

0

0

0

000ms

passed

Totals

2

0

2

0

0

0

0

0

0

0

000ms

Glossary

Body

The second component of an LWE ciphertext, computed as the sum of the mask elements multiplied by the secret key elements plus the plaintext.

Bootstrapping

An operation that reduces noise in ciphertexts while maintaining the encrypted data. In TFHE, bootstrapping is programmable, allowing functions to be computed during the noise reduction process.

Bootstrapping Key

A public evaluation key required for performing Programmable Bootstrapping operations.

Carry

Extra bits that may be needed when operations on encrypted values exceed the original interval. TFHE-rs uses padding bits on the most significant bits to accommodate carries.

Ciphertext

An encrypted value consisting of a mask and body, computed using an LWE secret key. Fresh ciphertexts result from encryption, while derived ciphertexts result from operations.

Client Key

The secret key used by the client to encrypt and decrypt data. It must be kept private and secure.

FHE

Fully Homomorphic Encryption - a cryptographic scheme that allows arbitrary computations on encrypted data without decrypting it.

GLWE

Generalized Learning With Errors - an extension of LWE that operates on polynomials rather than single values, used in TFHE for certain operations.

Homomorphic Operation

An operation performed on encrypted data that produces an encrypted result corresponding to the operation on the plaintext data.

Keyswitch

An operation that changes the encryption key of a ciphertext, typically used before or after bootstrapping to ensure input and output are encrypted under the same key.

Key switching Key

A public evaluation key required for performing keyswitch operations.

Leveled Operation

A homomorphic operation that increases the noise in ciphertexts. These operations are typically fast but require noise management.

LWE

Learning With Errors - the mathematical problem that forms the basis of TFHE security. It is considered resistant to quantum attacks.

LWE Ciphertext

A ciphertext based on the Learning With Errors problem, consisting of a mask (list of random values) and a body (computed value).

LWE Dimension

The parameter 'n' representing the number of elements in the LWE secret key, which directly affects security level and performance.

Mask

The first component of an LWE ciphertext, consisting of a list of uniformly random values used in the encryption process.

Noise

Random values added to plaintexts during encryption to ensure security. Noise is encoded in the least significant bits and grows with leveled operations.

Noise Distribution

The statistical distribution from which noise values are drawn, either Centered Normal Distribution or Tweaked Uniform (TUniform) Distribution.

Padding

Additional bits defined on the most significant bits of encoded values to prevent precision loss or wraparound when operations produce results outside the original interval.

PBS

Programmable BootStrapping - a core TFHE operation that both reduces noise and computes arbitrary functions represented as look-up tables.

Plaintext

An encoded message prepared for encryption by shifting the message to the most significant bits and adding noise to the least significant bits.

Public Key

A key derived from the client key that allows encryption without revealing the secret key, enabling third parties to encrypt data.

Secret Key

The private key consisting of n random integers used to encrypt and decrypt LWE ciphertexts. Also known as the LWE secret key.

Server Key

The public evaluation key used by the server to perform homomorphic operations on encrypted data without being able to decrypt it.

TFHE

Torus Fully Homomorphic Encryption - a FHE scheme that enables fast homomorphic operations on booleans, integers, and reals using Learning With Errors over the torus.

TFHE-rs

A pure Rust implementation of the TFHE scheme for Boolean and integer arithmetics over encrypted data, including Rust, C, and WASM APIs.

Trivial Ciphertext

A ciphertext created without actual encryption, where the plaintext value is publicly known. Useful for mixing encrypted and unencrypted values in operations.

TUniform

Tweaked Uniform Distribution - a bounded noise distribution where values in the interval (-2^b, …​, 2^b) are selected with specific probabilities.

Zero-Knowledge Proof

A cryptographic protocol that allows one party to prove to another that a statement is true without revealing any information beyond the validity of the statement itself.

Bibliography

  • [github-repo] Project repository, GitHub Repository

  • [github-doc] Project documentation, GitHub Pages

  • [fhe-org] FHE.org - Fully Homomorphic Encryption Community, fhe.org

  • [zama-ai] Zama - Fully Homomorphic Encryption Solutions, zama.ai

  • [tfhe-rs-repo] TFHE-rs Repository, TFHE-rs GitHub

  • [tfhe-rs-handbook] TFHE-rs Handbook - Algorithm Documentation, TFHE-rs Handbook

  • [tfhe-deep-dive-1] TFHE Deep Dive - Part I - Ciphertext types, Zama Blog

  • [tfhe-deep-dive-2] TFHE Deep Dive - Part II - Encodings and linear leveled operations, Zama Blog

  • [tfhe-deep-dive-3] TFHE Deep Dive - Part III - Key switching and leveled multiplications, Zama Blog

  • [tfhe-deep-dive-4] TFHE Deep Dive - Part IV - Programmable Bootstrapping, Zama Blog

  • [zama-community] Zama Community Forum, Zama Community

  • [fhe-org-discord] FHE.org Discord Community, Discord

  • [tfhe-iacr-paper] Guide to Fully Homomorphic Encryption over the Discretized Torus, IACR ePrint