FluxEncrypt

A high-performance, secure encryption SDK for Rust applications, providing both hybrid encryption capabilities and streaming data protection with enterprise-grade security features.

Authors

• Wyatt Roersma - Lead Developer
• Claude Code - AI Assistant Developer
• Codex - Architecture Consultant

Developed for the ThreatFlux Organization

Features

🔐 Core Encryption

• Hybrid Encryption: Combines RSA-OAEP and AES-GCM for optimal security and performance
• AES-256-GCM: Fast symmetric encryption with authenticated encryption
• RSA-OAEP: Secure asymmetric encryption with optimal padding (4096-bit keys by default)
• Symmetric Cipher: Simple AES-256-GCM for secret storage (API tokens, MFA secrets, etc.)
• Key Derivation: PBKDF2 and Argon2 support for secure key generation
• Base64 Encoding: Default base64 output for easy handling in text environments
• Unified API: Cryptum provides a single interface for all encryption operations

🚀 Performance

• Stream Processing: Handle large files and data streams efficiently
• Batch Operations: Process multiple files with parallel execution
• Memory Safety: Zero-copy operations where possible
• Hardware Acceleration: Leverages hardware crypto instructions

🔧 Developer Experience

• Simple API: Intuitive interface for common use cases
• Flexible Configuration: Customizable security parameters
• String Data Support: Direct encryption/decryption of string data via CLI
• Multiple Output Formats: Base64 (default) and raw binary output options
• Comprehensive Examples: Ready-to-use code samples
• Excellent Documentation: Detailed guides and API references

🛡️ Security

• Memory Protection: Automatic secret zeroization
• Timing limitations: RSA private-key operations have the unpatched RUSTSEC-2023-0071 timing advisory; see modernization notes.
• Secure Random Generation: Cryptographically secure randomness
• Environment Integration: Secure secret management from environment variables

📦 Async Support

• Tokio Integration: Full async/await support
• Streaming Operations: Process large datasets asynchronously
• Concurrent Processing: Handle multiple operations simultaneously

Quick Start

Installation

FluxEncrypt is published on crates.io. Add it to your Cargo.toml:

[dependencies]
fluxencrypt = "0.7"

# For async support
fluxencrypt-async = "0.7"

Install the command-line tool with cargo install fluxencrypt-cli.

Basic Usage

use fluxencrypt::{Config, HybridCipher};
use fluxencrypt::keys::KeyPair;

// Generate a new key pair (default 4096-bit)
let keypair = KeyPair::generate(4096)?;

// Create cipher with default configuration
let cipher = HybridCipher::new(Config::default());

// Encrypt data
let plaintext = b"Hello, FluxEncrypt!";
let ciphertext = cipher.encrypt(&keypair.public_key(), plaintext)?;

// Decrypt data
let decrypted = cipher.decrypt(&keypair.private_key(), &ciphertext)?;
assert_eq!(plaintext, &decrypted[..]);

File Encryption

use fluxencrypt::stream::FileStreamCipher;
use std::path::Path;

let cipher = FileStreamCipher::new(config);

// Encrypt a file
cipher.encrypt_file(
    Path::new("document.pdf"),
    Path::new("document.pdf.enc"),
    &public_key
)?;

// Decrypt a file
cipher.decrypt_file(
    Path::new("document.pdf.enc"),
    Path::new("document_restored.pdf"),
    &private_key
)?;

Async Operations

use fluxencrypt_async::{AsyncHybridCipher, Config};

let cipher = AsyncHybridCipher::new(Config::default());

// Async encryption
let ciphertext = cipher.encrypt_async(&public_key, data).await?;

// Async decryption  
let plaintext = cipher.decrypt_async(&private_key, &ciphertext).await?;

Environment-based Key Management

use fluxencrypt::env::EnvSecretProvider;

// Load keys from environment variables
let provider = EnvSecretProvider::new();
let private_key = provider.get_private_key("FLUX_PRIVATE_KEY")?;
let public_key = provider.get_public_key("FLUX_PUBLIC_KEY")?;

Symmetric Encryption for Secrets

For simple secret storage (API tokens, MFA secrets, database credentials):

use fluxencrypt::SymmetricCipher;

// Create cipher from a 32-byte hex-encoded key
let key = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
let cipher = SymmetricCipher::new(key)?;

