4

Server Side Encryption SSE KMS

Chris Lu edited this page 2026-01-29 22:49:54 -08:00

Table of Contents

• SSE-KMS: Server-Side Encryption with Key Management Service
• Supported KMS Providers
• Quick Start Guide
• 1. Configure SeaweedFS
• 2. Start S3 with KMS Config
• 3. Test the Integration
• AWS KMS Integration
• Step 1: Create KMS Key
• Step 2: Configure SeaweedFS
• Step 3: Test AWS KMS
• Google Cloud KMS Integration
• Step 1: Create KMS Resources
• Step 2: Configure SeaweedFS
• OpenBao/Vault Integration
• Step 1: Setup OpenBao/Vault
• Step 2: Configure SeaweedFS
• Step 3: Test OpenBao/Vault
• Azure Key Vault Integration (Experimental)
• Multi-Provider Configuration
• Provider Selection Strategies
• Security Best Practices
• 1. Key Management
• 2. Access Control
• Related Documentation

SSE-KMS: Server-Side Encryption with Key Management Service

SeaweedFS works with your existing Key Management Service (KMS) so you can keep keys where they belong. This guide walks you through AWS KMS, Google Cloud KMS, and OpenBao/Vault. Azure Key Vault is also available as experimental (build tag azurekms).

Supported KMS Providers

Provider	Status	Use Cases
AWS KMS	Full support	AWS-centric deployments
Google Cloud KMS	Full support	GCP-centric deployments
OpenBao/Vault	Full support	Hybrid/on-premises environments
Azure Key Vault	Experimental (build tag azurekms)	Azure-centric deployments

Quick Start Guide

1. Configure SeaweedFS

Tell SeaweedFS about your KMS in the S3 config JSON file:

{
  "identities": [
    {
      "name": "admin",
      "credentials": [{"accessKey": "admin", "secretKey": "password"}],
      "actions": ["Admin", "Read", "Write"]
    }
  ],
  "kms": {
    "default_provider": "openbao",
    "providers": {
      "openbao": {
        "type": "openbao",
        "address": "http://localhost:8200",
        "token": "root-token",
        "transit_path": "transit",
        "cache_enabled": true,
        "cache_ttl": "1h"
      }
    }
  }
}

2. Start S3 with KMS Config

# Start S3 API with KMS and IAM configuration
weed s3 -config=s3_kms_config.json -port=8333

Note: The S3 config JSON file contains both KMS provider settings AND IAM-style access control (identities, credentials, permissions).

3. Test the Integration

# Ensure $S3_ENDPOINT is set
export S3_ENDPOINT=http://localhost:8333

# Upload object with SSE-KMS
aws --endpoint-url $S3_ENDPOINT s3 cp test-file.txt s3://mybucket/test-file.txt \
  --server-side-encryption aws:kms \
  --ssekms-key-id alias/my-key

---

AWS KMS Integration

Step 1: Create KMS Key

# Create customer-managed KMS key
aws kms create-key --description "SeaweedFS encryption key"

# Create key alias
aws kms create-alias \
  --alias-name alias/seaweedfs-key \
  --target-key-id <key-id-from-above>

Step 2: Configure SeaweedFS

{
  "identities": [
    {
      "name": "admin",
      "credentials": [{"accessKey": "admin", "secretKey": "password"}],
      "actions": ["Admin", "Read", "Write"]
    }
  ],
  "kms": {
    "default_provider": "aws-kms",
    "providers": {
      "aws-kms": {
        "type": "aws-kms",
        "region": "us-east-1",
        "key_id": "alias/seaweedfs-key"
      }
    }
  }
}

Step 3: Test AWS KMS

# Upload with AWS KMS encryption
aws --endpoint-url $S3_ENDPOINT s3 cp file.txt s3://mybucket/file.txt \
  --server-side-encryption aws:kms \
  --ssekms-key-id alias/seaweedfs-key

---

Google Cloud KMS Integration

Step 1: Create KMS Resources

# Create key ring
gcloud kms keyrings create seaweedfs-keyring --location us-east1

