HAWKEYE

Automated tool to locate arbitrary symmetric cryptographic implementations in gate-level netlists.

hawkeye.detect_candidates(nl: hal_py.Netlist, configs: List[hawkeye.DetectionConfiguration], min_state_size: int = 40, start_ffs: List[hal_py.Gate] = []) → Optional[List[hawkeye.RegisterCandidate]]

Attempt to locate candidates for symmetric cryptographic implementations within a gate-level netlist. Search operates only on an abstraction of the netlist that contains only flip-flops as nodes and connections through combinational logic as edges. The algorithm computes the k-neighborhood of each flip-flop for k = 1, ..., config.timeout and stops when the neighborhood size saturates. Depending on the config, additional criteria are used to narrow down the search space, see DetectionConfiguration.Control and DetectionConfiguration.Components for details. When the neighborhood size saturates, a register candidate is created if the last neighborhood size is larger than config.min_register_size. After the candidates have been identified, they are reduced further to produce the final set of register candidates. To this end, large candidates that fully contain a smaller candidate and candidates that are smaller than min_state_size are discarded.

Parameters

nl (hal_py.Netlist) – The netlist to operate on.
configs (list[hawkeye.DetectionConfiguration]) – The configurations of the detection approaches to be executed one after another on each start flip-flop.
min_state_size (int) – The minimum size of a register candidate to be considered a cryptographic state register. Defaults to 40.
start_ffs (list[hal_py.Gate]) – The flip-flops to analyze. Defaults to an empty list, i.e., all flip-flops in the netlist will be analyzed.

Returns

A list of candidates on success, None otherwise.

Return type

list[hawkeye.RegisterCandidate] or None

hawkeye.identify_sbox(sbox_candidate: hawkeye.SBoxCandidate, db: hawkeye.SBoxDatabase) → Optional[str]

Try to identify an S-box candidate by matching it against a database of known S-boxes under affine equivalence.

Parameters

sbox_candidate (hawkeye.SBoxCandidate) – An S-box candidate.
db (hawkeye.SBoxDatabase) – A database of known S-boxes.

Returns

The name of the S-box on success, None otherwise.

Return type

str or None

hawkeye.locate_sboxes(candidate: hawkeye.RoundCandidate) → Optional[List[hawkeye.SBoxCandidate]]

Try to locate S-box candidates within the combinational next-state logic of the round function candidate. Computes an initial set of connected components within the round function extracted between the input and output register of the round candidate. If these initial components are reasonably small and their input and output sizes match, construct S-box candidates for further analysis right away. Otherwise, iteratively consider more combinational gates starting from the components’ input gates and search for sub-components. Create S-box candidates for these sub-components after determining the respective S-box output gates.

Parameters: candidate (hawkeye.RoundCandidate) – A round function candidate.
Returns: A list of S-box candidates on success, None otherwise.
Return type: list[hawkeye.SBoxCandidate] or None

class hawkeye.DetectionConfiguration

This class holds important parameters that configure the candidate search of HAWKEYE.

__init__(self: hawkeye.DetectionConfiguration) → None: Constructs a default DetectionConfiguration.

class Components

This enum specifies whether SCC detection should be used to refine the results of neighborhood discovery. If SCC detection is used, the exploration only stops if the size of the largest discovered SCC saturates. Specifically, it does no longer require the size of the entire neighborhood to saturate.

Members:

NONE : Do not use SCC detection and instead resort to the simple neighborhood discovery algorithm.

CHECK_SCC : Use SCC detection within the currently explored neighborhood of a start flip-flop.

property name

class Control

This enum specifies the checks that are to be performed on the flip-flops of the netlist to determine whether there should be an edge between two flip-flops or not.

Members:

CHECK_FF : If two flip-flops ff1 and ff2 are connected through combinational logic, an edge is added such that (ff1,ff2) is part of the graph.

CHECK_TYPE : If two flip-flops ff1 and ff2 are connected through combinational logic and are of the same gate type, an edge is added such that (ff1,ff2) is part of the graph.

CHECK_PINS : If two flip-flops ff1 and ff2 are connected through combinational logic and are controlled through the same input pins, an edge is added such that (ff1,ff2) is part of the graph.

CHECK_NETS : If two flip-flops ff1 and ff2 are connected through combinational logic and are controlled through the same input nets, an edge is added such that (ff1,ff2) is part of the graph.

property name

property components

Determines whether to use SCC detection as part of neighborhood discovery.

Type: hawkeye.DetectionConfiguration.Components

property control

Checks to be performed on flip-flop control inputs during candidate search.

Type: hawkeye.DetectionConfiguration.Control

property equivalent_types

A list of a list of gate types that are treated as identical types by the candidate search, i.e., when checking equality of the types of two gates that are different but declared equivalent, True is returned.

Type: list[list[str]]

property min_register_size

Minimum number of flip-flops for a register candidate to be created.

Type: int

property timeout

Neighborhood discovery iteration timeout.

