biencrypt 1.0.0
Multi-algorithm encryption library supporting Adjacent Swap, XOR+Base64, and AES-256-GCM
Requires Python: >=3.7
Keywords: encryption cryptography aes xor cipher security crypto

# Multilingual Encryption-Decryption System

A comprehensive collection of **three cross-language encryption implementations** ranging from educational demos to production-grade security. All methods produce **identical outputs** across Python and JavaScript.

## 🔐 Available Encryption Methods

### 1. 🔄 Adjacent Character Swap (Simple)
Educational algorithm for learning encryption basics
- **Security**: Very Low (for learning only)
- **Files**: `encrypt.py`, `encrypt.js`, `adjacent_swap.html`

### 2. 🔒 XOR+Base64 Cipher (Key-Based)
Basic obfuscation with key requirement
- **Security**: Low-Medium (basic obfuscation)
- **Files**: `xor_encrypt.py`, `xor_encrypt.js`, `xor_base64.html`

### 3. 🛡️ AES-256-GCM (Production-Grade)
Military-level encryption for real security
- **Security**: Very High (production ready)
- **Files**: `aes_encrypt.py`, `aes_encrypt.js`, `aes_encryption.html`

---

## 🚀 Quick Start

### Interactive Demos
Open `index.html` in your browser to try all three methods with a beautiful UI!

### Documentation
- **New to this project?** → [QUICKSTART.md](QUICKSTART.md)
- **Adjacent Swap details** → [ALGORITHM.md](ALGORITHM.md)
- **XOR+Base64 guide** → [XOR_README.md](XOR_README.md)
- **AES-256 guide** → [AES_README.md](AES_README.md)
- **Compare all methods** → [COMPARISON.md](COMPARISON.md)

