deploy: 34233c3

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 2ec2c988acfef4a8b92f24e10976535e
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/cwscope.rst.txt

@@ -0,0 +1,98 @@
+ChipWhisperer Scope Interface
+======================
+
+Researchers at WPI and across the country use ChipWhisperer devices to conduct
+side-channel analysis research. ChipWhisperer has an existing library developed to
+interface with their devices. However, this library was improved upon by providing
+higher-level API calls
+
+.. class:: CWScope
+
+    .. method:: __init__(self, firmware_path: str, gain: int = 25, num_samples: int = 5000, offset: int = 0, target_type: any = cw.targets.SimpleSerial, target_programmer: any = cw.programmers.STM32FProgrammer) -> None:
+
+        Initializes a CW scope object
+
+        :param firmware_path: The name of the compiled firmware that will be loaded on the CW target board
+        :type firmware_path: str
+        :param gain: The gain of the CW scope
+        :type gain: int
+        :param num_samples: The number of samples to collect for each trace on the CW scope
+        :type num_samples: int
+        :param offset: The tine offset for CW scope trace collection
+        :type offset: int
+        :param target_type: The target type of the CW scope. This depends on the specific ChipWhisperer device that you are using.
+        :type target_type: any
+        :param target_programmer: The target programmer of the CW scope. This depends on the specific ChipWhisperer device that you are using.
+        :type target_programmer: any
+        :return: None
+        :Authors: Samuel Karkache (swkarkache@wpi.edu)
+
+    .. method:: disconnect(self)
+
+        Disconnect CW Scope and Target
+
+    .. method:: standard_capture_traces(self, num_traces: int, experiment_keys: np.ndarray = None, experiment_texts: np.ndarray = None, fixed_key: bool = True, fixed_pt: bool = False) -> (np.ndarray, np.ndarray, np.ndarray, np.ndarray):
+
+        Capture procedure for ChipWhisperer devices. Will return a specified number of traces and the data associated
+        with the collection.
+
+        :param num_traces: The number of traces to capture
+        :type num_traces: int
+        :param experiment_keys: A collection of keys to use for the capture of each trace. If not specified, the procedure
+                                will use the cw basic key generation `key = cw.ktp.Basic()[0]`
+        :type experiment_keys: list
+        :param experiment_texts: A collection of texts to use for the capture of each trace. If not specified, the procedure
+                                will use the cw basic plaintext generation `text = cw.ktp.Basic()[1]`
+        :type experiment_texts: list
+        :param fixed_key: Whether to use a fixed key for cw.ktp key generation. Ignored if a collection of keys are supplied.
+        :type fixed_key: bool
+        :param fixed_pt: Whether to use a fixed plaintext for cw.ktp text generation. Ignored if a collection of texts are supplied.
+        :type fixed_pt: bool
+        :return: a tuple containing the power traces, keys, plaintexts, and ciphertexts for the experiment
+        :rtype: tuple(np.ndarray, np.ndarray, np.ndarray, np.ndarray)
+        :raises TypeError: if the length of the specified experiment keys and experiment texts are not equal to each other or the number of traces
+                            to be collected.
+        :Authors: Samuel Karkache (swkarkache@wpi.edu)
+
+    .. method:: capture_traces_tvla(self, num_traces: int, group_a_keys: np.ndarray = None, group_a_texts: np.ndarray = None, group_b_keys: np.ndarray = None, group_b_texts: np.ndarray = None, ktp: any = cwtvla.ktp.FixedVRandomText()) -> (np.ndarray, np.ndarray):
+
+        Captures fixed and random trace set needed for TVLA. Group A is the fixed set and group B is the random set.
+
+        :param num_traces: The number of traces to capture for each set
+        :type num_traces: int
+        :param group_a_keys: An array of keys for group A
+        :type group_a_keys: list
+        :param group_a_texts: An array of texts for group A
+        :type group_a_texts: list
+        :param group_b_keys: An array of keys for group B
+        :type group_b_keys: list
+        :param group_b_texts: An array of texts for group B
+        :type group_b_texts: list
+        :param ktp: the key text pair algorithm, defaults to cwtvla.ktp.FixedVRandomText(). This is ignored if keys or texts
+                    for group A and group B are provided.
+        :rtype: (np.ndarray, np.ndarray)
+        :Authors: Samuel Karkache (swkarkache@wpi.edu)
+
+    .. method:: cw_to_file_framework(self, num_traces: int,  file_parent: FileParent, experiment_name: str, keys: np.ndarray = None, texts: np.ndarray = None, fixed_key: bool = True, fixed_pt: bool = False) -> None:
+
+        Captures traces on a ChipWhisperer device and saves them directly to the custom file framework. The collected
+        traces, keys, plaintexts, and ciphertexts are saved as dataset to the specified experiment. If the experiment
+        specified does not exist in the file, then a new one is created.
+
+        :param num_traces: The number of traces to capture
+        :type num_traces: int
+        :param file_parent: The FileParent object to save the file to
+        :type file_parent: FileParent
+        :param experiment_name: The name of the experiment
+        :type experiment_name: str
+        :param keys: The keys for the experiment
+        :type keys: np.ndarray
+        :param texts: The plaintexts for the experiment
+        :param texts: np.ndarray
+        :param fixed_key: Whether the key should be fixed (assuming the keys and texts parameters are None)
+        :type fixed_key: bool
+        :param fixed_pt: Whether the plaintext should be fixed (assuming the keys and texts parameters are None)
+        :type fixed_pt: bool
+        :return: None
+        :Authors: Samuel Karkache (swkarkache@wpi.edu)
+