# Create encryption key
gcloud kms keys create seaweedfs-key \
  --keyring seaweedfs-keyring \
  --location us-east1 \
  --purpose encryption

Step 2: Configure SeaweedFS

{
  "identities": [
    {
      "name": "admin",
      "credentials": [{"accessKey": "admin", "secretKey": "password"}],
      "actions": ["Admin", "Read", "Write"]
    }
  ],
  "kms": {
    "default_provider": "gcp-kms",
    "providers": {
      "gcp-kms": {
        "type": "gcp-kms",
        "project_id": "my-project-id",
        "location": "us-east1", 
        "key_ring": "seaweedfs-keyring",
        "key_name": "seaweedfs-key",
        "credentials_file": "/etc/seaweedfs/gcp-kms-key.json"
      }
    }
  }
}

---

OpenBao/Vault Integration

Step 1: Setup OpenBao/Vault

# Start OpenBao in dev mode (for testing)
openbao server -dev -dev-root-token-id="root-token"

# Enable transit secrets engine
openbao secrets enable transit

# Create encryption key
openbao write -f transit/keys/seaweedfs-key

Step 2: Configure SeaweedFS

{
  "identities": [
    {
      "name": "admin",
      "credentials": [{"accessKey": "admin", "secretKey": "password"}],
      "actions": ["Admin", "Read", "Write"]
    }
  ],
  "kms": {
    "default_provider": "openbao",
    "providers": {
      "openbao": {
        "type": "openbao",
        "address": "http://localhost:8200",
        "token": "root-token",
        "transit_path": "transit",
        "cache_enabled": true,
        "cache_ttl": "1h"
      }
    }
  }
}

Step 3: Test OpenBao/Vault

# Upload with Vault encryption
aws --endpoint-url $S3_ENDPOINT s3 cp file.txt s3://mybucket/file.txt \
  --server-side-encryption aws:kms \
  --ssekms-key-id seaweedfs-key

---

Azure Key Vault Integration (Experimental)

Azure Key Vault support exists behind the build tag azurekms and is considered experimental. To enable it, build SeaweedFS with the tag and configure the provider:

# Build with Azure KMS support (example)
go build -tags azurekms ./weed

{
  "kms": {
    "providers": {
      "azure": {
        "type": "azure",
        "vault_url": "https://<your-vault>.vault.azure.net/",
        "tenant_id": "<tenant>",
        "client_id": "<client>",
        "client_secret": "<secret>",
        "use_default_creds": false
      }
    }
  }
}

---

Multi-Provider Configuration

Provider Selection Strategies

{
  "identities": [...],
  "kms": {
    "default_provider": "openbao",
    "providers": {
      "openbao": {
        "type": "openbao",
        "address": "https://vault.internal:8200",
        "token": "root-token",
        "transit_path": "transit"
      },
      "aws-kms": {
        "type": "aws-kms",
        "region": "us-east-1",
        "key_id": "alias/seaweedfs-aws"
      },
      "gcp-kms": {
        "type": "gcp-kms",
        "project_id": "my-gcp-project",
        "location": "global",
        "key_ring": "seaweedfs-keyring",
        "key_name": "seaweedfs-gcp-key",
        "credentials_file": "/etc/seaweedfs/gcp-key.json"
      }
    },
    "buckets": {
      "financial-data": {"provider": "openbao"},
      "ml-models": {"provider": "gcp-kms"},
      "general-storage": {"provider": "aws-kms"}
    }
  }
}

Security Best Practices

1. Key Management

• Grant minimal required KMS permissions
• Use resource-based policies where possible
• Implement proper key rotation policies
• Document key usage and ownership

2. Access Control

{
  "identities": [
    {
      "name": "admin",
      "credentials": [{"accessKey": "admin", "secretKey": "password"}],
      "actions": ["Admin", "Read", "Write"]
    },
    {
      "name": "readonly",
      "credentials": [{"accessKey": "readonly", "secretKey": "password"}], 
      "actions": ["Read"]
    }
  ]
}

Related Documentation

• Server-Side Encryption: Overview of all SSE types
• SSE-C Guide: Customer-provided keys
• Amazon S3 API: Main S3 API documentation

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