cascade.shuffle module

class cascade.shuffle.Shuffle(size, algorithm, shuffle_seed=None)

Bases: object

A shuffling (i.e. re-ordering) of the bits in a key.

SHUFFLE_KEEP_SAME = 0

Do not shuffle the bits in the key.

SHUFFLE_RANDOM = 1

Randomly shuffle the bits in the key.

__init__(size, algorithm, shuffle_seed=None)

Create a shuffle. A shuffle represents a permutation of the bits in a key. The shuffle can be random or deterministic depending on the shuffle algorithm. A Shuffle object is de-coupled from the Key objects: the same Shuffle object can be applied to multiple different Key objects, to permute (shuffle) the bits in those different keys according to the same pattern.

Parameters

• size (int) – The size of the shuffle, i.e. the number of bits in the keys that this shuffle will be applied to. Must be >= 0 (i.e. empty shuffles are allowed).

• algorithm (int) – The algorithm for generating the shuffle pattern: SHUFFLE_KEEP_SAME: Do not shuffle the key (keep the key bits in the original order). SHUFFLE_RANDOM: Randomly shuffle the key.

• shuffle_seed (None or int) – The seed value for the isolated shuffle random number generator that is used to generate the shuffling permutation. If shuffle_seed is None, then a random shuffle_seed value will be generated.

__repr__()

Get the unambiguous string representation of the shuffle.

Returns

The unambiguous string representation of the shuffle.

Example

>>> shuffle.__repr__()
'Shuffle: 0->3 1->1 2->2 3->0 4->4 5->5'

__str__()

Get the human-readable string representation of the shuffle.

Returns

The human-readable string representation of the shuffle.

Example

>>> shuffle.__str__()
'0->3 1->1 2->2 3->0 4->4 5->5'

calculate_parity(key, shuffle_start_index, shuffle_end_index)

Calculate the parity of a contiguous sub-range of bits in a shuffled key.

Parameters

• key (Key) – The key for which to calculate the parity after shuffling it.

• shuffle_start_index (int) – The index of the first bit (inclusive) in the range of bits in the shuffled key over which to calculate the parity.

• shuffle_end_index (int) – The index of the last bit (exclusive) in the range of bits in the shuffled key over which to calculate the parity.

Returns

The parity of the contiguous sub-range of bits in the shuffled key.

static create_shuffle_from_identifier(identifier)

Create a shuffle object from a shuffle identifier.

Alice and Bob need to agree on how to shuffle the bits in each pass. Bob could send complete shuffle objects to Alice, but that would be expensive because shuffle objects are large. Instead, Bob sends a short shuffle identifier from Alice from which Alice can reconstruct the shuffle object.

Parameters

identifier (int) – The shuffle identifier.

flip_bit(key, shuffle_index)

Flip a bit in a shuffled key (flip 0 to 1 and vice versa).

Parameters

• key (Key) – The key. We first shuffle this key according to this shuffle pattern and then flip the bit at shuffle_index in the shuffled key. The size of the key must be equal to the size of this shuffle.

• shuffle_index (int) – The index of the bit in the shuffled key. The index must be in range [0, shuffle.size).

get_bit(key, shuffle_index)

Get a bit from a shuffled key.

Parameters

• key (Key) – The key. We first shuffle this key according to this shuffle pattern and then retrieve the bit at shuffle_index in the shuffled key. The size of the key must be equal to the size of this shuffle.

• shuffle_index (int) – The index of the bit in the shuffled key. The index must be in range [0, shuffle.size).

Returns

The value (0 or 1) of the shuffled key bit at the given index.

get_identifier()

Get the shuffle identifier.

Returns

The shuffle identifier.

get_key_index(shuffle_index)

Get the key index that a given shuffle index is mapped to.

Parameters

shuffle_index (int) – The shuffle index of the bit. Index must be in range [0, shuffle._size).

Returns

The key index.

get_size()

Get the size of the shuffle in bits.

Returns

The size of the shuffle in bits.

set_bit(key, shuffle_index, value)

Set a bit in a shuffled key to a given value.

Parameters

• key (Key) – The key. We first shuffle this key according to this shuffle pattern and then set the bit at shuffle_index in the shuffled key to the given value. The size of the key must be equal to the size of this shuffle.

• shuffle_index (int) – The index of the bit in the shuffled key. The index must be in range [0, shuffle.size).

• value (int) – The new value of the bit. Must be 0 or 1.

static set_random_seed(seed)

Set the seed for the isolated random number generated that is used only in the shuffle module and nowhere else. If two applications set the seed to the same value, the shuffle module produces the exact same sequence of shuffles. This is used to make experiments reproduceable.

Parameters

seed (int) – The seed value for the random number generator which is isolated to the shuffle module.