src/constants.py

"""
Centralized constants for the ASCAD training pipeline.

All magic numbers, lookup tables, and configuration defaults are defined here
to avoid duplication and ensure consistency across modules.
"""

import numpy as np

# ---------------------------------------------------------------------------
# AES S-Box lookup table (used for label computation and key-rank evaluation)
# ---------------------------------------------------------------------------
AES_SBOX = np.array([
    0x63, 0x7C, 0x77, 0x7B, 0xF2, 0x6B, 0x6F, 0xC5,
    0x30, 0x01, 0x67, 0x2B, 0xFE, 0xD7, 0xAB, 0x76,
    0xCA, 0x82, 0xC9, 0x7D, 0xFA, 0x59, 0x47, 0xF0,
    0xAD, 0xD4, 0xA2, 0xAF, 0x9C, 0xA4, 0x72, 0xC0,
    0xB7, 0xFD, 0x93, 0x26, 0x36, 0x3F, 0xF7, 0xCC,
    0x34, 0xA5, 0xE5, 0xF1, 0x71, 0xD8, 0x31, 0x15,
    0x04, 0xC7, 0x23, 0xC3, 0x18, 0x96, 0x05, 0x9A,
    0x07, 0x12, 0x80, 0xE2, 0xEB, 0x27, 0xB2, 0x75,
    0x09, 0x83, 0x2C, 0x1A, 0x1B, 0x6E, 0x5A, 0xA0,
    0x52, 0x3B, 0xD6, 0xB3, 0x29, 0xE3, 0x2F, 0x84,
    0x53, 0xD1, 0x00, 0xED, 0x20, 0xFC, 0xB1, 0x5B,
    0x6A, 0xCB, 0xBE, 0x39, 0x4A, 0x4C, 0x58, 0xCF,
    0xD0, 0xEF, 0xAA, 0xFB, 0x43, 0x4D, 0x33, 0x85,
    0x45, 0xF9, 0x02, 0x7F, 0x50, 0x3C, 0x9F, 0xA8,
    0x51, 0xA3, 0x40, 0x8F, 0x92, 0x9D, 0x38, 0xF5,
    0xBC, 0xB6, 0xDA, 0x21, 0x10, 0xFF, 0xF3, 0xD2,
    0xCD, 0x0C, 0x13, 0xEC, 0x5F, 0x97, 0x44, 0x17,
    0xC4, 0xA7, 0x7E, 0x3D, 0x64, 0x5D, 0x19, 0x73,
    0x60, 0x81, 0x4F, 0xDC, 0x22, 0x2A, 0x90, 0x88,
    0x46, 0xEE, 0xB8, 0x14, 0xDE, 0x5E, 0x0B, 0xDB,
    0xE0, 0x32, 0x3A, 0x0A, 0x49, 0x06, 0x24, 0x5C,
    0xC2, 0xD3, 0xAC, 0x62, 0x91, 0x95, 0xE4, 0x79,
    0xE7, 0xC8, 0x37, 0x6D, 0x8D, 0xD5, 0x4E, 0xA9,
    0x6C, 0x56, 0xF4, 0xEA, 0x65, 0x7A, 0xAE, 0x08,
    0xBA, 0x78, 0x25, 0x2E, 0x1C, 0xA6, 0xB4, 0xC6,
    0xE8, 0xDD, 0x74, 0x1F, 0x4B, 0xBD, 0x8B, 0x8A,
    0x70, 0x3E, 0xB5, 0x66, 0x48, 0x03, 0xF6, 0x0E,
    0x61, 0x35, 0x57, 0xB9, 0x86, 0xC1, 0x1D, 0x9E,
    0xE1, 0xF8, 0x98, 0x11, 0x69, 0xD9, 0x8E, 0x94,
    0x9B, 0x1E, 0x87, 0xE9, 0xCE, 0x55, 0x28, 0xDF,
    0x8C, 0xA1, 0x89, 0x0D, 0xBF, 0xE6, 0x42, 0x68,
    0x41, 0x99, 0x2D, 0x0F, 0xB0, 0x54, 0xBB, 0x16,
], dtype=np.uint8)

