doc/book/cookbook/encryption.md

@@ -53,20 +53,43 @@ and that's also why your nodes have super long identifiers.
 
 Adding TLS support built into Garage is not currently planned.
 
-## Garage stores data in plain text on the filesystem
+## Garage stores data in plain text on the filesystem or encrypted using customer keys (SSE-C)
 
-Garage does not handle data encryption at rest by itself, and instead delegates
+For standard S3 API requests, Garage does not encrypt data at rest by itself.
-to the user to add encryption, either at the storage layer (LUKS, etc) or on
+For the most generic at rest encryption of data, we recommend setting up your
-the client side (or both). There are no current plans to add data encryption
+storage partitions on encrypted LUKS devices.
-directly in Garage.
 
-Implementing data encryption directly in Garage might make things simpler for
+If you are developping your own client software that makes use of S3 storage,
-end users, but also raises many more questions, especially around key
+we recommend implementing data encryption directly on the client side and never
-management: for encryption of data, where could Garage get the encryption keys
+transmitting plaintext data to Garage. This makes it easy to use an external
-from ? If we encrypt data but keep the keys in a plaintext file next to them,
+untrusted storage provider if necessary.
-it's useless. We probably don't want to have to manage secrets in garage as it
+
-would be very hard to do in a secure way. Maybe integrate with an external
+Garage does support [SSE-C
-system such as Hashicorp Vault?
+encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ServerSideEncryptionCustomerKeys.html),
+an encryption mode of Amazon S3 where data is encrypted at rest using
+encryption keys given by the client.  The encryption keys are passed to the
+server in a header in each request, to encrypt or decrypt data at the moment of
+reading or writing. The server discards the key as soon as it has finished
+using it for the request.  This mode allows the data to be encrypted at rest by
+Garage itself, but it requires support in the client software. It is also not
+adapted to a model where the server is not trusted or assumed to be
+compromised, as the server can easily know the encryption keys.  Note however
+that when using SSE-C encryption, the only Garage node that knows the
+encryption key passed in a given request is the node to which the request is
+directed (which can be a gateway node), so it is easy to have untrusted nodes
+in the cluster as long as S3 API requests containing SSE-C encryption keys are
+not directed to them.
+
+Implementing automatic data encryption directly in Garage without client-side
+management of keys (something like
+[SSE-S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html))
+could make things simpler for end users that don't want to setup LUKS, but also
+raises many more questions, especially around key management: for encryption of
+data, where could Garage get the encryption keys from? If we encrypt data but
+keep the keys in a plaintext file next to them, it's useless. We probably don't
+want to have to manage secrets in Garage as it would be very hard to do in a
+secure way. At the time of speaking, there are no plans to implement this in
+Garage.
 
 
 # Adding data encryption using external tools

doc/book/cookbook/real-world.md

@@ -68,11 +68,6 @@ to store 2 TB of data in total.
   EXT4 is not recommended as it has more strict limitations on the number of inodes,
   which might cause issues with Garage when large numbers of objects are stored.
 
-- If you only have an HDD and no SSD, it's fine to put your metadata alongside the data
-  on the same drive. Having lots of RAM for your kernel to cache the metadata will
-  help a lot with performance.  The default LMDB database engine is the most tested
-  and has good performance.
-
 - Servers with multiple HDDs are supported natively by Garage without resorting
   to RAID, see [our dedicated documentation page](@/documentation/operations/multi-hdd.md).
 
@@ -92,6 +87,12 @@ to store 2 TB of data in total.
   and 2/ LMDB is not suited for 32-bit platforms. Sqlite is a viable alternative
   if any of these are of concern.
 
+- If you only have an HDD and no SSD, it's fine to put your metadata alongside
+  the data on the same drive, but then consider your filesystem choice wisely
+  (see above). Having lots of RAM for your kernel to cache the metadata will
+  help a lot with performance.  The default LMDB database engine is the most
+  tested and has good performance.
+
 ## Get a Docker image
 
 Our docker image is currently named `dxflrs/garage` and is stored on the [Docker Hub](https://hub.docker.com/r/dxflrs/garage/tags?page=1&ordering=last_updated).