From f3c6e2c54d6362482d2cf491ddcef793085c0961 Mon Sep 17 00:00:00 2001 From: TrAyZeN Date: Wed, 19 Jun 2024 14:23:44 +0200 Subject: [PATCH] Improve documentation --- src/cpa.rs | 17 +++++++++++++---- src/cpa_normal.rs | 10 +++++----- src/dpa.rs | 16 ++++++++++++---- 3 files changed, 30 insertions(+), 13 deletions(-) diff --git a/src/cpa.rs b/src/cpa.rs index f49c858..01c2a64 100644 --- a/src/cpa.rs +++ b/src/cpa.rs @@ -6,7 +6,7 @@ use rayon::{ }; use std::{iter::zip, ops::Add}; -/// Computes the [`Cpa`] of the given traces using [`CpaProcessor`]. +/// Compute the [`Cpa`] of the given traces using [`CpaProcessor`]. /// /// # Panics /// - Panic if `leakages.shape()[0] != plaintexts.shape()[0]` @@ -47,6 +47,9 @@ where .finalize() } +/// Result of the CPA[^1] on some traces. +/// +/// [^1]: #[derive(Debug)] pub struct Cpa { /// Guess range upper excluded bound @@ -56,16 +59,19 @@ pub struct Cpa { } impl Cpa { + /// Rank guesses. pub fn rank(&self) -> Array1 { let rank = argsort_by(&self.max_corr().to_vec()[..], f32::total_cmp); Array1::from_vec(rank) } + /// Return the Pearson correlation coefficients. pub fn corr(&self) -> ArrayView2 { self.corr.view() } + /// Return the guess with the highest Pearson correlation coefficient. pub fn best_guess(&self) -> usize { let max_corr = self.max_corr(); @@ -81,6 +87,7 @@ impl Cpa { best_guess } + /// Return the maximum Pearson correlation coefficient for each guess. pub fn max_corr(&self) -> Array1 { max_per_row(self.corr.view()) } @@ -88,7 +95,9 @@ impl Cpa { /// A processor that computes the [`Cpa`] of the given traces. /// -/// It implements Algorithm 4 of https://eprint.iacr.org/2013/794.pdf +/// It implements algorithm 4 from [^1]. +/// +/// [^1]: pub struct CpaProcessor where F: Fn(usize, usize) -> usize, @@ -108,7 +117,7 @@ where /// Sum of square of traces per key guess guess_sum_squares_leakages: Array1, /// Sum of traces per plaintext used - /// See 4.3 in https://eprint.iacr.org/2013/794.pdf + /// See 4.3 in plaintext_sum_leakages: Array2, /// Leakage model leakage_func: F, @@ -165,7 +174,7 @@ where self.num_traces += 1; } - /// Finalizes the calculation after feeding the overall traces. + /// Finalize the calculation after feeding the overall traces. pub fn finalize(&self) -> Cpa { let mut modeled_leakages = Array1::zeros(self.guess_range); diff --git a/src/cpa_normal.rs b/src/cpa_normal.rs index f508ba3..a5984a7 100644 --- a/src/cpa_normal.rs +++ b/src/cpa_normal.rs @@ -4,7 +4,7 @@ use std::{iter::zip, ops::Add}; use crate::cpa::Cpa; -/// Computes the [`Cpa`] of the given traces using [`CpaProcessor`]. +/// Compute the [`Cpa`] of the given traces using [`CpaProcessor`]. /// /// # Panics /// - Panic if `leakages.shape()[0] != plaintexts.shape()[0]` @@ -42,6 +42,9 @@ where .finalize() } +/// A processor that computes the [`Cpa`] of the given traces. +/// +/// [^1]: pub struct CpaProcessor where F: Fn(ArrayView1, usize) -> usize, @@ -68,9 +71,6 @@ where num_traces: usize, } -/* This class implements the CPA algorithm shown in: -https://www.iacr.org/archive/ches2004/31560016/31560016.pdf */ - impl CpaProcessor where F: Fn(ArrayView1, usize) -> usize, @@ -144,7 +144,7 @@ where } } - /// Finalizes the calculation after feeding the overall traces. + /// Finalize the calculation after feeding the overall traces. pub fn finalize(&self) -> Cpa { let cov_n = self.cov.clone() / self.num_traces as f32; let avg_keys = self.guess_sum_leakages.clone() / self.num_traces as f32; diff --git a/src/dpa.rs b/src/dpa.rs index 23864c8..4ffd1f2 100644 --- a/src/dpa.rs +++ b/src/dpa.rs @@ -4,8 +4,10 @@ use std::{iter::zip, marker::PhantomData, ops::Add}; use crate::util::{argsort_by, max_per_row}; +/// Compute the [`Dpa`] of the given traces using [`DpaProcessor`]. +/// /// # Panics -/// Panics if `chunk_size` is not strictly positive. +/// Panic if `chunk_size` is not strictly positive. pub fn dpa( leakages: ArrayView2, metadata: ArrayView1, @@ -40,6 +42,9 @@ where .finalize() } +/// Result of the DPA[^1] on some traces. +/// +/// [^1]: #[derive(Debug)] pub struct Dpa { /// Guess range upper excluded bound @@ -48,16 +53,19 @@ pub struct Dpa { } impl Dpa { + /// Return the rank of guesses pub fn rank(&self) -> Array1 { let rank = argsort_by(&self.max_differential_curves().to_vec()[..], f32::total_cmp); Array1::from_vec(rank) } + /// Return the differential curves pub fn differential_curves(&self) -> ArrayView2 { self.differential_curves.view() } + /// Return the guess with the highest differential peak. pub fn best_guess(&self) -> usize { let max_corr = self.max_differential_curves(); @@ -73,6 +81,7 @@ impl Dpa { best_guess } + /// Return the maximum differential peak for each guess. pub fn max_differential_curves(&self) -> Array1 { max_per_row(self.differential_curves.view()) } @@ -80,9 +89,8 @@ impl Dpa { /// A processor that computes the [`Dpa`] of the given traces. /// -/// It implements algorithm from: -/// https://paulkocher.com/doc/DifferentialPowerAnalysis.pdf -/// https://web.mit.edu/6.857/OldStuff/Fall03/ref/kocher-DPATechInfo.pdf +/// [^1]: +/// [^2]: pub struct DpaProcessor where F: Fn(M, usize) -> bool,