.. krypteia Side-Channel Analysis and Countermeasures — documentation
   master file.

###################################################################
krypteia — Side-Channel Analysis and Countermeasures
###################################################################

:Status:  Draft
:Version: |release|
:Scope:   Part I of the krypteia workspace — post-quantum cryptography
          (:doc:`countermeasures/ml_kem`, :doc:`countermeasures/ml_dsa`,
          :doc:`countermeasures/slh_dsa`). Part II (classical crypto in
          the ``arcana`` crate) is not covered here.

Document purpose
================

This document describes the physical and logical side-channel threat
model that the ``quantica`` crate is designed to resist, and maps each
threat to the corresponding countermeasure(s) implemented in the code
together with:

* the published attack or countermeasure paper the construction is
  drawn from (:doc:`biblio`);
* a pointer to the exact source file(s) and function(s) implementing it
  (:doc:`countermeasures/ml_kem`, :doc:`countermeasures/ml_dsa`,
  :doc:`countermeasures/slh_dsa`);
* a qualitative estimate of the attack's cost in equipment and effort
  when mounted against an **unprotected** implementation, so that the
  reader can judge the criticality of each countermeasure.

The intended audience is a cryptographic integrator or security
reviewer deciding whether ``quantica`` fits their threat model,
and contributors maintaining or extending the code.

Scope of the threat model
=========================

The analysis covers passive and active physical side-channels, and
software-observable timing / memory-access side-channels:

* Simple / Differential / Correlation Power Analysis (SPA / DPA / CPA)
* Template attacks (supervised profiled attacks)
* Timing and cache-timing attacks (software attacker)
* Differential Fault Analysis (DFA) and Statistical Ineffective
  Fault Analysis (SIFA)
* Electromagnetic side-channels (SEMA / DEMA / CEMA — treated
  jointly with their power equivalents)

Purely cryptanalytic attacks on the underlying lattice / hash-based
problems are **out of scope** — they are covered by the NIST security
arguments for FIPS 203/204/205.

Document structure
==================

.. toctree::
   :maxdepth: 2
   :caption: Contents

   threat_model
   primitives
   countermeasures/ml_kem
   countermeasures/ml_dsa
   countermeasures/slh_dsa
   verification
   biblio

.. toctree::
   :maxdepth: 1
   :caption: Audits

   audits/hermelink_masked

.. note::

   The companion document :file:`doc/infra/ctgrind.md` is the
   operator-facing reference for running the Valgrind-based CT
   verifier. It is Markdown rather than rST and is not inlined here;
   link from :doc:`verification` when needed.

Change log
==========

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Date
     - Change
   * - 2026-04-21
     - Initial draft covering ML-KEM, ML-DSA, SLH-DSA; threat model;
       silentops primitives; ctgrind verification; current suppressions
       and Tier-4 hardening roadmap.