otp/README.md

# 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
- **Keyboard Entropy**: Optional keyboard entropy collection for enhanced randomness
- **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)
```

## Examples

### Build and Version Tracking
```bash
$ ./build.sh build
[INFO] Incrementing version...
[INFO] Current version: v0.1.4  
[INFO] New version: v0.1.5
[SUCCESS] Created new version tag: v0.1.5
[SUCCESS] Build completed successfully

$ ./otp
=== OTP Cipher v0.1.5 ===

=== Main Menu ===
1. Generate new pad
2. Encrypt message
3. Decrypt message
4. List available pads
5. Show pad information
6. Exit

$ ./otp --help
OTP Cipher - One Time Pad Implementation v0.1.5
Built on 2025-08-10 at 08:17:47 from commit 9edfa5f on branch master
Usage:
  ./otp                              - Interactive mode
  ...
```

### Version History
```bash
$ git tag --list
v0.1.0
v0.1.1  
v0.1.2
v0.1.3
v0.1.4
v0.1.5
```

## 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