deploy: 2938443

.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: 099c39ebe5776b7cc82cd99c8d9261bb
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/about_project.rst.txt

@@ -0,0 +1,2 @@
+About Project
+=============

_sources/fileformat.rst.txt

@@ -0,0 +1,13 @@
+Custom File Framework
+==================
+The file framework is split into three separate classes.
+
+.. class:: FileParent
+
+    The base directory for
+
+    .. method:: __init__
+
+    .. method:: add_experiment(self, name: str)
+
+        Add Experiment to file

_sources/index.rst.txt

@@ -0,0 +1,24 @@
+SCApe Goat - Side Channel Analysis Library
+===================================
+
+Purpose
+-------
+One of the research topics at Worcester Polytechnic Institute's Vernam Lab involves side-channel analysis attacks and defence.
+In attacking encryption algorithms with different side channel techniques, researchers are able to draw conclusions about the
+security of different cryptographic implementations and develop better defences 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 for 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
+   scope.rst
+   metrics.rst
+   leakagemodels.rst
+   about_project.rst

_sources/leakagemodels.rst.txt

@@ -0,0 +1,37 @@
+Leakage Models
+==============
+This module contains pre-defined leakage models that can be used during side-channel analysis experiments. For example,
+these leakage models are useful when generating the predicted leakage for Pearson's correlation coefficient.
+
+.. py:function:: leakage_model_hamming_weight(num_traces, plaintexts, subkey_guess, target_byte)
+
+    Generates hypothetical leakage based on the hamming weight of the AES sbox.
+
+    :param num_traces: The number of traces collected when measuring the observed leakage
+    :type num_traces: int
+    :param plaintexts: The array of plaintexts used to collect the observed leakage
+    :type plaintexts: list | np.ndarray
+    :param subkey_guess: the subkey guess
+    :type subkey_guess: any
+    :param target_byte: the target byte of the key
+    :type target_byte: int
+    :return: numpy array of the hypothetical leakage
+    :rtype: np.ndarray
+    :Authors: Samuel Karkache ([email protected])
+
+.. py:function:: leakage_model_hamming_distance(num_traces, plaintexts, subkey_guess, target_byte)
+
+    Generates hypothetical leakage using the damming distance leakage model. In this implementation the reference state
+    is the output of the sbox at index 0.
+
+    :param num_traces: The number of traces collected when measuring the observed leakage
+    :type num_traces: int
+    :param plaintexts: The array of plaintexts used to collect the observed leakage
+    :type plaintexts: list | np.ndarray
+    :param subkey_guess: the subkey guess
+    :type subkey_guess: any
+    :param target_byte: the target byte of the key
+    :type target_byte: int
+    :return: numpy array of the hypothetical leakage
+    :rtype: np.ndarray
+    :Authors: Samuel Karkache ([email protected])

_sources/metrics.rst.txt

