Glossary
Terms used across the docs. Skim it once; refer back when something on another page isn't clicking.
AES-256-CTR. A symmetric encryption mode used for everything stored under /secret/ on your own card. AES is the cipher, 256 the key size, CTR ("counter mode") the way the cipher is chained block-to-block. CTR is what lets the firmware seek into the middle of a 5 MB encrypted file and decrypt only the few bytes needed for one message, instead of decrypting the whole file.
AXP2101. The PMIC (power management chip) on the Waveshare board. Handles battery charging, voltage regulation, the power button, and the controlled hardware shutdown. Controlled over I2C.
Card init. The first-time flow when a blank own MicroSD card is inserted. Sets the PIN, writes the master key, the recovery token, the card salt, and the verify blob.
Contact. A person you've completed a key exchange with. Each contact has a name, a send pad (bytes you encrypt with when messaging them), a receive pad (bytes you decrypt with when reading from them), and bookkeeping that tracks how much of each pad has been used.
DEK (Data Encryption Key). The 32-byte AES key that actually encrypts everything under /secret/. Generated once at card init, never changes. Wrapped under the KEK and stored as master_key.enc.
Device secret. A 256-bit random value generated on first power-on of a fresh gadget. Stored on MCU flash at /flash/device_secret.bin. Mixed into the PIN-derivation function, used to derive the recovery key, and shown once on first boot so you can back it up. If you forget your PIN and don't have this backed up, you can't recover your card.
FT6336U. The capacitive touch controller on the Waveshare board, sitting under the LCD glass. Reads finger touches over I2C and reports portrait (x, y) coordinates.
Guest slot. The external MicroSD slot (the 3.3 V SPI breakout board), used only during key exchange. "Guest" is a slot, not a dedicated card — the card placed in it is the other person's own card, handed over for the exchange and taken back afterward. Only its plaintext /exchange/ staging area is read or written (and wiped once the exchange finalizes); the encrypted /secret/ on it is never touched.
HAL (Hardware Abstraction Layer). The small Python interface that separates firmware/core/ (pure business logic) from the hardware. Two implementations: real.py (the board) and sim.py (a laptop). The core never knows which one it's talking to.
HMAC-SHA256. A message authentication construction. Used in this firmware truncated to 8 bytes as the per-message MAC tag.
KEK (Key Encryption Key). The AES-256 key derived from your PIN (plus the device secret and card salt) via PBKDF2. Used only to encrypt and decrypt the DEK — never used directly on pad files.
MAC tag. The 8-byte HMAC-SHA256 truncation appended to every message. Authenticates the message and lets the receiver figure out which contact sent it.
MicroPython. The Python flavour the firmware is written in. Runs on the RP2350 microcontroller. Has a stdlib similar to Python 3 but stripped down to fit.
mpremote. The CLI tool used to flash code onto the RP2350 over USB. pip install mpremote. The scripts/flash.sh helper wraps it.
One-time pad (OTP). An encryption technique where the key is the same length as the message, used exactly once, and consists of truly random bytes. Mathematically unbreakable when used correctly. Catastrophically broken if any byte is reused.
Own card. Your personal MicroSD card. Stays in the gadget's onboard slot. Holds everything encrypted: the DEK wrap, all contact pads, settings, watermarks, contact list.
Pad. Shorthand for the OTP key bytes. Each contact has two: a pad_send (5 MB of random bytes you use to encrypt outgoing messages to that contact) and a pad_receive (5 MB used to decrypt incoming messages from them).
PBKDF2. A password-based key derivation function. The standard way to turn a low-entropy input (a PIN) into a high-entropy key (the KEK). The "iterations" parameter sets how slow it is — too fast and the PIN can be brute-forced; too slow and boot takes forever.
PMIC. Power management integrated circuit. The AXP2101 chip on the Waveshare board.
PWR button. The hardware power button on the Waveshare module. Short press to power on; long press (~5 s) to force AXP2101 shutdown if the firmware hangs.
Recovery token. A second wrapping of the DEK, kept on the own card, that's encrypted under a key derived from your device_secret. The thing that makes "forgot my PIN, here's my device secret" work.
RP2350. The microcontroller on the Waveshare board. Made by Raspberry Pi. Dual Cortex-M33 cores, 520 KB SRAM, hardware TRNG on silicon.
ST7789. The display controller on the Waveshare board's LCD. Passive driver chip, talks SPI, no firmware on it. Drives the 320 × 480 IPS panel.
TRNG. True Random Number Generator. Hardware that produces randomness from a physical process (thermal noise, oscillator jitter) rather than from a software algorithm. The RP2350's silicon TRNG is the source of every byte used in OTP key material.
Verify blob (verify.bin). A fixed known plaintext encrypted with the DEK at card-init time. Used to detect whether the PIN you typed is correct: if decryption produces the expected magic + salt, the PIN was right; otherwise it was wrong and the attempt counter is incremented.
Watermark. A small ASCII integer file per contact tracking how many bytes of that contact's pad_send have been used. Sending a message advances it by len(plaintext) + 8.