cicada.additive module

Functionality for creating, manipulating, and revealing additive-shared secrets.

class cicada.additive.AdditiveArrayShare(storage)[source]

Bases: object

Stores the local share of a secret shared array for AdditiveProtocolSuite.

Instances of AdditiveArrayShare should only be created using AdditiveProtocolSuite.

property storage

Private storage for the local share of a secret shared array. Access is provided only for serialization and communication - callers must use AdditiveProtocolSuite to manipulate secret shares.

class cicada.additive.AdditiveProtocolSuite(communicator, *, seed=None, seed_offset=None, order=None, encoding=None)[source]

Bases: object

Protocol suite implementing computation with additive-shared secrets.

Multiplication is implemented using a generalization of “Protocols for secure remote database access with approximate matching” by Du and Atallah, which provides semi-honest security and does not require Beaver triples or other offline computation.

Comparisons are based on “Multiparty computation for interval, equality, and comparison without bit-decomposition protocol” by Nishide and Ohta, and inherit the semi-honest security model from multiplication.

Note

Creating the protocol is a collective operation that must be called by all players that are members of communicator.

Parameters:

  • communicator (cicada.communicator.interface.Communicator, required) – The communicator that this protocol will use for communication.

  • seed (int, optional) – Seed used to initialize random number generators. For privacy, this value should be different for each player. By default, the seed will be chosen at random, and is guaranteed to be different even on forked processes. If you specify seed yourself, the actual seed used will be the sum of this value and the value of seed_offset.

  • seed_offset (int, optional) – Value added to the value of seed. This value defaults to the player’s rank.

  • order (int, optional) – Field size for storing encoded values. Defaults to the largest prime less than \(2^{64}\).

  • encoding (object, optional) – Default encoding to use for operations that require encoding/decoding. Uses an instance of FixedPoint with 16 bits of floating-point precision if None.

absolute(operand)[source]

Elementwise absolute value of a secret shared array.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

operand (AdditiveArrayShare, required) – Secret shared value to which the absolute value function should be applied.

Returns:

result – Secret-shared elementwise absolute value of operand.

Return type:

AdditiveArrayShare

add(lhs, rhs, *, encoding=None)[source]

Privacy-preserving elementwise sum of arrays.

This method can be used to perform private-private, public-private, and private-public addition. The result is the secret shared elementwise sum of the operands. Note that public-public addition isn’t allowed, as it isn’t privacy-preserving!

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared sum of lhs and rhs.

Return type:

AdditiveArrayShare

bit_compose(operand)[source]

Compose an array of secret-shared bits into an array of corresponding integer field values.

The result array will will have one fewer dimensions than the operand, which must contain bits in big-endian order in its last dimension. Note that the input must contain the field values \(0\) and \(1\).

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

operand (AdditiveArrayShare, required) – Secret shared array containing bits to be composed.

Returns:

result – Share of the resulting field values.

Return type:

AdditiveArrayShare

bit_decompose(operand, *, bits=None)[source]

Decompose operand into shares of its bitwise representation.