@@ -0,0 +1,150 @@
+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 ([email protected]), Trey Marcantonio ([email protected])
+
+.. py:function:: organize_snr_label(traces: np.ndarray | list, 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 | list
+    :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 ([email protected]), Trey Marcantonio ([email protected])
+
+.. py:function:: unmasked_sbox_output_intermediate(keys: np.ndarray | list, 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 | list
+    :param plaintexts: The plaintexts used to calculate sbox output
+    :type plaintexts: np.ndarray | list
+    :return: A list containing all intermediate values
+    :rtype: np.ndarray
+
+.. py:function:: t_test_tvla(fixed_t: np.ndarray | list, random_t: np.ndarray | list, 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.
+
+    :param random_t: The random trace set
+    :type random_t: np.ndarray | list
+    :param fixed_t: The fixed trace set
+    :type fixed_t: np.ndarray | list
+    :param visualize: Whether to visualize the result
+    :type visualize: bool
+    :param visualization_paths: The paths to be used to save the t-statistic (first idx) and t-max visualizations (second idx)
+    :type visualization_paths: tuple
+    :return: The t-statistic at each time sample and t-max at each trace as a tuple of numpy arrays
+    :rtype: (np.ndarray, np.ndarray)
+    :raises ValueError: if fixed_t and random_t do not have the same length
+    :Authors: Dev Mehta ([email protected]), Samuel Karkache ([email protected])
+
+.. py:function:: pearson_correlation(predicted_leakage: np.ndarray | list, observed_leakage: np.ndarray | list, 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 | list
+    :param observed_leakage: actual power traces collected from the cryptographic target
+    :type observed_leakage: np.ndarray | list
+    :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 ([email protected])
+
+
+.. 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 | list
+    :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 | list
+    :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 ([email protected])
+
+
+.. 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 ([email protected])
+
+
+.. 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)
+

_sources/scope.rst.txt

@@ -0,0 +1,14 @@
+Oscilloscope Interface
+======================
+
+The ChipWhisperer scope interface documentation
+
+.. class:: CWScope
+
+    Initializes the scope object...
+
+    .. method:: __init__
+
+    .. method:: disconnect(self)
+
+        Disconnect from...

_static/_sphinx_javascript_frameworks_compat.js

@@ -0,0 +1,123 @@
+/* Compatability shim for jQuery and underscores.js.
+ *
+ * Copyright Sphinx contributors
+ * Released under the two clause BSD licence
+ */
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+    if (!x) {
+        return x
+    }
+    return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+    if (typeof s === 'undefined')
+        s = document.location.search;
+    var parts = s.substr(s.indexOf('?') + 1).split('&');
+    var result = {};
+    for (var i = 0; i < parts.length; i++) {
+        var tmp = parts[i].split('=', 2);
+        var key = jQuery.urldecode(tmp[0]);
+        var value = jQuery.urldecode(tmp[1]);
+        if (key in result)
+            result[key].push(value);
+        else
+            result[key] = [value];
+    }
+    return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+    function highlight(node, addItems) {
+        if (node.nodeType === 3) {
+            var val = node.nodeValue;
+            var pos = val.toLowerCase().indexOf(text);
+            if (pos >= 0 &&
+                !jQuery(node.parentNode).hasClass(className) &&
+                !jQuery(node.parentNode).hasClass("nohighlight")) {
+                var span;
+                var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+                if (isInSVG) {
+                    span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+                } else {
+                    span = document.createElement("span");
+                    span.className = className;
+                }
+                span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+                node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+                    document.createTextNode(val.substr(pos + text.length)),
+                    node.nextSibling));
+                node.nodeValue = val.substr(0, pos);
+                if (isInSVG) {
+                    var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+                    var bbox = node.parentElement.getBBox();
+                    rect.x.baseVal.value = bbox.x;
+                    rect.y.baseVal.value = bbox.y;
+                    rect.width.baseVal.value = bbox.width;
+                    rect.height.baseVal.value = bbox.height;
+                    rect.setAttribute('class', className);
+                    addItems.push({
+                        "parent": node.parentNode,
+                        "target": rect});
+                }
+            }
+        }
+        else if (!jQuery(node).is("button, select, textarea")) {
+            jQuery.each(node.childNodes, function() {
+                highlight(this, addItems);
+            });
+        }
+    }
+    var addItems = [];
+    var result = this.each(function() {
+        highlight(this, addItems);
+    });
+    for (var i = 0; i < addItems.length; ++i) {
+        jQuery(addItems[i].parent).before(addItems[i].target);
+    }
+    return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+    jQuery.uaMatch = function(ua) {
+        ua = ua.toLowerCase();
+
+        var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+            /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+            /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+            /(msie) ([\w.]+)/.exec(ua) ||
+            ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+            [];
+
+        return {
+            browser: match[ 1 ] || "",
+            version: match[ 2 ] || "0"
+        };
+    };
+    jQuery.browser = {};
+    jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}