_sources/dpa.rst.txt

@@ -0,0 +1,2 @@
+Differential Power Analysis (DPA)
+================================

_sources/fileformat.rst.txt

@@ -0,0 +1,260 @@
+Custom File Framework
+==================
+The file framework is split into three separate classes.
+
+.. class:: FileParent
+
+    .. method:: __init__(self, name: str, path: str, existing: bool = False):
+
+        Initialize FileFormatParent class. Creates the basic file structure including JSON metadata holder. If the file
+        already exists it simply returns a reference to that file. To create a file named "ExampleFile" in your downloads
+        directory set the name parameter to `name="ExampleFile` and the path to `path="C:\\users\\username\\\desktop`. The
+        path needs to be structured as shown with double back slashes.
+
+        :param name: The name of the file parent directory
+        :type name: str
+        :param path: The path to the file parent.
+        :type path: str
+        :param existing: whether the file already exists
+        :type existing: bool
+        :returns: None
+
+    .. method:: update_metadata(self, key: str, value: any) -> None:
+
+        Update file JSON metadata with key-value pair
+
+        :param key: The key of the metadata
+        :type key: str
+        :param value: The value of the metadata. Can be any datatype supported by JSON
+        :type value: any
+        :returns: None
+
+
+    .. method:: read_metadata(self) -> dict:
+
+        Read JSON metadata from file
+
+        :returns: The metadata dictionary for the FileParent object
+        :rtype: dict
+
+    .. methood:: add_experiment(self, name: str) -> 'Experiment':
+
+        Adds a new experiment to the FileParent object
+
+        :param name: The desired name of the new experiment
+        :type name: str
+        :returns: The newly created Experiment object
+        :rtype: Experiment
+
+    .. method:: get_experiment(self, experiment_name: str) -> 'Experiment':
+
+        Get an existing experiment from the FileParent.
+
+        :param experiment_name: The name of the requested experiment
+        :type experiment_name: str
+        :returns: The requested experiment. None if it does not exist.
+        :rtype: Experiment. None if not found.
+
+    .. method:: delete_file(self) -> None:
+
+        Deletes the entire file. Confirmation required.
+
+        :returns: None
+
+    .. method:: delete_experiment(self, experiment_name: str) -> None:
+
+        Deletes an experiment and all of its datasets from a FileParent. Confirmation Required.
+
+        :param experiment_name: The name of the experiment
+        :type experiment_name: str
+        :returns: None
+
+    .. method:: query_experiments_with_metadata(self, key: str, value: any, regex: bool = False) -> list['Experiment']:
+
+        Query all experiments in the FileParent object based on exact metadata key-value pair or using regular expressions.
+
+        :param key: The key to be queried
+        :type key: str
+        :param value: The value to be queried. Supply a regular expression if the `regex` parameter is set to true. Supplying
+                        a value of "*" will return all experiments with the `key` specified in the key parameter.
+        :type value: any
+        :returns: A list of queried experiments
+        :rtype: list['Experiment']
+
+
+.. class:: Experiment
+
+    .. method:: __init__(self, name: str, path: str, file_format_parent: FileParent, existing: bool = False, index: int = 0, experiment: dict = None):
+
+        Creates an Experiment object. Do not call this constructor. Please use `FileParent.add_experiment()` to
+        create a new Experiment object. DO NOT USE.
+
+    .. method:: update_metadata(self, key: str, value: any) -> None:
+
+        Update the experiment metadata using a new key value pair.
+
+        :param key: The key of the metadata
+        :type key: str
+        :param value: The value of the metadata. Can be any datatype supported by JSON.
+        :type value: any
+        :returns: None
+
+
+    .. method:: read_metadata(self) -> dict:
+
+        Reads experiment metadata
+
+        :returns: The experiment's metadata dictionary
+        :rtype: dict
+
+    .. method:: add_dataset(self, name: str, data_to_add: np.ndarray, datatype: any) -> 'Dataset':
+
+        Adds a new Dataset to a given Experiment
+
+        :param name: The desired name of the new dataset
+        :type name: str
+        :param data_to_add: The NumPy array of data to be added to the new dataset
+        :type data_to_add: np.ndarray
+        :returns: The newly created dataset
+        :rtype: Dataset
+
+    .. method:: get_dataset(self, dataset_name: str) -> 'Dataset':
+
+        Get a dataset from a given experiment.
+
+        :param dataset_name: The name of the requested dataset
+        :type dataset_name: str
+        :returns: The requested dataset. None if it is not found.
+        :rtype: Dataset. None if not found.
+
+
+    .. method:: delete_dataset(self, dataset_name: str) -> None:
+
+        Deletes a dataset and all its contents. Confirmation required.
+
+        :param dataset_name: The name of the dataset to be deleted
+        :type dataset_name: str
+        :returns: None
+
+    .. method:: query_datasets_with_metadata(self, key: str, value: any, regex: bool = False) -> list['Dataset']:
+
+        Query all datasets in the Experiment object based on exact metadata key-value pair or using regular expressions.
+
+        :param key: The key to be queried
+        :type key: str
+        :param value: The value to be queried. Supply a regular expression if the `regex` parameter is set to true. Supplying
+                        a value of "*" will return all experiments with the `key` specified in the key parameter.
+        :type value: any
+        :returns: A list of queried datasets
+        :rtype: list['Dataset']
+
+    .. method:: get_visualization_path(self) -> str:
+
+        Get the path to the visualization directory for the Experiment object.
+
+        :returns: The visualization path of the experiment
+        :rtype: str
+
+    .. method:: calculate_snr(self, traces_dataset: str, intermediate_fcn: Callable, *args: any,  visualize: bool = False, save_data: bool = False, save_graph: bool = False) -> np.ndarray:
+
+        Integrated signal-to-noise ratio metric.
+
+        :param traces_dataset: The name of the traces dataset
+        :type traces_dataset: str
+        :param intermediate_fcn: A callback function that determines how the intermediate values for SNR labels are calculated.
+        :type intermediate_fcn: Callable
+        :param *args: Additonal datasets needed for the parameters of the intermediate_fnc.
+        :type *args: any
+        :param visualize: Whether to visualize the result or not
+        :type visualize: bool
+        :param save_data: Whether to save the metric result as a new dataset or not
+        :type save_data: bool
+        :param save_graph: Whether to save the visualization to the experiments visualization folder or not
+        :type save_graph: bool
+        :returns: The SNR metric result
+        :rtype: np.ndarray
+
+    .. method:: calculate_t_test(self, fixed_dataset: str, random_dataset: str, visualize: bool = False, save_data: bool = False, save_graph: bool = False) -> (np.ndarray, np.ndarray):
+
+        Integrated t-test metric.
+
+        :param fixed_dataset: The name of the dataset containing the fixed trace set
+        :type fixed_dataset: str
+        :param random_dataset: The name of the dataset containing the random trace set
+        :type random_dataset: str
+        :param visualize: Whether to visualize the result or not
+        :type visualize: bool
+        :param save_data: Whether to save the metric result as a new dataset or not
+        :type save_data: bool
+        :param save_graph: Whether to save the visualization to the experiments visualization folder or not
+        :type save_graph: bool
+        :returns: The t-test metric result
+        :rtype: np.ndarray
+
+    .. method:: calculate_correlation(self, predicted_dataset_name: str, observed_dataset_name: str, visualize: bool = False, save_data: bool = False, save_graph: bool = False) -> np.ndarray:
+
+        Integrated correlation metric.
+
+        :param predicted_dataset_name: The name of the dataset containing the predicted leakage
+        :type predicted_dataset_name: str
+        :param observed_dataset_name: The name of the dataset containing the observed leakage
+        :type observed_dataset_name: str
+        :param visualize: Whether to visualize the result or not
+        :type visualize: bool
+        :param save_data: Whether to save the metric result as a new dataset or not
+        :type save_data: bool
+        :param save_graph: Whether to save the visualization to the experiments visualization folder or not
+        :type save_graph: bool
+        :returns: The correlation metric result
+        :rtype: np.ndarray
+
+
+
+.. class:: Dataset
+
+    .. method:: __init__(self, name: str, path: str, file_format_parent: FileParent, experiment_parent: Experiment, index: int, existing: bool = False, dataset: dict = None):
+
+        Creates an Dataset object. Do not call this constructor. Please use `Experiment.add_dataset()` to
+        create a new Dataset object. DO NOT USE.
+
+    .. method:: read_data(self, start: int, end: int) -> np.ndarray:
+
+        Read data from the dataset a specific start and end index.
+
+        :param start: the start index of the data
+        :type start: int
+        :param end: the end index of the data
+        :type end: int
+        :returns: An NumPy array containing the requested data over the specified interval
+        :rtype: np.ndarray
+
+    .. method:: read_all(self) -> np.ndarray:
+
+        Read all data from the dataset
+
+        :returns: All data contained in the dataset
+        :rtype: np.ndarray
+
+    .. method:: add_data(self, data_to_add: np.ndarray, datatype: any) -> None:
+
+        Add data to an existing dataset
+
+        :param data_to_add: The data to be added to the dataset as a NumPy array
+        :type data_to_add: np.ndarray
+        :param datatype: The datatype of the data being added
+        :type datatype: any
+        :returns: None
+
+    .. method:: update_metadata(self, key: str, value: any) -> None:
+
+        Update the dataset metadata using a new key value pair.
+
+        :param key: The key of the metadata
+        :type key: str
+        :param value: The value of the metadata. Can be any datatype supported by JSON.
+        :type value: any
+        :returns: None
+
+
+
+

