cicada.shamir module

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

class cicada.shamir.ShamirArrayShare(storage)[source]

Bases: object

Stores the local share of a Shamir-shared secret array.

Instances of ShamirArrayShare should only be created using ShamirBasicProtocolSuite or ShamirProtocolSuite.

property storage

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

class cicada.shamir.ShamirBasicProtocolSuite(communicator, *, threshold, seed=None, seed_offset=None, order=None, encoding=None, indices=None)[source]

Bases: object

Protocol suite implementing limited computation with Shamir-shared secrets.

ShamirBasicProtocolSuite implements a limited set of operations that can be performed on Shamir-shared secrets, chosen so that the minimum number of shares \(k\) needed to recover a secret is \(k <= n\), where \(n\) is the number of players.

If you need a full set of operations including multiplication, use ShamirProtocolSuite instead.

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.

  • threshold (int, required) – The minimum number of shares \(k\) needed to recover a secret, where \(k <= n\) and \(n\) is the number of players.

  • 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.

  • indices (sequence of int, optional) – The \(x\)-values where coefficients for secret shares generated by this protocol are defined. The default is the integers \([1, n]\) where \(n\) is the number of players.

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:

ShamirArrayShare

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 (ShamirArrayShare, required) – Secret shared array containing bits to be composed.

Returns:

result – Share of the resulting field values.

Return type:

ShamirArrayShare

property communicator

The Communicator used by this protocol.

property encoding

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

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:

ShamirArrayShare

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:

ShamirArrayShare

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:

ShamirArrayShare

property indices

Return the \(x\)-values used by this protocol to reveal secrets.

Returns:

indices – One dimensional array of \(x\)-values where coefficients for secret shares generated by this protocol are defined.

Return type:

numpy.ndarray

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 (ShamirArrayShare, required) – Secret shared operand to be additively inverted.

Returns:

result – Secret-shared elementwise additive inverse of operand.

Return type:

ShamirArrayShare

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 (ShamirArrayShare, required) – Secret shared operand which should be re-randomized.

Returns:

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

Return type:

ShamirArrayShare

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 (ShamirArrayShare, 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

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:

ShamirArrayShare

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:

ShamirArrayShare

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 (ShamirArrayShare, required) – Secret shared array containing elements to be summed.

Returns:

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

Return type:

ShamirArrayShare

property threshold

Return the threshold (minimum number of players required to reveal a secret).

class cicada.shamir.ShamirProtocolSuite(communicator, *, threshold, seed=None, seed_offset=None, order=None, encoding=None, indices=None)[source]

Bases: ShamirBasicProtocolSuite

Protocol suite implementing a full set of operations on Shamir-shared secrets.

ShamirProtocolSuite provides a complete set of operations on Shamir-shared secrets including multiplication and logical comparisons. However, in order to do this, the minimum number of shares \(k\) needed to recover a secret must be constrained to \(k <= \frac{n+1}{2}\), where \(n\) is the number of players.

If you don’t need multiplication or logical comparisons, and do need a less restrictive threshold \(k\), use ShamirBasicProtocolSuite instead.

Multiplication is based on “Simplified VSS and fast-track multiparty computations with applications to threshold cryptography” by Gennaro, Rabin, and Rabin, 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.

  • threshold (int, required) – The minimum number of shares \(k\) needed to recover a secret, where \(k <= \frac{n+1}{2}\) and \(n\) is the number of players.

  • 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.

  • indices (sequence of int, optional) – The \(x\)-values where coefficients for secret shares generated by this protocol are defined. The default is the integers \([1, n]\) where \(n\) is the number of players.

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 (ShamirArrayShare, required) – Secret shared value to which the absolute value function should be applied.

Returns:

result – Secret-shared elementwise absolute value of operand.

Return type:

ShamirArrayShare

add(lhs, rhs, *, encoding=None)

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:

ShamirArrayShare

bit_compose(operand)

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 (ShamirArrayShare, required) – Secret shared array containing bits to be composed.

Returns:

result – Share of the resulting field values.

Return type:

ShamirArrayShare

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 (ShamirArrayShare, 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:

ShamirArrayShare

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 (ShamirArrayShare, required) – Secret shared value to be divided.

  • rhs (ShamirArrayShare 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:

ShamirArrayShare

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 (ShamirArrayShare, required) – Secret shared vector.

  • rhs (ShamirArrayShare, 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:

ShamirArrayShare

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:

ShamirArrayShare

property field

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

field_add(lhs, rhs)

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:

ShamirArrayShare

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:

ShamirArrayShare

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:

ShamirArrayShare

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 (ShamirArrayShare, 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:

ShamirArrayShare

field_subtract(lhs, rhs)

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:

ShamirArrayShare

field_uniform(*, shape=None, generator=None)

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:

ShamirArrayShare

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 (ShamirArrayShare, 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:

ShamirArrayShare

property indices

Return the \(x\)-values used by this protocol to reveal secrets.

Returns:

indices – One dimensional array of \(x\)-values where coefficients for secret shares generated by this protocol are defined.

Return type:

numpy.ndarray

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:

ShamirArrayShare

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:

ShamirArrayShare

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:

ShamirArrayShare

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 (ShamirArrayShare, required) – Secret shared array for logical NOT.

Returns:

result – Secret-shared elementwise logical NOT of operand.

Return type:

ShamirArrayShare

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:

ShamirArrayShare

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:

ShamirArrayShare

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

Privacy-preserving product of a matrix and a vector.

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:

ShamirArrayShare

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:

ShamirArrayShare

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:

ShamirArrayShare

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 (ShamirArrayShare, required) – Secret shared operand to be multiplicatively inverted.

Returns:

result – Secret-shared elementwise multiplicative inverse of operand.

Return type:

ShamirArrayShare

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:

ShamirArrayShare

negative(operand)

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 (ShamirArrayShare, required) – Secret shared operand to be additively inverted.

Returns:

result – Secret-shared elementwise additive inverse of operand.

Return type:

ShamirArrayShare

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 (ShamirArrayShare, required) – Secret shared values which will be raised to a power.

  • rhs (numpy.ndarray containing integers, required) – Public non-negative integer power to which each element in lhs will be raised. Normal numpy broadcasting rules apply, so rhs can be any shape that is compatible with lhs.

  • encoding (object, optional) – Determines how far to right shift 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:

ShamirArrayShare

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 (ShamirArrayShare) – Secret shared array of randomly-generated bits, with shape \(shape \times bits\).

  • secrets (ShamirArrayShare) – 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 (ShamirArrayShare, required) – Secret shared operand to which the ReLU function will be applied.

Returns:

result – Secret-shared elementwise ReLU of operand.

Return type:

ShamirArrayShare

reshare(operand)

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 (ShamirArrayShare, required) – Secret shared operand which should be re-randomized.

Returns:

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

Return type:

ShamirArrayShare

reveal(share, *, dst=None, encoding=None)

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 (ShamirArrayShare, 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 (ShamirArrayShare, 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:

ShamirArrayShare

share(*, src, secret, shape, encoding=None)

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:

ShamirArrayShare

subtract(lhs, rhs, *, encoding=None)

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:

ShamirArrayShare

sum(operand)

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 (ShamirArrayShare, required) – Secret shared array containing elements to be summed.

Returns:

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

Return type:

ShamirArrayShare

property threshold

Return the threshold (minimum number of players required to reveal a secret).

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 (ShamirArrayShare, required) – Secret shared operand to which the zigmoid function will be applied.

Returns:

result – Secret-shared elementwise zigmoid of operand.

Return type:

ShamirArrayShare