xtrace_sdk.x_vec.crypto.paillier_lookup_client¶

Attributes¶

DEVICE

Classes¶

`PaillierLookupGPU`	Wrapper for the C++ GPU implementation of the Paillier-Lookup cryptography system.
`PaillierLookupCPU`	This is an implementation of paillier cryptography system optimized for caculating hamming distance between
`PaillierLookupClient`	Paillier-Lookup homomorphic encryption client optimised for computing encrypted Hamming

Module Contents¶

xtrace_sdk.x_vec.crypto.paillier_lookup_client.DEVICE¶

class xtrace_sdk.x_vec.crypto.paillier_lookup_client.PaillierLookupGPU(embed_len=512, key_len=1024, alpha_len=50, skip_key_gen=False)¶

Wrapper for the C++ GPU implementation of the Paillier-Lookup cryptography system.

This class is not instantiated directly — use PaillierLookupClient which dispatches to this backend automatically when DEVICE=gpu.

Parameters:

embed_len (int)
key_len (int)
alpha_len (int)
skip_key_gen (bool)

gpu_client¶

encrypt(embds)¶

Encrypt a batch of binary embedding vectors on GPU.

Parameters:: embds (list[list[int]]) – List of binary vectors with values in {0, 1}.
Returns:: List of encrypted vectors.
Return type:: list[PaillierEncryptedNumber]

decode_hamming_client(cipher)¶

Decrypt a batch of encrypted Hamming distances on GPU.

Parameters:: cipher (list[list[int]]) – Batch of encrypted Hamming encodings from the server.
Returns:: List of plain-text Hamming distances.
Return type:: list[int]

stringify_pk()¶

Return a JSON string representation of the public key.

Return type:: str

stringify_sk()¶

Return a JSON string representation of the secret key.

Return type:: str

stringify_config()¶

Return a JSON string representation of the encryption configuration.

Return type:: str

load_stringified_keys(pk, sk)¶

Load public and secret keys from their JSON string representations.

Parameters:

pk (str) – JSON-encoded public key produced by stringify_pk().
sk (str) – JSON-encoded secret key produced by stringify_sk().

Return type:

None

load_config(config, precomputed_tables=None, tables_bytes=None)¶

Load encryption configuration and optionally restore precomputed tables.

Parameters:

config (dict) – Configuration dict (embed_len, key_len, etc.).
precomputed_tables (dict | None) – Optional dict of precomputed g_table / noise_table to skip recomputation.
tables_bytes (dict | None) – Optional dict of the same tables in raw binary format (faster to load).

Return type:

None

dump_tables()¶

Dump precomputed tables as a dict of Python-native types for caching.

Return type:: dict

dump_tables_bytes()¶

Dump precomputed tables in compact raw binary format for caching.

Return type:: dict

class xtrace_sdk.x_vec.crypto.paillier_lookup_client.PaillierLookupCPU(embed_len=512, key_len=1024, alpha_len=50, skip_key_gen=False)¶

This is an implementation of paillier cryptography system optimized for caculating hamming distance between two binary vectors.

Parameters:

embed_len (int)
key_len (int)
alpha_len (int)
skip_key_gen (bool)

alpha_len = 50¶

key_len = 1024¶

chunk_len = 2048¶

keys: xtrace_sdk.x_vec.utils.xtrace_types.PaillierLookupKeyPair | None¶

embed_len = 512¶

stringify_pk()¶

stringify public key for networking/storage purpose

Returns:: stringified public key
Return type:: str

stringify_sk()¶

stringify secret key for networking/storage purpose

Returns:: stringified secret key
Return type:: str

stringify_config()¶

stringify crypto context for networking/storage purpose

Returns:: stringified crypto context
Return type:: str

dump_tables()¶

Dump g_table and noise_table for caching

Return type:: dict

load_stringified_keys(pk, sk)¶

load stringified keys

Parameters:

pk (str) – stringified public key
sk (str) – stringified secret key

Return type:

None

load_config(config, precomputed_tables=None)¶

load crypto context from a json string

Parameters:

