Utils

add_arcs(arcs, component, curr_input_bit_ids, input_bit_size, intermediate_output_arcs, previous_output_bit_ids)

check_if_implemented_component(component)

convert_solver_solution_to_dictionary(cipher, model_type, solver_name, solve_time, memory, components_values, total_weight)

Return a dictionary that represents the solution obtained from the solver.

INPUT:

• cipher_id – string; the cipher id

• model_type – string; the type of the model that has been solved

• solver_name – string; the solver used to get the solution

• solve_time – float; the time (in seconds) consumed by the solver finding the solution

• memory – float; the memory (in MB) consumed by the solver finding the solution

• components_values – dictionary; each key of the dictionary is the component id, each value is a dictionary whose keys are value and weight

• total_weight – integer; representing the total weight

See also

set_component_value_weight_sign()

EXAMPLES:

sage: from claasp.cipher_modules.models.utils import convert_solver_solution_to_dictionary
sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: speck = SpeckBlockCipher(number_of_rounds=4)
sage: convert_solver_solution_to_dictionary(speck.id, 'xor_differential', 'z3', 0.239, 175.5, [], 0)
{'cipher': 'speck_p32_k64_o32_r4',
 'components_values': [],
 'memory_megabytes': 175.500000000000,
 'model_type': 'xor_differential',
 'solver_name': 'z3',
 'solving_time_seconds': 0.239000000000000,
 'total_weight': 0}

differential_checker_permutation(cipher, input_difference, output_difference, number_of_samples, state_size, seed=None)

Verifies experimentally differential distinguishers for permutations using the vectorized evaluator

differential_linear_checker_for_block_cipher_single_key(cipher, input_difference, output_mask, number_of_samples, block_size, key_size, fixed_key, seed=None)

Verifies experimentally differential-linear distinguishers for block ciphers using the vectorized evaluator

differential_linear_checker_for_permutation(cipher, input_difference, output_mask, number_of_samples, state_size, seed=None)

This method helps to verify experimentally differential-linear distinguishers for permutations using the vectorized evaluator

differential_truncated_checker_permutation(cipher, input_difference, output_difference, number_of_samples, state_size, seed=None)

Verifies experimentally differential-truncated distinguishers for permutations in the single-key scenario

differential_truncated_checker_single_key(cipher, input_difference, output_difference, number_of_samples, state_size, fixed_key, key_size, seed=None)

Verifies experimentally differential-truncated distinguishers for block_ciphers in the single-key scenario

extract_bit_positions(binary_str)

Extracts bit positions from a binary+unknows string.

extract_bits(columns, positions)

Extracts the bits from columns at the specified positions.

find_sign_for_one_xor_linear_trail(cipher, solution)

Return the trail together with the sign of the weight and of every single component.

INPUT:

• solution – dictionary; the dictionary showing a linear trail for the cipher

EXAMPLES:

sage: from claasp.cipher_modules.models.milp.milp_models.milp_xor_linear_model import MilpXorLinearModel
sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: from claasp.cipher_modules.models.utils import set_fixed_variables, integer_to_bit_list, find_sign_for_one_xor_linear_trail
sage: speck = SpeckBlockCipher(block_bit_size=32, key_bit_size=64, number_of_rounds=3).remove_key_schedule()
sage: milp = MilpXorLinearModel(speck)
sage: fixed_variables = [set_fixed_variables('plaintext', 'not equal', list(range(32)),
....: integer_to_bit_list(0, 32, 'little'))]
sage: trail = milp.find_lowest_weight_xor_linear_trail(fixed_variables)
sage: trail_with_sign = find_sign_for_one_xor_linear_trail(speck, trail)
sage: abs(trail_with_sign['final_sign'])
1

find_sign_for_xor_linear_trails(cipher, solutions)

Return the trails together with the sign of the weight and of every single component.

INPUT:

• solutions – dictionary; the list of dictionaries showing a linear trail for the cipher.

EXAMPLES:

sage: from claasp.cipher_modules.models.milp.milp_models.milp_xor_linear_model import MilpXorLinearModel
sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: from claasp.cipher_modules.models.utils import set_fixed_variables, integer_to_bit_list, find_sign_for_xor_linear_trails
sage: speck = SpeckBlockCipher(block_bit_size=8, key_bit_size=16, number_of_rounds=3).remove_key_schedule()
sage: milp = MilpXorLinearModel(speck)
sage: plaintext = set_fixed_variables(
....: component_id='plaintext', constraint_type='not equal',
....: bit_positions=range(8), bit_values=integer_to_bit_list(0x0, 8, 'big'))
sage: trails = milp.find_all_xor_linear_trails_with_fixed_weight(1, fixed_values = [plaintext])
sage: trails_with_sign = find_sign_for_xor_linear_trails(speck, trails)
sage: abs(trails_with_sign[0]['final_sign'])
1