Type: int

class hawkeye.RegisterCandidate

This class holds all information belonging to a register candidate discovered by HAWKEYE’s candidate search and makes these information accessible through getters.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: hawkeye.RegisterCandidate) -> None

Default constructor for RegisterCandidate.

__init__(self: hawkeye.RegisterCandidate, round_reg: Set[hal_py.Gate]) -> None

Construct a state register candidate from the state register of a round-based implementation.

param set[hal_py.Gate] round_reg

The state register.
__init__(self: hawkeye.RegisterCandidate, in_reg: Set[hal_py.Gate], out_reg: Set[hal_py.Gate]) -> None

Construct a state register candidate from the input and output registers from one round of a pipelined implementation.

param set[hal_py.Gate] in_reg

The input register.

param set[hal_py.Gate] out_reg

The output register.

get_input_reg(self: hawkeye.RegisterCandidate) → Set[hal_py.Gate]

Get the candidate’s input register.

Returns: The input register of the candidate.
Return type: set[hal_py.Gate]

get_netlist(self: hawkeye.RegisterCandidate) → hal_py.Netlist

Get the netlist associated with the candidate.

Returns: The netlist of the candidate.
Return type: hal_py.Netlist

get_output_reg(self: hawkeye.RegisterCandidate) → Set[hal_py.Gate]

Get the candidate’s output register.

Returns: The output register of the candidate.
Return type: set[hal_py.Gate]

get_size(self: hawkeye.RegisterCandidate) → int

Get the size of the candidate, i.e., the width of its registers.

Returns: The size of the candidate.
Return type: int

is_round_based(self: hawkeye.RegisterCandidate) → bool

Check if the candidate is round-based, i.e., input and output register are the same.

Returns: True if the candidate is round-based, False otherwise.
Return type: bool

class hawkeye.RoundCandidate

This class holds all information belonging to a round candidate. Round candidates are constructed from register candidates by copying the sub-circuit consisting of the input and (if pipelined) output registers as well as the next-state/round-function logic in between these registers. For round-based implementations, commonly only a single register exists that acts as an input and output register at the same time. In such cases, this register is considered to be the input register of the round function and an exact copy of the register will be appended to the round function outputs so that input and output register are guaranteed to be distinct.

__init__(self: hawkeye.RoundCandidate) → None: Default constructor for RoundCandidate.

static from_register_candidate(candidate: hawkeye.RegisterCandidate) → hawkeye.RoundCandidate

Compute a round candidate from a previously identified register candidate. The netlist of this candidate will be a partial copy of the original netlist, comprising only the gates belonging to the registers and the logic computing the next state. In case of a round-based implementation, the output register will be a copy of the input register. All data structures of the round candidate will be initialized in the process.

Parameters: candidate (hawkeye.RegisterCandidate) – The register candidate.
Returns: The round candidate on success, None otherwise.
Return type: hawkeye.RoundCandidate or None

get_control_inputs(self: hawkeye.RoundCandidate) → Set[hal_py.Net]

Get the candidate’s control inputs to the logic computing the next state.

Returns: The control inputs of the candidate.
Return type: set[hal_py.Net]

get_graph(self: hawkeye.RoundCandidate) → graph_algorithm.NetlistGraph

Get the netlist graph of the round candidate.

Returns: The netlist graph of the candidate.
Return type: graph_algorithm.NetlistGraph

get_input_ffs_of_gate(self: hawkeye.RoundCandidate) → Dict[hal_py.Gate, Set[hal_py.Gate]]

Get a dict from each combinational gate of the round function to all the input flip-flops it depends on.

Returns: A dict from gates to sets of input flip-flops.
Return type: dict[hal_py.Gate,set[hal_py.Gate]]

get_input_reg(self: hawkeye.RoundCandidate) → Set[hal_py.Gate]

Get the candidate’s input register.

Returns: The input register of the candidate.
Return type: set[hal_py.Gate]

get_longest_distance_to_gate(self: hawkeye.RoundCandidate) → Dict[int, Set[hal_py.Gate]]

Get a dict from an integer distance to all gates that are reachable within at most that distance when starting at any input flip-flop.

Returns: A dict from longest distance to a set of gates being reachable in at most that distance.
Return type: dict[int,set[hal_py.Gate]]

get_netlist(self: hawkeye.RoundCandidate) → hal_py.Netlist

Get the netlist of the round candidate. The netlist is a partial copy of the netlist of the register candidate.

Returns: The netlist of the candidate.
Return type: hal_py.Netlist

get_other_inputs(self: hawkeye.RoundCandidate) → Set[hal_py.Net]

Get the candidate’s other inputs to the logic computing the next state.

Returns: The other inputs of the candidate.
Return type: set[hal_py.Net]

get_output_reg(self: hawkeye.RoundCandidate) → Set[hal_py.Gate]

Get the candidate’s output register.

Returns: The output register of the candidate.
Return type: set[hal_py.Gate]

