xtrace_sdk.x_vec.crypto.paillier_client¶

Attributes¶

DEVICE

Classes¶

`PaillierGPU`	Wrapper for the C++ GPU implementation of the Paillier cryptography system.
`PaillierCPU`	CPU implementation of Paillier homomorphic encryption optimised for Hamming distance.
`PaillierClient`	Paillier homomorphic encryption client optimised for computing encrypted Hamming distances

Module Contents¶

xtrace_sdk.x_vec.crypto.paillier_client.DEVICE¶

class xtrace_sdk.x_vec.crypto.paillier_client.PaillierGPU(embed_len=512, key_len=1024, skip_key_gen=False)¶

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

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

Parameters:

embed_len (int)
key_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) – 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)¶

Load encryption configuration from a dict produced by stringify_config().

Parameters:: config (dict) – Configuration dict (embed_len, key_len).
Return type:: None

class xtrace_sdk.x_vec.crypto.paillier_client.PaillierCPU(embed_len=512, key_len=1024, skip_key_gen=False)¶

CPU implementation of Paillier homomorphic encryption optimised for Hamming distance.

Parameters:

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

chunk_len = 2048¶

key_len = 1024¶

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

embed_len = 512¶

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)¶

Load encryption configuration from a dict produced by stringify_config().

Parameters:: config (dict) – Configuration dict (embed_len, key_len).
Return type:: None

id2power(id_)¶

Return the chunk index and bit power for a given position in the padded embedding.

Parameters:

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

Returns:

Tuple of (chunk_index, bit_power).

Return type:

tuple[int, int]

encrypt(embd)¶

Encrypt a single binary embedding vector.

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

decode_hamming_client(cipher)¶

Decrypt an encoded Hamming distance returned by the XTrace server.

Parameters:: cipher (PaillierEncryptedNumber) – Encrypted Hamming encoding as returned by the server.
Returns:: Plain-text Hamming distance.
Return type:: int

class xtrace_sdk.x_vec.crypto.paillier_client.PaillierClient(embed_len=512, key_len=1024, skip_key_gen=False)¶

Bases: xtrace_sdk.x_vec.crypto.hamming_client_base.HammingClientBase

Paillier homomorphic encryption client optimised for computing encrypted Hamming distances between binary embedding vectors. Dispatches to CPU or GPU backend via the DEVICE environment variable (cpu by default).

Parameters:

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

embed_len = 512¶

key_len = 1024¶

chunk_len = 2048¶

device¶

client: PaillierGPU | PaillierCPU¶

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)¶

Load encryption configuration from a dict produced by stringify_config().

Parameters:: config (dict) – Configuration dict (embed_len, key_len).
Return type:: None