// Encrypt a secret - output is base64 encoded
let encrypted = cipher.encrypt("my-api-token-secret")?;

// Decrypt it back
let decrypted = cipher.decrypt(&encrypted)?;

// Generate a new random key
let new_key = SymmetricCipher::generate_key();

Unified Cryptum Interface

For applications needing all encryption features in one interface:

use fluxencrypt::{Cryptum, cryptum};

// Create with defaults
let crypto = cryptum()?;

// Or use the builder for custom configuration
let crypto = Cryptum::builder()
    .cipher_suite(CipherSuite::Aes256Gcm)
    .memory_limit_mb(256)
    .hardware_acceleration(true)
    .build()?;

// Generate keys
let keypair = crypto.generate_keypair(4096)?;

// Encrypt/decrypt data
let ciphertext = crypto.encrypt(keypair.public_key(), b"secret data")?;
let plaintext = crypto.decrypt(keypair.private_key(), &ciphertext)?;

// File operations with progress
crypto.encrypt_file("input.pdf", "output.enc", keypair.public_key())?;
crypto.decrypt_file("output.enc", "restored.pdf", keypair.private_key())?;

Command Line Interface

FluxEncrypt includes a powerful CLI for file encryption operations:

# Install the CLI
cargo install fluxencrypt-cli

# Generate a new key pair (4096-bit RSA by default)
fluxencrypt-cli keygen --output-dir ./keys

# Generate keys in base64 format
fluxencrypt-cli keygen --output-dir ./keys --base64

# Encrypt a file
fluxencrypt-cli encrypt --key ./keys/fluxencrypt_key.pub --input document.pdf --output document.pdf.enc

# Encrypt string data directly (outputs base64 by default)
fluxencrypt-cli encrypt --key ./keys/fluxencrypt_key.pub --data "Hello, World!"

# Encrypt with raw binary output
fluxencrypt-cli encrypt --key ./keys/fluxencrypt_key.pub --input document.pdf --output document.pdf.enc --raw

# Decrypt a file  
fluxencrypt-cli decrypt --key ./keys/fluxencrypt_key.pem --input document.pdf.enc --output document.pdf

# Decrypt base64 string data directly
fluxencrypt-cli decrypt --key ./keys/fluxencrypt_key.pem --data "base64encodeddata..."

# Decrypt raw binary input
fluxencrypt-cli decrypt --key ./keys/fluxencrypt_key.pem --input document.pdf.enc --raw

# Batch encrypt multiple files
fluxencrypt-cli batch-encrypt --key ./keys/fluxencrypt_key.pub --input-dir ./documents --output-dir ./encrypted

# Stream encrypt large files
fluxencrypt-cli stream-encrypt --key ./keys/fluxencrypt_key.pub --input large-file.bin --output large-file.bin.enc

Container Image

The CLI is also published to the GitHub Container Registry as ghcr.io/threatflux/fluxencrypt for linux/amd64 and linux/arm64. Each release is tagged with its version (for example 0.7.11); 0.7, 0 and latest point at the newest release of their line. main and the short commit SHA follow the main branch. A tag is applied only after every platform passed its smoke test and its Trivy scan and the image was signed with keyless cosign. The image is scratch-based (no shell), runs as the non-root user 65532, and its entrypoint is the CLI:

# Verify the signature of a release image
cosign verify ghcr.io/threatflux/fluxencrypt:0.7 \
  --certificate-identity-regexp '^https://github\.com/ThreatFlux/FluxEncrypt/\.github/workflows/docker\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# Generate keys and encrypt a file in the current directory
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" -w /work \
  ghcr.io/threatflux/fluxencrypt:0.7 keygen --output-dir ./keys
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" -w /work \
  ghcr.io/threatflux/fluxencrypt:0.7 encrypt --key ./keys/fluxencrypt_key.pub --input document.pdf --output document.pdf.enc

The Compose example defaults to ghcr.io/threatflux/fluxencrypt:0.7.11@sha256:07cf961ffbbab7b79f1b9e02a45511d255fb7ab06dc4838da75aee8aefb8b8e9, the verified multi-platform release index for source f358d3fa934c0362f8c9ea76e45dbc4424635bcc. See the dated release and scan evidence for its scope and scanner limits. Run from docker/:

mkdir -p data keys
FLUXENCRYPT_UID=$(id -u) FLUXENCRYPT_GID=$(id -g) docker compose run --rm fluxencrypt keygen

