paillier.paillier module

Implementation of the Asymmetric Encryption Scheme known as Paillier.

class paillier.paillier.Paillier(public_key, secret_key, precision=0, share_secret_key=False, randomizations=None, max_size=100, total=None, nr_of_threads=1, path=None, separator=',', start_generation=True, debug=False)[source]

Bases: AsymmetricEncryptionScheme[Tuple[PaillierPublicKey, PaillierSecretKey], Union[int, float, FixedPoint], int, int, PaillierCiphertext, PaillierPublicKey, PaillierSecretKey], RandomizedEncryptionScheme[Tuple[PaillierPublicKey, PaillierSecretKey], Union[int, float, FixedPoint], int, int, PaillierCiphertext]

Paillier Encryption Scheme. This is an AsymmetricEncryptionScheme, with a public and secret key. This is also a RandomizedEncryptionScheme, thus having internal randomness generation and allowing for the use of precomputed randomness.

__eq__(other)[source]

Compare this Paillier scheme with another to determine (in)equality. Does not take the secret key into account as it might not be known and the public key combined with the precision should be sufficient to determine equality.

Parameters:

other (object) – Object to compare this Paillier scheme with.

Return type:

bool

Returns:

Boolean value representing (in)equality of both objects.

__init__(public_key, secret_key, precision=0, share_secret_key=False, randomizations=None, max_size=100, total=None, nr_of_threads=1, path=None, separator=',', start_generation=True, debug=False)[source]

Construct a new Paillier encryption scheme, with the given keypair, randomness object, precision for floating point encryption.

Parameters:
  • public_key (PaillierPublicKey) – Public key for this Paillier Scheme.

  • secret_key (Optional[PaillierSecretKey]) – Optional Secret Key for this Paillier Scheme (None when unknown).

  • precision (int) – Floating point precision of this encoding (Default: 0), in decimal places.

  • share_secret_key (bool) – Boolean value stating whether or not the secret key should be included in serialization. This should only be set to True if one is really sure of it. (Default: False)

  • debug (bool) – flag to determine whether debug information should be displayed (Default: False)

  • start_generation (bool) – flag that determines whether the scheme starts generating randomness immediately (Default: True)

  • randomizations (Optional[Queue[int]]) – queue with randomizations. If no queue is given, it creates a fresh one (Default: None)

  • max_size (int) – maximum size of the queue (Default: 100)

  • total (Optional[int]) – upper bound on the total amount of randomizations to generate. (Default: None)

  • nr_of_threads (int) – number of generation worker threads that should be started (Default: 1)

  • path (Optional[str]) – path (including filename) to the file that contains randomizations. By default no path is given and no randomness is extracted from any files. (Default: “”)

  • separator (str) – separator for the random values in the given file (Default: “,”)

add(ciphertext_1, ciphertext_2)[source]

Add the underlying plaintext value of ciphertext_1 \(c_1\) with the underlying plaintext value of ciphertext_2 if ciphertext_2 is another PaillierCiphertext \(c_2\), if it is a Plaintext, we add the plaintext value \(m_2\) to ciphertext_1, by first encryption it and obtaining \(c_2 = Enc(m_2)\).

