sboxU.core.sbox package

This module contains the various utilities needed to store and generate S-boxes.

The idea here is not yet to study S-boxes, only to generate them, and store them in a way that allows calling C++ functions without

Submodules

sboxU.core.sbox.cython_functions module

sboxU.core.sbox.cython_functions.F2_trans()

Returns an S_box containing the lookup table of a simple XOR over a given field extension of F_2.

If additive_cstte is an integer, then either field or bit_length must be set. If it is a field element, both field and bit_length will be ignored.

Parameters:

additive_cstte – the constant to add. Can be a field element or an integer. If an integer, then the field used must be specified.
field – the field in which the multiplication must be made if additive_cstte is an integer.
bit_length – the bit-length to use for both the input and output if additive_cstte is an integer.

Returns:

An S_box instance

class sboxU.core.sbox.cython_functions.S_box

Bases: object

The S_box class stores the lookup table of an vectorial boolean function, and provides useful methods to interact with it.

Objects of this class should be initialized using the :py:func:Sb function.

attach_casts_pair()

component(): Returns: An S_box instance mapping n bits to 1 corresponding to the component x mapsto S(x) cdot a, where cdot is the standard scalar product.

coordinate()

Parameters:: i – the index of the coordinate, where 0 is the bit of lowest weight.
Returns:: An S_box instance mapping n bits to 1 corresponding to the i-th coordinate of S.

derivative(): Returns: An S_box of the same dimension as S corresponding to its derivative in the direction delta, i.e. x mapsto S(x+delta)+S(x).

get_input_length()

get_output_length()

input_space()

input_space_size()

inverse()

Returns:: An S_box instance corresponding to the compositional inverse of the current S_box.

If the current S_box is not invertible, will probably crash.

is_invertible(): Returns: True if the current S_box is a bijection, False otherwise.

lut()

name()

output_space()

output_space_size()

rename()

to_bytes()

class sboxU.core.sbox.cython_functions.S_box_fp

Bases: object

coordinate()

Parameters:: i – the index of the coordinate, where 0 is the Fp word of lowest weight.
Returns:: An S_box instance mapping n Fp words to 1 corresponding to the i-th coordinate of S.

derivative()

Parameters:: i – the index of the coordinate, where 0 is the bit of lowest weight.
Returns:: An S_box_fp instance mapping n Fp words to 1 corresponding to the i-th coordinate of S.

get_input_size()

get_input_space()

get_input_space_size()

get_lut()

get_name()

get_output_size()

get_output_space()

get_output_space_size()

get_p()

static identity_S_box()

inverse()

Returns:: An S_box instance corresponding to the compositional inverse of the current S_box.

If the current S_box is not invertible, will throw an error.

is_invertible(): Returns: True if the current S_box is a bijection, False otherwise.

rename()

sboxU.core.sbox.cython_functions.get_Sbox_from_F2AffineMap()

sboxU.core.sbox.cython_functions.get_Sbox_from_bytes()

sboxU.core.sbox.cython_functions.get_Sbox_from_list()

sboxU.core.sbox.cython_functions.get_Sbox_from_lut()

sboxU.core.sbox.cython_functions.get_Sbox_from_multivariate_polynomials()

sboxU.core.sbox.cython_functions.get_Sbox_from_sage_SBox()

sboxU.core.sbox.cython_functions.get_Sbox_from_univariate_polynomial()

sboxU.core.sbox.cython_functions.get_sbox()

Turns its input into an object of the S_box class.

If it is already an S_box instance, simply returns its input. Otherwise, builds the lookup table, and then create the corresponding S_box instance.

Parameters:

s – an object of a class that can be turned into an S_box.
name – the name to give the object. If none is provided, one will be picked using sboxU_SBOXES_COUNTER.
input_casts – a list of casts that are allowed for this S_box.
output_cast – the function to apply to the integer output when querying the LUT.

