Reupload

README.md

@@ -48,7 +48,9 @@ One-time pads can be trivially encrypted and decrypted using pencil and paper, m
 - **Perfect Security**: Implements true one-time pad encryption with information-theoretic security
 - **Text & File Encryption**: Supports both inline text and file encryption
 - **Multiple Output Formats**: Binary (.otp) and ASCII armored (.otp.asc) file formats
+- **Hardware RNG Support**: Direct entropy collection from TrueRNG USB devices with automatic detection
 - **Keyboard Entropy**: Optional keyboard entropy collection for enhanced randomness
+- **Modular Architecture**: Clean separation of concerns across multiple source modules
 - **Short Command Flags**: Convenient single-character flags for all operations
 - **Automatic Versioning**: Built-in semantic versioning with automatic patch increment
 - **Multiple Build Options**: Standard and static linking builds
@@ -169,14 +171,118 @@ These files are excluded from git (.gitignore) and regenerated on each build.
 ```
 otp/
 ├── build.sh          # Build script with automatic versioning
-├── Makefile         # Traditional make build system  
-├── otp.c            # Main source code
+├── Makefile         # Traditional make build system
+├── otp.c            # Legacy compatibility and global definitions
 ├── README.md        # This file
 ├── .gitignore       # Git ignore rules
+├── include/
+│   └── otp.h        # Public API header with all function prototypes
+├── src/
+│   ├── main.c       # Main application entry point and command line handling
+│   ├── ui.c         # Interactive user interface and menu system
+│   ├── state.c      # Global state management (pads directory, terminal dimensions)
+│   ├── crypto.c     # Core cryptographic operations (XOR, ChaCha20)
+│   ├── pads.c       # Pad management and file operations
+│   ├── entropy.c    # Entropy collection from various sources
+│   ├── trng.c       # Hardware RNG device detection and entropy collection
+│   └── util.c       # Utility functions and helpers
 ├── pads/            # OTP pad storage directory (created at runtime)
 └── VERSION          # Plain text version (generated)
 ```
 
+## Architecture
+
+The OTP cipher uses a modular architecture with clean separation of concerns:
+
+- **main.c**: Application entry point, command line parsing, and mode selection
+- **ui.c**: Interactive user interface, menus, and terminal management
+- **state.c**: Global state management (pads directory, terminal dimensions, preferences)
+- **crypto.c**: Core cryptographic operations (XOR encryption, ChaCha20 entropy mixing)
+- **pads.c**: Pad file management, checksums, and state tracking
+- **entropy.c**: Entropy collection from keyboard, dice, and other sources
+- **trng.c**: Hardware RNG device detection and entropy collection from USB devices
+- **util.c**: Utility functions, file operations, and helper routines
+
+All modules share a common header (`include/otp.h`) that defines the public API and data structures.
+
+## Hardware RNG Device Support
+
+The OTP cipher includes comprehensive support for hardware random number generators (RNGs) to enhance entropy quality for pad generation and entropy addition operations.
+
+### Supported Devices
+
+The system automatically detects and supports the following hardware RNG devices:
+
+| Device | VID:PID | Status | Notes |
+|--------|---------|--------|-------|
+| **TrueRNG** | 04d8:f5fe | ✅ Working | Original TrueRNG device |
+| **TrueRNG (Alt)** | 1fc9:8111 | ✅ Working | Alternative VID/PID combination |
+| **TrueRNG Pro** | 04d8:f5fe | ✅ Working | Professional version |
+| **TrueRNG Pro V2** | 04d8:f5fe | ✅ Working | Latest professional version |
+
+### Device Detection
+
+The system automatically scans `/dev/ttyACM*` ports and identifies hardware RNG devices by:
+
+1. **USB VID/PID Detection**: Reading vendor and product IDs from sysfs
+2. **Device Type Classification**: Identifying specific device variants
+3. **Port Configuration**: Applying device-specific serial port settings
+4. **Interactive Selection**: Presenting available devices for user selection
+
+### Testing Hardware Devices
+
+A comprehensive test script is included to verify hardware RNG functionality:
+
+```bash
+# Run hardware device tests
+./test.sh
+```
+
+The test script performs:
+- **Device Detection**: Scans for and identifies all connected hardware RNG devices
+- **Connectivity Testing**: Verifies each device can be opened and read from
+- **Configuration Testing**: Validates serial port configuration for each device type
+- **Entropy Quality Analysis**: Measures Shannon entropy of collected random data
+
+### Current Test Results
+
+Based on testing with actual hardware devices:
+
+**✅ Working Devices:**
+- TrueRNG (Type 1): Full functionality confirmed
+- TrueRNG Pro V2 (Type 3): Full functionality confirmed
+
+  - Device is detected and identified correctly
+  - Serial port configuration may need adjustment for this device variant
+
+### Usage in Entropy Collection
+
+When generating pads or adding entropy, the system will:
+
+1. **Auto-detect** all connected hardware RNG devices
+2. **Present a menu** of available devices if multiple are found
+3. **Test connectivity** before beginning entropy collection
+4. **Estimate completion time** based on device speed testing
+5. **Collect entropy** with progress indicators and quality metrics
+
+### Device Configuration
+
+Each device type uses optimized serial port settings:
+
+- **TrueRNG devices**: 3Mbps baud rate, 8N1, no flow control
+- **Automatic timeout protection**: Prevents hanging on unresponsive devices
+- **Error recovery**: Graceful handling of device disconnection during operation
+
+### Troubleshooting
+
+If hardware RNG devices are not detected:
+
+1. **Check USB connections**: Ensure devices are properly connected
+2. **Verify permissions**: User must have access to `/dev/ttyACM*` devices
+3. **Check device enumeration**: Use `lsusb` to verify USB device recognition
+4. **Review sysfs entries**: Ensure VID/PID information is available in `/sys/bus/usb/devices/`
+
+
 ## File Formats
 
 ### .otp File Format (Binary)