Generic functions

AND(input, number_of_inputs, verbosity=False)

INPUT:

  • input – BitArray object; BitArray

  • number_of_inputs – integer; specify in how many parts must the input be split

  • verbosity – boolean (default: False); set this flag to True to print the input/output

MODADD(input, number_of_inputs, modulus, verbosity=False)

The modulus is 2^w, where w=Floor(input_length/number_of_inputs).

INPUT:

  • input – BitArray object; BitArray

  • number_of_inputs – integer; specify in how many parts must the input be split

  • verbosity – boolean (default: False); set this flag to True to print the input/output

MODSUB(input, number_of_inputs, modulus, verbosity=False)

The modulus is 2^w, where w=Floor(input_length/number_of_inputs).

INPUT:

  • input – BitArray object; BitArray

  • number_of_inputs – integer; specify in how many parts must the input be split

  • verbosity – boolean (default: False); set this flag to True to print the input/output

NOT(input, verbosity=False)

INPUT:

  • input – BitArray object; BitArray

  • verbosity – boolean (default: False); set this flag to True to print the input/output

OR(input, number_of_inputs, verbosity=False)

INPUT:

  • input – BitArray object; BitArray

  • number_of_inputs – integer; specify in how many parts must the input be split

  • verbosity – boolean (default: False); set this flag to True to print the input/output

ROTATE(input, rotation_amount, verbosity=False)

If rotation_amount is negative rotation happens to the left, to the right otherwise.

INPUT:

  • input – BitArray object; a BitArray representing a binary string

  • rotation_amount – integer; an integer indicating the amount of the rotation, positive for right rotation, negative for left rotation

  • verbosity – boolean (default: False); set this flag to True to print the input/output

EXAMPLES:

sage: from claasp.cipher_modules.generic_functions import ROTATE
sage: from bitstring import BitArray
sage: b = BitArray("0x8")
sage: b.bin
'1000'
sage: ROTATE(b,1).bin
'0100'
sage: ROTATE(b,-2).bin
'0010'
ROTATE_BY_VARIABLE_AMOUNT(input, input_size, rotation_direction, verbosity=False)

INPUT:

  • input – BitArray object; a BitArray representing a binary string

  • input_size – integer; size in bits of the binary string to be rotated

  • rotation_direction – integer; an integer indicating the direction of the rotation, positive for right

    and negative for left

  • verbosity – boolean (default: False); set this flag to True to print the input/output

ROTATE_boolean_function(component, BoolPolyRing)

INPUT:

  • component – Component object; is a component of a cipher

  • BoolPolyRing – Boolean Polynomial Ring object; is a Boolean Polynomial Ring

SHIFT(input, shift_amount, verbosity=False)

If shift_amount is negative shift happens to the left, to the right otherwise.

INPUT:

  • input – BitArray object; a BitArray representing a binary string

  • shift_amount – integer; an integer indicating the amount of the shift, positive for right shift,

    negative for left shift

  • verbosity – boolean (default: False); set this flag to True to print the input/output

EXAMPLES:

sage: from claasp.cipher_modules.generic_functions import SHIFT
sage: from bitstring import BitArray
sage: b = BitArray("0xF")
sage: b.bin
'1111'
sage: SHIFT(b,1).bin
'0111'
sage: SHIFT(b,-2).bin
'1100'
SHIFT_BY_VARIABLE_AMOUNT(input, input_size, shift_direction, verbosity=False)

INPUT:

  • input – BitArray object; a BitArray representing a binary string

  • input_size – integer; size in bits of the binary string to be shifted

  • shift_direction – integer; an integer indicating the direction of the shift, positive for right and

    negative for left

  • verbosity – boolean (default: False); set this flag to True to print the input/output

SIGMA(input, rotation_amounts, verbosity=False)

If rotation_amount is negative rotation happens to the left, to the right otherwise.

INPUT:

  • input – BitArray object; a BitArray representing a binary string

  • rotation_amounts – list; list indicating the amount of the rotations

  • verbosity – boolean (default: False); set this flag to True to print the input/output

EXAMPLES:

sage: from claasp.cipher_modules.generic_functions import SIGMA
sage: from bitstring import BitArray
sage: b = BitArray("0x8")
sage: SIGMA(b,[1,3]).bin
'1101'
THETA_GASTON(input, rotation_amounts=(1, 18, 23, 25, 32, 52, 60, 63))

Perform the twin column parity mixer (mixing layer) of Gaston.

