xtrace_sdk.x_vec.crypto.paillier_client ======================================= .. py:module:: xtrace_sdk.x_vec.crypto.paillier_client Attributes ---------- .. autoapisummary:: xtrace_sdk.x_vec.crypto.paillier_client.DEVICE Classes ------- .. autoapisummary:: xtrace_sdk.x_vec.crypto.paillier_client.PaillierGPU xtrace_sdk.x_vec.crypto.paillier_client.PaillierCPU xtrace_sdk.x_vec.crypto.paillier_client.PaillierClient Module Contents --------------- .. py:data:: DEVICE .. py:class:: 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 :class:`PaillierClient` 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 :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) Load encryption configuration from a dict produced by :meth:`stringify_config`. :param config: Configuration dict (``embed_len``, ``key_len``). :type config: dict .. py:class:: PaillierCPU(embed_len = 512, key_len = 1024, skip_key_gen = False) CPU implementation of Paillier homomorphic encryption optimised for Hamming distance. .. py:attribute:: chunk_len :value: 2048 .. py:attribute:: key_len :value: 1024 .. py:attribute:: keys :type: xtrace_sdk.x_vec.utils.xtrace_types.PaillierKeyPair | None .. py:attribute:: embed_len :value: 512 .. 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) Load encryption configuration from a dict produced by :meth:`stringify_config`. :param config: Configuration dict (``embed_len``, ``key_len``). :type config: dict .. py:method:: id2power(id_) Return the chunk index and bit power for a given position in the padded embedding. :param id_: Index of an entry in the embedding vector. :type id_: int :return: Tuple of (chunk_index, bit_power). :rtype: tuple[int, int] .. py:method:: encrypt(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: List of Paillier ciphertexts (one per chunk). :rtype: PaillierEncryptedNumber .. py:method:: decode_hamming_client(cipher) Decrypt an encoded Hamming distance returned by the XTrace server. :param cipher: Encrypted Hamming encoding as returned by the server. :type cipher: PaillierEncryptedNumber :return: Plain-text Hamming distance. :rtype: int .. py:class:: PaillierClient(embed_len = 512, key_len = 1024, skip_key_gen = False) Bases: :py:obj:`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). .. py:attribute:: embed_len :value: 512 .. py:attribute:: key_len :value: 1024 .. py:attribute:: chunk_len :value: 2048 .. py:attribute:: device .. py:attribute:: client :type: PaillierGPU | PaillierCPU .. 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) Load encryption configuration from a dict produced by :meth:`stringify_config`. :param config: Configuration dict (``embed_len``, ``key_len``). :type config: dict