XPFF Header Generator

A Rust implementation of XPFF header generation using AES-256-GCM encryption. This library provides secure header generation for authentication and data protection using a combination of SHA-256 key derivation and AES-256-GCM authenticated encryption.

Acknowledgments

This project is based on the original work from dsekz/twitter-x-xp-forwarded-for-header. Special thanks to @dsekz for creating the foundation that made this project possible.

Original Repository

• Repository: twitter-x-xp-forwarded-for-header
• Author: @dsekz

All modifications and enhancements in this fork are my own work. Please refer to the original repository for the initial implementation and documentation.

Twitter X-Xp-Forwarded-For Header

https://heysmmreseller.com/

http://heysmmprovider.com/

Features

• 🔐 AES-256-GCM encryption with authenticated encryption
• 🔑 SHA-256 key derivation from base key and guest ID
• 🎲 Secure random nonce generation for each encryption
• 🦀 Pure Rust implementation with no unsafe code
• 📦 Simple API with both struct-based and function-based interfaces
• ⚡ Zero-copy operations where possible
• 🧪 Comprehensive test coverage
• 📚 Full documentation with examples

Installation

Add this to your Cargo.toml:

[dependencies]
xpff-header-generator = "0.1.0"

Quick Start

use xpff_header_generator::XPFFHeaderGenerator;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a generator with your base key
    let generator = XPFFHeaderGenerator::new("your_secret_base_key");
    
    // Encrypt a message
    let encrypted = generator.generate_xpff("Hello, World!", "guest123")?;
    println!("Encrypted: {}", encrypted);
    
    // Decrypt the message
    let decrypted = generator.decode_xpff(&encrypted, "guest123")?;
    println!("Decrypted: {}", decrypted);
    
    Ok(())
}

Usage Examples

Using the struct-based API

use xpff_header_generator::XPFFHeaderGenerator;

let base_key = "0e6be1f1e21ffc33590b888fd4dc81b19713e570e805d4e5df80a493c9571a05";
let generator = XPFFHeaderGenerator::new(base_key);

let guest_id = "v1%3A174849298500261196";
let message = r#"{"user_id": 123, "timestamp": 1234567890}"#;

// Generate encrypted header
let encrypted = generator.generate_xpff(message, guest_id)?;

// Decode the header
let decrypted = generator.decode_xpff(&encrypted, guest_id)?;
assert_eq!(message, decrypted);

Using convenience functions

use xpff_header_generator::{generate_xpff, decode_xpff};

let encrypted = generate_xpff("Hello", "guest123", "base_key")?;
let decrypted = decode_xpff(&encrypted, "guest123", "base_key")?;

Error handling

use xpff_header_generator::{XPFFHeaderGenerator, XPFFError};

let generator = XPFFHeaderGenerator::new("base_key");

match generator.decode_xpff("invalid_data", "guest123") {
    Ok(decrypted) => println!("Decrypted: {}", decrypted),
    Err(XPFFError::HexError(e)) => eprintln!("Invalid hex: {}", e),
    Err(XPFFError::DecryptionError(e)) => eprintln!("Decryption failed: {}", e),
    Err(e) => eprintln!("Error: {}", e),
}

How It Works

1. Key Derivation: The library derives a 256-bit encryption key by concatenating the base key with the guest ID and computing SHA-256 hash
2. Encryption: Uses AES-256-GCM with a random 96-bit nonce for authenticated encryption
3. Output Format: Returns hex-encoded string containing: nonce (12 bytes) || ciphertext || auth_tag (16 bytes)

API Documentation

XPFFHeaderGenerator

The main struct for generating and decoding XPFF headers.

Methods

• new(base_key: impl Into<String>) -> Self - Creates a new generator instance
• generate_xpff(&self, plaintext: &str, guest_id: &str) -> Result<String, XPFFError> - Encrypts a message
• decode_xpff(&self, hex_string: &str, guest_id: &str) -> Result<String, XPFFError> - Decrypts a message

Convenience Functions

• generate_xpff(plaintext: &str, guest_id: &str, base_key: &str) -> Result<String, XPFFError>
• decode_xpff(hex_string: &str, guest_id: &str, base_key: &str) -> Result<String, XPFFError>

Error Types

The library uses a custom XPFFError enum for error handling:

• EncryptionError - Encryption operation failed
• DecryptionError - Decryption operation failed
• HexError - Invalid hex encoding
• Utf8Error - Invalid UTF-8 in decrypted data
• InvalidDataLength - Data too short to be valid

Security Considerations

• Each encryption uses a unique random nonce
• AES-256-GCM provides authenticated encryption
• Keys are derived using SHA-256
• The base key should be kept secret and stored securely
• Guest IDs should be unique per user/session

Performance

The library is designed for performance:

• Zero-copy operations where possible
• Efficient memory allocation
• Minimal dependencies

Development

Building

cargo build --release

Running tests

cargo test

Running benchmarks

cargo bench

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the Python implementation using PyCrypto
• Built with excellent Rust cryptography libraries

Related Projects

• aes-gcm - AES-GCM implementation
• sha2 - SHA-256 implementation

Support

If you have any questions or run into issues, please open an issue on the GitHub repository.