mirror of
https://github.com/mytechnotalent/Embedded-Hacking.git
synced 2026-10-01 13:40:32 +02:00
Kevin Thomas
35eacd2c0e
- 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
144 lines
4.4 KiB
C
144 lines
4.4 KiB
C
// 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
|