get_bit_bindings(cipher, format_func=<function <lambda>>)

Return two dictionaries.

A key is an output bit of a component. A value is a list of input bits which are the end point of an arc in cipher for the relative key.

EXAMPLES:

sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: from claasp.cipher_modules.models.utils import get_bit_bindings
sage: speck = SpeckBlockCipher(block_bit_size=32, key_bit_size=64, number_of_rounds=2)
sage: speck_without_key_schedule = speck.remove_key_schedule()
sage: arcs, intermediate_output_arcs = get_bit_bindings(speck_without_key_schedule, '_'.join)
sage: arcs
{'key_0_2_0_o': ['xor_0_2_16_i'],
 'key_0_2_10_o': ['xor_0_2_26_i'],
 'key_0_2_11_o': ['xor_0_2_27_i'],
 ...
 'xor_1_8_7_o': ['xor_1_10_7_i', 'cipher_output_1_12_7_i'],
 'xor_1_8_8_o': ['xor_1_10_8_i', 'cipher_output_1_12_8_i'],
 'xor_1_8_9_o': ['xor_1_10_9_i', 'cipher_output_1_12_9_i']}
sage: intermediate_output_arcs
{'intermediate_output_0_6': {'intermediate_output_0_6_0_i': ['xor_0_2_0_o',
   'xor_0_4_0_i'],
  'intermediate_output_0_6_10_i': ['xor_0_2_10_o', 'xor_0_4_10_i'],
  'intermediate_output_0_6_11_i': ['xor_0_2_11_o', 'xor_0_4_11_i'],
  ...
  'intermediate_output_0_6_7_i': ['xor_0_2_7_o', 'xor_0_4_7_i'],
  'intermediate_output_0_6_8_i': ['xor_0_2_8_o', 'xor_0_4_8_i'],
  'intermediate_output_0_6_9_i': ['xor_0_2_9_o', 'xor_0_4_9_i']}}

get_previous_output_bit_ids(input_bit_positions, input_id_links, format_func)

get_related_key_scenario_format_for_fixed_values(_cipher)

Return a list of dictionary in standard format representing the fixed values in a related key scenario.

See also

set_fixed_variables()

EXAMPLES:

sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: from claasp.cipher_modules.models.utils import get_related_key_scenario_format_for_fixed_values
sage: speck = SpeckBlockCipher(number_of_rounds=4)
sage: fixed_values = get_related_key_scenario_format_for_fixed_values(speck)
sage: fixed_values[0]["constraint_type"]
'not_equal'

get_single_key_scenario_format_for_fixed_values(_cipher)

Return a list of dictionary in standard format representing the fixed values in a single key scenario.

See also

set_fixed_variables()

EXAMPLES:

sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: from claasp.cipher_modules.models.utils import get_single_key_scenario_format_for_fixed_values
sage: speck = SpeckBlockCipher(number_of_rounds=4)
sage: fixed_values = get_single_key_scenario_format_for_fixed_values(speck)
sage: fixed_values[0]["constraint_type"]
'equal'
sage: fixed_values[1]["constraint_type"]
'not_equal'

integer_to_bit_list(int_value, list_length, endianness='little')

Return a list that contains the binary value for each bit position.

INPUT:

• int_value – integer; the value to convert in binary

• list_length – integer; the value representing the desired length of the output list

• endianness – string (default: little); the endianess of the list

  • endianess='big', the bit list will be returned with the MSB indexed by 0

  • endianess='little', the bit list will be returned with the LSB indexed by 0

EXAMPLES:

sage: from claasp.cipher_modules.models.utils import integer_to_bit_list
sage: integer_to_bit_list(5, 5, 'big')
[0, 0, 1, 0, 1]

print_components_values(solution)

Print the dict of component values in standard format.

See also

set_component_value_weight_sign()

INPUT:

• solution – dictionary; the solution as given by convert_solver_solution_to_dictionary()

EXAMPLES:

sage: from claasp.cipher_modules.models.utils import print_components_values
sage: print_components_values({
....:     'components_values': {
....:         'plaintext': {
....:             'value': '0x1234',
....:             'weight': 0
....:         },
....:         'key': {
....:             'value': '0xabcd',
....:             'weight': 7
....:         }
....:     }
....: })
┌───────────────────────────┬──────────────────────────────────────────┬────────┐
│ COMPONENT ID              │ VALUE                                    │ WEIGHT │
├───────────────────────────┼──────────────────────────────────────────┼────────┤
│ plaintext                 │ 0x1234                                   │ -      │
├───────────────────────────┼──────────────────────────────────────────┼────────┤
│ key                       │ 0xabcd                                   │ 7      │
└───────────────────────────┴──────────────────────────────────────────┴────────┘