_sources/index.rst.txt

@@ -0,0 +1,28 @@
+SCApe Goat - Side Channel Analysis Library
+===================================
+
+Purpose
+-------
+Many years of cryptographic research have focused on the software security of different encryption algorithms.
+One of the most well-known encryption algorithms, AES-128, would require billions of years to guess its 128-bit encryption key.
+However, there exist hardware attacks that could extract this cryptography key in mere hours. A side-channel attack can use the
+information received from device power consumption and electromagnetic emanation to guess a cryptographic key with immense accuracy.
+Therefore, the field of side-channel analysis is of utmost importance if engineers want to design cryptographic devices that can withstand
+even the most intense side-channel attacks. One of the research topics at Worcester Polytechnic Institute's Vernam Lab involves side-channel
+analysis attacks and defense. In attacking encryption algorithms with different side-channel techniques, researchers can draw conclusions
+about the security of different cryptographic implementations and develop better defenses against such attacks. However, Vernam Lab and
+Worcester Polytechnic Institute as a whole, lack a unified repository of information and tools to help with side-channel analysis research
+and education. The lab has access to the specialized equipment needed to conduct SCA research, however, there does not exist a
+standardized interface for side-channel data collection, analysis, and data storage that the lab uses to conduct research.
+Therefore, this necessitates an accessible set of tools that allow researchers and students alike to learn and contribute
+to the ever-growing field of security analysis of side-channel attacks.
+
+Library Features
+---------------------
+.. toctree::
+   :maxdepth: 3
+
+   fileformat.rst
+   cwscope.rst
+   metrics.rst
+   leakagemodels.rst