3-Layer File Encryption System

A complete file encryption/decryption system using a 3-layer cryptographic pipeline:

1. Playfair Cipher (substitution)
2. Columnar Transposition (transposition)
3. DES Block Cipher (block encryption)

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Initialize Encryption Keys

Run this ONCE to generate and save the system keys to .keys.json:

python -m backend.keys --init

Important: Keep .keys.json safe! It's in .gitignore but contains all encryption keys.

3. Install Testing Dependencies (Optional)

pip install pytest pytest-asyncio pytest-cov

4. Start the Web Application

python app.py

The application will start on http://localhost:8000

API Documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

System Architecture

3-Layer Pipeline

┌─────────────────────────────────────────────────────┐
│                    ENCRYPTION FLOW                   │
├─────────────────────────────────────────────────────┤
│                                                      │
│  Plaintext                                          │
│      ↓                                              │
│  [Layer 1: Playfair Cipher]                         │
│    • 5×5 Polybius square                            │
│    • Digraph substitution                           │
│    • I/J merged (25 letters)                       │
│      ↓                                              │
│  [Layer 2: Columnar Transposition]                  │
│    • Column reordering via key                      │
│    • Row-write, column-read                         │
│    • Aligned with Playfair output                   │
│      ↓                                              │
│  [Layer 3: DES Block Cipher]                        │
│    • 8-byte blocks (64-bit key)                     │
│    • ECB mode operation                             │
│    • PKCS7 padding                                  │
│      ↓                                              │
│  Ciphertext (Hex-encoded)                           │
│                                                      │
└─────────────────────────────────────────────────────┘

Decryption Flow

Reverses all steps in order:

1. DES decryption (hex → text)
2. Columnar transposition reversal
3. Playfair substitution reversal

---

API Endpoints

File Operations

POST /api/encrypt

Upload and encrypt a file.

Request:

multipart/form-data:
  file: <binary data>

Response:

• Status 200: Encrypted file download
• Status 400/500: JSON error message

Allowed file types: .txt, .log, .csv, .json, .md

Example (curl):

curl -F "file=@plaintext.txt" http://localhost:5000/api/encrypt -o plaintext.txt.encrypted

POST /api/decrypt

Upload and decrypt a file.

Request:

multipart/form-data:
  file: <encrypted file>

Response:

• Status 200: Decrypted file download
• Status 400/500: JSON error message

Example (curl):

curl -F "file=@plaintext.txt.encrypted" http://localhost:5000/api/decrypt -o plaintext_decrypted.txt

Text Operations (Testing)

POST /api/encrypt-text

Encrypt a text string (useful for testing).

Request:

{
  "text": "HELLO WORLD"
}

Response:

{
  "status": "success",
  "plaintext": "HELLO WORLD",
  "ciphertext": "hex-encoded-output...",
  "size_increase": "2.5x"
}

POST /api/decrypt-text

Decrypt a hex-encoded ciphertext.

Request:

{
  "ciphertext": "hex-encoded-input..."
}

Response:

{
  "status": "success",
  "plaintext": "HELLO WORLD",
  "ciphertext": "hex-encoded-input..."
}

System

GET /api/status

Check system status and key information.

Response:

{
  "status": "ready",
  "pipeline": "3-layer (Playfair → Columnar → DES)",
  "keys_loaded": true,
  "playfair_key_length": 12,
  "columnar_key_length": 9,
  "des_key_length": 16,
  "max_file_size_mb": 10.0
}

---

Usage Examples

Using Python Directly

Encrypt Text

from backend import pipeline

plaintext = "HELLO WORLD"
ciphertext = pipeline.encrypt_text(plaintext)
print(f"Encrypted: {ciphertext}")

Decrypt Text

from backend import pipeline

ciphertext = "..."  # from above
plaintext = pipeline.decrypt_text(ciphertext)
print(f"Decrypted: {plaintext}")

Encrypt/Decrypt File

from backend import file_io

# Encrypt with metadata
result = file_io.encrypt_file_with_metadata("input.txt", "outputs")
print(result)

# Decrypt with metadata
result = file_io.decrypt_file_with_metadata(result['output_file'])
print(result)

Using Web Interface (FastAPI + Swagger UI):

1. Start the server: python app.py
2. Open http://localhost:8000 for the web interface
3. Or go to http://localhost:8000/docs for interactive API docs
4. Choose a file to encrypt or decrypt
5. Downloaded encrypted/decrypted file

Or test with text:

1. Enter text in "Test Text Encryption" section
2. Click Encrypt/Decrypt
3. Results shown immediately

---

File Structure

