diff --git a/Security-Overview.md b/Security-Overview.md index fe4dc7c..9fc9787 100644 --- a/Security-Overview.md +++ b/Security-Overview.md @@ -1,19 +1,48 @@ # Overview -There are a few things to secure the SeaweedFS system: -1. Secure GRPC operations server via mutual TLS -1. Secure file upload/delete to volume server -Not covered, yet: -1. master server http access -1. filer server http access +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. + +We will address the volume servers first. The following items are not covered, yet: +1. master server http REST services +1. filer server http REST services + +Servers in SeaweedFS usually support 2 kinds of operations: gRPC and REST. + +# Securing gRPC operations + +The following operations are implemented via gRPC. +* requests from filer to master +* requests from master to volume servers +* delete operations from filer or other clients (mount, s3, filer.copy, filer.replicate, etc) to volume servers +* requests from clients to filer + +All gRPC operations can optionally be secured via mutual TLS, by customizing the `weed scaffold -config=security` generated `security.toml` file. # Securing Volume Servers -Since SeaweedFS is a distributed system with many volume servers, the volume servers have the risk of being changed without proper access control. There are 2 ways to change volume servers: -1. Administrative operations via GRPC +1. Administrative operations via gRPC 1. File upload, update, and delete operations. To control administrative operations, mutual TLS can be enabled for all GRPC calls. -To control file upload/update/delete operations, Json Web Token (JWT) is used to control access for each file id. +To control file upload/update/delete operations, Json Web Token (JWT) is used to authorize access for each file id. + +## JWT-based access control +To enable JWT-based access control, +1. generate `security.toml` file by `weed scaffold -config=security` +1. set `jwt.signing.key` to a secrete string +1. copy the same `security.toml` file to the masters and all volume servers. + +## How JWT-based access control works +* To upload a new file, when requesting a new fileId via `http://:/dir/assign`, the master will use the `jwt.signing.key` to generate and sign a JWT, and set it to response header `Authorization`. The JWT is valid for 10 seconds. +* To update or delete a file by fileId, the JWT can be read from the response header `Authorization` of `http://:/dir/lookup?fileId=xxxxx`. +* When sending upload/update/delete HTTP operations the volume server, the same header `Authorization` should be set to the request header. If the volume server checks the JWT is valid via the `jwt.signing.key`, the operation can be executed as usual. + +JWT Summary: +* JWT is set in `/dir/assign` or `/dir/lookup` response header `Authorization` +* JWT is read from request header `Authorization` +* JWT is valid for 10 seconds. +* JWT only has permission to create/modify/delete one fileId. +* The volume server HTTP access is only for read if the fileId is known. +* All other volume server HTTP accesses are disabled when `jwt.signing` is enabled. \ No newline at end of file