INPUT: - input – BitArray of length 320 or 640, interpreted as 5 rows of 64 bits. - rotation_amounts – tuple of 8 integers (default: (1, 18, 23, 25, 32, 52, 60, 63)):

  • First three values: r, s, u — rotation amounts for P, Q, and E.

  • Remaining five values: t0 through t4 — row-specific rotation amounts used in computing Q.

EXAMPLES:

sage: from claasp.cipher_modules.generic_functions import THETA_GASTON
sage: from bitstring import BitArray
sage: b = BitArray(bytes=range(40))
sage: THETA_GASTON(b).bin[:70] == '0011010110100010000110000010011000101100101110110000000100111111001111'
True
THETA_KECCAK(input)

Perform the mixing layer of Keccak.

INPUT:

  • input – BitArray object; a BitArray representing a binary string

EXAMPLES:

sage: from claasp.cipher_modules.generic_functions import THETA_KECCAK
sage: from bitstring import BitArray
sage: b = BitArray("0xf1258f7940e1dde784d5ccf933c0478ad598261ea65aa9eebd1547306f80494d8b284e056253d057ff97a42d7f8e6fd490fee5a0a44647c48c5bda0cd6192e76ad30a6f71b19059c30935ab7d08ffc64eb5aa93f2317d635a9a6e6260d71210381a57c16dbcf555f43b831cd0347c82601f22f1a11a5569f05e5635a21d9ae6164befef28cc970f2613670957bc46611b87c5a554fd00ecb8c3ee88a1ccf32c8940c7922ae3a26141841f924a2c509e416f53526e70465c275f644e97f30a13beaf1ff7b5ceca249")
sage: THETA_KECCAK(b).hex == '09b84e4804496b9b7c480dc87768f1f62d05e72fe2f21f92458886012b28ff3173b58f3426fb662b6be4933769b0bcec048dd2bab27894fc1828ed16c027fd4e394391ed0d27d6a4a4e06dadc6b12f5cfd95713beec720a9bf693e22c0a1d79f976aa412161fa3c35577e9c9ce973eba173df71edc75a0038f8853e756dc0031eed3ce4ffbccdea2eb5b40280cc1c84132116ae838d5a09b0653d8376bca9c988c89ff979aa0f7a600c47f91965fd8560e70b393d39eb4706d73c25c4baa7089f27479ce687673fb'
True
THETA_XOODOO(input)

Perform the mixing layer of Xoodoo.

INPUT:

  • input – BitArray object; a BitArray representing a binary string

EXAMPLES:

sage: from claasp.cipher_modules.generic_functions import THETA_XOODOO
sage: from bitstring import BitArray
sage: b = BitArray("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef")
sage: THETA_XOODOO(b).bin[:10] == '0101100100'
True
XOR(input, number_of_inputs, verbosity=False)

INPUT:

  • input – BitArray object; BitArray

  • number_of_inputs – integer; specify in how many parts must the input be split

  • verbosity – boolean (default: False); set this flag to True to print the input/output

XOR_boolean_function(component, BoolPolyRing)

INPUT:

  • component – object; component of a cipher

  • BoolPolyRing – Boolean Polynomial Ring object; Boolean Polynomial Ring

add_padding(a, number_of_rows, res_vector, word_size)
compute_indexed_sum(index_list, bits)

Compute the XOR-sum of products of bits at specified indices.

compute_word_indexed_sum(index_list, word_array, word_gf)

Evaluate an index-based expression sum in GF(2^w). Each entry in index_list: (field coefficient as int, [word indices]). The sum is computed and returned.

concatenate_bool_func(component, BoolPolyRing)

INPUT:

  • component – Component object; component of a cipher

  • BoolPolyRing – Boolean Polynomial Ring object; Boolean Polynomial Ring

constant_bool_func(component)

INPUT:

  • component – Component object; component of a cipher

convert_polynomial_to_binary_matrix_given_polynomial_modulus(word_size, polynomial, N)

Calculate binary matrix from word_size, polynomial and N.

Multiplication by N in the QuotientRing defined by word_size and the irreducible polynomial.

INPUT:

  • word_size – integer; size of each element of the input_matrix and the input_vector

  • polynomial – integer; irreducible polynomial that defines the quotient ring

  • N – integer; a polynomial

OUTPUT:

  • Binary matrix.

convert_x_to_binary_matrix_given_polynomial_modulus(word_size, polynomial)

