cicada.active module
Functionality for creating, manipulating, and revealing additive-shared secrets.
Bases:
object
Stores the local share of a secret shared array for
ActiveProtocolSuite
.Instances of
ActiveArrayShare
should only be created usingActiveProtocolSuite
.Additive secret-shared portion of
storage
.
Shamir secret-shared portion of
storage
.
Private storage for the local share of a secret shared array. Access is provided only for serialization and communication - callers must use
ActiveProtocolSuite
to manipulate secret shares.
- class cicada.active.ActiveProtocolSuite(communicator, *, threshold, seed=None, seed_offset=None, order=None, encoding=None)[source]
Bases:
object
Protocol suite implementing shared secret computation that is secure against an active adversary.
Implements “Combining Shamir & additive secret sharing to improve efficiency of SMC primitives against malicious adversaries” by Goss, which provides honest majority security with abort.
Both
AdditiveProtocolSuite
andShamirProtocolSuite
are used in the implementation.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 ofFixedPoint
with 16 bits of floating-point precision ifNone
.
- 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 (
ActiveArrayShare
, required) – Secret shared value to which the absolute value function should be applied.- Returns:
result – Secret-shared elementwise absolute value of operand.
- Return type:
- 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:
lhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public values to be added.rhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public values to be added.encoding (
object
, optional) – Encodes public operands. The protocol’sencoding
is used by default ifNone
.
- Returns:
result – Secret-shared sum of lhs and rhs.
- Return type:
- 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 (
ActiveArrayShare
, required) – Secret shared array containing bits to be composed.- Returns:
result – Share of the resulting field values.
- Return type:
- 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 (
ActiveArrayShare
, 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’sfield
.
- Returns:
result – Share of the bit decomposed secret.
- Return type:
- property communicator
The
Communicator
used by this protocol.
- divide(lhs, rhs, *, encoding=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 (
ActiveArrayShare
, required) – Secret shared value to be divided.rhs (
ActiveArrayShare
ornumpy.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’sencoding
is used by default ifNone
.
- Returns:
result – Secret-shared quotient of lhs and rhs.
- Return type:
- 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 (
ActiveArrayShare
, required) – Secret shared vector.rhs (
ActiveArrayShare
, required) – Secret shared vector.encoding (
object
, optional) – Determines the number of bits to truncate from intermediate results. The protocol’sencoding
is used by default ifNone
.
- Returns:
result – Secret-shared dot product of lhs and rhs.
- Return type:
- 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:
lhs (
ActiveArrayShare
, required) – Secret shared array to be compared.rhs (
ActiveArrayShare
, required) – Secret shared array to be compared.
- Returns:
result – Secret-shared result from comparing lhs == rhs elementwise.
- Return type:
- 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:
lhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public value to be added.rhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public value to be added.
- Returns:
result – Secret-shared sum of lhs and rhs.
- Return type:
- 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:
lhs (
ActiveArrayShare
, required) – Secret shared vector.rhs (
ActiveArrayShare
, required) – Secret shared vector.
- Returns:
result – Secret-shared dot product of lhs and rhs.
- Return type:
- 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:
lhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public value to be multiplied.rhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public value to be multiplied.
- Returns:
result – Secret-shared product of lhs and rhs.
- Return type:
- 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 (
ActiveArrayShare
, required) – Secret shared values which iwll be raised to a power.rhs (
int
or integernumpy.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:
- 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:
lhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public value to be subtracted.rhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public value to be subtracted.
- Returns:
result – Secret-shared difference of lhs and rhs.
- Return type:
- 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:
- 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 (
ActiveArrayShare
, 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’sencoding
is used by default ifNone
.
- Returns:
result – Secret-shared floor of operand.
- Return type:
- 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:
lhs (
ActiveArrayShare
, required) – Secret shared values to be compared.rhs (
ActiveArrayShare
, required) – Secret shared values to be compared.
- Returns:
result – Secret-shared comparison \(lhs \lt rhs\).
- Return type:
- 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:
lhs (
ActiveArrayShare
, required) – Secret shared values to be compared.rhs (
ActiveArrayShare
, required) – Secret shared values to be compared.
- Returns:
result – Secret-shared comparison \(operand \lt 0\).
- Return type:
- 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:
lhs (
ActiveArrayShare
, required) – Secret shared array for logical AND.rhs (
ActiveArrayShare
, required) – Secret shared array for logical AND.
- Returns:
result – Secret-shared elementwise logical AND of lhs and rhs.
- Return type:
- 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 (
ActiveArrayShare
, required) – Secret shared array for logical NOT.- Returns:
result – Secret-shared elementwise logical NOT of operand.
- Return type:
- 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:
lhs (
ActiveArrayShare
, required) – Secret shared array for logical OR.rhs (
ActiveArrayShare
, required) – Secret shared array for logical OR.
- Returns:
result – Secret-shared elementwise logical OR of lhs and rhs.
- Return type:
- 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:
lhs (
ActiveArrayShare
, required) – Secret shared array for logical XOR.rhs (
ActiveArrayShare
, required) – Secret shared array for logical XOR.
- Returns:
result – Secret-shared elementwise logical XOR of lhs and rhs.
- Return type:
- 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:
lhs (
ActiveArrayShare
, required) – Secret shared operand.rhs (
ActiveArrayShare
, required) – Secret shared operand.
- Returns:
result – Secret-shared elementwise maximum of lhs and rhs.
- Return type:
- 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:
lhs (
ActiveArrayShare
, required) – Secret shared operand.rhs (
ActiveArrayShare
, required) – Secret shared operand.
- Returns:
result – Secret-shared elementwise minimum of lhs and rhs.
- Return type:
- 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 (
ActiveArrayShare
, required) – Secret shared operand to be multiplicatively inverted.- Returns:
result – Secret-shared elementwise multiplicative inverse of operand.
- Return type:
- 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:
lhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public value to be multiplied.rhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public value to be multiplied.encoding (
object
, optional) – Encodes public operands and determines the number of bits to shift right the results. The protocol’sencoding
is used by default ifNone
.
- Returns:
result – Secret-shared product of lhs and rhs.
- Return type:
- 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 (
ActiveArrayShare
, required) – Secret shared operand to be additively inverted.- Returns:
result – Secret-shared elementwise additive inverse of operand.
- Return type:
- 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 (
ActiveArrayShare
, required) – Secret shared values which iwll be raised to a power.rhs (
int
or integernumpy.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’sencoding
is used by default ifNone
.
- Returns:
result – Secret-shared result of raising lhs to the power(s) in rhs.
- Return type:
- random_bitwise_secret(*, bits, src=None, generator=None, shape=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 (
ActiveArrayShare
) – Secret shared array of randomly-generated bits, with shape \(shape \times bits\).secrets (
ActiveArrayShare
) – 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 (
ActiveArrayShare
, required) – Secret shared operand to which the ReLU function will be applied.- Returns:
result – Secret-shared elementwise ReLU of operand.
- Return type:
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 (
ActiveArrayShare
, required) – Secret shared operand which should be re-randomized.- Returns:
result – Secret-shared, re-randomized version of operand.
- Return type:
- Raises:
ConsistencyError – If the consistency of the returned secret shares cannot be confirmed.
- 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 (
ActiveArrayShare
, required) – The local share of the secret to be revealed.dst (sequence of
int
, optional) – List of players who will receive the revealed secret. IfNone
(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:
- Raises:
ConsistencyError – If the consistency of the returned secret shares cannot be confirmed.
- right_shift(operand, *, bits, src=None, generator=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
.- Parameters:
operand (
ActiveArrayShare
, 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:
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
orNone
, 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:
- 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:
lhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public values to be subtracted.rhs (
ActiveArrayShare
ornumpy.ndarray
, required) – Secret shared or public values to be subtracted.encoding (
object
, optional) – Encodes public operands. The protocol’sencoding
is used by default ifNone
.
- Returns:
result – Secret-shared difference of lhs and rhs.
- Return type:
- 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 (
ActiveArrayShare
, required) – Secret shared array containing elements to be summed.- Returns:
value – Secret-shared sum of operand’s elements.
- Return type:
- verify(operand)[source]
Test whether shares are consistent.
Tests the consistency of secret shares among all players using a zero knowledge proof. This method allows the players to prove to one another (in zero knowledge) that a consistent set of shares is known by all players. It can provide a “safe” point at which calculations are known to be good, so that parties can “rewind” if consistency problems are later discovered in the protocol.
Note
This is a collective operation that must be called by all players that are members of
communicator
.- Parameters:
operand (
ActiveArrayShare
, required) – Secret shared operand which will be verified for consistency.- Returns:
consistency –
True
if every player has demonstrated that they have consistent shares, otherwiseFalse
.- Return type:
- 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 (
ActiveArrayShare
, required) – Secret shared operand to which the zigmoid function will be applied.- Returns:
result – Secret-shared elementwise zigmoid of operand.
- Return type:
- exception cicada.active.ConsistencyError[source]
Bases:
Exception
Exception raised when the consistency of secret shares cannot be confirmed.
- add_note()
Exception.add_note(note) – add a note to the exception
- args
Warning
attribute ‘cicada.active.ConsistencyError.args’ undocumented
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.