Course update: lessons, CTF 0x0011a_cb, and documentation

- 0x0011a_cb (Operation Dark Vector): nation-state CTF redesign with an
  AES-128-ECB sealed target and a plaintext launch origin; RP2350 firmware with
  bearing-driven servo, tri-color LEDs, GSV stats, and a realistic no-fix path
- docs: story-driven classified brief, GDB and Ghidra tutorials with deep
  step-throughs, regenerated artifacts and PDFs
- scripts: docstring standard, AES per-student randomizer, telemetry monitor
- week 3 to week 5 lessons: Ghidra patching tutorial, CMSIS-SVD hardware RE,
  double floating-point and GPIO architecture chapters, README structure

0x0017a_ctf/include/auth.h

@@ -0,0 +1,143 @@
+// MIT License
+//
+// Copyright (c) 2026 Kevin Thomas
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+// Author:  Kevin Thomas
+// Email:   kevin@mytechnotalent.com
+// GitHub:  https://github.com/mytechnotalent/encryption-c-rp2350
+// File:    auth.h
+// Desc:    Declares the Ouroboros authentication engine API for RP2350 firmware.
+// Created: 2026
+
+#ifndef AUTH_H
+#define AUTH_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+/**
+ * @brief Onboard LED GPIO pin number.
+ *
+ * The RP2350 Pico 2 onboard LED is connected to GPIO 25. Driven high
+ * on successful authentication and low on failure or idle.
+ */
+#define AUTH_LED_PIN 25u
+
+/**
+ * @brief Maximum accepted terminal passphrase length in bytes.
+ *
+ * The CLI accepts interactive human-entered passphrases up to 512 bytes,
+ * matching the hardened host demo boundary before policy validation.
+ */
+#define AUTH_PASSPHRASE_MAX_LEN 512u
+
+/**
+ * @brief Required number of lowercase words in the hardened passphrase.
+ *
+ * The embedded hardened workflow matches the host-side policy exactly:
+ * twelve lowercase ASCII words separated by whitespace.
+ */
+#define AUTH_REQUIRED_WORDS 12u
+
+/**
+ * @brief Hardened Argon2id salt size in bytes.
+ *
+ * Every demo artifact carries a per-ciphertext random 128-bit salt.
+ */
+#define AUTH_SALT_SIZE 16u
+
+/**
+ * @brief Hardened XChaCha20 nonce size in bytes.
+ *
+ * XChaCha20-Poly1305 consumes a 192-bit nonce in the outer construction.
+ */
+#define AUTH_NONCE_SIZE 24u
+
+/**
+ * @brief Subkey size in bytes derived from Argon2id.
+ *
+ * The AEAD key size is 256 bits.
+ */
+#define AUTH_KEY_SIZE 32u
+
+/**
+ * @brief AEAD authentication tag size in bytes.
+ *
+ * XChaCha20-Poly1305 appends a 128-bit authentication tag.
+ */
+#define AUTH_TAG_SIZE 16u
+
+/**
+ * @brief Plaintext payload size in bytes.
+ *
+ * The fixed dispatch payload is 48 bytes: LED state, UART bytes,
+ * and trailing reserved bytes matching the Rust hardened demo layout.
+ */
+#define AUTH_PAYLOAD_SIZE 48u
+
+/**
+ * @brief Full ciphertext-plus-tag artifact size in bytes.
+ *
+ * The encrypted payload is 48 bytes followed by a 16-byte tag.
+ */
+#define AUTH_CIPHERTEXT_SIZE (AUTH_PAYLOAD_SIZE + AUTH_TAG_SIZE)
+
+/**
+ * @brief Authentication result codes returned by the hardened engine.
+ *
+ * These values let the CLI distinguish policy failures from
+ * cryptographic authentication failures without guessing.
+ */
+typedef enum auth_result {
+    AUTH_RESULT_SUCCESS = 0,
+    AUTH_RESULT_POLICY_VIOLATION = 1,
+    AUTH_RESULT_AUTHENTICATION_FAILED = 2,
+    AUTH_RESULT_INTERNAL_ERROR = 3,
+} auth_result_t;
+
+/**
+ * @brief Initialize the Ouroboros authentication module.
+ *
+ * Configures the onboard LED GPIO and marks the hardened engine as ready
+ * for passphrase authentication.
+ *
+ * @param None.
+ * @return bool true when initialization is successful, else false.
+ */
+bool auth_init(void);
+
+/**
+ * @brief Execute the hardened Ouroboros authentication pipeline.
+ *
+ * Validates the strict 12-word lowercase passphrase policy, derives the
+ * 256-bit AEAD key with Argon2id using artifact parameters, decrypts the
+ * embedded XChaCha20-Poly1305 ciphertext, and dispatches GPIO25/UART
+ * payload bytes on success.
+ *
+ * @param passphrase Pointer to passphrase bytes.
+ * @param passphrase_len Number of passphrase bytes.
+ * @return auth_result_t Detailed authentication outcome for the caller.
+ */
+auth_result_t auth_execute(const uint8_t *passphrase,
+                           size_t passphrase_len);
+
+#endif // AUTH_H