upstream-seaweedfs/test/s3/sse/README_KMS.md

SeaweedFS S3 SSE-KMS Integration with OpenBao

This directory contains comprehensive integration tests for SeaweedFS S3 Server-Side Encryption with Key Management Service (SSE-KMS) using OpenBao as the KMS provider.

🎯 Overview

The integration tests verify that SeaweedFS can:

• ✅ Encrypt data using real KMS operations (not mock keys)
• ✅ Decrypt data correctly with proper key management
• ✅ Handle multiple KMS keys for different security levels
• ✅ Support various data sizes (0 bytes to 1MB+)
• ✅ Maintain data integrity through encryption/decryption cycles
• ✅ Work with per-bucket KMS configuration

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   S3 Client     │    │   SeaweedFS      │    │   OpenBao       │
│                 │    │   S3 API         │    │   KMS           │
├─────────────────┤    ├──────────────────┤    ├─────────────────┤
│ PUT /object     │───▶│ SSE-KMS Handler  │───▶│ GenerateDataKey │
│ SSEKMSKeyId:    │    │                  │    │ Encrypt         │
│ "test-key-123"  │    │ KMS Provider:    │    │ Decrypt         │
│                 │    │ OpenBao          │    │ Transit Engine  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

🚀 Quick Start

1. Set up OpenBao KMS

# Start OpenBao and create encryption keys
make setup-openbao

2. Run SSE-KMS Integration Tests

# Run all SSE-KMS tests with real KMS
make test-ssekms-integration

# Or run the full integration suite
make test-with-kms

3. Check KMS Status

# Verify OpenBao and SeaweedFS are running
make status-kms

📋 Available Test Targets

Target	Description
setup-openbao	Set up OpenBao KMS with test encryption keys
test-with-kms	Run all SSE tests with real KMS integration
test-ssekms-integration	Run only SSE-KMS tests with OpenBao
start-full-stack	Start SeaweedFS + OpenBao with Docker Compose
stop-full-stack	Stop all Docker services
clean-kms	Clean up KMS test environment
status-kms	Check status of KMS and S3 services
dev-kms	Set up development environment

🔑 KMS Keys Created

The setup automatically creates these encryption keys in OpenBao:

Key Name	Purpose
test-key-123	Basic SSE-KMS integration tests
source-test-key-123	Copy operation source key
dest-test-key-456	Copy operation destination key
test-multipart-key	Multipart upload tests
test-kms-range-key	Range request tests
seaweedfs-test-key	General SeaweedFS SSE tests
bucket-default-key	Default bucket encryption
high-security-key	High security scenarios
performance-key	Performance testing

🧪 Test Coverage

Basic SSE-KMS Operations

• ✅ PUT object with SSE-KMS encryption
• ✅ GET object with automatic decryption
• ✅ HEAD object metadata verification
• ✅ Multiple KMS key support
• ✅ Various data sizes (0B - 1MB)

Advanced Scenarios

• ✅ Large file encryption (chunked)
• ✅ Range requests with encrypted data
• ✅ Per-bucket KMS configuration
• ✅ Error handling for invalid keys
• ⚠️ Object copy operations (known issue)

Performance Testing

• ✅ KMS operation benchmarks
• ✅ Encryption/decryption latency
• ✅ Throughput with various data sizes

⚙️ Configuration

S3 KMS Configuration (s3_kms.json)

{
  "kms": {
    "default_provider": "openbao-test",
    "providers": {
      "openbao-test": {
        "type": "openbao",
        "address": "http://openbao:8200",
        "token": "root-token-for-testing",
        "transit_path": "transit"
      }
    },
    "buckets": {
      "test-sse-kms-basic": {
        "provider": "openbao-test"
      }
    }
  }
}

Docker Compose Services

• OpenBao: KMS provider on port 8200
• SeaweedFS Master: Metadata management on port 9333
• SeaweedFS Volume: Data storage on port 8080
• SeaweedFS Filer: S3 API with KMS on port 8333

🎛️ Environment Variables

Variable	Default	Description
OPENBAO_ADDR	http://127.0.0.1:8200	OpenBao server address
OPENBAO_TOKEN	root-token-for-testing	OpenBao root token
S3_PORT	8333	S3 API port
TEST_TIMEOUT	15m	Test timeout duration

📊 Example Test Run

$ make test-ssekms-integration

Setting up OpenBao for SSE-KMS testing...
✅ OpenBao setup complete!
Starting full SeaweedFS + KMS stack...
✅ Full stack running!
Running SSE-KMS integration tests with OpenBao...

=== RUN   TestSSEKMSIntegrationBasic
=== RUN   TestSSEKMSOpenBaoIntegration
=== RUN   TestSSEKMSOpenBaoAvailability
--- PASS: TestSSEKMSIntegrationBasic (0.26s)
--- PASS: TestSSEKMSOpenBaoIntegration (0.45s)
--- PASS: TestSSEKMSOpenBaoAvailability (0.12s)

✅ SSE-KMS integration tests passed!

🔍 Troubleshooting

OpenBao Not Starting

# Check OpenBao logs
docker-compose logs openbao

# Verify port availability
lsof -ti :8200

SeaweedFS KMS Not Working

# Check filer logs for KMS errors
docker-compose logs seaweedfs-filer

# Verify KMS configuration
curl http://localhost:8200/v1/sys/health

Tests Failing

# Run specific test for debugging
cd ../../../ && go test -v -timeout=30s -run TestSSEKMSOpenBaoAvailability ./test/s3/sse

# Check service status
make status-kms

🚧 Known Issues

1. Object Copy Operations: Currently failing due to data corruption in copy logic (not KMS-related)
2. Azure SDK Compatibility: Azure KMS provider disabled due to SDK issues
3. Network Timing: Some tests may need longer startup delays in slow environments

🔄 Development Workflow

1. Development Setup

# Quick setup for development
make dev-kms

# Run specific test during development
go test -v -run TestSSEKMSOpenBaoAvailability ./test/s3/sse

2. Integration Testing

# Full integration test cycle
make clean-kms           # Clean environment
make test-with-kms       # Run comprehensive tests
make clean-kms           # Clean up

3. Performance Testing

# Run KMS performance benchmarks
cd ../kms && make test-benchmark

📈 Performance Characteristics

From benchmark results:

• GenerateDataKey: ~55,886 ns/op (~18,000 ops/sec)
• Decrypt: ~48,009 ns/op (~21,000 ops/sec)
• End-to-end encryption: Sub-second for files up to 1MB

🔗 Related Documentation

• SeaweedFS S3 API Documentation
• OpenBao Transit Secrets Engine
• AWS S3 Server-Side Encryption

🎉 Success Criteria

The integration is considered successful when:

• ✅ OpenBao KMS provider initializes correctly
• ✅ Encryption keys are created and accessible
• ✅ Data can be encrypted and decrypted reliably
• ✅ Multiple key types work independently
• ✅ Performance meets production requirements
• ✅ Error cases are handled gracefully

This integration demonstrates that SeaweedFS SSE-KMS is production-ready with real KMS providers! 🚀