exclusive module

Data structure for representing secret shares of byte vectors based on bitwise XOR, designed for use within secure multi-party computation (MPC) protocol implementations.

class exclusive.exclusive.share

Bases: bytes

Data structure for representing a XOR-based secret share of a bytes-like object.

Normally, the shares function should be used to construct a list of share objects.

>>> (a, b) = shares(bytes([1, 2, 3]))
>>> (c, d) = shares(bytes([4, 5, 6]))
>>> xor([xor([a, c]), xor([b, d])]) == xor([bytes([1, 2, 3]), bytes([4, 5, 6])])
True

static from_bytes(bs: Union[bytes, bytearray]) → exclusive.exclusive.share

Convert a secret share represented as a bytes-like object into a share object. This method is provided primarily for forward-compatibility and for consistency with related libraries such as additive.

>>> share.from_bytes(bytes([1, 2, 3]))
share([1, 2, 3])

static from_base64(s: str) → exclusive.exclusive.share

Convert a secret share represented as a Base64 encoding of a bytes-like object into a share object.

>>> share.from_base64('AQID')
share([1, 2, 3])

__xor__(other: exclusive.exclusive.share) → exclusive.exclusive.share

Return the bitwise exclusive disjunction (XOR) of this share and another share.

>>> share(bytes([1, 2, 3])) ^ share(bytes([4, 5, 6]))
share([5, 7, 5])

If the two share arguments do not have equal lengths, an exception is raised.

>>> share(bytes([1, 2, 3])) ^ share(bytes([4, 5]))
Traceback (most recent call last):
  ...
ValueError: shares must have equal lengths

to_bytes() → bytes

Return a bytes-like object that encodes this share object. This method is provided primarily for forward-compatibility and for consistency with related libraries such as additive.

>>> share.from_base64('HgEA').to_bytes().hex()
'1e0100'
>>> ss = [s.to_bytes() for s in shares(bytes([1, 2, 3]))]
>>> xor(share.from_bytes(s) for s in ss).hex()
'010203'

to_base64() → str

Return a Base64 string representation of this share object.

>>> share(bytes([1, 2, 3])).to_base64()
'AQID'
>>> ss = [s.to_base64() for s in shares(bytes([1, 2, 3]))]
>>> xor(share.from_base64(s) for s in ss).hex()
'010203'

__str__() → str

Return string representation of this share object.

>>> str(share(bytes([1, 2, 3])))
'share([1, 2, 3])'

__repr__() → str

Return string representation of this share object.

>>> share(bytes([1, 2, 3]))
share([1, 2, 3])

exclusive.exclusive.shares(value: Union[bytes, bytearray], quantity: Optional[int] = 2) → Sequence[exclusive.exclusive.share]

Convert a bytes-like object into two or more secret shares.

>>> (s, t) = shares(bytes([1, 2, 3]))
>>> s ^ t == bytes([1, 2, 3])
True
>>> ss = shares(bytes([1, 2, 3]), 20)
>>> len(ss)
20
>>> bytes(xor(ss)).hex()
'010203'
>>> all(isinstance(s, share) for s in shares(bytes([1, 2, 3])))
True

Some compatibility and validity checks of the supplied parameter values are performed.

>>> shares(bytes([1, 2, 3]), 1)
Traceback (most recent call last):
  ...
ValueError: quantity of shares must be at least 2

exclusive.exclusive.xor(iterable: Iterable[Union[bytes, bytearray]]) → bytes

Apply the exclusive disjunction operation across all of the elements of the supplied iterable.

>>> xor([bytes([1, 2]), bytes([3, 4]), bytes([5, 6])]).hex()
'0700'

If all bytes-like objects in the supplied iterable do not have the same length, an exception is raised.

>>> xor([bytes([1, 2]), bytes([3, 4, 5]), bytes([5, 6])]).hex()
Traceback (most recent call last):
  ...
ValueError: all bytes-like objects must have the same length

If the supplied iterable does not contain at least one item, an exception is raised.

>>> xor([]).hex()
Traceback (most recent call last):
  ...
ValueError: iterable must have at least one item