Calculate binary matrix from word_size and polynomial.

Multiplication by 2 in the QuotientRing defined by word_size and the irreducible polynomial.

INPUT:

  • word_size – integer; size of each element of the input_matrix and the input_vector

  • polynomial – integer; irreducible polynomial that defines the quotient ring

OUTPUT:

  • Binary matrix.

fsr_binary(input, registers_info, number_of_clocks, verbosity=False)

INPUT:

  • input – BitArray object; a BitArray

  • registers_info – list; a list of [register_bit_length, update_expression, clock_condition (optional)],

    register_bit_length is an integer to indicate the length of the register. update_expression and clock_condition are lists of index groups, represented as integer lists. For example [[0], [1], [2, 3]] represents x0 + x1 + x2*x3. [] represents a constant 1.

  • number_of_clocks – integer; indicates how many loops this FSR component would operate, this is optional

    by default it is 1.

  • verbosity – boolean (default: False); set this flag to True to print the input/output

fsr_word(input, registers_info, bits_inside_word, number_of_clocks, verbosity=False)

INPUT:

  • input – BitArray object; a BitArray

  • registers_info – list; a list of [register_bit_length, update_expression, clock_condition (optional)],

    register_bit_length is an integer to indicate the length of the register. update_expression and clock_condition are lists of index groups, represented as integer lists. Each entry in update_expression has a field coefficient and a list of word indices. For example: [[1, [0]], [1, [1]], [1, [2, 3]]] represents x0 + x1 + x2*x3. [] represents a constant 1.

  • bits_inside_word – integer; number of bits in a word.

  • number_of_clocks – integer; indicates how many loops this FSR component would operate.

  • verbosity – boolean (default: False); set this flag to True to print the input/output.

index_list_to_expression_str(index_list)

Convert an index-based expression list to a readable string.

Example: [[0], [1], [2, 3]] -> ‘x0 + x1 + x2*x3’

index_list_to_expression_str_word(index_list)

Convert a word-level index-based expression list to a readable string.

Each entry is [field_coefficient, [indices]]. For example:

[[1, [0]], [1, [2]], [1, [11]]] -> ‘x0 + x2 + x11’

int_to_byte_array(integer_value, bit_length)
linear_layer(input, matrix, verbosity=False)

INPUT:

  • input – BitArray object; a BitArray

  • matrix – list; a list of lists of 0s and 1s. len(matrix) should be equal to input.len

  • verbosity – boolean (default: False); set this flag to True to print the input/output

merge_bits()
mix_column_generalized(input_vector, input_matrix, polynomial, word_size, verbosity=False)

INPUT:

  • input_vector – BitArray object; BitArray

  • input_matrix – list; 2 dimensional list

  • polynomial – integer; irreducible polynomial that defines the quotient ring

  • word_size – integer; size of each element of the input_matrix and the input_vector

  • verbosity – boolean (default: False); set this flag to True to print the input/output

mix_column_generalized_bool_func(component, BoolPolyRing)

INPUT:

  • component – object; component of a cipher

  • BoolPolyRing – Boolean Polynomial Ring object; Boolean Polynomial Ring

padding(input, verbosity=False)

INPUT:

  • input – BitArray object; BitArray

  • verbosity – boolean (default: False); set this flag to True to print the input/output

sbox(input, lookup_table, output_len, verbosity=False)

INPUT:

  • input – BitArray object; BitArray

  • lookup_table – list; list of integers

  • output_len – integer; output bit size of sbox

  • verbosity – boolean (default: False); set this flag to True to print the input/output

sbox_bool_func(component, BoolPolyRing)

INPUT:

  • component – Component object; component of a cipher

  • BoolPolyRing – Boolean Polynomial Ring object; Boolean Polynomial Ring

select_bits(input, bit_positions, verbosity=False)

INPUT:

  • input – BitArray object; a BitArray representing a binary string

  • bit_positions – list; the positions of the bits

  • verbosity – boolean (default: False); set this flag to True to print the input/output

set_from_hex_string(hex_str)
transform_GF2NMatrix_to_BinMatrix(GF2NMatrix, polynomial, word_size)

Transform the binary matrix into the equivalent GF2NMatrix.

INPUT:

  • GF2NMatrix – matrix; matrix

  • polynomial – integer; irreducible polynomial that defines the quotient ring

  • word_size – integer; size of each element of the input_matrix and the input_vector

OUTPUT:

  • Binary matrix.