How cardware-wallet/cardware-hardware works
Project Type and Purpose
• The project is firmware designed for a cryptocurrency hardware wallet (specifically BTC only).
• Its purpose is to securely manage Bitcoin functionalities such as transaction creation, cryptographic operations (using both built-in crypto and external secure elements), and potentially QR code generation for display.
• The firmware integrates various modules including display drivers (e.g., ST7735), cryptographic routines (Bitcoin module with mbedTLS and optiga libraries), and hardware device drivers (STM32 HAL and CMSIS).
Main Components
• Hardware Abstraction Layer (HAL) & Microcontroller Infrastructure:
• STM32H7xx HAL Driver files in the “Drivers” directory (e.g., stm32h7xx_hal*.c/h).
• Startup assembly (Core/Startup) and linker scripts (STM32H743VITX_FLASH.ld, STM32H743VITX_RAM.ld) indicating the microcontroller’s boot and memory configuration.
• Core Firmware Application (under “Core”):
• Initialization and main application entry (Core/Src/main.cpp).
• Peripheral drivers and middleware (e.g., GFX_FUNCTIONS for display, ST7735 for LCD control, fonts, JPEG utilities).
• Bitcoin Module:
• All Bitcoin-related source files (Core/Src/Bitcoin) that cover Bitcoin-specific algorithms, data conversions, transaction handling, hashing (SHA, ripemd160, secp256k1) and utility functions.
• Supporting submodules for cryptographic routines, including a well-organized “utility/crypto” folder.
• Secure Element and Cryptographic Interface:
• “Optiga” libraries in both Inc and Src directories under Core/Inc/optiga and Core/Src/optiga provide abstraction for secure cryptographic operations.
• The included Ifx_I2C and PAL (platform abstraction layer) subdirectories indicate structured communication with a potential secure element chip.
• Integration with mbedTLS (see Core/Src/optiga/mbedtls) for a standard crypto framework.
• Peripheral & Utility Modules:
• Imaging and QR code functionalities (Core/Src/qrcode.c, Core/Src/quirc) for handling QR code data which is useful for wallet operation.
• JPEG functionality provided in the “Utilities/JPEG” folder for image handling (possibly for displaying logos or QR codes).
Relationships and Interactions
• At the bottom, the Hardware Layer including the STM32 microcontroller, its startup code, and low-level drivers (Drivers, CMSIS, STM32 HAL).
• Above that, the Hardware Abstraction Layer combines the STM32 HAL and CMSIS layers with board-specific configuration.
• The Application Layer (Core) sits on this platform and includes modules for display control, secure communications (optiga, I2C layers), and overall firmware logic.
• A dedicated module for Bitcoin handling connects to both the cryptographic routines and the UI/display components. It interacts with secure element modules to perform sensitive operations securely.
• The optiga module communicates with external secure elements (over I2C) which should be shown as an external dependency for secure operations.
Architectural Patterns and Design Principles
• Layered design is evident: separation between hardware drivers, middleware (crypto, secure element interfaces), and application logic.
• Modular organization: Each specific functionality (Bitcoin, display, secure element communications) is isolated in its own folder/module to maintain clarity and ease maintenance.
• Abstraction over hardware specifics: The use of CMSIS, HAL libraries, and PAL indicates that hardware details are abstracted away from the high-level Bitcoin logic.
• Security-first approach: Integration of secure cryptographic libraries (mbedTLS) and specialized hardware modules (optiga) shows a focus on maintaining a secure firmware environment.
Specific Elements
• Initialization sequence from Bootloader/Startup → HAL Drivers → Application.
• Data flows between Bitcoin logic ←→ Crypto modules and Bitcoin logic ←→ UI Display.
• That security-critical interfaces (optiga, crypto libraries) are visually distinct to highlight their importance.