450 lines
15 KiB
Markdown
450 lines
15 KiB
Markdown
# OTP Cipher - One Time Pad Implementation
|
|
|
|
## Introduction
|
|
|
|
A secure one-time pad (OTP) cipher implementation in C.
|
|
|
|
## Why One-Time Pads
|
|
|
|
Nostr and much of the web runs on public key cryptography. Public key cryptography is great, but it is vulnerable. Cryptographers know this, and they know what it takes to attack it, so what they do is just make the keys large enough such that the system is resistant to attack given computers as they are today.
|
|
|
|
There is one type of cryptography, however, that is invulnerable to any type of attack in our universe, and that is known as a one-time pad.
|
|
|
|
One-time pads rely directly on the laws of physics and what it means for a number to be truly random.
|
|
|
|
If you take your secret message and mix it with truly random numbers, and don't use those random numbers again, then that message is unbreakable by any computer, no matter how powerful, quantum or not, forever.
|
|
|
|
In fact, one-time pads are so powerful that if you have data encrypted by a one-time pad located in a distant galaxy, and that data is not kept anywhere else, then by destroying the pad used for encryption in your galaxy, the data is wiped from the universe and can never be recovered.
|
|
|
|
## Advantages and Limitations
|
|
|
|
### Limitations
|
|
|
|
1. The pad must be shared between the parties wanting to use it.
|
|
2. The pad must be as long or longer than what you want to encrypt, and it can't be used a second time.
|
|
|
|
### Modern Advantages
|
|
|
|
While in the past, pad length might have been a problem, readily available USB drives in the terabytes make size less of a problem for many uses.
|
|
|
|
We are also becoming very accustomed to YubiKey authenticators in the USB ports of our computers. A small USB drive in our devices can now easily contain a key of greater length than all the text messages we would expect to send over a lifetime.
|
|
|
|
### Multi-Device Coordination
|
|
|
|
One of the problems to address is the fact that to use an OTP across several devices means that they have to coordinate to know when they are encrypting new plaintext and where to start in the key. Reusing the same section of the pad, while not necessarily fatal, degrades the encryption from its status as "Information Theoretically Secure".
|
|
|
|
To address this problem, we can use Nostr to share among devices the place in the pad that was last left off.
|
|
|
|
### Additional Benefits
|
|
|
|
One-time pads can be trivially encrypted and decrypted using pencil and paper, making them accessible even without electronic devices.
|
|
|
|
|
|
## Features
|
|
|
|
- **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
|
|
- **Cross-Platform**: Works on Linux and other UNIX-like systems
|
|
|
|
|
|
## Quick Start
|
|
|
|
### Download Pre-Built Binaries
|
|
|
|
**[Download Current Linux x86](https://git.laantungir.net/laantungir/otp/releases/download/v0.3.31/otp-v0.3.31-linux-x86_64)**
|
|
|
|
**[Download Current Raspberry Pi 64](https://git.laantungir.net/laantungir/otp/releases/download/v0.3.31/otp-v0.3.31-linux-arm64)**
|
|
|
|
After downloading:
|
|
```bash
|
|
# Make executable and run
|
|
chmod +x otp-v0.3.31-linux-x86_64
|
|
./otp-v0.3.31-linux-x86_64
|
|
```
|
|
|
|
### First Steps
|
|
|
|
1. **Generate your first pad:**
|
|
```bash
|
|
./otp-v0.3.31-linux-x86_64 generate 1GB
|
|
```
|
|
|
|
2. **Encrypt a message:**
|
|
```bash
|
|
./otp-v0.3.31-linux-x86_64 encrypt
|
|
# Follow the interactive prompts
|
|
```
|
|
|
|
3. **Decrypt a message:**
|
|
```bash
|
|
./otp-v0.3.31-linux-x86_64 decrypt
|
|
# Paste the encrypted message
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Building from Source
|
|
|
|
### Prerequisites
|
|
|
|
- GCC compiler
|
|
- Make
|
|
|
|
### Build Commands
|
|
|
|
```bash
|
|
make # Build for current architecture
|
|
make static # Static linking (standalone binary)
|
|
make clean # Clean build artifacts
|
|
make install # Install to /usr/local/bin/otp
|
|
make uninstall # Remove from system
|
|
```
|
|
|
|
Output: `build/otp-$(ARCH)` (e.g., `build/otp-x86_64`)
|
|
|
|
After building, run with:
|
|
```bash
|
|
./build/otp-x86_64
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Interactive Mode
|
|
```bash
|
|
# If you downloaded the binary:
|
|
./otp-v0.3.31-linux-x86_64
|
|
|
|
# If you built from source:
|
|
./build/otp-x86_64
|
|
```
|
|
|
|
### Command Line Mode
|
|
```bash
|
|
# Generate a new pad
|
|
./otp-v0.3.31-linux-x86_64 generate 1GB
|
|
|
|
# Encrypt text (interactive input)
|
|
./otp-v0.3.31-linux-x86_64 encrypt <pad_hash_or_prefix>
|
|
|
|
# Decrypt message (interactive input)
|
|
./otp-v0.3.31-linux-x86_64 decrypt <pad_hash_or_prefix>
|
|
|
|
# List available pads
|
|
./otp-v0.3.31-linux-x86_64 list
|
|
```
|
|
|
|
## Version System
|
|
|
|
### Centralized Version Management
|
|
Version is defined in a single location: `src/main.h`
|
|
```c
|
|
#define OTP_VERSION "v0.3.24"
|
|
```
|
|
|
|
All code references this constant, ensuring consistency across:
|
|
- Main menu display
|
|
- ASCII armor output
|
|
- Help/usage text
|
|
|
|
### Automatic Version Increment
|
|
The `build.sh` script automatically:
|
|
1. Increments patch version (v0.3.24 → v0.3.25)
|
|
2. Updates `OTP_VERSION` in `src/main.h`
|
|
3. Creates git commit and tag
|
|
4. Pushes to remote repository
|
|
|
|
### Manual Version Control
|
|
For major/minor releases, create tags manually:
|
|
```bash
|
|
# Feature release (minor bump)
|
|
git tag v0.4.0 # Next build: v0.4.1
|
|
|
|
# Breaking change (major bump)
|
|
git tag v1.0.0 # Next build: v1.0.1
|
|
```
|
|
|
|
## Security Features
|
|
|
|
- Uses `/dev/urandom` for cryptographically secure random number generation
|
|
- Optional keyboard entropy mixing using simple XOR operations
|
|
- Custom 256-bit XOR checksum for pad identification (encrypted with pad data)
|
|
- Read-only pad files to prevent accidental modification
|
|
- State tracking to prevent pad reuse
|
|
- **Zero external crypto dependencies** - completely self-contained implementation
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
otp/
|
|
├── build.sh # Build script with automatic versioning
|
|
├── Makefile # Traditional make build system
|
|
├── README.md # This file
|
|
├── .gitignore # Git ignore rules
|
|
├── src/
|
|
│ ├── main.h # Main header with all prototypes and OTP_VERSION
|
|
│ ├── main.c # Application entry point and command line handling
|
|
│ ├── ui.c # Interactive user interface and menu system
|
|
│ ├── state.c # Global state management (pads directory, preferences)
|
|
│ ├── crypto.c # Core cryptographic operations (XOR, base64)
|
|
│ ├── pads.c # Pad management and file operations
|
|
│ ├── entropy.c # Entropy collection from various sources
|
|
│ ├── trng.c # Hardware RNG device detection and collection
|
|
│ ├── util.c # Utility functions and helpers
|
|
│ ├── nostr_chacha20.c # ChaCha20 implementation for entropy expansion
|
|
│ └── nostr_chacha20.h # ChaCha20 header
|
|
├── build/
|
|
│ ├── otp-x86_64 # Native x86_64 binary (created by build)
|
|
│ └── otp-arm64 # ARM64 binary (created by cross-compilation)
|
|
├── pads/ # OTP pad storage directory (created at runtime)
|
|
├── files/ # Encrypted file storage (created at runtime)
|
|
└── tests/ # Test scripts and utilities
|
|
```
|
|
|
|
## 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, base64 encoding)
|
|
- **pads.c**: Pad file management, checksums, and state tracking
|
|
- **entropy.c**: Entropy collection from keyboard, dice, files, and hardware RNG
|
|
- **trng.c**: Hardware RNG device detection and entropy collection from USB devices
|
|
- **util.c**: Utility functions, file operations, and helper routines
|
|
- **nostr_chacha20.c**: ChaCha20 stream cipher for entropy expansion
|
|
|
|
All modules share a common header (`src/main.h`) that defines the public API, data structures, and version constant.
|
|
|
|
## 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)
|
|
|
|
Binary encrypted files use a structured header format:
|
|
|
|
```
|
|
Offset | Size | Field | Description
|
|
-------|------|-------------------|----------------------------------
|
|
0 | 4 | Magic | "OTP\0" - File type identifier
|
|
4 | 2 | Version | Format version (currently 1)
|
|
6 | 32 | Pad Checksum | Binary pad checksum (32 bytes)
|
|
38 | 8 | Pad Offset | Offset in pad file (uint64_t)
|
|
46 | 4 | File Mode | Original file permissions (uint32_t)
|
|
50 | 8 | File Size | Original file size (uint64_t)
|
|
58 | var | Encrypted Data | XOR-encrypted file contents
|
|
```
|
|
|
|
### .otp.asc File Format (ASCII Armored)
|
|
|
|
ASCII armored files use the same format as encrypted text messages:
|
|
|
|
```
|
|
-----BEGIN OTP MESSAGE-----
|
|
Version: v0.2.15
|
|
Pad-ChkSum: <64-character-hex-checksum>
|
|
Pad-Offset: <decimal-offset-value>
|
|
|
|
<base64-encoded-encrypted-data>
|
|
-----END OTP MESSAGE-----
|
|
```
|
|
|
|
**Note:** ASCII armored files do not preserve original file permissions metadata.
|
|
|
|
## Usage Examples
|
|
|
|
### Short Command Flags
|
|
```bash
|
|
# Quick commands using short flags
|
|
./otp -g 1GB # Generate 1GB pad
|
|
./otp -l # List available pads
|
|
./otp -e 1a2b "Hello world" # Encrypt text inline
|
|
./otp -d "-----BEGIN OTP..." # Decrypt message inline
|
|
|
|
# File operations
|
|
./otp -f document.pdf 1a2b # Encrypt file (binary)
|
|
./otp -f document.pdf 1a2b -a # Encrypt file (ASCII)
|
|
./otp -f document.pdf 1a2b -o secret.otp # Custom output name
|
|
```
|
|
|
|
### Text Encryption
|
|
```bash
|
|
# Interactive text encryption
|
|
./otp encrypt 1a2b3c
|
|
Enter text to encrypt: This is my secret message
|
|
# Outputs ASCII armored message
|
|
|
|
# Inline text encryption
|
|
./otp -e 1a2b3c "This is my secret message"
|
|
# Outputs ASCII armored message immediately
|
|
```
|
|
|
|
### File Encryption
|
|
```bash
|
|
# Binary format (preserves metadata)
|
|
./otp -f sensitive.doc a1b2c3
|
|
|
|
# ASCII armored format (text-safe)
|
|
./otp -f sensitive.doc a1b2c3 -a
|
|
|
|
# Custom output filename
|
|
./otp -f sensitive.doc a1b2c3 -o encrypted_document.otp
|
|
```
|
|
|
|
### Decryption
|
|
```bash
|
|
# Auto-detect format and pad from message/file
|
|
./otp -d encrypted.otp.asc
|
|
./otp -d "-----BEGIN OTP MESSAGE-----..."
|
|
|
|
# Interactive mode
|
|
./otp decrypt
|
|
# Prompts for encrypted message input
|
|
```
|
|
|
|
### Build and Version Tracking
|
|
```bash
|
|
$ ./build.sh build
|
|
[INFO] Incrementing version...
|
|
[INFO] Current version: v0.2.14
|
|
[INFO] New version: v0.2.15
|
|
[SUCCESS] Created new version tag: v0.2.15
|
|
[SUCCESS] Build completed successfully
|
|
|
|
$ ./otp --help
|
|
OTP Cipher - One Time Pad Implementation v0.2.15
|
|
Built on 2025-08-10 at 14:07:58 from commit ae0afcf on branch master
|
|
```
|
|
|
|
### Advanced Features
|
|
```bash
|
|
# Generate pad with keyboard entropy
|
|
./otp generate 5GB
|
|
# Follow prompts for keyboard entropy collection
|
|
|
|
# Check pad usage
|
|
./otp -l
|
|
Available pads:
|
|
No. ChkSum (first 16 chars) Size Used % Used
|
|
--- ------------------- ---------- ---------- ------
|
|
1 97d9d82b5414a943 1.00GB 156B 0.0%
|
|
2 0c8e19fde996e683 1000B 248B 24.8%
|
|
|
|
# Show detailed pad information
|
|
./otp
|
|
# Select "S" for show pad info, enter checksum or prefix
|
|
```
|
|
|
|
## License
|
|
|
|
This project includes automatic versioning system based on the Generic Automatic Version Increment System.
|
|
|
|
## State Files
|
|
|
|
Pad state files (`.state`) use a human-readable text format:
|
|
```
|
|
offset=1234567890
|
|
```
|
|
|
|
This tracks how many bytes of each pad have been used. The format is:
|
|
- **Human-readable**: Can inspect with `cat checksum.state`
|
|
- **Backward compatible**: Automatically reads old binary format
|
|
- **Easy to debug**: Can manually edit if needed
|
|
|
|
## Contributing
|
|
|
|
When contributing:
|
|
1. The version will automatically increment on builds via `build.sh`
|
|
2. Version is centralized in `src/main.h` as `OTP_VERSION`
|
|
3. For major features, manually create minor/major version tags
|
|
4. Build artifacts in `build/` and object files are auto-cleaned
|