set_component_solution(value, weight=None, sign=None)

Return a dictionary that represents the solution for one component of the cipher.

INPUT:

• value – string; hexadecimal representation (e.g. 'abcd1234') that represents the output of the component

• weight – integer (default: None); the weight of the component

• sign – integer (default: None); the sign of the weight of the component (either 1 or -1)

EXAMPLES:

sage: from claasp.cipher_modules.models.utils import set_component_solution
sage: set_component_solution('abcd1234', 0, 1)
{'sign': 1, 'value': 'abcd1234', 'weight': 0}

set_component_value_weight_sign(value, weight=0, sign=1)

Return a dictionary that represents the solution for one component of the cipher.

INPUT:

• value – string; hexadecimal representation (e.g. '0x1234') that represents the output of the component

• weight – integer (default: 0); the weight of the component (remark: if different from 0, the current component is non-linear operation)

• sign – integer (default: 1); the sign of the weight of the component (either 1 or -1)

EXAMPLES:

sage: from claasp.cipher_modules.models.utils import set_component_value_weight_sign
sage: set_component_value_weight_sign('0x0000', 0, 1)
{'sign': 1, 'value': '0x0000', 'weight': 0}

set_fixed_variables(component_id, constraint_type, bit_positions, bit_values)

Return a dictionary.

The dictionary has the information needed to fix the output of a component to a specific value or some bits of the output to specific values.

INPUT:

• component_id – string; the id of the component

• constraint_type – string; the type of the constraint

  • 'equal', the constraints will fix bit_values for the component specified by component_id

  • 'not_equal', the constraints will avoid at least one of the bit_values for the component specified by component_id

• bit_positions – list of int; the positions of the bits to be fixed

• bit_values – list of int; the values of each bit. If len(bit_values) < len(bit_positions) the bit_values list will be padded with ‘0’ values, otherwise bit_values will be truncated to match the bit_positions list length

EXAMPLES:

sage: from claasp.cipher_modules.models.utils import set_fixed_variables, integer_to_bit_list
sage: set_fixed_variables('key', 'equal', list(range(4)), integer_to_bit_list(5, 4, 'little'))
{'bit_positions': [0, 1, 2, 3],
 'bit_values': [1, 0, 1, 0],
 'component_id': 'key',
 'constraint_type': 'equal'}

shared_difference_paired_input_differential_checker_permutation(cipher, input_difference, output_difference, number_of_samples, state_size, seed=None)

Verifies experimentally SharedDifferencePairedInputDifferential distinguishers for permutations using the vectorized evaluator

shared_difference_paired_input_differential_linear_checker_permutation(cipher, input_difference, output_mask, number_of_samples, state_size, seed=None)

This method helps to verify experimentally SharedDifferencePairedInputDifferentialLinear distinguishers for permutations using the vectorized evaluator

to_bias_for_correlation_measure(cipher, solution)

to_bias_for_probability_measure(cipher, solution)

to_bias_for_xor_linear_trail(cipher, solution)

Return the trail of solution but with the weights corresponding to the bias.

The value returned is a solution in standard format.

INPUT:

• solution – dictionary; a trail found with find_lowest_weight_xor_linear_trail()

EXAMPLES:

sage: from claasp.cipher_modules.models.milp.milp_models.milp_xor_linear_model import MilpXorLinearModel
sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: from claasp.cipher_modules.models.utils import set_fixed_variables, integer_to_bit_list, to_bias_for_xor_linear_trail
sage: speck = SpeckBlockCipher(block_bit_size=32, key_bit_size=64, number_of_rounds=4).remove_key_schedule()
sage: milp = MilpXorLinearModel(speck)
sage: plaintext = set_fixed_variables(component_id='plaintext', constraint_type='not equal',
....: bit_positions=range(32), bit_values=integer_to_bit_list(0x0, 32, 'big'))
sage: trail = milp.find_lowest_weight_xor_linear_trail([plaintext]) # long
...

sage: to_bias_for_xor_linear_trail(speck, trail) # random
{'building_time_seconds': 0.06306815147399902,
 'cipher_id': 'speck_p32_k64_o32_r4',
 ...
 'measure': 'bias',
 ...
 'total_weight': 4.0}

to_correlation_for_bias_measure(cipher, solution)

to_correlation_for_probability_measure(cipher, solution)