### Live Demo
🌐 [Try it online](https://bibekchandsah.github.io/encryption/) (if deployed)

---

## 📊 Quick Comparison

| Feature | Adjacent Swap | XOR+Base64 | AES-256-GCM |
|---------|--------------|------------|-------------|
| **Security** | Very Low | Low-Medium | **Very High** |
| **Use Case** | Learning | Obfuscation | **Production** |
| **Key Required** | Optional | Required | Required |
| **Output** | Plain text | Base64 | Base64 JSON |
| **Standards** | - | - | **NIST Approved** |
| **Real Security** | ❌ | ❌ | **✅** |

---

## 🎯 Installation & Usage

### Prerequisites

**Python:**
```bash
# For AES-256 only
pip install cryptography
```

**JavaScript:**
- Node.js 12+ (for CLI)
- Modern browser (for web demos)

### Run Tests

```bash
# Adjacent Character Swap
python encrypt.py
node encrypt.js

# XOR+Base64
python xor_encrypt.py
node xor_encrypt.js

# AES-256-GCM
python aes_encrypt.py
node aes_encrypt.js
```

All tests should pass with identical cross-language outputs! ✅

---

## 📖 Usage Examples

### 1. Adjacent Character Swap (Learning)

## 📖 Usage Examples

### 1. Adjacent Character Swap (Learning)

**Features:**
✅ **Cross-Language Compatible**: Identical encryption output in Python, JavaScript  
✅ **Deterministic**: Same input always produces the same output  
✅ **No Dependencies**: Pure implementation  
✅ **Unicode Support**: Works with emojis, international characters  
✅ **Optional Seeding**: Add numeric seed for customizable encryption  

**Python:**
```bash
python encrypt.py
```

**JavaScript:**
```bash
node encrypt.js
```

**Web Demo:**
Open `adjacent_swap.html` in your browser

---

### 2. XOR+Base64 Cipher (Obfuscation)

**Features:**
✅ **Key-Based**: Requires encryption key  
✅ **Base64 Output**: Binary-safe encoding  
✅ **Cross-Language**: Identical outputs  
✅ **Better than Simple Swap**: Moderate security  

**Python:**
```bash
python xor_encrypt.py
```

**JavaScript:**
```bash
node xor_encrypt.js
```

**Web Demo:**
Open `xor_base64.html` in your browser

---

### 3. AES-256-GCM (Production Security)

**Features:**
✅ **Military-Grade**: AES-256 in GCM mode  
✅ **NIST Approved**: Government standard  
✅ **Authenticated**: Tamper detection included  
✅ **PBKDF2**: 100,000 iterations for key derivation  
✅ **Production Ready**: Real security for sensitive data  

**Installation:**
```bash
pip install cryptography
```

**Python:**
```bash
python aes_encrypt.py
```

**JavaScript:**
```bash
node aes_encrypt.js
```

**Web Demo:**
Open `aes_encryption.html` in your browser

---

## 🐍 Python Code Examples

### Adjacent Swap
```python
from encrypt import encrypt, decrypt

encrypted = encrypt("bibek")
print(encrypted)  # Output: ibebk

decrypted = decrypt("ibebk")
print(decrypted)  # Output: bibek

# With seed
encrypted_seed = encrypt("bibek", 2)
print(encrypted_seed)  # Output: keibb
```

### XOR+Base64
```python
from xor_encrypt import xor_encrypt, xor_decrypt

encrypted = xor_encrypt("bibek", "secret")
print(encrypted)  # Output: EQwBFw4=

decrypted = xor_decrypt("EQwBFw4=", "secret")
print(decrypted)  # Output: bibek
```

### AES-256-GCM
```python
from aes_encrypt import aes_encrypt, aes_decrypt, generate_key

# Password-based
encrypted = aes_encrypt("sensitive data", "MyStr0ngP@ssw0rd")
decrypted = aes_decrypt(encrypted, "MyStr0ngP@ssw0rd")

# Key-based
key = generate_key()
encrypted = aes_encrypt_with_key("secret message", key)
decrypted = aes_decrypt_with_key(encrypted, key)
```

---

## 🟨 JavaScript Code Examples

### Adjacent Swap
```javascript
const { encrypt, decrypt } = require('./encrypt.js');

const encrypted = encrypt("bibek");
console.log(encrypted);  // Output: ibebk

const decrypted = decrypt("ibebk");
console.log(decrypted);  // Output: bibek

// With seed
const encryptedSeed = encrypt("bibek", 2);
console.log(encryptedSeed);  // Output: keibb
```

### XOR+Base64
```javascript
const { xorEncrypt, xorDecrypt } = require('./xor_encrypt.js');

const encrypted = xorEncrypt("bibek", "secret");
console.log(encrypted);  // Output: EQwBFw4=

const decrypted = xorDecrypt("EQwBFw4=", "secret");
console.log(decrypted);  // Output: bibek
```

### AES-256-GCM
```javascript
const { aesEncrypt, aesDecrypt, generateKey } = require('./aes_encrypt.js');

// Password-based (async)
(async () => {
    const encrypted = await aesEncrypt("sensitive data", "MyStr0ngP@ssw0rd");
    const decrypted = await aesDecrypt(encrypted, "MyStr0ngP@ssw0rd");
    
    // Key-based
    const key = await generateKey();
    const encrypted2 = await aesEncryptWithKey("secret", key);
    const decrypted2 = await aesDecryptWithKey(encrypted2, key);
})();
```

---

## 🌐 Web Interface

All three encryption methods include interactive HTML demos with:
- ✨ Beautiful gradient UI
- 📋 One-click copy to clipboard
- 📱 Responsive design (mobile-friendly)
- ⚡ Real-time encryption/decryption
- 📚 Built-in example test cases
- 🎨 Method-specific color themes

**Getting Started:**
1. Open `index.html` in your browser
2. Choose your encryption method
3. Start encrypting!

**Features:**
- No server required (runs entirely in browser)
- No installation needed for demos
- Cross-browser compatible
- Clean, modern interface

---

## 🔒 Security Recommendations

### ⚠️ DO NOT USE for Real Security:
- ❌ Adjacent Character Swap - Educational only
- ❌ XOR+Base64 - Basic obfuscation only

### ✅ USE for Real Security:
- ✅ **AES-256-GCM** - Production-grade encryption
  - Suitable for sensitive data
  - Meets compliance standards (GDPR, HIPAA, PCI-DSS)
  - NIST approved
  - Authenticated encryption with tamper detection

**For Production Use:**
- Use strong passwords (16+ characters)
- Implement proper key management
- Use HTTPS/TLS for data transmission
- Never hardcode keys in source code
- Rotate keys periodically
- Follow OWASP security guidelines

---

## 🧪 Testing & Verification

All implementations include comprehensive test suites:

### Test Coverage
- ✅ Basic encryption/decryption
- ✅ Unicode and emoji support
- ✅ Wrong password/key detection
- ✅ Empty string handling
- ✅ Special characters
- ✅ Long text processing
- ✅ Cross-language compatibility

### Cross-Language Verification

**Verify identical outputs:**
```bash
# Adjacent Swap
python -c "from encrypt import encrypt; print(encrypt('test'))"
node -e "const {encrypt} = require('./encrypt.js'); console.log(encrypt('test'));"
# Both output: etts

# XOR+Base64
python -c "from xor_encrypt import xor_encrypt; print(xor_encrypt('hello', 'key'))"
node -e "const {xorEncrypt} = require('./xor_encrypt.js'); console.log(xorEncrypt('hello', 'key'));"
# Both output: AwAVBwo=
```

---

## 📂 Project Structure

```
encryption/
├── index.html                 # Landing page with method selection
├── adjacent_swap.html         # Adjacent swap demo
├── xor_base64.html           # XOR+Base64 demo
├── aes_encryption.html       # AES-256 demo
├── encrypt.py                # Adjacent swap (Python)
├── encrypt.js                # Adjacent swap (JavaScript)
├── xor_encrypt.py            # XOR+Base64 (Python)
├── xor_encrypt.js            # XOR+Base64 (JavaScript)
├── aes_encrypt.py            # AES-256-GCM (Python)
├── aes_encrypt.js            # AES-256-GCM (JavaScript)
├── README.md                 # This file
├── ALGORITHM.md              # Adjacent swap algorithm details
├── XOR_README.md             # XOR+Base64 documentation
├── AES_README.md             # AES-256 documentation
├── COMPARISON.md             # Side-by-side comparison
├── QUICKSTART.md             # Quick start guide
└── instruction.md            # Original project specifications
```

---

## 🛠️ Requirements

### Python
- Python 3.6+ (no dependencies for basic methods)
- `cryptography` library for AES-256 only

### JavaScript
- Node.js 12+ (for CLI usage)
- Modern browser with Web Crypto API (for AES-256 in browser)
- No external dependencies

---

## 📝 Notes
</body>
</html>
```

### Interactive Mode (Node.js)
Uncomment the last line in `encrypt.js`:
```javascript
if (typeof require !== 'undefined' && require.main === module) {
    runTests();
    interactiveMode();  // Uncomment this line
}
```

---

## 🧪 Test Cases

### Basic Test: "bibek"
| Language   | Input    | Encrypted | Decrypted |
|------------|----------|-----------|-----------||
| Python     | `bibek`  | `ibebk`   | `bibek`   |
| JavaScript | `bibek`  | `ibebk`   | `bibek`   |

### Additional Test Cases

| Input             | Encrypted Output  | Description          |
|-------------------|-------------------|----------------------|
| `hello`           | `ehllo`           | Basic word           |
| `world`           | `owlrd`           | Another word         |
| `test`            | `etts`            | 4 characters         |
| `a`               | `a`               | Single character     |
| `ab`              | `ba`              | Two characters       |
| `abc`             | `bac`             | Odd length           |
| `HELLO`           | `EHLLO`           | Uppercase            |
| `Hello World!`    | `eHll ooWlr!d`    | Mixed case + space   |
| `12345`           | `21435`           | Numbers              |
| `!@#$%`           | `@!$#%`           | Special characters   |
| `café`            | `acéf`            | Accented characters  |
| `hello😀world`     | `ehll😀oowlrd`     | With emoji           |
| `こんにちは`       | `んこちには`        | Japanese             |
| `你好世界`         | `好你界世`          | Chinese              |
| ` ` (empty)       | ` ` (empty)       | Empty string         |

---

## 🔍 Edge Cases Handled

| Case                  | Behavior                              |
|-----------------------|---------------------------------------|
| Empty string          | Returns empty string                  |
| Single character      | Returns same character                |
| Odd-length string     | Last character stays in place         |
| Numbers               | Treated as characters, swapped        |
| Uppercase/Lowercase   | Case preserved (case-sensitive)       |
| Unicode (emoji, etc.) | Full Unicode support                  |
| Spaces/Punctuation    | Treated as regular characters         |

---

## 🔄 Alternative Algorithms

If you need different encryption methods, here are alternatives:

### 1. **XOR+Base64 Cipher with Key** ⭐ **IMPLEMENTED**
- XOR each byte with a repeating key
- Encode result in Base64 for safe text representation
- **Pros**: Key-based, cross-language compatible, more secure than Caesar
- **Files**: `xor_encrypt.py`, `xor_encrypt.js`
- **Documentation**: See [XOR_README.md](XOR_README.md)

**Quick Example:**
```bash
# Python
python -c "from xor_encrypt import xor_encrypt; print(xor_encrypt('hello', 'key'))"
# Output: AwAVBwo=

# JavaScript
node -e "const {xorEncrypt} = require('./xor_encrypt.js'); console.log(xorEncrypt('hello', 'key'));"
# Output: AwAVBwo=
```

### 2. **Caesar Cipher with Fixed Shift**
- Shift each character by a fixed number (e.g., +3)
- `a` → `d`, `b` → `e`, etc.
- **Pros**: Simple, well-known
- **Cons**: Easily breakable, doesn't preserve character types

---

## 📊 Cross-Language Validation

To verify identical output across languages:

1. **Python**:
   ```bash
   python -c "from encrypt import encrypt; print(encrypt('bibek'))"
   ```
   Output: `ibebk`

2. **JavaScript (Node.js)**:
   ```bash
   node -e "const {encrypt} = require('./encrypt.js'); console.log(encrypt('bibek'))"
   ```
   Output: `ibebk`

Both should produce **exactly the same output**.

---

## 🔐 Using a Seed (Custom Value)

You can pass an optional numeric seed to both `encrypt` and `decrypt` to change the transformation deterministically. The implementations rotate the string by `seed % len` before (encrypt) / after (decrypt) swapping pairs.

Python example:
```bash
python -c "from encrypt import encrypt, decrypt; print(encrypt('bibek', 2)); print(decrypt('keibb', 2))"
```

Node.js example:
```bash
node -e "const {encrypt, decrypt} = require('./encrypt.js'); console.log(encrypt('bibek', 2)); console.log(decrypt('keibb', 2));"
```

Both commands will output the same encrypted/decrypted results when using the same seed.

---

## 🛠️ Requirements

### Python
- Python 3.6+ (no external dependencies)

### JavaScript
- Node.js 12+ (for CLI usage)
- Any modern browser (for web usage)

---

## 📝 Notes

- **⚠️ Security Warning**: 
  - **Adjacent Swap & XOR+Base64** are **NOT suitable for real-world encryption**
  - These are **educational/demonstration implementations only**
  - **For Real Security**: Use **AES-256-GCM** (included in this project!)
- **Character Encoding**: All implementations use UTF-8/Unicode for international character support
- **Performance**: O(n) time complexity for all methods
- **Cross-Platform**: All methods work identically across Python, JavaScript, and browsers

---

## 📄 License

This is an educational project demonstrating encryption concepts from simple to production-grade. Feel free to use and modify as needed.

---

## 🤝 Contributing

Contributions welcome! To add support for another language:
1. Implement the encryption logic following existing patterns
2. Ensure all test cases pass
3. Verify output matches existing implementations exactly
4. Add appropriate documentation

---

## 🌟 Features Highlights

- 🎨 **Beautiful Web Interface** - Modern, responsive design
- 📋 **Copy to Clipboard** - One-click result copying
- 🔄 **Cross-Language** - Python ↔ JavaScript compatibility
- 🧪 **Comprehensive Tests** - 34+ test cases across all methods
- 📚 **Detailed Docs** - Complete guides for each method
- 🛡️ **Production Ready** - AES-256 for real security
- 📱 **Mobile Friendly** - Responsive tables and layouts
- 🎓 **Educational** - Learn from simple to advanced encryption

---

## 🔗 Quick Links

- 📖 [Quick Start Guide](QUICKSTART.md)
- 🔄 [Adjacent Swap Algorithm](ALGORITHM.md)
- 🔒 [XOR+Base64 Documentation](XOR_README.md)
- 🛡️ [AES-256 Documentation](AES_README.md)
- ⚖️ [Full Comparison](COMPARISON.md)
- 📋 [Original Specifications](instruction.md)

---

## 🙏 Acknowledgments

- AES-256-GCM implementation uses industry-standard cryptographic libraries
- All algorithms are well-documented and tested
- UI inspired by modern web design principles

---

## 📞 Support & Issues

If you find any issues:
- Verify string encoding (UTF-8)
- Check character iteration order
- Ensure proper dependency installation
- Review test outputs for cross-language compatibility

**For AES-256 issues:**
- Ensure `cryptography` library is installed (Python)
- Verify Web Crypto API support (Browser)
- Check password/key correctness

---

**Built with ❤️ for learning and production use**

Happy encrypting! 🔐

---

## 📊 Stats

- **3 Encryption Methods**: Simple → Moderate → Production
- **6 Core Files**: Python & JavaScript for each method
- **4 HTML Demos**: Interactive web interfaces
- **34+ Tests**: Comprehensive test coverage
- **6 Documentation Files**: Detailed guides
- **100% Cross-Language Compatible**: Verified identical outputs