AEGIS-128L and AEGIS-256: C sources and modules
===============================================

Which file includes which, and what each Python extension module is
compiled from (see setup.py and compiler_opt.py).
Lines from a module name go to the file it is built from;
the other arrows are #include.

           _raw_aegis                       _raw_aegis_aesni      _raw_aegis_armv8
               │                                   │                     │
               ▼                                   ▼                     ▼
  ┌─────────────────────────┐               ┌──────────────┐     ┌───────────────┐
  │    aegis_portable.c     │               │aegis_aesni.c │     │aegis_armv8.c  │
  │                         │               │              │     │               │
  │  word, bitsliced S-box  │               │  AESRound =  │     │  AESRound =   │
  │ bit_stage(), mix_xtime()│               │    AESENC    │     │ AESE + AESMC  │
  └──────┬───────────┬──────┘               └──────┬───────┘     └───────┬───────┘
         │           │                             │                     │
  NEON   │           │  otherwise                  │                     │
  or SSE2│           │                             │                     │
         ▼           ▼                             │                     │
  ┌────────────┐ ┌──────────────┐                  │                     │
  │aegis_simd.c│ │aegis_scalar.c│                  │                     │
  │            │ │              │                  │                     │
  │ 128-bit    │ │ 64-bit words │                  │                     │
  │ vectors,   │ │ state kept   │                  │                     │
  │ aes_rounds │ │ bitsliced,   │                  │                     │
  │            │ │ core_*()     │                  │                     │
  └────────────┘ └──────────────┘                  │                     │
                                                   │                     │
  aegis_portable.c then includes aegis.c ──┐       │                     │
                                           ▼       ▼                     ▼
  ┌──────────────────────────────────────────────────────────────────────────────┐
  │                                   aegis.c                                    │
  │                                                                              │
  │   Init, associated data, Enc/Dec with the partial blocks, Finalize (tag);    │
  │   a generic state over aes_rounds(), unless the backend defines AEGIS_CORE   │
  └──────────────────────────────────────────────────────────────────────────────┘


  Module             Built from          Exports         Compiler flags            AES round
  -----------------  ------------------  --------------  ------------------------  ------------------------
  _raw_aegis         aegis_portable.c    AEGIS_*         -msse2 on x86 (gcc,       bitsliced, constant time:
                     -> aegis_simd.c                     clang), as for all        NEON or SSE2 vectors
                        or aegis_scalar.c                modules                   (aegis_simd.c), else
                     -> aegis.c                                                    64-bit words (aegis_scalar.c)
  _raw_aegis_aesni   aegis_aesni.c       AEGIS_AESNI_*   -maes (gcc, clang)        AESENC
                     -> aegis.c
  _raw_aegis_armv8   aegis_armv8.c       AEGIS_ARMV8_*   -march=armv8-a+crypto     AESE + AESMC
                     -> aegis.c                          (if needed)

Notes:
  - aegis.c is the same in the three modules: it is included last, and the
    backend first defines AEGIS_PREFIX (the prefix of the exported functions),
    aes_block with blk_load(), blk_store() and blk_xor(), and either
    blk_and() and aes_rounds() or, with AEGIS_CORE, its own state with the
    core_*() functions. Only aegis_scalar.c defines AEGIS_CORE.
  - aegis.h (enum AegisVariant and wipe()) is included by aegis_portable.c,
    which aegis_scalar.c needs before aegis.c, and by aegis.c.
  - aegis_simd.c and aegis_scalar.c are not modules: aegis_portable.c includes
    exactly one of them, right after the type word. Each defines the operations
    on words (XOR, AND, SHL, MASK, ...) for its layout; the S-box, bit_stage()
    and mix_xtime(), which follow in aegis_portable.c, use them, and are
    declared before the include, because bitslice_aes_round() calls them.
  - aegis_portable.c uses NEON on 64-bit ARM and on 32-bit ARM built with NEON,
    with gcc or clang (not MSVC, not big-endian), and SSE2 on x86 when USE_SSE2
    is defined (compiler_opt.py defines it for all modules if the compiler
    supports SSE2). Otherwise it uses aegis_scalar.c.
  - _raw_aegis_aesni is only compiled if the compiler supports the AES-NI
    intrinsics (and cpuid.h or intrin.h is present), and _raw_aegis_armv8
    only on 64-bit ARM targets (including macOS universal2, where the x86-64
    half of the module is empty).
  - lib/Crypto/Cipher/AEGIS.py always loads _raw_aegis, and also
    _raw_aegis_aesni if the CPU has AES-NI, or _raw_aegis_armv8 if it has
    the ARMv8 AES instructions; the last one loaded is the default.
  - The C tests include the sources directly, so that they can call the
    internal functions: src/test/test_aegis.c includes aegis_portable.c,
    aegis_aesni.c (TEST_AEGIS_AESNI) or aegis_armv8.c (TEST_AEGIS_ARMV8), and
    test_aegis_ct.c (constant time, under Valgrind) aegis_portable.c.
