API cleanup (#172)

* Remove deprecated SASCA
* Cleanup function arguments (names, unnecessary arguments): SNR, Ttest, LDA, RLDA
* Allow non-contiguous trace arrays
* Fix the execution of the `examples/` in pytest (was not running).

Author: cassiersg

CHANGELOG.rst

@@ -5,6 +5,10 @@ Changelog
 Not released
 ------------
 
+* **Breaking** change parameter names ``l`` to ``traces`` for many functions.
+* **Breaking** remove unnecessary parameters from initializers (e.g. trace
+  length where it can be inferred).
+
 v0.5.8 (2024/05/21)
 -------------------
 * Add ``scalib.preprocessing.Quantizer`` for conversions of floating-point

examples/aes_attack.py

@@ -1,4 +1,4 @@
-from scalib.metrics import SNR, Ttest
+from scalib.metrics import SNR
 from scalib.modeling import LDAClassifier
 from scalib.attacks import FactorGraph, BPState
 from scalib.postprocessing import rank_accuracy
@@ -39,7 +39,7 @@ def main():
         x[:, i] = labels_p[f"x{i}"]
 
     # estimate SNR
-    snr = SNR(nc=nc, ns=ns, np=16)
+    snr = SNR(nc=nc)
     snr.fit_u(traces_p, x)
     snr_val = snr.get_snr()
 
@@ -53,8 +53,11 @@ def main():
     print("    3.1 Build LDAClassifier for each xi")
     models = []
     for i in range(16):
-        lda = LDAClassifier(nc=nc, ns=npoi, p=1)
-        lda.fit_u(l=traces_p[:, pois[i]], x=labels_p[f"x{i}"].astype(np.uint16))
+        lda = LDAClassifier(nc=nc, p=1)
+        lda.fit_u(
+            traces=np.ascontiguousarray(traces_p[:, pois[i]]),
+            x=labels_p[f"x{i}"].astype(np.uint16),
+        )
         lda.solve()
         models.append(lda)
 
@@ -113,7 +116,7 @@ def main():
         distribution = bp.get_distribution(f"k{i}")
 
         guess_key.append(np.argmax(distribution))
-        ranks.append(256 - np.where(np.argsort(distribution) == sk)[0])
+        ranks.append(256 - (np.argsort(distribution) == sk).nonzero()[0][0])
 
         secret_key.append(sk)
         key_distribution.append(distribution)
@@ -124,7 +127,7 @@ def main():
     print("        key byte ranks  :", " ".join(["%3d" % (x) for x in ranks]))
     print("")
 
-    print(f"   5.2 Estimate full log2 key rank:")
+    print("   5.2 Estimate full log2 key rank:")
     key_distribution = np.array(key_distribution)
 
     # Scores are negative log-likelihoods.
@@ -139,4 +142,5 @@ def main():
 
 
 if __name__ == "__main__":
+    print("attack")
     main()

examples/aes_info.py

@@ -1,15 +1,11 @@
-from scalib.metrics import SNR, Ttest
 from scalib.modeling import LDAClassifier
-from scalib.attacks import FactorGraph, BPState
-from scalib.postprocessing import rank_accuracy
 
-from utils import sbox, gen_traces
+from utils import gen_traces
 import numpy as np
 
 
 def main():
     nc = 256
-    npoi = 2
 
     # Parameters
     std = 2
@@ -30,13 +26,11 @@ def main():
         ntraces_v, std, random_key=True, random_plaintext=True
     )
 
-    _, ns = traces_p.shape
-
     print("2. Profiling the value of the first Sbox.")
     print("")
 
-    lda = LDAClassifier(nc=256, ns=ns, p=1)
-    lda.fit_u(l=traces_p, x=labels_p["x0"].astype(np.uint16))
+    lda = LDAClassifier(nc=256, p=1)
+    lda.fit_u(traces=traces_p, x=labels_p["x0"].astype(np.uint16))
     lda.solve()
 
     def eval_info(test_traces, test_labels):

examples/aes_tvla.py

@@ -1,9 +1,6 @@
-from scalib.metrics import SNR, Ttest
-from scalib.modeling import LDAClassifier
-from scalib.attacks import FactorGraph, BPState
-from scalib.postprocessing import rank_accuracy
+from scalib.metrics import Ttest
 
-from utils import sbox, gen_traces
+from utils import gen_traces
 import numpy as np
 
 
@@ -18,7 +15,7 @@ def main():
     traces_rk, _ = gen_traces(ntraces, std, random_key=True, random_plaintext=False)
     traces_fk, _ = gen_traces(ntraces, std, random_key=False, random_plaintext=False)
     # Ttest needs the lenght of the traces, and the test order (here, two)
-    ttest = Ttest(traces_rk.shape[1], 2)
+    ttest = Ttest(2)
     # Ttest can be updated multiple times, and the order of the updates does not matter.
     ttest.fit_u(traces_rk, np.zeros((traces_rk.shape[0],), dtype=np.uint16))
     ttest.fit_u(traces_fk, np.ones((traces_fk.shape[0],), dtype=np.uint16))

examples/test_examples.py

@@ -12,4 +12,5 @@ def example_path(example_file):
 
 def test_examples():
     for p in ["aes_attack.py", "aes_tvla.py", "aes_info.py"]:
-        runpy.run_path(example_path(p))
+        print(f"####### {p} #######")
+        runpy.run_path(example_path(p), run_name="__main__")

src/scalib/attacks/__init__.py

@@ -12,21 +12,8 @@
    FactorGraph
    GenFactor
    BPState
-
-Deprecated
-~~~~~~~~~~
-
-.. currentmodule:: scalib.attacks
-
-.. autosummary::
-   :toctree:
-   :recursive:
-   :nosignatures:
-
-   SASCAGraph
 """
 
 __all__ = ["FactorGraph", "BPState", "GenFactor"]
 
-from .sascagraph import SASCAGraph
 from .factor_graph import FactorGraph, BPState, GenFactor