Metric Solver API

This API can be used to compute various different metrics relating to side-channel analysis. These metrics will aid with assessing a systems security and identifying areas of interest in large trace sets. Each metric is a standalone function and requires minimal setup to utilize.

signal_to_noise_ratio(labels: dict, visualize: bool = False, visualization_path: any = None) → np.ndarray:

Computes the signal-to-noise ratio of a trace set and associated labels. High magnitudes of the resulting SNR traces indicate cryptographic leakage at that sample.

Parameters:

  • labels (dict) – A Python dictionary where the keys are labels and the values are the associated power traces. The value of labels[L] is a list of power traces, list[trace_0, trace_1, …, trace_N], associated with label L. For example, the label can be the output of the AES Sbox such that L = Sbox[key ^ text].

  • visualize (bool) – Whether to visualize the result

  • visualization_path (any) – The path of where to save the visualization result, does not save if set to None

Returns:

The SNR of the provided trace set

Return type:

np.ndarray

Raises:

TypeError – if any value in labels.items() is not a np.ndarray or list type

Authors:

Samuel Karkache (swkarkache@wpi.edu), Trey Marcantonio (tmmarcantonio@wpi.edu)

organize_snr_label(traces: np.ndarray, intermediate_fcn: Callable, *args: any) → dict:

Organizes label dictionary for SNR metric using a specified intermediate function.

Parameters:

  • traces (np.ndarray) – The trace set to be used in label organization

  • intermediate_fcn (Callable) – A callback function used to generate np array of possible labels. Custom functions can be defined by the user as long as they return an np.ndarray

  • *args –

    Additional arguments needed for intermediate_func

Returns:

The labels dictionary organized

Return type:

dict

Authors:

Samuel Karkache (swkarkache@wpi.edu), Trey Marcantonio (tmmarcantonio@wpi.edu)

unmasked_sbox_output_intermediate(keys: np.ndarray, plaintexts: np.ndarray) → np.ndarray:

Unmasked sbox intermediate output for AES. Can be used with the organize_snr_label as the intermediate_fcn

Parameters:

  • keys (np.ndarray) – The set of keys used to calculate sbox output

  • plaintexts (np.ndarray) – The plaintexts used to calculate sbox output

Returns:

A list containing all intermediate values

Return type:

np.ndarray

t_test_tvla(fixed_t: np.ndarray, random_t: np.ndarray, visualize: bool = False, visualization_paths: tuple = None) → (np.ndarray, np.ndarray):

Computes the t-statistic and t-max between fixed and random trace sets. T-statistic magnitudes above or below |th| = 4.5 indicate cryptographic vulnerabilities.

Parameters:

  • random_t (np.ndarray) – The random trace set

  • fixed_t (np.ndarray) – The fixed trace set

  • visualize (bool) – Whether to visualize the result

  • visualization_paths (tuple) – The paths to be used to save the t-statistic (first idx) and t-max visualizations (second idx)

Returns:

The t-statistic at each time sample and t-max at each trace as a tuple of numpy arrays

Return type:

(np.ndarray, np.ndarray)

Raises:

ValueError – if fixed_t and random_t do not have the same length

Authors:

Dev Mehta (dmmehta2@wpi.edu), Samuel Karkache (swkarkache@wpi.edu)

pearson_correlation(predicted_leakage: np.ndarray, observed_leakage: np.ndarray, visualize: bool = False, visualization_path: any = None) → np.ndarray:

Computes the correlation between observed power traces and predicted power leakage corresponding to a key guess. The correlation when the predicted power leakage is modeled using the correct key guess has a relatively high magnitude.

Parameters:

  • predicted_leakage (np.ndarray) – predicted power consumption generated by a leakage model

  • observed_leakage (np.ndarray) – actual power traces collected from the cryptographic target

  • visualize (bool) – Whether to visualize the result

  • visualization_path (any) – The path of where to save the visualization result, does not save if set to None

Returns:

The correlation trace corresponding to the predicted leakage

Return type:

np.ndarray

Raises:

ValueError – if the predicted power leakage and the observed power leakage do not have the same length

Authors:

Samuel Karkache (swkarkache@wpi.edu)

score_and_rank(key_candidates: Iterable, target_byte: int, traces: list | np.ndarray, score_fcn: Callable, *args: any) → np.ndarray:

Scores and ranks a set of key candidates based on how likely they are to be the actual key.

Parameters:

  • key_candidates (np.ndarray) – List of key possible key candidates. For a one-byte subkey it would be [0, 1, …, 255].

  • target_byte (int) – The byte of the full key that you are targeting. Ignore and set to 0 if your scoring function does not need it.

  • traces (numpy.ndarray) – The set of power traces that will be used for scoring

  • multi_threaded (bool) – Whether to multithread the operator or not

  • score_fcn (Callable) – Callback to the scoring function used to score each key candidate. The score with correlation scoring function is pre-defined and can be used. NOTE: User defined scoring functions must be in the form score_fcn(traces, key_guess, target_byte, …) to work with this metric. Your scoring function does not need to use all the required arguments, but they must be present as shown.

  • args (Any) – Additional arguments for the scoring function supplied in score_fcn. For example, the predefined score with correlation function requires plaintexts and a leakage model callback as additional arguments.

Returns:

An numpy array of sorted tuples containing the key candidates and corresponding scores. For example, assuming that numpy array ranks was returned from the metric, ranks[0][0] is the highest ranked key candidate and ranks[0][1] is the score of the highest ranked key candidate.

Return type:

numpy.ndarray

Authors:

Samuel Karkache (swkarkache@wpi.edu), Amit Virchandbhai Prajapati (aprajapati@wpi.edu)

score_with_correlation(traces: list | np.ndarray, key_guess: any, target_byte: int, plaintexts: list | np.ndarray, leakage_model: Callable) → Number:

Scoring function that assigns a key guess a score based on the max value of the pearson correlation.

Parameters:

  • traces (list | np.ndarray) – The collected power traces

  • key_guess (any) – The key guess

  • target_byte (int) – The target byte of the key

  • plaintexts (list | np.ndarray) – The plaintexts used during trace capture

  • leakage_model (Callable) – The leakage model function. The hamming weight and hamming distance leakage model function are pre-defined in this library.

Returns:

The score of the key guess

Return type:

Number

Authors:

Samuel Karkache (swkarkache@wpi.edu)

success_rate_guessing_entropy(correct_keys: list | np.ndarray, experiment_ranks: list | np.ndarray, order: int, num_experiments: int) → (Number, Number):

Computes the success rate and guessing entropy based on computed key ranks.

Parameters:

  • correct_keys (list | np.ndarray) – an array of the correct keys of the given experiment

  • experiment_ranks (list | np.ndarray) – The ranks of a given key guess for all experiments conducted

  • order (int) – If a key is within the number specified by the order ranks, then it will count towards the success rate

  • num_experiments (int) – The number of experiments conducted

Returns:

The values of success_rate and guessing_entropy for the given number of experiments

Return type:

(Number, Number)

Authors:

Samuel Karkache (swkarkache@wpi)