2

Cryptography and FIPS Compliance

Chris Lu edited this page 2026-01-29 19:24:42 -08:00

Table of Contents

• Cryptography and FIPS Compliance
• Overview
• Cryptographic Algorithms Used
• Data Encryption (At Rest)
• Authentication & Signatures
• Transport Encryption (In Transit)
• FIPS 140-3 Compliance
• Algorithm Compliance
• FIPS 140-3 Mode
• Recommended Configuration for FIPS Environments
• Cryptographic Implementation Details
• Random Number Generation
• Key Storage
• Security Best Practices
• Related Documentation

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
OIDC Tokens	RSA, ECDSA	For OIDC identity provider integration
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
OIDC Validation	RSA, ECDSA	✅ 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.

# 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:

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:

   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:

   # 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 Configuration
• Server-Side Encryption
• Filer Data Encryption

Introduction

• Quick Start with weed mini
• Components
• Getting Started
• Production Setup
• Benchmarks
• FAQ
• Applications

API

• Master Server API
• Volume Server API
• Filer Server API
• Client Libraries
• SeaweedFS Java Client

Configuration

• Replication
• Store file with a Time To Live
• Failover Master Server
• Erasure coding for warm storage
• Server Startup via Systemd
• Environment Variables

Filer

• Filer Setup
• Directories and Files
• File Operations Quick Reference
• Data Structure for Large Files
• Filer Data Encryption
• Filer Commands and Operations
• Filer JWT Use
• TUS Resumable Uploads

Filer Stores

• Filer Cassandra Setup
• Filer Redis Setup
• Super Large Directories
• Path-Specific Filer Store
• Choosing a Filer Store
• Customize Filer Store

Management

• Admin UI
• Worker

Advanced Filer Configurations

• Migrate to Filer Store
• Add New Filer Store
• Filer Store Replication
• Filer Active Active cross cluster continuous synchronization
• Filer as a Key-Large-Value Store
• Path Specific Configuration
• Filer Change Data Capture

FUSE Mount

• FIO benchmark
• fstab

WebDAV

Cloud Drive

• Cloud Drive Benefits
• Cloud Drive Architecture
• Configure Remote Storage
• Mount Remote Storage
• Cache Remote Storage
• Cloud Drive Quick Setup
• Gateway to Remote Object Storage

AWS S3 API

• Amazon S3 API
• S3 Conditional Operations
• S3 CORS
• S3 Object Lock and Retention
• S3 Object Versioning
• S3 API Benchmark
• S3 API FAQ
• S3 Bucket Quota
• S3 Rate Limiting
• S3 API Audit log
• S3 Nginx Proxy
• Docker Compose for S3

S3 Table Bucket

• S3 Table Bucket

S3 Authentication & IAM

• S3 Configuration - Start Here
• S3 Credentials (-s3.config)
• OIDC Integration (-s3.iam.config)
• S3 Policy Variables
• Amazon IAM API
• AWS IAM CLI

Server-Side Encryption

• Server-Side Encryption
• Server-Side Encryption SSE-KMS
• Server-Side Encryption SSE-C

S3 Client Tools

• AWS CLI with SeaweedFS
• s3cmd with SeaweedFS
• rclone with SeaweedFS
• restic with SeaweedFS
• nodejs with Seaweed S3

Machine Learning

• TensorFlow with SeaweedFS

HDFS

• Hadoop Compatible File System
• run Spark on SeaweedFS
• run HBase on SeaweedFS
• run Presto on SeaweedFS
• Hadoop Benchmark
• HDFS via S3 connector

Replication and Backup

• Async Replication to another Filer [Deprecated]
• Async Backup
• Async Filer Metadata Backup
• Async Replication to Cloud [Deprecated]
• Kubernetes Backups and Recovery with K8up

Metadata Change Events

• Filer Metadata Events
• Filer Notification Webhook

Messaging

• Structured Data Lake with SMQ and SQL
• Seaweed Message Queue
• SQL Queries on Message Queue
• SQL Quick Reference
• PostgreSQL-compatible Server weed db
• Pub-Sub to SMQ to SQL
• Kafka to Kafka Gateway to SMQ to SQL

Use Cases

• Use Cases
• Actual Users

Operations

• System Metrics
• weed shell
• Data Backup
• Deployment to Kubernetes and Minikube

Advanced

• Large File Handling
• Optimization
• Volume Management
• Tiered Storage
• Cloud Tier
• Cloud Monitoring
• Load Command Line Options from a file
• SRV Service Discovery
• Volume Files Structure

Security

• Security Overview
• Security Configuration
• Cryptography and FIPS Compliance
• Run Blob Storage on Public Internet

Misc Use Case Examples

• UrBackup with SeaweedFS
• Docker Image Registry with SeaweedFS
• SeaweedFS in Docker Swarm
• Words from SeaweedFS Users
• Independent Benchmarks
• Hardware