An S-box located within the round function of a CipherCandidate. More...

#include </home/runner/work/hal/hal/plugins/hawkeye/include/hawkeye/cipher_candidate.h>

Collaboration diagram for hal::hawkeye::SBox:

Public Member Functions
std::vector< Gate * >	get_combinational_gates () const
	Get the combinational gates computing the outputs of the S-box from its input flip-flops. More...

Public Attributes
std::vector< Gate * >	component
	The gates of the connected component that the S-box was located in, including its input flip-flops. More...

std::vector< Gate * >	input_gates
	The input flip-flops of the S-box, ordered by gate ID. More...

std::vector< Gate * >	output_gates
	The output gates of the S-box, ordered by gate ID. Usually combinational gates feeding the linear layer. More...

std::string	identified_as
	The name of the S-box in the database it was identified as, empty unless `status` is `identified`. More...

SBoxStatus	status = SBoxStatus::unidentified
	The outcome of trying to identify the S-box, `unidentified` until `identify_sboxes` ran. More...

Detailed Description

An S-box located within the round function of a CipherCandidate.

Owned by the candidate it was located in, which also owns every gate it refers to, so an S-box is only valid for as long as its candidate is.

The exact size and shape of an S-box is not known in advance, so the search deliberately produces more S-boxes than the round function actually contains, among them smaller ones nested inside larger ones. Identification resolves that, see SBoxStatus.

Definition at line 78 of file cipher_candidate.h.

Member Function Documentation

◆ get_combinational_gates()

std::vector< Gate * > hal::hawkeye::SBox::get_combinational_gates ( ) const

Get the combinational gates computing the outputs of the S-box from its input flip-flops.

Walks back from the output gates within the component and stops at the flip-flops, so the result is the logic of this S-box alone rather than that of the whole component, which several S-boxes may share.

Returns: The combinational gates of the S-box, ordered by gate ID.

Definition at line 184 of file cipher_candidate.cpp.

References component, hal::ff, and output_gates.

Referenced by hal::hawkeye::CipherCandidate::identify_sbox(), and hal::PYBIND11_PLUGIN().

Member Data Documentation

◆ component

std::vector<Gate*> hal::hawkeye::SBox::component

The gates of the connected component that the S-box was located in, including its input flip-flops.

Definition at line 83 of file cipher_candidate.h.

Referenced by get_combinational_gates(), and hal::PYBIND11_PLUGIN().

◆ identified_as

std::string hal::hawkeye::SBox::identified_as

The name of the S-box in the database it was identified as, empty unless status is identified.

Definition at line 103 of file cipher_candidate.h.

Referenced by hal::PYBIND11_PLUGIN().

◆ input_gates

std::vector<Gate*> hal::hawkeye::SBox::input_gates

The input flip-flops of the S-box, ordered by gate ID.

These are the flip-flops of the state register that the S-box reads, and hence the only link between the identified S-box and the state bits it operates on. They are not ordered by S-box input bit: the database matches under affine equivalence, which absorbs any permutation of the input and output bits, so no bit correspondence is established during identification.

Definition at line 93 of file cipher_candidate.h.

Referenced by hal::hawkeye::CipherCandidate::identify_sbox(), and hal::PYBIND11_PLUGIN().

◆ output_gates

std::vector<Gate*> hal::hawkeye::SBox::output_gates

The output gates of the S-box, ordered by gate ID. Usually combinational gates feeding the linear layer.

Definition at line 98 of file cipher_candidate.h.

Referenced by get_combinational_gates(), hal::hawkeye::CipherCandidate::identify_sbox(), and hal::PYBIND11_PLUGIN().

◆ status

SBoxStatus hal::hawkeye::SBox::status = SBoxStatus::unidentified

The outcome of trying to identify the S-box, unidentified until identify_sboxes ran.

Distinguishes an S-box that was checked against the database without a match from one that was never checked because a larger S-box containing it had already been identified.

Definition at line 111 of file cipher_candidate.h.