The result array will have one more dimension than the operand, containing the returned bits in big-endian order. Note that the results will contain the field values \(0\) and \(1\).

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

  • operand (AdditiveArrayShare, required) – Secret shared array containing values to be decomposed.

  • bits (int, optional) – The number of rightmost bits in each value to extract. Defaults to all bits (i.e. the number of bits used for storage by the protocol’s field.

Returns:

result – Share of the bit decomposed secret.

Return type:

AdditiveArrayShare

property communicator

The Communicator used by this protocol.

divide(lhs, rhs, *, encoding=None, rmask=None, mask1=None, rem1=None, mask2=None, rem2=None, mask3=None, rem3=None)[source]

Privacy-preserving elementwise division of arrays.

This method can be used to perform private-private and private-public division. The result is the secret shared elementwise quotient of the operands.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

  • lhs (AdditiveArrayShare, required) – Secret shared value to be divided.

  • rhs (AdditiveArrayShare or numpy.ndarray, required) – Secret shared or public value to be divided.

  • encoding (object, optional) – Encodes public operands and determines the number of bits to shift right from intermediate results. The protocol’s encoding is used by default if None.

Returns:

result – Secret-shared quotient of lhs and rhs.

Return type:

AdditiveArrayShare

dot(lhs, rhs, *, encoding=None)[source]

Privacy-preserving dot product of two secret shared vectors.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

  • lhs (AdditiveArrayShare, required) – Secret shared vector.

  • rhs (AdditiveArrayShare, required) – Secret shared vector.

  • encoding (object, optional) – Determines the number of bits to truncate from intermediate results. The protocol’s encoding is used by default if None.

Returns:

result – Secret-shared dot product of lhs and rhs.

Return type:

AdditiveArrayShare

property encoding

Default encoding to use for operations that require encoding/decoding.

equal(lhs, rhs)[source]

Elementwise probabilistic equality comparison between secret shared arrays.

The result is the secret shared elementwise comparison lhs == rhs. Note that the results will contain the field values \(0\) and \(1\).

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared result from comparing lhs == rhs elementwise.

Return type:

AdditiveArrayShare

property field

Integer Field used for arithmetic on and storage of secret shared values.

field_add(lhs, rhs)[source]

Privacy-preserving elementwise sum of arrays.

This method can be used to perform private-private, public-private, and private-public addition. The result is the secret shared elementwise sum of the operands. Note that public-public addition isn’t allowed, as it isn’t privacy-preserving!

Unlike add(), field_add() only operates on field values, no encoding is performed on its inputs.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared sum of lhs and rhs.

Return type:

AdditiveArrayShare

field_dot(lhs, rhs)[source]

Privacy-preserving dot product of two secret shared vectors.

Unlike dot(), field_dot() only operates on field values, no right shift is performed on the results.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared dot product of lhs and rhs.

Return type:

AdditiveArrayShare

field_multiply(lhs, rhs)[source]

Privacy-preserving elementwise multiplication of arrays.

This method can be used to perform private-private, public-private, and private-public multiplication. The result is the secret shared elementwise sum of the operands. Note that public-public multiplication isn’t allowed, as it isn’t privacy-preserving!

Unlike multiply(), field_multiply() only operates on field values, no encoding is performed on its inputs, and no right shift is performed on the results.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared product of lhs and rhs.

Return type:

AdditiveArrayShare

field_power(lhs, rhs)[source]

Privacy-preserving elementwise exponentiation.

Raises secret shared array values to public integer values. Unlike power(), field_power() only operates on field values, no right shift is performed on the results.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

  • lhs (AdditiveArrayShare, required) – Secret shared values which iwll be raised to a power.

  • rhs (int or integer numpy.ndarray, required) – Public integer power(s) to which each element in lhs will be raised.

Returns:

result – Secret-shared result of raising lhs to the power(s) in rhs.

Return type:

AdditiveArrayShare

field_subtract(lhs, rhs)[source]

Privacy-preserving elementwise difference of arrays.

This method can be used to perform private-private, public-private, and private-public subtraction. The result is the secret shared elementwise difference of the operands. Note that public-public subtraction isn’t allowed, as it isn’t privacy-preserving!

Unlike subtract(), field_subtract() only operates on field values, no encoding is performed on its inputs.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared difference of lhs and rhs.

Return type:

AdditiveArrayShare

field_uniform(*, shape=None, generator=None)[source]

Generate private random field elements.

This method can be used to generate a secret shared array containing random field elements of any shape.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

  • shape (tuple, optional) – Shape of the array to populate. By default, a shapeless array of one random element will be generated.

  • src (sequence of int, optional) – Players that will contribute to random array generation. By default, all players contribute.

  • generator (numpy.random.Generator, optional) – A psuedorandom number generator for sampling. By default, numpy.random.default_rng() will be used.

Returns:

result – Secret-shared array of random field elements.

Return type:

AdditiveArrayShare

floor(operand, *, encoding=None)[source]

Privacy-preserving elementwise floor of encoded, secret-shared arrays.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

  • operand (AdditiveArrayShare, required) – Secret shared values to which floor should be applied.

  • encoding (object, optional) – Determines the number of fractional bits used for encoded values. The protocol’s encoding is used by default if None.

Returns:

result – Secret-shared floor of operand.

Return type:

AdditiveArrayShare

less(lhs, rhs)[source]

Privacy-preserving elementwise less-than comparison.

The result is the secret shared elementwise comparison \(lhs \lt rhs\). Note that the results will contain the field values \(0\) or \(1\), which do not require decoding if revealed.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared comparison \(lhs \lt rhs\).

Return type:

AdditiveArrayShare

less_zero(operand)[source]

Privacy-preserving elementwise less-than-zero comparison.

The result is the secret shared elementwise comparison \(operand \lt 0\). Note that the results will contain the field values \(0\) or \(1\), which do not require decoding if revealed.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared comparison \(operand \lt 0\).

Return type:

AdditiveArrayShare

logical_and(lhs, rhs)[source]

Privacy-preserving elementwise logical AND of secret shared arrays.

The operands must contain the field values \(0\) or \(1\). The result will be the secret shared elementwise logical AND of lhs and rhs, and will also contain the field values \(0\) or \(1\), which do not require decoding if revealed.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared elementwise logical AND of lhs and rhs.

Return type:

AdditiveArrayShare

logical_not(operand)[source]

Privacy-preserving elementwise logical NOT.

The operand must contain the field values \(0\) or \(1\). The result will be the secret shared elementwise logical NOT of operand, and will also contain the field values \(0\) or \(1\), which do not require decoding if revealed.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

operand (AdditiveArrayShare, required) – Secret shared array for logical NOT.

Returns:

result – Secret-shared elementwise logical NOT of operand.

Return type:

AdditiveArrayShare

logical_or(lhs, rhs)[source]

Privacy-preserving elementwise logical OR of secret shared arrays.

The operands must contain the field values \(0\) or \(1\). The result will be the secret shared elementwise logical OR of lhs and rhs, and will also contain the field values \(0\) or \(1\), which do not require decoding if revealed.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared elementwise logical OR of lhs and rhs.

Return type:

AdditiveArrayShare

logical_xor(lhs, rhs)[source]

Privacy-preserving elementwise logical XOR of secret shared arrays.

The operands must contain the field values \(0\) or \(1\). The result will be the secret shared elementwise logical XOR of lhs and rhs, and will also contain the field values \(0\) or \(1\), which do not require decoding if revealed.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared elementwise logical XOR of lhs and rhs.

Return type:

AdditiveArrayShare

maximum(lhs, rhs)[source]

Privacy-preserving elementwise maximum of secret shared arrays.

The result is the secret shared elementwise maximum of the operands. Note: the magnitude of the field elements should be less than one quarter of the field order for this method to be accurate in general.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared elementwise maximum of lhs and rhs.

Return type:

AdditiveArrayShare

minimum(lhs, rhs)[source]

Privacy-preserving elementwise minimum of secret shared arrays.

The result is the secret shared elementwise minimum of the operands. Note: the magnitude of the field elements should be less than one quarter of the field order for this method to be accurate in general.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared elementwise minimum of lhs and rhs.

Return type:

AdditiveArrayShare

multiplicative_inverse(operand)[source]

Privacy-preserving elementwise multiplicative inverse of a secret shared array.

Returns the multiplicative inverse of a secret shared array in the context of the underlying finite field. Explicitly, this function returns a same shape array which, when multiplied elementwise with operand, will return a same shape array comprised entirely of ones, assuming operand is entirely non-trivial elements.

This function does not take into account any field-external symantics. There is a potential for information leak here if operand contains any zero elements, that will be revealed. There is a small probability, 2^-operand.storage.size, for this approach to fail by zero being randomly generated by the parties as the mask.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

operand (AdditiveArrayShare, required) – Secret shared operand to be multiplicatively inverted.

Returns:

result – Secret-shared elementwise multiplicative inverse of operand.

Return type:

AdditiveArrayShare

multiply(lhs, rhs, *, encoding=None)[source]

Privacy-preserving elementwise multiplication of arrays.

This method can be used to perform private-private, public-private, and private-public multiplication. The result is the secret shared elementwise sum of the operands. Note that public-public multiplication isn’t allowed, as it isn’t privacy-preserving!

Unlike field_multiply(), multiply() is encoding aware: encoding is performed on its public inputs, and the results are shifted right to produce correct results when decoded.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared product of lhs and rhs.

Return type:

AdditiveArrayShare

negative(operand)[source]

Privacy-preserving elementwise additive inverse of a secret shared array.

Returns the additive inverse of a secret shared array in the context of the underlying finite field. Explicitly, this function returns a same shape array which, when added elementwise with operand, will return a same shape array comprised entirely of zeros.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

operand (AdditiveArrayShare, required) – Secret shared operand to be additively inverted.

Returns:

result – Secret-shared elementwise additive inverse of operand.

Return type:

AdditiveArrayShare

power(lhs, rhs, *, encoding=None)[source]

Privacy-preserving elementwise exponentiation.

Raises secret shared array values to public integer values. Unlike field_power(), power() operates on encoded values, shifting the results right to ensure correct decoded results.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

  • lhs (AdditiveArrayShare, required) – Secret shared values which iwll be raised to a power.

  • rhs (int or integer numpy.ndarray, required) – Public integer power(s) to which each element in lhs will be raised.

  • encoding (object, optional) – Determines the number of bits to shift right the results. The protocol’s encoding is used by default if None.

Returns:

result – Secret-shared result of raising lhs to the power(s) in rhs.

Return type:

AdditiveArrayShare

random_bitwise_secret(*, bits, shape=None, src=None, generator=None)[source]

Return secret values created by combining randomly generated bits.

This method returns two outputs - a secret shared array of randomly generated bits, and a secret shared array of values created by combining the bits in big-endian order. It is secure against non-colluding semi-honest adversaries. A subset of players (by default: all) generate and secret share vectors of pseudo-random bits which are then XOR-ed together elementwise. Communication and computation costs increase with the number of bits and the number of players, while security increases with the number of players.

The bit array will have one more dimension than the secret array, containing the bits in big-endian order.

Warning

If you supply your own generators, be careful to ensure that each has a unique seed value to preserve privacy (for example: a constant plus the player’s rank). If players receive generators with identical seed values, even numbers of players will produce all zero bits.

Note

This is a collective operation that must be called by all players that are members of communicator, even if they aren’t participating in the random bit generation.

Parameters:

  • bits (int, required) – Number of bits to generate.

  • shape (sequence of int, optional) – Shape of the output secrets array. The output bits array will have this shape, plus one extra dimension for the bits.

  • src (sequence of int, optional) – Players that will contribute to random bit generation. By default, all players contribute.

  • generator (numpy.random.Generator, optional) – A psuedorandom number generator for sampling. By default, numpy.random.default_rng() will be used.

Returns:

  • bits (AdditiveArrayShare) – Secret shared array of randomly-generated bits, with shape \(shape \times bits\).

  • secrets (AdditiveArrayShare) – Secret shared array of values created by combining the generated bits in big-endian order, with shape shape.

relu(operand)[source]

Privacy-preserving elementwise ReLU of a secret shared array.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

operand (AdditiveArrayShare, required) – Secret shared operand to which the ReLU function will be applied.

Returns:

result – Secret-shared elementwise ReLU of operand.

Return type:

AdditiveArrayShare

reshare(operand)[source]

Privacy-preserving re-randomization of a secret shared array.

This method returns a new set of secret shares that contain different random values than the input but represent the same secret value.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

operand (AdditiveArrayShare, required) – Secret shared operand which should be re-randomized.

Returns:

result – Secret-shared, re-randomized version of operand.

Return type:

AdditiveArrayShare

reveal(share, *, dst=None, encoding=None)[source]

Reveals a secret shared value to a subset of players.

Note

This is a collective operation that must be called by all players that are members of communicator, whether they are receiving the revealed secret or not.

Parameters:

  • share (AdditiveArrayShare, required) – The local share of the secret to be revealed.

  • dst (sequence of int, optional) – List of players who will receive the revealed secret. If None (the default), the secret will be revealed to all players.

  • encoding (object, optional) – Encoding used to extract the revealed secret from field values. The protocol’s default encoding will be used if None.

Returns:

value – The revealed secret, if this player is a member of dst, or None.

Return type:

numpy.ndarray or None

right_shift(operand, *, bits, src=None, generator=None, trunc_mask=None, rem_mask=None)[source]

Privacy-preserving elementwise right-shift of a secret shared array.

Note

This is a collective operation that must be called by all players that are members of communicator.

Also, this approach may probabilstically introduce a small error in the least significant bits of the result. The is that we generate masks for the two sections of the secret shared value of interest, one to be used in clearing out the low order bits, the other for masking the higher order bits that will remain. There is a chance that adding the masks in will generate a carry into the region that will remain after the shift. Therefore there is a chance that the effects of that carry will remain in the least significant bits of the final result, which, with the default parameters and encoding, means there could be an error in the final result on the order of 2^-16, and with decreasing probability 2^-15, or 2^-14 depending on how far the carry propagates.

Parameters:

  • operand (AdditiveArrayShare, required) – Secret-shared values to be shifted right.

  • bits (int, optional) – Number of bits to shift.

  • src (sequence of int, optional) – Players who will participate in generating random bits as part of the shift process. More players increases security but decreases performance. Defaults to all players.

  • generator (numpy.random.Generator, optional) – A psuedorandom number generator for generating random bits. By default, numpy.random.default_rng() will be used.

Returns:

result – Secret-shared result of shifting operand to the right by bits bits.

Return type:

AdditiveArrayShare

share(*, src, secret, shape, encoding=None)[source]

Convert an array of scalars to an additive secret share.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

  • src (int, required) – The player providing the private array to be secret shared.

  • secret (numpy.ndarray or None, required) – The secret array to be shared. This value is ignored for all players except src.

  • shape (tuple, required) – The shape of the secret. Note that all players must specify the same shape.

  • encoding (object, optional) – Encoding used to convert secret into field values. The protocol’s default encoding will be used if None.

Returns:

share – The local share of the secret shared array.

Return type:

AdditiveArrayShare

subtract(lhs, rhs, *, encoding=None)[source]

Privacy-preserving elementwise difference of arrays.

This method can be used to perform private-private, public-private, and private-public addition. The result is the secret shared elementwise difference of the operands. Note that public-public subtraction isn’t allowed, as it isn’t privacy-preserving!

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:
Returns:

result – Secret-shared difference of lhs and rhs.

Return type:

AdditiveArrayShare

sum(operand)[source]

Privacy-preserving sum of a secret shared array’s elements.

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

operand (AdditiveArrayShare, required) – Secret shared array containing elements to be summed.

Returns:

value – Secret-shared sum of operand’s elements.

Return type:

AdditiveArrayShare

zigmoid(operand, *, encoding=None)[source]

Privacy-preserving elementwise zigmoid of a secret shared array.

Zigmoid is a piecewise approximation to the popular sigmoid activation function that is more efficient to compute in an MPC context:

\[\begin{split}zigmoid(x) = \left\{ \begin{array}\\ 0 & if\ x<-0.5 \\ x+0.5 & if\ -0.5\leq x \leq 0.5 \\ 1 & if x>0.5 \end{array} \right.\end{split}\]

Note

This is a collective operation that must be called by all players that are members of communicator.

Parameters:

operand (AdditiveArrayShare, required) – Secret shared operand to which the zigmoid function will be applied.

Returns:

result – Secret-shared elementwise zigmoid of operand.

Return type:

AdditiveArrayShare