# ---------------------------------------------------------------------------
# Per-byte POI windows derived from masked SNR analysis on raw traces.
# Each window is 700 samples extracted from ATMega8515_raw_traces.h5.
# Byte 2 window [45400, 46100) validated against official ASCAD extraction.
# ---------------------------------------------------------------------------
BYTE_POI_WINDOWS = {
    0:  (30838, 31538),
    1:  (24525, 25225),
    2:  (45400, 46100),
    3:  (32824, 33524),
    4:  (47508, 48208),
    5:  (41258, 41958),
    6:  (37094, 37794),
    7:  (35018, 35718),
    8:  (26631, 27331),
    9:  (39145, 39845),
    10: (28766, 29466),
    11: (43333, 44033),
    12: (20418, 21118),
    13: (22499, 23199),
    14: (49571, 50271),
    15: (18363, 19063),
}

# Per-byte peak SNR values from our SNR analysis (10,000 profiling traces)
BYTE_PEAK_SNR = {
    0:  1.72, 1:  1.44, 2:  2.99, 3:  1.82,
    4:  2.24, 5:  2.22, 6:  2.10, 7:  1.95,
    8:  1.28, 9:  1.68, 10: 1.15, 11: 2.48,
    12: 0.78, 13: 0.94, 14: 2.55, 15: 0.83,
}

# Global window covering all 16 POI regions (for multi-task models)
GLOBAL_WINDOW_START = 18000
GLOBAL_WINDOW_END = 50272
GLOBAL_WINDOW_SIZE = GLOBAL_WINDOW_END - GLOBAL_WINDOW_START  # 32,272

# ---------------------------------------------------------------------------
# Dataset configuration
# ---------------------------------------------------------------------------
NUM_CLASSES = 256
WINDOW_SIZE = 700
NUM_PROFILING_TRACES = 50000
NUM_ATTACK_TRACES = 10000
DEFAULT_PROFILING_RANGE = (0, 50000)
DEFAULT_ATTACK_RANGE = (50000, 60000)

# Map desync level to HDF5 filename (pre-extracted, byte 2 only)
DESYNC_FILES = {
    0: "ASCAD.h5",
    50: "ASCAD_desync50.h5",
    100: "ASCAD_desync100.h5",
}

ASCAD_DOWNLOAD_URL = (
    "https://www.data.gouv.fr/api/1/datasets/r/"
    "e7ab6f9e-79bf-431f-a5ed-faf0ebe9b08e"
)
ASCAD_ZIP_FILENAME = "ASCAD_data.zip"
ASCAD_DB_SUBDIR = "ASCAD_data/ASCAD_databases"
ASCAD_RAW_FILENAME = "ATMega8515_raw_traces.h5"

# ---------------------------------------------------------------------------
# Training defaults
# ---------------------------------------------------------------------------
MLP_DEFAULTS = {
    "epochs": 200,
    "batch_size": 100,
    "learning_rate": 1e-5,
    "num_hidden_layers": 5,
    "hidden_units": 200,
}

CNN_DEFAULTS = {
    "epochs": 150,
    "batch_size": 200,
    "learning_rate": 1e-5,
    "conv_filters": [64, 128, 256, 512, 512],
    "kernel_size": 11,
    "pool_size": 2,
    "fc_units": 4096,
    "num_fc_layers": 2,
}

# ---------------------------------------------------------------------------
# HuggingFace repository IDs
# ---------------------------------------------------------------------------
HF_MLP_REPO = "lemousehunter/ascad-mlp-rank0-models"  # Legacy
HF_CNN_REPO = "lemousehunter/ascad-cnn-rank0-models"  # Legacy
HF_MTAN_REPO = "lemousehunter/ascad-mtan-rank0-models"  # Legacy
HF_PIPELINE_REPO = "lemousehunter/ascad-training-pipeline"
HF_V1_REPO = "lemousehunter/ascad-v1-models"  # Unified repo for final runs