We then compute the result as \(c' = c_1 \cdot c_2 \mod n^2\)

Parameters:
  • ciphertext_1 (PaillierCiphertext) – First PaillierCiphertext \(c_1\) of which the underlying plaintext is added.

  • ciphertext_2 (Union[PaillierCiphertext, int, float, FixedPoint]) – Either a second PaillierCiphertext \(c_2\) of which the underlying plaintext is added to the first. Or a plaintext \(m_2\) that is added to the underlying plaintext of the first.

Raises:

AttributeError – When ciphertext_2 does not have the same public key as ciphertext_1.

Return type:

PaillierCiphertext

Returns:

A PaillierCiphertext \(c'\) containing the encryption of the addition of both values.

decode(encoded_plaintext)[source]

Decode an EncodedPlaintext given the specified precision of this instantiation.

Parameters:

encoded_plaintext (EncodedPlaintext[int]) – Plaintext to be decoded.

Return type:

Union[int, float, FixedPoint]

Returns:

decoded Plaintext value

static deserialize(json_obj, *, origin=None, **_kwargs)[source]

Deserialization function for Paillier schemes, which will be passed to the communication module.

Parameters:
  • json_obj (Dict[str, Any]) – JSON serialized version of a Paillier scheme.

  • _kwargs (Any) – optional extra keyword arguments

  • origin (Optional[HTTPClient]) – HTTPClient representing where the message came from if applicable

Raises:
  • SerializationError – When communication library is not installed.

  • ValueError – When a scheme is sent through ID without any prior communication of the scheme

Return type:

Paillier

Returns:

Deserialized Paillier scheme from the given JSON dict. Might not have a secret key when that was not included in the received serialization.

encode(plaintext)[source]

Encode a float or int with the given precision of this instantiation. Allows for positive and negative numbers.

Parameters:

plaintext (Union[int, float, FixedPoint]) – Plaintext to be encoded.

Raises:

ValueError – If the plaintext is outside the supported range of this Paillier instance.

Return type:

EncodedPlaintext[int]

Returns:

EncodedPlaintext object containing the encoded value.

static func_l(input_x, n)[source]

Paillier specific \(L(\cdot)\) function: \(L(x) = (x-1)/n\).

Parameters:
  • input_x (int) – input \(x\)

  • n (int) – input \(n\) (public key modulus)

Return type:

int

Returns:

value of \(L(x) = (x-1)/n\).

static generate_key_material(key_length)[source]

Method to generate key material (PaillierPublicKey and PaillierPrivateKey).

Parameters:

key_length (int) – Bit length of the public key \(n\).

Return type:

Tuple[PaillierPublicKey, PaillierSecretKey]

Returns:

Tuple with first the Public Key and then the Secret Key.

generate_randomness()[source]

Method to generate randomness value \(r^n \mod n^2\), from a random number \(r \in_R \mathbb{Z}^*_{n}\) for Paillier.

Return type:

int

Returns:

A random number.

classmethod id_from_arguments(public_key, precision=0)[source]

Method that turns the arguments for the constructor into an identifier. This identifier is used to find constructor calls that would result in identical schemes.

Parameters:
  • public_key (PaillierPublicKey) – PaillierPublicKey of the Paillier instance.

  • precision (int) – Precision of the Paillier instance

Return type:

int

Returns:

Identifier of the Paillier instance

mul(ciphertext, scalar)[source]

Multiply the underlying plaintext value of ciph \(c\) with the given scalar \(s\). We obtain the result by computing \(c' = c^s\).

Parameters:
  • ciphertext (PaillierCiphertext) – PaillierCiphertext \(c\) of which the underlying plaintext is multiplied.

  • scalar (int) – A scalar \(s\) with which the plaintext underlying ciph should be multiplied.

Raises:

TypeError – When the scalar is not an integer.

Return type:

PaillierCiphertext

Returns:

A PaillierCiphertext \(c'\) containing the encryption of the product of both values.

neg(ciphertext)[source]

Negate the underlying plaintext of this ciphertext. I.e. if the original plaintext of this ciphertext was 5. this method returns the ciphertext that has -5 as underlying plaintext. Given a ciphertext \(c\) we compute the negated ciphertext \(c'\) such that \(c \cdot c' = 1 \mod n^2\)

Parameters:

ciphertext (PaillierCiphertext) – PaillierCiphertext \(c\) of which the underlying plaintext should be negated.

Return type:

PaillierCiphertext

Returns:

PaillierCiphertext \(c'\) corresponding to the negated plaintext.

random_plaintext()[source]

Generate a uniformly random plaintext

Return type:

FixedPoint

Returns:

A uniformly random element from the plaintext space represented as a fixed point number.

serialize(*, destination=None, **kwargs)[source]

Serialization function for Paillier schemes, which will be passed to the communication module. The sharing of the secret key depends on the attribute share_secret_key.

Parameters:
  • kwargs (Any) – optional extra keyword arguments

  • destination (Optional[HTTPClient]) – HTTPClient representing where the message will go if applicable

Raises:

SerializationError – When communication library is not installed.

Return type:

Dict[str, Any]

Returns:

JSON serialized version of this Paillier scheme.

serialize_with_secret_key(**kwargs)[source]

Serialization function for Paillier schemes, that does include the secret key.

Parameters:

kwargs (Any) – optional extra keyword arguments

Raises:

SerializationError – When communication library is not installed.

Return type:

Dict[str, Any]

Returns:

JSON serialized version of this Paillier scheme.

serialize_without_secret_key(**kwargs)[source]

Serialization function for Paillier schemes, that does not include the secret key.

Parameters:

kwargs (Any) – optional extra keyword arguments

Raises:

SerializationError – When communication library is not installed.

Return type:

Dict[str, Any]

Returns:

JSON serialized version of this Paillier scheme (without the secret key).

class paillier.paillier.PaillierCiphertext(raw_value, scheme)[source]

Bases: RandomizableCiphertext[Tuple[PaillierPublicKey, PaillierSecretKey], Union[int, float, FixedPoint], int, int]

Ciphertext for the Paillier asymmetric encryption scheme. This ciphertext is rerandomizable and supports homomorphic operations.

__eq__(other)[source]

Compare this PaillierCiphertext with another to determine (in)equality.

Parameters:

other (object) – Object to compare this PaillierCiphertext with.

Raises:

TypeError – When other object is not a PaillierCiphertext.

Return type:

bool

Returns:

Boolean value representing (in)equality of both objects.

__init__(raw_value, scheme)[source]

Construct a RandomizableCiphertext, with the given value for the given EncryptionScheme.

Parameters:
  • raw_value (int) – PaillierCiphertext value \(c \in \mathbb{Z}_{n^2}\).

  • scheme (Paillier) – Paillier scheme that is used to encrypt this ciphertext.

Raises:

TypeError – When the given scheme is not a Paillier scheme.

apply_randomness(randomization_value)[source]

Rerandomize this ciphertext using the given random value.

Parameters:

randomization_value (int) – Random value used for rerandomization.

Return type:

None

copy()[source]

Create a copy of this Ciphertext, with the same value and scheme.

Return type:

PaillierCiphertext

Returns:

Copied PaillierCiphertext.

static deserialize(json_obj, **kwargs)[source]

Deserialization function for Paillier ciphertexts, which will be passed to the communication module.

Parameters:
  • json_obj (Dict[str, Any]) – JSON serialized version of a PaillierCiphertext.

  • kwargs (Any) – optional extra keyword arguments

Raises:

SerializationError – When communication library is not installed.

Return type:

PaillierCiphertext

Returns:

Deserialized PaillierCiphertext from the given JSON dict.

scheme: Paillier
serialize(**kwargs)[source]

Serialization function for Paillier ciphertexts, which will be passed to the communication module.

Parameters:

kwargs (Any) – optional extra keyword arguments

Raises:

SerializationError – When communication library is not installed.

Return type:

Dict[str, Any]

Returns:

JSON serialized version of this PaillierCiphertext.

class paillier.paillier.PaillierPublicKey(n, g)[source]

Bases: PublicKey

PublicKey for the Paillier encryption scheme.

__eq__(other)[source]

Compare this PaillierPublicKey with another to determine (in)equality.

Parameters:

other (object) – Object to compare this PaillierPublicKey with.

Raises:

TypeError – When other object is not a PaillierPublicKey.

Return type:

bool

Returns:

Boolean value representing (in)equality of both objects.

__hash__()[source]

Compute a hash from this PaillierPublicKey instance.

Return type:

int

Returns:

Hash value.

__init__(n, g)[source]

Constructs a new Paillier public key \((n, g)\), should have \(n=pq\), with \(p, q\) prime, and \(g \in \mathbb{Z}^*_{n^2}\).

Parameters:
  • n (int) – Modulus \(n\) of the plaintext space.

  • g (int) – Plaintext base \(g\) for encryption.

Also contains: n_squared: Modulus of the ciphertext space \(n^2\).

static deserialize(json_obj, **kwargs)[source]

Deserialization function for public keys, which will be passed to the communication module.

Parameters:
  • json_obj (Dict[str, Any]) – JSON serialized version of a PaillierPublicKey.

  • kwargs (Any) – optional extra keyword arguments

Raises:

SerializationError – When communication library is not installed.

Return type:

PaillierPublicKey

Returns:

Deserialized PaillierPublicKey from the given JSON dict.

serialize(**kwargs)[source]

Serialization function for public keys, which will be passed to the communication module.

Parameters:

kwargs (Any) – optional extra keyword arguments

Raises:

SerializationError – When communication library is not installed.

Return type:

Dict[str, Any]

Returns:

JSON serialized version of this PaillierPublicKey.

class paillier.paillier.PaillierSecretKey(lambda_value, mu, n)[source]

Bases: SecretKey

SecretKey for the Paillier encryption scheme.

__eq__(other)[source]

Compare this PaillierSecretKey with another to determine (in)equality.

Parameters:

other (object) – Object to compare this PaillierSecretKey with.

Raises:

TypeError – When other object is not a PaillierSecretKey.

Return type:

bool

Returns:

Boolean value representing (in)equality of both objects.

__hash__()[source]

Compute a hash from this PaillierSecretKey instance.

Return type:

int

Returns:

Hash value.

__init__(lambda_value, mu, n)[source]

Constructs a new Paillier secret key \((\lambda, \mu)\), also contains \(n\). Should have \(n=pq\), with \(p, q\) prime, \(\lambda = \text{lcm}(p-1, q-1)\), and \(\mu = (L(g^\lambda \mod n^2))^{-1} \mod n\), where \(L(\cdot)\) is defined as \(L(x) = (x-1)/n\).

Parameters:
  • lambda_value (int) – Decryption exponent \(\lambda\) of the ciphertext.

  • mu (int) – Decryption divisor \(\mu\) for the ciphertext.

  • n (int) – Modulus \(n\) of the plaintext space.

static deserialize(json_obj, **kwargs)[source]

Deserialization function for public keys, which will be passed to the communication module

Parameters:
  • json_obj (Dict[str, Any]) – JSON serialized version of a PaillierSecretKey.

  • kwargs (Any) – optional extra keyword arguments

Raises:

SerializationError – When communication library is not installed.

Return type:

PaillierSecretKey

Returns:

Deserialized PaillierSecretKey from the given JSON dict.

serialize(**kwargs)[source]

Serialization function for secret keys, which will be passed to the communication module.

Parameters:

kwargs (Any) – optional extra keyword arguments

Raises:

SerializationError – When communication library is not installed.

Return type:

Dict[str, Any]

Returns:

JSON serialized version of this PaillierSecretKey.

exception paillier.paillier.SerializationError[source]

Bases: Exception

Serialization error for Paillier.