context (str) – the json string containing crypto context
precomputed_tables (dict | None) – optional dict containing ‘g_table’ and ‘noise_table’ to skip recomputation
config (dict)

Return type:

None

id2power(id_)¶

Helper: return chunk index and corresponding power of 2 for a given position in the padded array.

Parameters:

id (int) – Index of an entry in the embedding vector.
id_ (int)

Return type:

tuple[int, int]

encrypt(embd)¶

This function implements the encryption scheme on embedding vectors that needs to be run on client side.

Parameters:: embd (iterable[0,1]) – the embedding vector to be encrypted
Returns:: return a list of length chunk_num contaning PaillierEncryptedNumber
Return type:: PaillierEncryptedNumber

decode_hamming_client(cipher)¶

Given a PaillierEncryptedNumber returned from server, calculate the hamming distance encoded

Parameters:: cipher (list[int | bytes])
Return type:: int

class xtrace_sdk.x_vec.crypto.paillier_lookup_client.PaillierLookupClient(embed_len=512, key_len=1024, alpha_len=50, skip_key_gen=False)¶

Bases: xtrace_sdk.x_vec.crypto.hamming_client_base.HammingClientBase

Paillier-Lookup homomorphic encryption client optimised for computing encrypted Hamming distances between binary embedding vectors.

Uses precomputed lookup tables to accelerate encryption, making it significantly faster than PaillierClient for large collections. Dispatches to CPU or GPU backend via the DEVICE environment variable (cpu by default).

Parameters:

embed_len (int)
key_len (int)
alpha_len (int)
skip_key_gen (bool)

alpha_len = 50¶

key_len = 1024¶

embed_len = 512¶

chunk_len = 2048¶

device¶

client: PaillierLookupGPU | PaillierLookupCPU¶

static has_gpu()¶

Return True if the GPU backend extension is available and loadable.

Return type:: bool

encrypt_vec_one(embd)¶

Encrypt a single binary embedding vector.

Parameters:: embd (list[int]) – Binary vector of length embed_len with values in {0, 1}.
Returns:: Encrypted vector.
Return type:: PaillierEncryptedNumber

encrypt_vec_batch(embds)¶

Encrypt a batch of binary embedding vectors.

Parameters:: embds (list[list[int]]) – List of binary vectors, each of length embed_len with values in {0, 1}.
Returns:: List of encrypted vectors.
Return type:: list[PaillierEncryptedNumber]

decode_hamming_client_one(cipher)¶

Decrypt a single encrypted Hamming distance returned by the XTrace server.

Parameters:: cipher (PaillierEncryptedNumber) – Encrypted Hamming encoding.
Returns:: Plain-text Hamming distance.
Return type:: int

decode_hamming_client_batch(ciphers)¶

Decrypt a batch of encrypted Hamming distances returned by the XTrace server.

Parameters:: ciphers (list[PaillierEncryptedNumber]) – List of encrypted Hamming encodings.
Returns:: List of plain-text Hamming distances.
Return type:: list[int]

stringify_pk()¶

Return a JSON string representation of the public key.

Return type:: str

stringify_sk()¶

Return a JSON string representation of the secret key.

Return type:: str

stringify_config()¶

Return a JSON string representation of the encryption configuration.

Return type:: str

load_stringified_keys(pk, sk)¶

Load public and secret keys from their JSON string representations.

Parameters:

pk (str) – JSON-encoded public key produced by stringify_pk().
sk (str) – JSON-encoded secret key produced by stringify_sk().

Return type:

None

load_config(config, precomputed_tables=None)¶

Load encryption configuration and optionally restore precomputed tables.

Parameters:

config (dict) – Configuration dict (embed_len, key_len, alpha_len, etc.).
precomputed_tables (dict | None) – Optional dict of precomputed g_table / noise_table to skip recomputation on the CPU backend.

Return type:

None

__getstate__()¶

Support for pickling. We serialize the configuration, keys, and for CPU, the precomputed tables.

Return type:: dict

__setstate__(state)¶

Restore from pickle

Parameters:: state (dict)
Return type:: None

dump_tables()¶

Return type:: dict