hal::hawkeye Namespace Reference

Classes
struct	DetectionConfiguration
	Configuration to set up the register candidate search. More...
class	RegisterCandidate
	A register candidate discovered by HAWKEYE. More...
class	RoundCandidate
	A round candidate constructed from a previously discovered register candidate. More...
class	SBoxDatabase
	Database of known S-boxes. More...
class	SBoxCandidate
	An S-box candidate discovered within the round function of a round candidate. More...

Functions
Result< std::vector< RegisterCandidate > >	detect_candidates (Netlist *nl, const std::vector< DetectionConfiguration > &configs, u32 min_state_size=40, const std::vector< Gate * > &start_ffs={})
	Attempt to locate candidates for symmetric cryptographic implementations within a gate-level netlist. More...
Result< std::vector< SBoxCandidate > >	locate_sboxes (const RoundCandidate *candidate)
	Try to locate S-box candidates within the combinational next-state logic of the round function candidate. More...
Result< std::string >	identify_sbox (const SBoxCandidate &sbox_candidate, const SBoxDatabase &db)
	Try to identify an S-box candidate by matching it against a database of known S-boxes under affine equivalence. More...

Detailed Description

Locates candidates for symmetric cryptographic implementations within a gate-level netlist.

Function Documentation

detect_candidates()

Result< std::vector< RegisterCandidate > > hal::hawkeye::detect_candidates	(	Netlist *	nl,
		const std::vector< DetectionConfiguration > &	configs,
		u32	min_state_size = 40,
		const std::vector< Gate * > &	start_ffs = {}
	)

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

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

Returns

Ok() and a vector of candidates on success, an error otherwise.

Definition at line 312 of file candidate_search.cpp.

References hal::hawkeye::DetectionConfiguration::CHECK_FF, hal::hawkeye::DetectionConfiguration::CHECK_NETS, hal::hawkeye::DetectionConfiguration::CHECK_PINS, hal::hawkeye::DetectionConfiguration::CHECK_SCC, hal::hawkeye::DetectionConfiguration::CHECK_TYPE, ERR, hal::ff, hal::graph_algorithm::NetlistGraph::from_netlist_no_edges(), hal::Netlist::get_gate_library(), hal::Netlist::get_gates(), hal::Gate::get_type(), in_reg, log_info, hal::hawkeye::DetectionConfiguration::NONE, OK, out_reg, and size.

Referenced by hal::PYBIND11_PLUGIN().

identify_sbox()

Result< std::string > hal::hawkeye::identify_sbox	(	const SBoxCandidate &	sbox_candidate,
		const SBoxDatabase &	db
	)

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

Parameters

[in]	sbox_candidate	- An S-box candidate.
[in]	db	- A database of known S-boxes.

Returns

OK() and the name of the matching S-box, or an empty string if no S-box of the database matched the candidate. An error is only returned if the candidate could not be analyzed at all.

Definition at line 291 of file sbox_lookup.cpp.

References hal::BooleanFunction::Const(), ERR, hal::BooleanFunctionNetDecorator::get_boolean_variable_name(), hal::hawkeye::RoundCandidate::get_control_inputs(), hal::hawkeye::RoundCandidate::get_input_reg(), hal::hawkeye::RoundCandidate::get_netlist(), hal::hawkeye::RoundCandidate::get_other_inputs(), hal::hawkeye::RoundCandidate::get_state_inputs(), in_reg, log_error, log_info, hal::hawkeye::SBoxDatabase::lookup(), hal::hawkeye::SBoxCandidate::m_candidate, hal::hawkeye::SBoxCandidate::m_component, hal::hawkeye::SBoxCandidate::m_input_gates, hal::hawkeye::SBoxCandidate::m_output_gates, OK, hal::sum, and hal::BooleanFunction::to_u64().

Referenced by hal::PYBIND11_PLUGIN().

locate_sboxes()

Result< std::vector< SBoxCandidate > > hal::hawkeye::locate_sboxes

(

const RoundCandidate *

candidate

)

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

[in]

candidate

- A round function candidate.

Returns

A vector of S-box candidates on success, an error otherwise.

Definition at line 18 of file sbox_lookup.cpp.

References hal::c_inverter, ERR, hal::ff, hal::graph_algorithm::get_connected_components(), hal::hawkeye::RoundCandidate::get_graph(), hal::hawkeye::RoundCandidate::get_input_ffs_of_gate(), hal::hawkeye::RoundCandidate::get_input_reg(), hal::hawkeye::RoundCandidate::get_longest_distance_to_gate(), hal::hawkeye::RoundCandidate::get_netlist(), hal::hawkeye::RoundCandidate::get_output_reg(), hal::graph_algorithm::get_subgraph(), log_info, hal::hawkeye::SBoxCandidate::m_candidate, hal::hawkeye::SBoxCandidate::m_component, hal::hawkeye::SBoxCandidate::m_input_gates, hal::hawkeye::SBoxCandidate::m_output_gates, and OK.

Referenced by hal::PYBIND11_PLUGIN().