# XOR Encryption in Go

A comprehensive implementation of XOR encryption in Go, following Go best practices and providing both binary and string encryption capabilities.

## Features

- **Simple XOR Cipher**: Symmetric encryption using XOR operations
- **String and Binary Support**: Encrypt both text strings and binary data
- **Random Key Generation**: Cryptographically secure random key generation
- **Base64 Encoding**: String encryption results are base64 encoded for easy handling
- **Memory Safe**: All operations use copies to prevent external modification
- **Comprehensive Testing**: Full test suite with benchmarks
- **Go Best Practices**: Follows Uber Go Style Guide and Go conventions

## Security Notice

⚠️ **Important**: XOR encryption is **NOT cryptographically secure** for production use. It's suitable for:
- Educational purposes
- Simple obfuscation
- Lightweight scenarios where strong security is not required

For production applications requiring security, use established cryptographic libraries like AES.

## Installation

```bash
go mod init your-project
go get .
```

## Usage

### Basic String Encryption

```go
package main

import (
    "fmt"
    "log"
)

func main() {
    // Create cipher with string key
    cipher, err := NewXORCipherFromString("mysecretkey")
    if err != nil {
        log.Fatal(err)
    }
    
    // Encrypt string (returns base64 encoded result)
    plaintext := "Hello, World!"
    encrypted := cipher.EncryptString(plaintext)
    fmt.Printf("Encrypted: %s\n", encrypted)
    
    // Decrypt string
    decrypted, err := cipher.DecryptString(encrypted)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Decrypted: %s\n", decrypted)
}
```

### Binary Data Encryption

```go
// Create cipher with byte key
key := []byte("binarykey")
cipher, err := NewXORCipher(key)
if err != nil {
    log.Fatal(err)
}

// Encrypt binary data
data := []byte{0x48, 0x65, 0x6c, 0x6c, 0x6f}
encrypted := cipher.Encrypt(data)
decrypted := cipher.Decrypt(encrypted)
```

### Random Key Generation

```go
// Generate cryptographically secure random key
randomKey, err := GenerateRandomKey(32) // 32 bytes = 256 bits
if err != nil {
    log.Fatal(err)
}

cipher, err := NewXORCipher(randomKey)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Random key (hex): %s\n", cipher.GetKeyHex())
```

### Direct XOR Operations

```go
// Direct XOR without cipher object
data := []byte("Direct XOR test")
key := []byte("key123")

encrypted, err := XORBytes(data, key)
if err != nil {
    log.Fatal(err)
}

// XOR is symmetric - same operation for decryption
decrypted, err := XORBytes(encrypted, key)
if err != nil {
    log.Fatal(err)
}
```

## API Reference

### Types

#### `XORCipher`
Main cipher type that holds the encryption key and provides encryption/decryption methods.

### Functions

#### `NewXORCipher(key []byte) (*XORCipher, error)`
Creates a new XOR cipher with the provided byte key.

#### `NewXORCipherFromString(key string) (*XORCipher, error)`
Creates a new XOR cipher from a string key.

#### `GenerateRandomKey(length int) ([]byte, error)`
Generates a cryptographically secure random key of specified length.

#### `XORBytes(data, key []byte) ([]byte, error)`
Performs direct XOR operation on data with key.

### Methods

#### `(x *XORCipher) Encrypt(plaintext []byte) []byte`
Encrypts binary data and returns encrypted bytes.

#### `(x *XORCipher) EncryptString(plaintext string) string`
Encrypts a string and returns base64 encoded result.

#### `(x *XORCipher) Decrypt(ciphertext []byte) []byte`
Decrypts binary data (same as Encrypt due to XOR symmetry).

#### `(x *XORCipher) DecryptString(ciphertext string) (string, error)`
Decrypts a base64 encoded string.

#### `(x *XORCipher) GetKey() []byte`
Returns a copy of the cipher key.

#### `(x *XORCipher) GetKeyHex() string`
Returns the cipher key as a hexadecimal string.

## Testing

Run the comprehensive test suite:

```bash
# Run all tests
go test -v

# Run tests with coverage
go test -cover

# Run benchmarks
go test -bench=.

# Run specific test
go test -run TestXORCipher_Encrypt
```

## How XOR Encryption Works

XOR (exclusive OR) encryption works by applying the XOR bitwise operation between each byte of the plaintext and the corresponding byte of the key:

1. **Encryption**: `ciphertext[i] = plaintext[i] XOR key[i % keyLength]`
2. **Decryption**: `plaintext[i] = ciphertext[i] XOR key[i % keyLength]`

The key is repeated cyclically if the plaintext is longer than the key.

### XOR Truth Table
```
A | B | A XOR B
--|---|--------
0 | 0 |   0
0 | 1 |   1
1 | 0 |   1
1 | 1 |   0
```

### Properties
- **Symmetric**: Encryption and decryption use the same operation
- **Reversible**: `A XOR B XOR B = A`
- **Fast**: Simple bitwise operation
- **Key-dependent**: Security depends entirely on key secrecy

## Examples

See `xor_encryption.go` main function for comprehensive examples including:
- Basic string encryption
- Random key generation
- Binary data handling
- Direct XOR operations

## License

Licensed under the Apache License, Version 2.0. See the source files for full license text.

## Contributing

This implementation follows the Uber Go Style Guide and Go best practices. When contributing:

1. Run `go fmt` and `goimports`
2. Ensure all tests pass: `go test`
3. Add tests for new functionality
4. Follow existing code patterns and documentation style