File_Encrypt/
├── app.py                                  # FastAPI web application
├── requirements.txt                        # Python dependencies
├── pytest.ini                              # Pytest configuration
├── .keys.json                              # Encryption keys (auto-generated, git-ignored)
│
├── backend/
│   ├── __init__.py
│   ├── keys.py                             # Key generation & loading
│   ├── playfair.py                         # Layer 1: Playfair cipher
│   ├── columnar.py                         # Layer 2: Columnar transposition
│   ├── des_cipher.py                       # Layer 3: DES block cipher
│   ├── pipeline.py                         # 3-layer pipeline orchestration
│   ├── file_io.py                          # File operations with metadata
│   └── format_preserving_encryption.py     # Formatting preservation utility
│
├── frontend/
│   ├── static/
│   │   ├── app.js                          # JavaScript UI logic
│   │   └── style.css                       # CSS styling
│   └── templates/
│       └── index.html                      # Web interface
│
├── tests/                                  # Automated test suite (20 test files)
│   ├── test_api.py
│   ├── test_playfair_*.py                  # Playfair cipher tests
│   ├── test_encryption_flow.py
│   ├── test_decrypt_*.py
│   ├── test_formatting_preservation.py
│   ├── conftest.py                         # Pytest configuration & fixtures
│   ├── examples.py                         # Annotated test examples
│   └── ... (15 other test files)
│
├── debug/                                  # Debug & diagnostic scripts
│   ├── debug_pipeline.py
│   ├── debug_detailed.py
│   ├── debug_corruption.py
│   └── debug_playfair_issue.py
│
├── uploads/                                # Temporary upload storage
├── outputs/                                # Encrypted/decrypted files
├── REPOSITORY_STRUCTURE.md                 # Detailed folder organization guide
└── README.md                               # This file

---

## Testing

FastAPI provides excellent built-in testing support. All tests use the `TestClient` from FastAPI, requiring no live server.

### Running Tests

