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. .. py:function:: 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. :param labels: 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]. :type labels: dict :param visualize: Whether to visualize the result :type visualize: bool :param visualization_path: The path of where to save the visualization result, does not save if set to None :type visualization_path: any :return: The SNR of the provided trace set :rtype: 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) .. py:function:: organize_snr_label(traces: np.ndarray, intermediate_fcn: Callable, *args: any) -> dict: Organizes label dictionary for SNR metric using a specified intermediate function. :param traces: The trace set to be used in label organization :type traces: np.ndarray :param intermediate_fcn: 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 :type intermediate_fcn: Callable :param *args: Additional arguments needed for intermediate_func :return: The labels dictionary organized :rtype: dict :Authors: Samuel Karkache (swkarkache@wpi.edu), Trey Marcantonio (tmmarcantonio@wpi.edu) .. py:function:: 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 :param keys: The set of keys used to calculate sbox output :type keys: np.ndarray :param plaintexts: The plaintexts used to calculate sbox output :type plaintexts: np.ndarray :return: A list containing all intermediate values :rtype: np.ndarray .. py:function:: t_test_tvla(fixed_t: any, random_t: any, exp:any ,partition:bool=False, index:int=None, start_index:int=None, end_index:int=None,visualize: bool = False,visualization_paths: tuple = None) -> (np.ndarray, np.ndarray): Performs a t-test to assess the statistical difference between fixed and random trace sets. T-statistic values exceeding ±4.5 may indicate cryptographic vulnerabilities. :param fixed_t: The set of fixed traces. :type fixed_t: np.ndarray :param random_t: The set of random traces. :type random_t: np.ndarray :param exp: Experimental data or configuration settings. :type exp: any :param partition: Whether to partition the data (default: False). :type partition: bool :param index: Specific index for analysis, if applicable. :type index: int, optional :param start_index: The starting index for analysis, if applicable. :type start_index: int, optional :param end_index: The ending index for analysis, if applicable. :type end_index: int, optional :param visualize: Whether to generate visualizations of the results. :type visualize: bool :param visualization_paths: Paths to save the t-statistic (first index) and t-max (second index) visualizations. :type visualization_paths: tuple, optional :return: A tuple containing the t-statistic for each time sample and t-max for each trace. :rtype: (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) .. py:function:: 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. :param predicted_leakage: predicted power consumption generated by a leakage model :type predicted_leakage: np.ndarray :param observed_leakage: actual power traces collected from the cryptographic target :type observed_leakage: np.ndarray :param visualize: Whether to visualize the result :type visualize: bool :param visualization_path: The path of where to save the visualization result, does not save if set to None :type visualization_path: any :return: The correlation trace corresponding to the predicted leakage :rtype: 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) .. py:function:: 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. :param key_candidates: List of key possible key candidates. For a one-byte subkey it would be [0, 1, ..., 255]. :type key_candidates: np.ndarray :param target_byte: The byte of the full key that you are targeting. Ignore and set to 0 if your scoring function does not need it. :type target_byte: int :param traces: The set of power traces that will be used for scoring :type traces: numpy.ndarray :param multi_threaded: Whether to multithread the operator or not :type multi_threaded: bool :param score_fcn: 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. :type score_fcn: Callable :param args: 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. :type args: Any :return: 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. :rtype: numpy.ndarray :Authors: Samuel Karkache (swkarkache@wpi.edu), Amit Virchandbhai Prajapati (aprajapati@wpi.edu) .. py:function:: 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. :param traces: The collected power traces :type traces: list | np.ndarray :param key_guess: The key guess :type key_guess: any :param target_byte: The target byte of the key :type target_byte: int :param plaintexts: The plaintexts used during trace capture :type plaintexts: list | np.ndarray :param leakage_model: The leakage model function. The hamming weight and hamming distance leakage model function are pre-defined in this library. :type leakage_model: Callable :return: The score of the key guess :rtype: Number :Authors: Samuel Karkache (swkarkache@wpi.edu) .. py:function:: 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. :param correct_keys: an array of the correct keys of the given experiment :type correct_keys: list | np.ndarray :param experiment_ranks: The ranks of a given key guess for all experiments conducted :type experiment_ranks: list | np.ndarray :param order: If a key is within the number specified by the order ranks, then it will count towards the success rate :type order: int :param num_experiments: The number of experiments conducted :type num_experiments: int :return: The values of success_rate and guessing_entropy for the given number of experiments :rtype: (Number, Number) :Authors: Samuel Karkache (swkarkache@wpi)