xtrace_sdk.x_vec.crypto.paillier_lookup_client ============================================== .. py:module:: xtrace_sdk.x_vec.crypto.paillier_lookup_client Attributes ---------- .. autoapisummary:: xtrace_sdk.x_vec.crypto.paillier_lookup_client.DEVICE Classes ------- .. autoapisummary:: xtrace_sdk.x_vec.crypto.paillier_lookup_client.PaillierLookupGPU xtrace_sdk.x_vec.crypto.paillier_lookup_client.PaillierLookupCPU xtrace_sdk.x_vec.crypto.paillier_lookup_client.PaillierLookupClient Module Contents --------------- .. py:data:: DEVICE .. py:class:: 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 :class:`PaillierLookupClient` which dispatches to this backend automatically when ``DEVICE=gpu``. .. py:attribute:: gpu_client .. py:method:: encrypt(embds) Encrypt a batch of binary embedding vectors on GPU. :param embds: List of binary vectors with values in {0, 1}. :type embds: list[list[int]] :return: List of encrypted vectors. :rtype: list[PaillierEncryptedNumber] .. py:method:: decode_hamming_client(cipher) Decrypt a batch of encrypted Hamming distances on GPU. :param cipher: Batch of encrypted Hamming encodings from the server. :type cipher: list[list[int]] :return: List of plain-text Hamming distances. :rtype: list[int] .. py:method:: stringify_pk() Return a JSON string representation of the public key. .. py:method:: stringify_sk() Return a JSON string representation of the secret key. .. py:method:: stringify_config() Return a JSON string representation of the encryption configuration. .. py:method:: load_stringified_keys(pk, sk) Load public and secret keys from their JSON string representations. :param pk: JSON-encoded public key produced by :meth:`stringify_pk`. :param sk: JSON-encoded secret key produced by :meth:`stringify_sk`. .. py:method:: load_config(config, precomputed_tables = None, tables_bytes = None) Load encryption configuration and optionally restore precomputed tables. :param config: Configuration dict (``embed_len``, ``key_len``, etc.). :type config: dict :param precomputed_tables: Optional dict of precomputed ``g_table`` / ``noise_table`` to skip recomputation. :param tables_bytes: Optional dict of the same tables in raw binary format (faster to load). .. py:method:: dump_tables() Dump precomputed tables as a dict of Python-native types for caching. .. py:method:: dump_tables_bytes() Dump precomputed tables in compact raw binary format for caching. .. py:class:: 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. .. py:attribute:: alpha_len :value: 50 .. py:attribute:: key_len :value: 1024 .. py:attribute:: chunk_len :value: 2048 .. py:attribute:: keys :type: xtrace_sdk.x_vec.utils.xtrace_types.PaillierLookupKeyPair | None .. py:attribute:: embed_len :value: 512 .. py:method:: stringify_pk() stringify public key for networking/storage purpose :return: stringified public key :rtype: str .. py:method:: stringify_sk() stringify secret key for networking/storage purpose :return: stringified secret key :rtype: str .. py:method:: stringify_config() stringify crypto context for networking/storage purpose :return: stringified crypto context :rtype: str .. py:method:: dump_tables() Dump g_table and noise_table for caching .. py:method:: load_stringified_keys(pk, sk) load stringified keys :param pk: stringified public key :type pk: str :param sk: stringified secret key :type sk: str .. py:method:: load_config(config, precomputed_tables = None) load crypto context from a json string :param context: the json string containing crypto context :type context: str :param precomputed_tables: optional dict containing 'g_table' and 'noise_table' to skip recomputation .. py:method:: id2power(id_) Helper: return chunk index and corresponding power of 2 for a given position in the padded array. :param id_: Index of an entry in the embedding vector. :type id_: int .. py:method:: encrypt(embd) This function implements the encryption scheme on embedding vectors that needs to be run on client side. :param embd: the embedding vector to be encrypted :type embd: iterable[0,1] :return: return a list of length chunk_num contaning PaillierEncryptedNumber :rtype: PaillierEncryptedNumber .. py:method:: decode_hamming_client(cipher) Given a PaillierEncryptedNumber returned from server, calculate the hamming distance encoded .. py:class:: PaillierLookupClient(embed_len = 512, key_len = 1024, alpha_len = 50, skip_key_gen = False) Bases: :py:obj:`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 :class:`PaillierClient` for large collections. Dispatches to CPU or GPU backend via the ``DEVICE`` environment variable (``cpu`` by default). .. py:attribute:: alpha_len :value: 50 .. py:attribute:: key_len :value: 1024 .. py:attribute:: embed_len :value: 512 .. py:attribute:: chunk_len :value: 2048 .. py:attribute:: device .. py:attribute:: client :type: PaillierLookupGPU | PaillierLookupCPU .. py:method:: has_gpu() :staticmethod: Return ``True`` if the GPU backend extension is available and loadable. :rtype: bool .. py:method:: encrypt_vec_one(embd) Encrypt a single binary embedding vector. :param embd: Binary vector of length ``embed_len`` with values in {0, 1}. :type embd: list[int] :return: Encrypted vector. :rtype: PaillierEncryptedNumber .. py:method:: encrypt_vec_batch(embds) Encrypt a batch of binary embedding vectors. :param embds: List of binary vectors, each of length ``embed_len`` with values in {0, 1}. :type embds: list[list[int]] :return: List of encrypted vectors. :rtype: list[PaillierEncryptedNumber] .. py:method:: decode_hamming_client_one(cipher) Decrypt a single encrypted Hamming distance returned by the XTrace server. :param cipher: Encrypted Hamming encoding. :type cipher: PaillierEncryptedNumber :return: Plain-text Hamming distance. :rtype: int .. py:method:: decode_hamming_client_batch(ciphers) Decrypt a batch of encrypted Hamming distances returned by the XTrace server. :param ciphers: List of encrypted Hamming encodings. :type ciphers: list[PaillierEncryptedNumber] :return: List of plain-text Hamming distances. :rtype: list[int] .. py:method:: stringify_pk() Return a JSON string representation of the public key. .. py:method:: stringify_sk() Return a JSON string representation of the secret key. .. py:method:: stringify_config() Return a JSON string representation of the encryption configuration. .. py:method:: load_stringified_keys(pk, sk) Load public and secret keys from their JSON string representations. :param pk: JSON-encoded public key produced by :meth:`stringify_pk`. :param sk: JSON-encoded secret key produced by :meth:`stringify_sk`. .. py:method:: load_config(config, precomputed_tables = None) Load encryption configuration and optionally restore precomputed tables. :param config: Configuration dict (``embed_len``, ``key_len``, ``alpha_len``, etc.). :type config: dict :param precomputed_tables: Optional dict of precomputed ``g_table`` / ``noise_table`` to skip recomputation on the CPU backend. .. py:method:: __getstate__() Support for pickling. We serialize the configuration, keys, and for CPU, the precomputed tables. .. py:method:: __setstate__(state) Restore from pickle .. py:method:: dump_tables()