**Quick Start:**
```bash
# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=backend --cov=app --cov-report=html

# Run tests matching pattern
pytest -k "encrypt" -v

# Run specific test file
pytest tests/test_playfair_known.py

Test Files Organization

Location: tests/ folder (20 automated test files)

Core Test Suites:

• test_api.py - FastAPI endpoint tests (38 tests)
• test_playfair_*.py - Playfair cipher algorithm tests (6 files)
  • test_playfair_known.py - Known plaintext-ciphertext pairs
  • test_playfair_monarchy.py - Classic "MONARCHY" example
  • test_playfair_roundtrip.py - Encryption/decryption round trips
  • test_playfair_direct.py - Direct cipher tests
  • test_playfair_wrl.py - Word example tests
• test_encryption_flow.py - End-to-end pipeline tests
• test_decrypt_*.py - Decryption-specific tests (3 files)
• test_formatting_preservation.py - Text formatting tests
• test_frontend_workflow.py - Frontend integration tests
• Other specialized tests (13 total files)

Shared Fixtures:

• conftest.py - Pytest configuration and shared test fixtures
• examples.py - Annotated examples for learning

Debug Scripts

Location: debug/ folder (for manual investigation)

Debug scripts are NOT automated tests but tools for developers to investigate issues:

• debug_pipeline.py - Trace encryption pipeline execution
• debug_detailed.py - Detailed step-by-step debugging
• debug_corruption.py - Diagnose file corruption issues
• debug_playfair_issue.py - Playfair cipher debugging

Usage:

python debug/debug_pipeline.py
python debug/debug_detailed.py

Test Coverage

• 20+ automated test files
• All 5 API endpoints
• All 3 encryption layers (Playfair, Columnar, DES)
• Error handling & validation
• Round-trip encryption/decryption verification
• File operations & edge cases
• Frontend workflow integration

See REPOSITORY_STRUCTURE.md for complete folder organization and guidelines on when to use tests vs debug scripts.

---

Layer 1: Playfair Cipher

How it works:

• Builds a 5×5 grid (Polybius square) from the key
• Processes plaintext as digraphs (letter pairs)
• Rules for each digraph:
  • Same row: Shift right (wrap around)
  • Same column: Shift down (wrap around)
  • Rectangle: Swap columns
  • Duplicates in pair: Insert 'X' filler
  • Odd-length text: Pad with 'X'

Key: 12 random uppercase letters (no repeats)

Example:

Key: MONARCHY
Square:
M O N A R
C H Y B D
E F G I K
L P Q S T
U V W X Z

Plaintext:  INSTRUMENTS
Encrypted:  GFHFXGDGJIS

Layer 2: Columnar Transposition

How it works:

• Takes Playfair output (uppercase letters)
• Determines column order from key alphabetical rank
• Writes plaintext row-by-row
• Reads columns in key-determined order

Key: 9 random uppercase letters

Example:

Key: SECRET

Column order: S(4) E(1) C(2) R(3) E(1) T(5)
              → sorted: E=1, C=2, R=3, S=4, T=5

Original (row-write):
S E C R E T
-----------
[row 1]
[row 2]

Read by column order (1,2,3,4,5):
Column 1, Column 2, Column 3, Column 4, Column 5

Layer 3: DES Block Cipher

How it works:

• Industry-standard block cipher (DES)
• 64-bit blocks (8 bytes)
• 56-bit effective key (from 64-bit input)
• ECB mode (Electronic Codebook) for academic purposes
• PKCS7 padding for block alignment

Key: 16-character hex string (8 bytes)

Note: DES is legacy and only included for academic requirements. For production, use AES-256.

---

Security Notes

Academic Use Only

This system is designed for educational purposes and demonstrates:

• How symmetric encryption works
• Multi-layer cipher composition
• Block cipher operation

Not suitable for production due to:

• Playfair: Vulnerable to frequency analysis
• Columnar: Can be broken with large ciphertexts
• DES: 56-bit key is too small (breakable in hours with modern hardware)

Protection Recommendations

For actual sensitive data, use:

• AES-256 instead of DES
• Modern block modes like CBC or GCM (not ECB)
• Key derivation functions (PBKDF2, Argon2)
• Message authentication (HMAC or authenticated encryption)

---

Troubleshooting

"Key file not found" Error

Solution: Run python -m backend.keys --init first

File Upload Size Exceeded

Solution: Maximum file size is 10 MB (configurable in app.py)

Decryption Produces Garbage

Possible causes:

• Wrong key file (regenerate with --init)
• File corrupted during transmission
• Unsupported file encoding

Server Won't Start

Check:

• Port 5000 is available: netstat -an | findstr 5000
• Dependencies installed: pip list | grep -E "Flask|pycryptodome"
• Python version 3.7+ installed: python --version

---

API Usage Examples

Using cURL

Encrypt file:

curl -F "file=@document.txt" \
  http://localhost:8000/api/encrypt \
  -o document.txt.encrypted

Decrypt file:

curl -F "file=@document.txt.encrypted" \
  http://localhost:8000/api/decrypt \
  -o document.txt

Test encryption:

curl -X POST http://localhost:8000/api/encrypt-text \
  -H "Content-Type: application/json" \
  -d '{"text":"HELLO"}' | jq

Check status:

curl http://localhost:8000/api/status | jq

Using Python Requests

import requests

# Upload file for encryption
with open('plaintext.txt', 'rb') as f:
    files = {'file': f}
    response = requests.post('http://localhost:8000/api/encrypt', files=files)
    
with open('plaintext.txt.encrypted', 'wb') as f:
    f.write(response.content)

# Test text encryption
response = requests.post('http://localhost:8000/api/encrypt-text', 
    json={"text": "HELLO WORLD"})
result = response.json()
print(result['ciphertext_full'])

---

Development & Testing

Run Pipeline Tests

python -m backend.pipeline

Test Playfair Cipher

python -m backend.playfair

Test Columnar Cipher

python -m backend.columnar

Test DES Cipher

python -m backend.des_cipher

Test File I/O

python -m backend.file_io

FastAPI Testing Features Used

This project uses FastAPI's built-in testing capabilities:

TestClient:

• Makes HTTP requests without running a server
• Provides full access to request/response details
• Can inspect headers, body, status codes

Pytest Integration:

• @pytest.fixture for reusable test data
• Parametrized testing with @pytest.mark.parametrize
• Class-based test organization
• Setup/teardown with fixtures

Features Demonstrated:

• Testing endpoints with different HTTP methods
• File upload testing
• JSON request/response body testing
• Error status code validation
• Round-trip encryption/decryption verification
• Performance testing
• Fixture dependency injection
• Test cleanup and resources

How to write tests:

• See tests/conftest.py for fixture patterns
• See tests/examples.py for annotated examples
• See individual test files in tests/ for practical patterns

Using fixtures effectively:

• Fixtures defined in conftest.py are automatically available
• Use @pytest.fixture for reusable test data
• Dependency injection with fixture parameters

Testing patterns and best practices: Check REPOSITORY_STRUCTURE.md for detailed guidelines on:

• When to write automated tests vs debug scripts
• Test organization best practices
• How pytest discovers and runs tests

Parametrized testing: Use @pytest.mark.parametrize decorator to test multiple inputs. Examples in test files.

Coverage reports:

pytest --cov=backend --cov=app --cov-report=html
# Opens coverage/ folder with detailed reports

CI/CD integration: Tests are ready for GitHub Actions, GitLab CI, or Jenkins - just run pytest in your pipeline.

---

Performance

Speed Benchmarks (approximate)

Operation	Time	Notes
Encrypt 1KB text	5-10ms	Playfair dominates
Encrypt 100KB text	500-800ms	DES blocks (8 bytes)
Encrypt 1MB file	5-8s	Network included
Decrypt 1MB file	5-8s	Reverse pipeline

Expansion Ratio

• Playfair: 0-5% (substitution only, same length)
• Columnar: 0% (transposition only, same length)
• DES: ~30-35% (hex encoding: 1 byte → 2 chars + padding)

Final ciphertext is typically 2-3x larger than plaintext (due to hex encoding).

---

Future Enhancements

• Add AES-256 as Layer 3 option
• Implement CBC/GCM modes
• Add file compression before encryption
• Multi-file batch processing
• Key management UI (rotate, backup)
• Performance profiling & optimization
• Docker containerization
• REST API authentication (JWT)
• File streaming for large files (>100MB)
• Progress indicators for long operations

---

License

This project is for educational purposes. See LICENSE file for details.

---

Support

For issues or questions:

1. Check this README
2. Review code comments
3. Run diagnostic tests
4. Check system status endpoint

---

Authors

• Samudyatha K Bhat
• Deeksha R
• Nicole Tabby
• Spoorthi R

---