gsadmin/rustfs
1
0
Fork 0
mirror of https://github.com/rustfs/rustfs.git synced 2026-08-27 15:37:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: simplify crates README files and enforce PR-only workflow (#110)

Browse Source 
* docs: simplify all crates README files

- Remove extensive code examples and detailed documentation
- Convert to minimal module introductions with core feature lists
- Direct users to main RustFS repository for comprehensive docs
- Updated 20 crate README files for consistency and brevity

Files updated:
- crates/rio/README.md (415→15 lines)
- crates/s3select-api/README.md (592→15 lines)
- crates/s3select-query/README.md (658→15 lines)
- crates/signer/README.md (407→15 lines)
- crates/utils/README.md (395→15 lines)
- crates/workers/README.md (463→15 lines)
- crates/zip/README.md (408→15 lines)

* docs: restore original headers in crates README files

- Add back RustFS logo image and CI badges
- Restore formatted headers and structured layout
- Keep simplified content with module introductions
- Maintain consistent documentation structure across all crates

All 20 crate README files now have proper headers while keeping
the simplified content that directs users to the main repository.

* rules: enforce PR-only workflow for main branch

- Strengthen rule that ALL changes must go through pull requests
- Explicitly forbid direct commits to main branch under any circumstances
- Add comprehensive PR requirements and enforcement guidelines
- Clarify that PRs are the ONLY way to merge to main branch
- Add requirement for PR approval before merging
- Include enforcement mechanisms for branch protection
This commit is contained in:
安正超
2025-07-08 21:10:07 +08:00
committed by GitHub
parent 49f480d346
commit 3dbcaaa221
22 changed files with 227 additions and 8348 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/crypto/README.md
+11 -303
View File
@@ -1,9 +1,9 @@
[![RustFS](https://rustfs.com/images/rustfs-github.png)](https://rustfs.com)
# RustFS Crypto Module
# RustFS Crypto - Cryptographic Operations
<p align="center">
<strong>High-performance cryptographic module for RustFS distributed object storage</strong>
<strong>High-performance cryptographic operations module for RustFS distributed object storage</strong>
</p>
<p align="center">
@@ -17,313 +17,21 @@
## 📖 Overview
The **RustFS Crypto Module** is a core cryptographic component of the [RustFS](https://rustfs.com) 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](https://github.com/rustfs/rustfs).
**RustFS Crypto** provides high-performance cryptographic operations for the [RustFS](https://rustfs.com) distributed object storage system. For the complete RustFS experience, please visit the [main RustFS repository](https://github.com/rustfs/rustfs).
## ✨ 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`:
```toml
[dependencies]
rustfs-crypto = "0.1.0"
```
### Feature Flags
```toml
[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
```rust
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
```rust
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
```rust
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:
```bash
# 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:
- [RustFS Main](https://github.com/rustfs/rustfs) - Core distributed storage system
- [RustFS ECStore](../ecstore) - Erasure coding storage engine
- [RustFS IAM](../iam) - Identity and access management
- [RustFS Policy](../policy) - Policy engine
- AES-GCM encryption with hardware acceleration
- RSA and ECDSA digital signature support
- Secure hash functions (SHA-256, BLAKE3)
- Key derivation and management utilities
- Stream ciphers for large data encryption
- Hardware security module integration
## 📚 Documentation
For comprehensive documentation, visit:
- [RustFS Documentation](https://docs.rustfs.com)
- [API Reference](https://docs.rustfs.com/crypto/)
- [Security Guide](https://docs.rustfs.com/security/)
## 🔗 Links
- [Documentation](https://docs.rustfs.com) - Complete RustFS manual
- [Changelog](https://github.com/rustfs/rustfs/releases) - Release notes and updates
- [GitHub Discussions](https://github.com/rustfs/rustfs/discussions) - Community support
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](https://github.com/rustfs/rustfs/blob/main/CONTRIBUTING.md) 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
```bash
# 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
- **Documentation**: [docs.rustfs.com](https://docs.rustfs.com)
- **Issues**: [GitHub Issues](https://github.com/rustfs/rustfs/issues)
- **Discussions**: [GitHub Discussions](https://github.com/rustfs/rustfs/discussions)
- **Security**: Report security issues to <security@rustfs.com>
## 📞 Contact
- **Bugs**: [GitHub Issues](https://github.com/rustfs/rustfs/issues)
- **Business**: <hello@rustfs.com>
- **Jobs**: <jobs@rustfs.com>
- **General Discussion**: [GitHub Discussions](https://github.com/rustfs/rustfs/discussions)
## 👥 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.
<a href="https://github.com/rustfs/rustfs/graphs/contributors">
<img src="https://contrib.rocks/image?repo=rustfs/rustfs" />
</a>
For comprehensive documentation, examples, and usage guides, please visit the main [RustFS repository](https://github.com/rustfs/rustfs).
## 📄 License
Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/rustfs/rustfs/blob/main/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.
```
---
<p align="center">
<strong>RustFS</strong> is a trademark of RustFS, Inc.<br>
All other trademarks are the property of their respective owners.
</p>
<p align="center">
Made with ❤️ by the RustFS Team
</p>
This project is licensed under the Apache License 2.0 - see the [LICENSE](../../LICENSE) file for details.