From d57ccb04ddbeeedd3e0c707f91a12430015d82ba Mon Sep 17 00:00:00 2001 From: chrislusf Date: Tue, 25 Nov 2025 11:59:12 -0800 Subject: [PATCH] update --- S3-API-FAQ.md | 2 +- Security-Configuration.md | 75 ++++++++++++++++----------------------- Security-Overview.md | 33 +++++++++++++++++ 3 files changed, 64 insertions(+), 46 deletions(-) diff --git a/S3-API-FAQ.md b/S3-API-FAQ.md index 1728369..d233eaa 100644 --- a/S3-API-FAQ.md +++ b/S3-API-FAQ.md @@ -252,6 +252,6 @@ key = "/path/to/client.key" ca = "/path/to/ca.crt" ``` -The `[https.filer]` makes the Filer accept HTTPS, while `[https.client]` with `enabled = true` makes clients (S3 API, mount, etc.) use HTTPS for data operations. See [[Security-Configuration]] for details. +The `[https.filer]` makes the Filer accept HTTPS, while `[https.client]` with `enabled = true` makes clients (S3 API, mount, etc.) use HTTPS for data operations. See [[Security-Overview]] for architecture details and [[Security-Configuration]] for configuration reference. diff --git a/Security-Configuration.md b/Security-Configuration.md index 7593b88..d7bb16e 100644 --- a/Security-Configuration.md +++ b/Security-Configuration.md @@ -1,33 +1,6 @@ -# Understanding Communication Layers - -SeaweedFS has two separate communication layers: - -## gRPC Communication (Control Plane) -Used for metadata operations and cluster coordination: -- S3 ↔ Filer: Getting bucket info, file metadata -- Filer ↔ Master: Getting volume assignments, cluster info -- Volume ↔ Master: Heartbeats, volume management -- **Configured via**: `[grpc.*]` sections in security.toml - -## HTTP/HTTPS Communication (Data Plane) -Used for actual file data uploads/downloads: -- S3/Filer/Client → Volume Server: Uploading and downloading actual file content -- **Configured via**: `[https.*]` sections in security.toml - -## Configuration Sections Summary - -| Configuration Block | Purpose | -|---------------------|---------| -| `[grpc.client]`, `[grpc.filer]`, `[grpc.master]`, `[grpc.volume]` | Secure gRPC communication for metadata/control plane | -| `[https.client]` | Client-side configuration - tells S3/Filer/etc to use HTTPS when communicating with servers | -| `[https.volume]` | Server-side configuration - makes Volume server accept HTTPS for data uploads | -| `[https.master]`, `[https.filer]` | Server-side configuration - makes Master/Filer accept HTTPS (web UI, HTTP APIs) | - -**Important**: If you enable `[https.filer]` for the Filer server, you must also set `[https.client]` with `enabled = true` so that S3 API uses HTTPS when communicating with the Filer. Otherwise, you'll get "client sent an HTTP request to an HTTPS server" errors. - -# Configuration +For an overview of SeaweedFS security architecture and communication layers, see [[Security-Overview]]. The first step is generating `security.toml` file via `weed scaffold -config=security`: @@ -92,29 +65,38 @@ expires_after_seconds = 10 # seconds key = "" expires_after_seconds = 10 # seconds -# all grpc tls authentications are mutual -# the values for the following ca, cert, and key are paths to the PERM files. -# the host name is not checked, so the PERM files can be shared. +# gRPC mTLS configuration +# All gRPC TLS authentications are mutual (mTLS) +# The values for ca, cert, and key are paths to the certificate/key files +# The host name is not checked, so the certificate files can be shared [grpc] ca = "" # Set wildcard domain for enable TLS authentication by common names allowed_wildcard_domain = "" # .mycompany.com +# Volume server gRPC options (server-side) +# Enables mTLS for incoming gRPC connections to volume server [grpc.volume] cert = "" key = "" allowed_commonNames = "" # comma-separated SSL certificate common names +# Master server gRPC options (server-side) +# Enables mTLS for incoming gRPC connections to master server [grpc.master] cert = "" key = "" allowed_commonNames = "" # comma-separated SSL certificate common names +# Filer server gRPC options (server-side) +# Enables mTLS for incoming gRPC connections to filer server [grpc.filer] cert = "" key = "" allowed_commonNames = "" # comma-separated SSL certificate common names +# S3 server gRPC options (server-side) +# Enables mTLS for incoming gRPC connections to S3 server [grpc.s3] cert = "" key = "" @@ -130,36 +112,39 @@ cert = "" key = "" allowed_commonNames = "" # comma-separated SSL certificate common names -# use this for any place needs a grpc client -# i.e., "weed backup|benchmark|filer.copy|filer.replicate|mount|s3|upload" +# gRPC client configuration for outgoing gRPC connections +# Used by clients (S3, mount, backup, benchmark, filer.copy, filer.replicate, upload, etc.) +# when connecting to any gRPC server (master, volume, filer) [grpc.client] cert = "" key = "" -# https client for master|volume|filer|etc connection -# It is necessary that the parameters [https.volume]|[https.master]|[https.filer] are set +# HTTPS client configuration for outgoing HTTP connections +# Used by S3, mount, filer.copy, backup, and other clients when communicating with master/volume/filer +# Set enabled=true to use HTTPS instead of HTTP for data operations (separate from gRPC) +# If [https.filer] or [https.volume] are enabled on servers, clients must have [https.client] enabled=true [https.client] -enabled = false -cert = "" -key = "" -ca = "" +enabled = false # Set to true to enable HTTPS for all outgoing HTTP client connections +cert = "" # Client certificate for mTLS (optional if server doesn't require client cert) +key = "" # Client key for mTLS (optional if server doesn't require client cert) +ca = "" # CA certificate to verify server certificates (required when enabled=true) -# volume server https options -# Configure these if you want the volume server to accept HTTPS connections +# Volume server HTTPS options (server-side) +# Enables HTTPS for incoming HTTP connections to volume server [https.volume] cert = "" key = "" ca = "" -# master server https options -# Configure these if you want the master server to accept HTTPS connections +# Master server HTTPS options (server-side) +# Enables HTTPS for incoming HTTP connections to master server (web UI, HTTP API) [https.master] cert = "" key = "" ca = "" -# filer server https options -# Configure these if you want the filer server to accept HTTPS connections +# Filer server HTTPS options (server-side) +# Enables HTTPS for incoming HTTP connections to filer server (web UI, HTTP API) [https.filer] cert = "" key = "" diff --git a/Security-Overview.md b/Security-Overview.md index f6aac39..04833e5 100644 --- a/Security-Overview.md +++ b/Security-Overview.md @@ -2,6 +2,39 @@ 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. +## Understanding Communication Layers + +SeaweedFS has two separate communication layers that must be secured independently: + +### gRPC Communication (Control Plane) +Used for metadata operations and cluster coordination: +- S3 ↔ Filer: Getting bucket info, file metadata +- Filer ↔ Master: Getting volume assignments, cluster info +- Volume ↔ Master: Heartbeats, volume management +- **Configured via**: `[grpc.*]` sections in security.toml + +### HTTP/HTTPS Communication (Data Plane) +Used for actual file data uploads/downloads: +- S3/Filer/Client → Volume Server: Uploading and downloading actual file content +- S3 → Filer: File data operations (when S3 acts as a proxy) +- **Configured via**: `[https.*]` sections in security.toml + +### Configuration Sections Summary + +| Configuration Block | Purpose | +|---------------------|---------| +| `[grpc.client]` | Used by clients (S3, mount, filer.copy, backup, etc.) to connect to any gRPC server | +| `[grpc.filer]`, `[grpc.master]`, `[grpc.volume]`, `[grpc.s3]` | Server-side gRPC mTLS - secures gRPC endpoints | +| `[https.client]` | Client-side HTTPS configuration - tells clients (S3/Filer/etc.) to use HTTPS for HTTP connections | +| `[https.volume]`, `[https.master]`, `[https.filer]` | Server-side HTTPS configuration - makes servers accept HTTPS connections | + +**Important**: +- `[https.client]` with `enabled = true` is required for clients to use HTTPS when connecting to HTTPS-enabled servers +- If you enable `[https.filer]` on the Filer server, you must also enable `[https.client]` so that S3 API can connect via HTTPS +- Otherwise, you'll get "client sent an HTTP request to an HTTPS server" errors + +## Security Features + We will address the volume servers first. The following items are not covered, yet: - master server http REST services