diff --git a/Cryptography-and-FIPS-Compliance.md b/Cryptography-and-FIPS-Compliance.md new file mode 100644 index 0000000..4352e54 --- /dev/null +++ b/Cryptography-and-FIPS-Compliance.md @@ -0,0 +1,139 @@ +# Cryptography and FIPS Compliance + +This document describes the cryptographic algorithms used in SeaweedFS and provides guidance for FIPS 140-3 compliance. + +## Overview + +SeaweedFS uses Go's standard library cryptographic packages (`crypto/*`) for all encryption operations. All algorithms used are **FIPS-approved algorithms**. Starting with Go 1.24, native FIPS 140-3 mode can be enabled at runtime. + +## Cryptographic Algorithms Used + +### Data Encryption (At Rest) + +| Feature | Algorithm | Key Size | Notes | +|---------|-----------|----------|-------| +| Filer Data Encryption | AES-256-GCM | 256-bit | Per-file random keys stored in filer metadata | +| SSE-C (Customer Keys) | AES-256-CTR | 256-bit | Customer-provided keys, never stored | +| SSE-S3 (Managed Keys) | AES-256-GCM | 256-bit | SeaweedFS-managed keys | +| SSE-KMS | AES-256-GCM | 256-bit | External KMS-managed data encryption keys | + +### Authentication & Signatures + +| Feature | Algorithm | Notes | +|---------|-----------|-------| +| S3 Signature V4 | HMAC-SHA256 | AWS-compatible request signing | +| S3 Signature V2 | HMAC-SHA1 | Legacy AWS signature support | +| JWT Tokens | HMAC-SHA256 | For volume server and filer access control | +| SSE-C Key Validation | MD5 | For key integrity verification (AWS S3 compatible) | + +### Transport Encryption (In Transit) + +| Feature | Protocol | Configuration | +|---------|----------|---------------| +| gRPC (Control Plane) | TLS 1.2/1.3 | mTLS with configurable cipher suites | +| HTTP (Data Plane) | HTTPS (TLS 1.2/1.3) | Certificate-based with configurable versions | + +## FIPS 140-3 Compliance + +### Algorithm Compliance + +All cryptographic algorithms used by SeaweedFS are **FIPS-approved**: + +| SeaweedFS Feature | Algorithm | FIPS 140-3 Status | +|-------------------|-----------|-------------------| +| Data Encryption | AES-256-GCM | ✅ Approved | +| SSE-C Encryption | AES-256-CTR | ✅ Approved | +| S3 Signatures | HMAC-SHA256 | ✅ Approved | +| Hashing | SHA-256 | ✅ Approved | +| Transport | TLS 1.2/1.3 | ✅ Approved | +| Legacy S3 Signatures | HMAC-SHA1 | ⚠️ Approved (use V4 preferred) | +| SSE-C Key Validation | MD5 | ⚠️ Used for AWS S3 compatibility only | + +### FIPS 140-3 Mode + +**FIPS 140-3 mode is enabled by default** in Docker containers. SeaweedFS requires Go 1.24+, which has native FIPS 140-3 support. + +```bash +# FIPS is enabled by default in Docker +docker run chrislusf/seaweedfs server ... + +# To disable FIPS mode +docker run -e GODEBUG=fips140=off chrislusf/seaweedfs server ... + +# For non-Docker: enable FIPS mode +GODEBUG=fips140=on ./weed server ... + +# Strict FIPS mode (non-approved functions will error/panic) +GODEBUG=fips140=only ./weed server ... +``` + +You can verify FIPS mode is enabled programmatically: + +```go +import "crypto/fips140" + +if fips140.Enabled() { + fmt.Println("FIPS 140-3 mode is enabled") +} +``` + +## Recommended Configuration for FIPS Environments + +1. **Enable FIPS mode** at runtime: + ```bash + GODEBUG=fips140=on ./weed server ... + ``` + +2. **Use S3 Signature V4** (not V2) to avoid SHA1: + - All modern S3 clients use V4 by default + +3. **Enable TLS 1.2 or higher** with FIPS-approved cipher suites: + ```toml + # In security.toml + [tls] + min_version = "TLS 1.2" + cipher_suites = "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" + ``` + +4. **Use SSE-KMS or SSE-S3** for encryption: + - Both use AES-256-GCM which is FIPS approved + - SSE-C also uses FIPS-approved algorithms but relies on MD5 for key validation (AWS S3 compatibility requirement) + +## Cryptographic Implementation Details + +### Random Number Generation + +SeaweedFS uses `crypto/rand` for all cryptographic random number generation: + +- Cipher key generation +- Nonce/IV generation +- Upload ID generation +- Version ID generation + +### Key Storage + +| Key Type | Storage Location | Protection | +|----------|-----------------|------------| +| Filer encryption keys | Filer metadata store | Per-file, randomly generated | +| SSE-C keys | Never stored | Customer-provided per request | +| SSE-S3 keys | In-memory or KMS | Managed by SeaweedFS or external KMS | +| SSE-KMS keys | External KMS | AWS KMS, Google Cloud KMS, OpenBao/Vault, Azure Key Vault | +| TLS certificates | File system | User-managed | +| JWT signing keys | security.toml | User-configured | + +## Security Best Practices + +1. **Enable FIPS mode** with `GODEBUG=fips140=on` in regulated environments +2. **Enable mTLS** for all gRPC communications +3. **Use HTTPS** for all HTTP endpoints in production +4. **Configure JWT signing** for volume server access control +5. **Use external KMS** (SSE-KMS) for enterprise key management with audit trails +6. **Regularly rotate** TLS certificates and JWT signing keys +7. **Restrict cipher suites** to FIPS-approved algorithms + +## Related Documentation + +- [Security Overview](Security-Overview.md) +- [Security Configuration](Security-Configuration.md) +- [Server-Side Encryption](Server-Side-Encryption.md) +- [Filer Data Encryption](Filer-Data-Encryption.md) diff --git a/Security-Overview.md b/Security-Overview.md index 04833e5..984b68c 100644 --- a/Security-Overview.md +++ b/Security-Overview.md @@ -1,6 +1,8 @@ # Overview -Since SeaweedFS is a distributed system with many volume servers, the volume servers have the risk of being changed without proper access control. We want to have the freedom to place a volume server anywhere we want, with the confidence that nobody can tamper the data. +Since SeaweedFS is a distributed system with many volume servers, the volume servers have the risk of being changed without proper access control. We want to have the freedom to place a volume server anywhere we want, with the confidence that nobody can tamper the data. + +> **Looking for FIPS 140-2/140-3 compliance information?** See [[Cryptography and FIPS Compliance]]. ## Understanding Communication Layers diff --git a/_Sidebar.md b/_Sidebar.md index 22b1a79..d6202f3 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -149,6 +149,7 @@ ### Security * [[Security Overview]] * [[Security Configuration]] +* [[Cryptography and FIPS Compliance]] * [[Run Blob Storage on Public Internet]] ### Misc Use Case Examples