to_correlation_for_xor_linear_trail(cipher, solution)

Return the trail of solution but with the weights corresponding to the correlation.

The value returned is a solutions in standard format.

INPUT:

• solution – dictionary; a trail found with find_lowest_weight_xor_linear_trail()

EXAMPLES:

sage: from claasp.cipher_modules.models.milp.milp_models.milp_xor_linear_model import MilpXorLinearModel
sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: from claasp.cipher_modules.models.utils import set_fixed_variables, integer_to_bit_list, to_correlation_for_xor_linear_trail
sage: speck = SpeckBlockCipher(block_bit_size=32, key_bit_size=64, number_of_rounds=4).remove_key_schedule()
sage: milp = MilpXorLinearModel(speck)
sage: plaintext = set_fixed_variables(component_id='plaintext', constraint_type='not equal',
....: bit_positions=range(32), bit_values=integer_to_bit_list(0x0, 32, 'big'))
sage: trail = milp.find_lowest_weight_xor_linear_trail([plaintext])
sage: to_correlation_for_xor_linear_trail(speck, trail) # random
{'building_time_seconds': 0.10187196731567383,
 'cipher_id': 'speck_p32_k64_o32_r4',
 ...
 'measure': 'correlation',
 ...
 'total_weight': 3.0}

to_probability_for_bias_measure(cipher, solution)

to_probability_for_correlation_measure(cipher, solution)

to_probability_for_xor_linear_trail(cipher, solution)

Return the trail of solution but with the weights corresponding to the probability.

The value returned is a solutions in standard format.

INPUT:

• solution – dictionary; a trail found with find_lowest_weight_xor_linear_trail()

EXAMPLES:

sage: from claasp.cipher_modules.models.milp.milp_models.milp_xor_linear_model import MilpXorLinearModel
sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: from claasp.cipher_modules.models.utils import set_fixed_variables, integer_to_bit_list, to_probability_for_xor_linear_trail
sage: speck = SpeckBlockCipher(block_bit_size=32, key_bit_size=64, number_of_rounds=4).remove_key_schedule()
sage: milp = MilpXorLinearModel(speck)
sage: plaintext = set_fixed_variables(component_id='plaintext', constraint_type='not equal',
....: bit_positions=range(32), bit_values=integer_to_bit_list(0x0, 32, 'big'))
sage: trail = milp.find_lowest_weight_xor_linear_trail([plaintext])
...

sage: to_probability_for_xor_linear_trail(speck, trail) # random
{'building_time_seconds': 0.13295412063598633,
 'cipher_id': 'speck_p32_k64_o32_r4',
 ...
 'measure': 'probability',
 ...
 'total_weight': 0.83}

write_model_to_file(model_to_write, file_name)

Write the solver model into a file inside the current directory.

Note

This file can be deleted once the solver has finished its computation.

INPUT:

• model_to_write – list; the model

• file_name – string; the path of the file that will contain the model. The suggested format for the name of the file is: [graph_representation_of_the_cipher]_[solver_type].txt (e.g. speck32_64_r22_sat.txt)

OUTPUT:

• This method does not return anything, but it creates a file with the specified model as a string in it

EXAMPLES:

sage: from claasp.cipher_modules.models.utils import write_model_to_file
sage: file_name = 'claasp/cipher_modules/models/model_file.txt'
sage: write_model_to_file(['xor_differential', 'xor_linear'], file_name)
sage: os.remove(file_name)

write_solution_to_file(solution, file_path)

Write the solver solution into a file.

INPUT:

• solution – dictionary; the solution in standard format

• file_path – string; the entire path of the file that will contain the solution

See also

convert_solver_solution_to_dictionary()

Note

The file_path should be composed like this: claasp/previous_results/cipher_name/solver_type/cipher_id_solver_name.py E.g. claasp/previous_results/speck/sat/speck32_64_r22_cryptominisat.py

OUTPUT:

• This method does not return anything, but it creates a file with a solution of a solver

EXAMPLES:

sage: from claasp.ciphers.block_ciphers.speck_block_cipher import SpeckBlockCipher
sage: from claasp.cipher_modules.models.utils import (convert_solver_solution_to_dictionary,
....: write_solution_to_file)
sage: speck = SpeckBlockCipher(number_of_rounds=4)
sage: file_name = 'claasp/previous_results/speck/sat/speck32_64_r22_cryptominisat.py'
sage: dict = convert_solver_solution_to_dictionary(speck.id, 'xor_differential', 'z3', 0.239, 175.5, [], 0)
sage: write_solution_to_file(dict, file_name) # doctest: +SKIP
sage: os.remove(file_name) # doctest: +SKIP