282 lines
7.7 KiB
Markdown
282 lines
7.7 KiB
Markdown
# OTP Cipher - One Time Pad Implementation
|
|
|
|
A secure one-time pad (OTP) cipher implementation in C with automatic versioning system.
|
|
|
|
## 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
|
|
- **Keyboard Entropy**: Optional keyboard entropy collection for enhanced randomness
|
|
- **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
|
|
|
|
## Version Information
|
|
|
|
This project uses an automatic versioning system that:
|
|
- Automatically increments the patch version on each build
|
|
- Embeds build timestamp, git commit hash, and branch information
|
|
- Creates git tags for version tracking
|
|
- Generates version header files with detailed build metadata
|
|
|
|
Current version can be viewed with: `./otp --help` or by running the interactive mode.
|
|
|
|
## Building
|
|
|
|
### Prerequisites
|
|
|
|
- GCC compiler
|
|
- Git (for version tracking)
|
|
- Make
|
|
|
|
**Note: OpenSSL is no longer required! This implementation is now completely self-contained.**
|
|
|
|
### Build Commands
|
|
|
|
Use the included build script for automatic versioning:
|
|
|
|
```bash
|
|
# Standard build (default)
|
|
./build.sh build
|
|
|
|
# Static linking build
|
|
./build.sh static
|
|
|
|
# Clean build artifacts
|
|
./build.sh clean
|
|
|
|
# Generate version files only
|
|
./build.sh version
|
|
|
|
# Install to system
|
|
./build.sh install
|
|
|
|
# Remove from system
|
|
./build.sh uninstall
|
|
|
|
# Show usage
|
|
./build.sh help
|
|
```
|
|
|
|
### Traditional Make
|
|
|
|
You can also use make directly (without automatic versioning):
|
|
|
|
```bash
|
|
make # Standard build
|
|
make static # Static linking
|
|
make clean # Clean artifacts
|
|
make install # Install to /usr/local/bin/
|
|
make uninstall # Remove from system
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Interactive Mode
|
|
```bash
|
|
./otp
|
|
```
|
|
|
|
### Command Line Mode
|
|
```bash
|
|
# Generate a new pad
|
|
./otp generate 1GB
|
|
|
|
# Encrypt text (interactive input)
|
|
./otp encrypt <pad_hash_or_prefix>
|
|
|
|
# Decrypt message (interactive input)
|
|
./otp decrypt <pad_hash_or_prefix>
|
|
|
|
# List available pads
|
|
./otp list
|
|
```
|
|
|
|
## Version System Details
|
|
|
|
### Automatic Version Increment
|
|
Every build automatically increments the patch version:
|
|
- v0.1.0 → v0.1.1 → v0.1.2, etc.
|
|
- Creates git tags for each version
|
|
- Embeds detailed build information
|
|
|
|
### Manual Version Control
|
|
For major/minor releases, create tags manually:
|
|
```bash
|
|
# Feature release (minor bump)
|
|
git tag v0.2.0 # Next build: v0.2.1
|
|
|
|
# Breaking change (major bump)
|
|
git tag v1.0.0 # Next build: v1.0.1
|
|
```
|
|
|
|
### Version Information Available
|
|
- Version number (major.minor.patch)
|
|
- Git commit hash and branch
|
|
- Build date and time
|
|
- Full version display with metadata
|
|
|
|
### Generated Files
|
|
The build system automatically generates:
|
|
- `src/version.h` - Version constants and macros
|
|
- `src/version.c` - Version API functions
|
|
- `VERSION` - Plain text version number
|
|
|
|
These files are excluded from git (.gitignore) and regenerated on each build.
|
|
|
|
## 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
|
|
|
|
## File Structure
|
|
|
|
```
|
|
otp/
|
|
├── build.sh # Build script with automatic versioning
|
|
├── Makefile # Traditional make build system
|
|
├── otp.c # Main source code
|
|
├── README.md # This file
|
|
├── .gitignore # Git ignore rules
|
|
├── src/ # Generated version files (auto-created)
|
|
│ ├── version.h # Version header (generated)
|
|
│ └── version.c # Version implementation (generated)
|
|
├── pads/ # OTP pad storage directory (created at runtime)
|
|
└── VERSION # Plain text version (generated)
|
|
```
|
|
|
|
## 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.
|
|
|
|
## Contributing
|
|
|
|
When contributing:
|
|
1. The version will automatically increment on builds
|
|
2. For major features, consider manually creating minor version tags
|
|
3. Generated version files (`src/version.*`, `VERSION`) should not be committed
|