sboxU.core.sbox.cython_functions.identity_S_box(): Returns an S_box instance corresponding to the identity function, i.e. the one mapping x to itself.

sboxU.core.sbox.cython_functions.new_sbox_name()

Returns a unique name that can be given to an S-box.

It uses the module variable sboxU_SBOXES_COUNTER to achieve this goal by incrementing it each time it is used.

Returns:: A bytearray corresponding to the next unique S_box name.

sboxU.core.sbox.linearCasts module

class sboxU.core.sbox.linearCasts.CastFromF2Product(input_lengths, name=None)[source]

Bases: object

Encapsulates a mapping from a cartesian product of vector spaces F_2^n_i into the modular ring of integers modulo 2^{sum_i n_i}, the idea being that the later is the actual input for the lookup query inside an S_box instance.

is_valid_input(x)[source]

structure(masks)[source]

class sboxU.core.sbox.linearCasts.CastFromF2n(gf, name=None)[source]

Bases: object

Encapsulates a mapping from a finite field of size 2**n into the modular ring of integers modulo 2^{sum_i n_i}, the idea being that the later is the actual input for the lookup query inside an S_box instance.

input_space()[source]

is_valid_input(x)[source]

class sboxU.core.sbox.linearCasts.CastToF2Product(output_lengths, name=None)[source]: Bases: object

class sboxU.core.sbox.linearCasts.CastToF2n(gf, name=None)[source]

Bases: object

Encapsulates a mapping from a finite field of size 2**n into the modular ring of integers modulo 2^{sum_i n_i}, the idea being that the later is the actual input for the lookup query inside an S_box instance.

sboxU.core.sbox.linearCasts.canonical_cast(x)[source]

sboxU.core.sbox.linearCasts.casts_from_field(gf)[source]

sboxU.core.sbox.linearCasts.loop_over_structure(input_lengths, masks=None)[source]

sboxU.core.sbox.misc module

This module contains pure python methods to generate simple S_box instances.

sboxU.core.sbox.misc.F2_mul(coeff, field=None)[source]

Returns an S_box containing the lookup table of a multiplication in an extension of F_2.

Parameters:

coeff – the coefficient by which to multiply. Can be a field element or an integer. If an integer, then the field used must be specified.
field – the field in which the multiplication must be made. If unspecified, the parent field of coeff is used.

sboxU.core.sbox.misc.inverse(s)[source]

Compositional inversion.

Parameters:: s (-) – an S_boxable object.
Returns:: An S_box object corresponding to the compositional inverse of s.

sboxU.core.sbox.misc.is_permutation(s)[source]

Returns True if and only if s is an S_boxable object corresponding to a bijective function.

Parameters:: s (-) – an S_boxable object
Returns:: True if and only if s corresponds to a bijection.

sboxU.core.sbox.misc.monomial(d, field)[source]

Returns an S_box containing the LUT of a monomial operating on the given field.

Parameters:

d – the exponent of the monomial (an integer)
field – a finite field instance assumed to be of characteristic 2.

sboxU.core.sbox.misc.random_function_S_box(input_bit_length, output_bit_length, name=None)[source]

Uses the standard randint function to generate a random S_box instance that is very unlikely to be bijective.

Parameters:

input_bit_length – the bit-length of the input of the function.
output_bit_length – the bit-length of its output.
name – a string intended to label the output.

Returns:

An S_box instance obtained by picking each output uniformly at random in the set {0, .., 2**output_bit_length-1}.

# !TODO! this function shouldn’t be here

sboxU.core.sbox.misc.random_permutation_S_box(bit_length, name=None)[source]

Uses the standard shuffle function to generate a random bijective S_box instance.

Parameters:

bit_length – the bit-length of the input (and output) of the function.
name – a string intended to label the output.

Returns:

An S_box instance picked uniformly at random from the set of all permutations operating on the set {0, .., 2**bit_length-1}.

# !TODO! this function shouldn’t be here