get_size(self: hawkeye.RoundCandidate) → int

Get the size of the candidate, i.e., the width of its registers.

Returns: The size of the candidate.
Return type: int

get_state_inputs(self: hawkeye.RoundCandidate) → Set[hal_py.Net]

Get the candidate’s state inputs to the logic computing the next state.

Returns: The state inputs of the candidate.
Return type: set[hal_py.Net]

get_state_logic(self: hawkeye.RoundCandidate) → Set[hal_py.Gate]

Get the candidate’s combinational logic computing the next state.

Returns: The state logic of the candidate.
Return type: set[hal_py.Gate]

get_state_outputs(self: hawkeye.RoundCandidate) → Set[hal_py.Net]

Get the candidate’s state outputs from the logic computing the next state.

Returns: The state outputs of the candidate.
Return type: set[hal_py.Net]

class hawkeye.SBoxCandidate

This class stores all information related to an S-box candidate discovered within the round function of a round candidate, such as the RoundCandidate it belongs to, the connected component it is part of, and its input and output gates.

__init__(self: hawkeye.SBoxCandidate) → None: Default constructor for SBoxCandidate.

property m_candidate: The RoundCandidate that the S-box candidate belongs to.

property m_component: The gates of the component which the S-box candidate is part of.

property m_input_gates: The input gates of the S-box candidate (will be flip-flops).

property m_output_gates: The output gates of the S-box candidate (usually combinational logic that is input to the linear layer).

class hawkeye.SBoxDatabase

This class holds and manages known S-boxes and allows to perform efficient S-box lookups in the database.

__init__(*args, **kwargs)

Overloaded function.

__init__(self: hawkeye.SBoxDatabase) -> None

Construct an empty S-box database.
__init__(self: hawkeye.SBoxDatabase, sboxes: Dict[str, List[int]]) -> None

Construct an S-box database from the given S-boxes.

param dict[str,list[int]] sboxes

A dict from S-box name to the respective S-box.

add(*args, **kwargs)

Overloaded function.

add(self: hawkeye.SBoxDatabase, name: str, sbox: List[int]) -> bool

Add an S-box to the database.

param str name

The name of the S-box.

patam list[int] sbox

The S-box.

returns

True on success, False otherwise.

rtype

bool
add(self: hawkeye.SBoxDatabase, sboxes: Dict[str, List[int]]) -> bool

Add multiple S-boxes to the database.

param dict[str,list[int]] sboxes

A dict from S-box name to the respective S-box.

returns

True on success, False otherwise.

rtype

bool

static compute_linear_representative(sbox: List[int]) → List[int]

Compute the linear representative of the given S-box.

Parameters: sbox (list[int]) – The S-box.
Returns: The linear representative.
Return type: list[int]

static from_file(file_path: os.PathLike) → Optional[hawkeye.SBoxDatabase]

Construct an S-box database from file.

Parameters: file_path (pathlib.Path) – The path from which to load the S-box database file.
Returns: The S-box database on success, None otherwise.
Return type: hawkeye.SBoxDatabase or None

load(self: hawkeye.SBoxDatabase, file_path: os.PathLike, overwrite: bool = False) → bool

Load S-boxes from a file and add them to the existing database.

Parameters

file_path (pathlib.Path) – The path from which to load the S-box database file.
overwrite (bool) – Set True to overwrite existing database, False otherwise. Defaults to False.

Returns

True on success, False otherwise.

Return type

bool

lookup(self: hawkeye.SBoxDatabase, sbox: List[int]) → Optional[str]

Attempt to look up an S-box in the database.

Parameters: sbox (list[int]) – The S-box to look for.
Returns: The S-box name on success, None otherwise.
Return type: str or None

print(self: hawkeye.SBoxDatabase) → None: Print the database.

store(self: hawkeye.SBoxDatabase, file_path: os.PathLike) → bool

Store the S-box database to a database file.

Parameters: file_path (pathlib.Path) – The path to where to store the S-box database file.
Returns: True on success, False otherwise.
Return type: bool

class hawkeye.HawkeyePlugin

This class provides an interface to integrate the HAWKEYE tool as a plugin within the HAL framework.

property dependencies

A set of plugin names that this plugin depends on.

Type: set[str]

property description

The description of the plugin.

Type: str

get_dependencies(self: hawkeye.HawkeyePlugin) → Set[str]

Get a set of plugin names that this plugin depends on.

Returns: A set of plugin names that this plugin depends on.
Return type: set[str]

get_description(self: hawkeye.HawkeyePlugin) → str

Get the description of the plugin.

Returns: The description of the plugin.
Return type: str

get_name(self: hawkeye.HawkeyePlugin) → str

Get the name of the plugin.

Returns: The name of the plugin.
Return type: str

get_version(self: hawkeye.HawkeyePlugin) → str

Get the version of the plugin.

Returns: The version of the plugin.
Return type: str

property name

The name of the plugin.

Type: str

property version

The version of the plugin.

Type: str