rustfs-crypto

Crates.iorustfs-crypto
lib.rsrustfs-crypto
version0.0.3
created_at2025-07-04 23:35:02.550745+00
updated_at2025-07-04 23:35:02.550745+00
descriptionCryptography and security features for RustFS, providing encryption, hashing, and secure authentication mechanisms.
homepagehttps://rustfs.com
repositoryhttps://github.com/rustfs/rustfs
max_upload_size
id1738632
size84,130
houseme (houseme)

documentation

https://docs.rs/rustfs-crypto/latest/rustfs_crypto/

README

RustFS

RustFS Crypto Module

High-performance cryptographic module for RustFS distributed object storage

CI ๐Ÿ“– Documentation ยท ๐Ÿ› Bug Reports ยท ๐Ÿ’ฌ Discussions


๐Ÿ“– Overview

The RustFS Crypto Module is a core cryptographic component of the RustFS distributed object storage system. This module provides secure, high-performance encryption and decryption capabilities, JWT token management, and cross-platform cryptographic operations designed specifically for enterprise-grade storage systems.

Note: This is a submodule of RustFS and is designed to work seamlessly within the RustFS ecosystem. For the complete RustFS experience, please visit the main RustFS repository.

โœจ Features

๐Ÿ” Encryption & Decryption

  • Multiple Algorithms: Support for AES-GCM, ChaCha20Poly1305, and PBKDF2
  • Key Derivation: Argon2id and PBKDF2 for secure key generation
  • Memory Safety: Built with Rust's memory safety guarantees
  • Cross-Platform: Optimized for x86_64, aarch64, s390x, and other architectures

๐ŸŽซ JWT Management

  • Token Generation: Secure JWT token creation with HS512 algorithm
  • Token Validation: Robust JWT token verification and decoding
  • Claims Management: Flexible claims handling with JSON support

๐Ÿ›ก๏ธ Security Features

  • FIPS Compliance: Optional FIPS 140-2 compatible mode
  • Hardware Acceleration: Automatic detection and utilization of CPU crypto extensions
  • Secure Random: Cryptographically secure random number generation
  • Side-Channel Protection: Resistant to timing attacks

๐Ÿš€ Performance

  • Zero-Copy Operations: Efficient memory usage with Bytes support
  • Async/Await: Full async support for non-blocking operations
  • Hardware Optimization: CPU-specific optimizations for better performance

๐Ÿ“ฆ Installation

Add this to your Cargo.toml:

[dependencies]
rustfs-crypto = "0.1.0"

Feature Flags

[dependencies]
rustfs-crypto = { version = "0.1.0", features = ["crypto", "fips"] }

Available features:

  • crypto (default): Enable all cryptographic functions
  • fips: Enable FIPS 140-2 compliance mode
  • default: Includes both crypto and fips

๐Ÿ”ง Usage

Basic Encryption/Decryption

use rustfs_crypto::{encrypt_data, decrypt_data};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let password = b"my_secure_password";
    let data = b"sensitive information";

    // Encrypt data
    let encrypted = encrypt_data(password, data)?;
    println!("Encrypted {} bytes", encrypted.len());

    // Decrypt data
    let decrypted = decrypt_data(password, &encrypted)?;
    assert_eq!(data, decrypted.as_slice());
    println!("Successfully decrypted data");

    Ok(())
}

JWT Token Management

use rustfs_crypto::{jwt_encode, jwt_decode};
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let secret = b"jwt_secret_key";
    let claims = json!({
        "sub": "user123",
        "exp": 1234567890,
        "iat": 1234567890
    });

    // Create JWT token
    let token = jwt_encode(secret, &claims)?;
    println!("Generated token: {}", token);

    // Verify and decode token
    let decoded = jwt_decode(&token, secret)?;
    println!("Decoded claims: {:?}", decoded.claims);

    Ok(())
}

Advanced Usage with Custom Configuration

