TenSEAL

Common errors

• RuntimeError: TenSEAL decryption error: input ciphertext does not have a matching public key

  cause The context used for decryption does not contain the correct secret key matching the one used for encryption, or the ciphertext itself is corrupted.
  fix Ensure the `context` object used for decryption (or the `secret_context` argument in `decrypt()`) is the exact same one (or a properly reconstructed one with the same secret key) that was used to create the encrypted data.

• ValueError: input vector has wrong size

  cause Attempting an operation between two TenSEAL vectors (or a vector and a plaintext array) where their dimensions are incompatible or do not match the expected size for the operation.
  fix Verify the length/shape of all input vectors involved in an operation. Ensure they are compatible according to TenSEAL's rules for the specific operation (e.g., element-wise addition requires same size).

• AttributeError: module 'tenseal' has no attribute 'context'

  cause This usually indicates attempting to access `context` or other core TenSEAL components directly as a top-level module attribute without proper import aliasing, or `tenseal` is not correctly installed.
  fix Ensure `tenseal` is installed and use `import tenseal as ts`, then access components via `ts.context(...)`, `ts.ckks_vector(...)`, etc.

Warnings

• breaking Support for Python 3.7 was dropped in TenSEAL v0.3.15. Projects requiring Python 3.7 must use TenSEAL v0.3.14 or earlier.
  Fix: Upgrade to Python 3.8 or newer, or pin TenSEAL to version <=0.3.14.
• gotcha The choice of homomorphic encryption parameters (e.g., `poly_mod_degree`, `coeff_mod_bit_sizes`, `global_scale`) is crucial for both security and functionality. Incorrect parameters can lead to insecure encryption, operations failing, or insufficient precision.
  Fix: Carefully consult TenSEAL and SEAL documentation for appropriate parameter selection based on security requirements, desired precision, and the complexity of operations. Start with recommended parameters for common schemes.
• gotcha Performance of homomorphic encryption operations is significantly lower than plaintext operations. Large vectors, high polynomial degrees, or complex operations can be very resource-intensive.
  Fix: Optimize vector sizes, choose the smallest secure parameters, and consider algorithmic changes to reduce the number or complexity of encrypted operations. Use TenSEAL's built-in optimized operations where possible.
• gotcha Updates to the underlying Microsoft SEAL library (e.g., in v0.3.9, v0.3.13, v0.3.14) can subtly change behavior, default parameters, or introduce new features. While TenSEAL aims for abstraction, parameter-sensitive operations might be affected.
  Fix: After upgrading TenSEAL to a new minor version (especially one that updates the underlying SEAL version), review and re-validate your encryption context parameters and test critical operations.

Install

• pip install tenseal Install TenSEAL

Imports

• context
  wrong:

  from tenseal import context

  correct:

  import tenseal as ts
  ctx = ts.context(...)

  While `from tenseal import context` might work for some IDEs, the idiomatic and most stable way to access core components like `context`, `ckks_vector`, etc., is via `import tenseal as ts` due to the library's structure.
• CKKSVector

  import tenseal as ts
  ciph = ts.ckks_vector(...)

• BFVVector

  import tenseal as ts
  ciph = ts.bfv_vector(...)

Quickstart

This quickstart demonstrates setting up a TenSEAL context for the CKKS scheme, encrypting two vectors, performing homomorphic addition on them, and then decrypting the result. It highlights the critical steps of context initialization, key generation, and scale setting for encrypted computations.

import tenseal as ts

# 1. Setup TenSEAL Context for CKKS scheme
# These parameters are critical for security and functionality.
poly_mod_degree = 8192
coeff_mod_bit_sizes = [60, 40, 40, 60]

# Create a TenSEAL context
context = ts.context(
    ts.SCHEME_TYPE.CKKS,
    poly_mod_degree=poly_mod_degree,
    coeff_mod_bit_sizes=coeff_mod_bit_sizes
)

# Generate keys for homomorphic operations (e.g., rotations, relinearization for multiplication)
context.generate_galois_keys()
context.generate_relin_keys()

# Set the scale for CKKS scheme
# The scale defines the precision of computations.
scale = 2**40
context.global_scale = scale

# 2. Encrypt some data
vector1 = [0, 1, 2, 3, 4]
vector2 = [5, 6, 7, 8, 9]

encrypted_vector1 = ts.ckks_vector(context, vector1)
encrypted_vector2 = ts.ckks_vector(context, vector2)

# 3. Perform homomorphic operations (e.g., addition)
encrypted_sum = encrypted_vector1 + encrypted_vector2

# 4. Decrypt and verify
# The decryption operation uses the secret key from the context.
decrypted_sum = encrypted_sum.decrypt()

print(f"Original vector 1: {vector1}")
print(f"Original vector 2: {vector2}")
print(f"Encrypted sum (truncated): {decrypted_sum[:5]}") # Print first 5 elements

# Expected result: [5.0, 7.0, 9.0, 11.0, 13.0]