Set FLUXENCRYPT_IMAGE to a complete image reference when upgrading; prefer a verified release tag and index digest together. The default stays on the verified release until explicitly updated rather than following the mutable latest tag. For a local scratch build, build docker/Dockerfile with a separate local tag and select it with the same override:

docker build -f Dockerfile -t fluxencrypt-local:dev ..
FLUXENCRYPT_IMAGE=fluxencrypt-local:dev docker compose run --rm fluxencrypt --version

The optional fluxencrypt-alpine service builds docker/Dockerfile.alpine locally as fluxencrypt-local:alpine (pull_policy: build). No published GHCR :alpine tag is established by the release evidence; the scratch release's digest and scan results do not cover this dynamic Alpine runtime. Use docker compose run --rm fluxencrypt-alpine --version to build and run it. These examples replace the repository's Docker Hub references; migration of external Docker Hub consumers remains unverified.

Configuration

FluxEncrypt provides flexible configuration options:

use fluxencrypt::config::{Config, CipherSuite, KeyDerivation, RsaKeySize};

let config = Config::builder()
    .cipher_suite(CipherSuite::Aes256Gcm)
    .rsa_key_size(RsaKeySize::Rsa4096)
    .key_derivation(KeyDerivation::Pbkdf2 {
        iterations: 100_000,
        salt_len: 32,
    })
    .memory_limit_mb(256)
    .hardware_acceleration(true)
    .secure_memory(true)
    .build()?;

Configuration Options

Option	Default	Description
cipher_suite	Aes256Gcm	Symmetric encryption algorithm
rsa_key_size	Rsa4096	RSA key size for hybrid encryption
memory_limit_mb	256	Memory limit for operations
hardware_acceleration	true	Enable hardware crypto instructions
stream_chunk_size	64KB	Chunk size for streaming operations
secure_memory	true	Enable automatic secret zeroization

Performance Benchmarks

FluxEncrypt is designed for high performance:

• AES-256-GCM: 2.5+ GB/s throughput on modern hardware
• RSA-4096: 500+ operations/sec for key operations (enhanced security)
• Hybrid Mode: Optimal balance of security and speed
• Stream Processing: Constant memory usage regardless of file size

Run benchmarks:

cd fluxencrypt && cargo bench

Security Considerations

Cryptographic Standards

• Uses only well-established, peer-reviewed algorithms
• Implements current NIST recommendations
• Regular security audits and updates

Memory Safety

• Automatic zeroization of sensitive data
• Protected memory allocation for keys
• Secure random number generation

Side-channel Resistance

• AES-GCM uses the ring backend; this does not remove the RSA limitation below.
• RSA private-key timing risk remains; avoid remotely observable decryption endpoints until upstream supplies a patched stable release.
• Secure coding practices throughout

Project Structure

fluxencrypt/
├── fluxencrypt/           # Core library
├── fluxencrypt-cli/       # Command line interface  
├── fluxencrypt-async/     # Async support
├── examples/              # Usage examples
├── benches/               # Performance benchmarks
├── tests/                 # Integration tests
└── docs/                  # Additional documentation

Examples

The fluxencrypt/examples/ directory contains comprehensive examples:

• basic_encryption.rs - Simple encrypt/decrypt operations with hybrid encryption
• file_encryption.rs - File-based encryption with streaming and progress tracking
• key_management.rs - Key generation, storage, and base64 handling
• environment_config.rs - Environment-based configuration and secret loading

Run an example:

cargo run --example basic_encryption
cargo run --example file_encryption

Security Note: Examples may use smaller key sizes for faster execution. Production deployments should always use 4096-bit RSA keys (the library default).

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Clone the repository
git clone https://github.com/ThreatFlux/fluxencrypt.git
cd fluxencrypt

# Install development dependencies
cargo install cargo-audit cargo-deny cargo-outdated

# Run tests
cargo test --all

# Run security audit
cargo audit

# Check for license compliance
cargo deny check

License

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

Support

• Documentation: https://docs.rs/fluxencrypt
• Issues: https://github.com/ThreatFlux/fluxencrypt/issues
• Discussions: https://github.com/ThreatFlux/fluxencrypt/discussions

Changelog

See CHANGELOG.md for a detailed history of changes.

---

FluxEncrypt - Secure, Fast, Reliable Encryption for Rust Applications