diff --git a/src/distinguishers/cpa.rs b/src/distinguishers/cpa.rs index b0c5ba8..fb57f9a 100644 --- a/src/distinguishers/cpa.rs +++ b/src/distinguishers/cpa.rs @@ -8,6 +8,39 @@ use std::{iter::zip, ops::Add}; /// Compute the [`Cpa`] of the given traces using [`CpaProcessor`]. /// +/// # Examples +/// ``` +/// use muscat::distinguishers::cpa::cpa; +/// use muscat::leakage::sbox; +/// use ndarray::array; +/// +/// let traces = array![ +/// [77, 137, 51, 91], +/// [72, 61, 91, 83], +/// [39, 49, 52, 23], +/// [26, 114, 63, 45], +/// [30, 8, 97, 91], +/// [13, 68, 7, 45], +/// [17, 181, 60, 34], +/// [43, 88, 76, 78], +/// [0, 36, 35, 0], +/// [93, 191, 49, 26], +/// ]; +/// let plaintexts = array![ +/// [1usize, 2], +/// [2, 1], +/// [1, 2], +/// [1, 2], +/// [2, 1], +/// [2, 1], +/// [1, 2], +/// [1, 2], +/// [2, 1], +/// [2, 1], +/// ]; +/// let cpa = cpa(traces.view(), plaintexts.view(), 256, 0, |key, guess| sbox((key ^ guess) as u8) as usize, 2); +/// ``` +/// /// # Panics /// - Panic if `traces.shape()[0] != plaintexts.shape()[0]` /// - Panic if `batch_size` is 0. diff --git a/src/distinguishers/cpa_normal.rs b/src/distinguishers/cpa_normal.rs index e5c94d9..b77728c 100644 --- a/src/distinguishers/cpa_normal.rs +++ b/src/distinguishers/cpa_normal.rs @@ -6,6 +6,39 @@ use crate::distinguishers::cpa::Cpa; /// Compute the [`Cpa`] of the given traces using [`CpaProcessor`]. /// +/// # Examples +/// ``` +/// use muscat::distinguishers::cpa_normal::cpa; +/// use muscat::leakage::sbox; +/// use ndarray::array; +/// +/// let traces = array![ +/// [77, 137, 51, 91], +/// [72, 61, 91, 83], +/// [39, 49, 52, 23], +/// [26, 114, 63, 45], +/// [30, 8, 97, 91], +/// [13, 68, 7, 45], +/// [17, 181, 60, 34], +/// [43, 88, 76, 78], +/// [0, 36, 35, 0], +/// [93, 191, 49, 26], +/// ]; +/// let plaintexts = array![ +/// [1usize, 2], +/// [2, 1], +/// [1, 2], +/// [1, 2], +/// [2, 1], +/// [2, 1], +/// [1, 2], +/// [1, 2], +/// [2, 1], +/// [2, 1], +/// ]; +/// let cpa = cpa(traces.map(|&x| x as f32).view(), plaintexts.view(), 256, |key, guess| sbox((key[0] ^ guess) as u8) as usize, 2); +/// ``` +/// /// # Panics /// - Panic if `traces.shape()[0] != plaintexts.shape()[0]` /// - Panic if `batch_size` is 0. diff --git a/src/distinguishers/dpa.rs b/src/distinguishers/dpa.rs index f038192..c0f899e 100644 --- a/src/distinguishers/dpa.rs +++ b/src/distinguishers/dpa.rs @@ -6,6 +6,50 @@ use crate::util::{argmax_by, argsort_by, max_per_row}; /// Compute the [`Dpa`] of the given traces using [`DpaProcessor`]. /// +/// # Examples +/// ``` +/// use muscat::distinguishers::dpa::dpa; +/// use muscat::leakage::sbox; +/// use ndarray::{array, Array1}; +/// +/// let traces = array![ +/// [77, 137, 51, 91], +/// [72, 61, 91, 83], +/// [39, 49, 52, 23], +/// [26, 114, 63, 45], +/// [30, 8, 97, 91], +/// [13, 68, 7, 45], +/// [17, 181, 60, 34], +/// [43, 88, 76, 78], +/// [0, 36, 35, 0], +/// [93, 191, 49, 26], +/// ]; +/// let plaintexts = array![ +/// [1, 2], +/// [2, 1], +/// [1, 2], +/// [1, 2], +/// [2, 1], +/// [2, 1], +/// [1, 2], +/// [1, 2], +/// [2, 1], +/// [2, 1], +/// ]; +/// let dpa = dpa( +/// traces.map(|&x| x as f32).view(), +/// plaintexts +/// .rows() +/// .into_iter() +/// .map(|x| x.to_owned()) +/// .collect::>>() +/// .view(), +/// 256, +/// |key: Array1, guess| sbox(key[0] ^ guess as u8) & 1 == 1, +/// 2 +/// ); +/// ``` +/// /// # Panics /// Panic if `batch_size` is not strictly positive. pub fn dpa( diff --git a/src/leakage_detection.rs b/src/leakage_detection.rs index 83c04eb..8773dac 100644 --- a/src/leakage_detection.rs +++ b/src/leakage_detection.rs @@ -8,6 +8,38 @@ use std::{iter::zip, ops::Add}; /// /// `get_class` is a function returning the class of the given trace by index. /// +/// # Examples +/// ``` +/// use muscat::leakage_detection::snr; +/// use ndarray::array; +/// +/// let traces = array![ +/// [77, 137, 51, 91], +/// [72, 61, 91, 83], +/// [39, 49, 52, 23], +/// [26, 114, 63, 45], +/// [30, 8, 97, 91], +/// [13, 68, 7, 45], +/// [17, 181, 60, 34], +/// [43, 88, 76, 78], +/// [0, 36, 35, 0], +/// [93, 191, 49, 26], +/// ]; +/// let plaintexts = array![ +/// [1usize, 2], +/// [2, 1], +/// [1, 2], +/// [1, 2], +/// [2, 1], +/// [2, 1], +/// [1, 2], +/// [1, 2], +/// [2, 1], +/// [2, 1], +/// ]; +/// let snr = snr(traces.view(), 256, |i| plaintexts.row(i)[0].into(), 2); +/// ``` +/// /// # Panics /// - Panic if `batch_size` is 0. pub fn snr( @@ -147,6 +179,28 @@ impl Add for SnrProcessor { /// Compute the Welch's T-test of the given traces using [`TTestProcessor`]. /// +/// # Examples +/// ``` +/// use muscat::leakage_detection::ttest; +/// use ndarray::array; +/// +/// let traces = array![ +/// [77, 137, 51, 91], +/// [72, 61, 91, 83], +/// [39, 49, 52, 23], +/// [26, 114, 63, 45], +/// [30, 8, 97, 91], +/// [13, 68, 7, 45], +/// [17, 181, 60, 34], +/// [43, 88, 76, 78], +/// [0, 36, 35, 0], +/// [93, 191, 49, 26], +/// ]; +/// let trace_classes = +/// array![true, false, false, true, false, false, true, false, false, true]; +/// let ttest = ttest(traces.view(), trace_classes.view(), 2); +/// ``` +/// /// # Panics /// - Panic if `traces.shape()[0] != trace_classes.shape()[0]` /// - Panic if `batch_size` is 0.