use rustfs_crypto::{encrypt_data, decrypt_data, Error};

#[cfg(feature = "crypto")]
fn secure_storage_example() -> Result<(), Error> {
    // Large data encryption
    let large_data = vec![0u8; 1024 * 1024]; // 1MB
    let password = b"complex_password_123!@#";

    // Encrypt with automatic algorithm selection
    let encrypted = encrypt_data(password, &large_data)?;

    // Decrypt and verify
    let decrypted = decrypt_data(password, &encrypted)?;
    assert_eq!(large_data.len(), decrypted.len());

    println!("Successfully processed {} bytes", large_data.len());
    Ok(())
}

๐Ÿ—๏ธ Architecture

Supported Encryption Algorithms

Algorithm Key Derivation Use Case FIPS Compliant
AES-GCM Argon2id General purpose, hardware accelerated โœ…
ChaCha20Poly1305 Argon2id Software-only environments โŒ
AES-GCM PBKDF2 FIPS compliance required โœ…

Cross-Platform Support

The module automatically detects and optimizes for:

  • x86/x86_64: AES-NI and PCLMULQDQ instructions
  • aarch64: ARM Crypto Extensions
  • s390x: IBM Z Crypto Extensions
  • Other architectures: Fallback to software implementations

๐Ÿงช Testing

Run the test suite:

# Run all tests
cargo test

# Run tests with all features
cargo test --all-features

# Run benchmarks
cargo bench

# Test cross-platform compatibility
cargo test --target x86_64-unknown-linux-gnu
cargo test --target aarch64-unknown-linux-gnu

๐Ÿ“Š Performance

The crypto module is designed for high-performance scenarios:

  • Encryption Speed: Up to 2GB/s on modern hardware
  • Memory Usage: Minimal heap allocation with zero-copy operations
  • CPU Utilization: Automatic hardware acceleration detection
  • Scalability: Thread-safe operations for concurrent access

๐Ÿค Integration with RustFS

This module is specifically designed to integrate with other RustFS components:

  • Storage Layer: Provides encryption for object storage
  • Authentication: JWT tokens for API authentication
  • Configuration: Secure configuration data encryption
  • Metadata: Encrypted metadata storage

๐Ÿ“‹ Requirements

  • Rust: 1.70.0 or later
  • Platforms: Linux, macOS, Windows
  • Architectures: x86_64, aarch64, s390x, and more

๐Ÿ”’ Security Considerations

  • All cryptographic operations use industry-standard algorithms
  • Key derivation follows best practices (Argon2id, PBKDF2)
  • Memory is securely cleared after use
  • Timing attack resistance is built-in
  • Hardware security modules (HSM) support planned

๐Ÿ› Known Issues

  • Hardware acceleration detection may not work on all virtualized environments
  • FIPS mode requires additional system-level configuration
  • Some older CPU architectures may have reduced performance

๐ŸŒ Related Projects

This module is part of the RustFS ecosystem:

๐Ÿ“š Documentation

For comprehensive documentation, visit:

๐Ÿ”— Links

๐Ÿค Contributing

We welcome contributions! Please see our Contributing Guide for details on:

  • Code style and formatting requirements
  • Testing procedures and coverage
  • Security considerations for cryptographic code
  • Pull request process and review guidelines

Development Setup

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

# Navigate to crypto module
cd crates/crypto

# Install dependencies
cargo build

# Run tests
cargo test

# Format code
cargo fmt

# Run linter
cargo clippy

๐Ÿ’ฌ Getting Help

๐Ÿ“ž Contact

๐Ÿ‘ฅ Contributors

This module is maintained by the RustFS team and community contributors. Special thanks to all who have contributed to making RustFS cryptography secure and efficient.

๐Ÿ“„ License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Copyright 2024 RustFS Team

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

RustFS is a trademark of RustFS, Inc.
All other trademarks are the property of their respective owners.

Made with โค๏ธ by the RustFS Team

Commit count: 0

cargo fmt