garage/doc/book/cookbook/encryption.md

+++ title = "Encryption" weight = 50 +++

Encryption is a recurring subject when discussing Garage. Garage does not handle data encryption by itself, but many things can already be done with Garage's current feature set and the existing ecosystem.

This page takes a high level approach to security in general and data encryption in particular.

Examining your need for encryption

• Why do you want encryption in Garage?

• What is your threat model? What are you fearing?

  • A stolen HDD?
  • A curious administrator?
  • A malicious administrator?
  • A remote attacker?
  • etc.

• What services do you want to protect with encryption?

  • An existing application? Which one? (eg. Nextcloud)
  • An application that you are writing

• Any expertise you may have on the subject

This page explains what Garage provides, and how you can improve the situation by yourself by adding encryption at different levels.

We would be very curious to know your needs and thougs about ideas such as encryption practices and things like key management, as we want Garage to be a serious base platform for the developpment of secure, encrypted applications. Do not hesitate to come talk to us if you have any thoughts or questions on the subject.

Capabilities provided by Garage

Traffic is encrypted between Garage nodes

RPCs between Garage nodes are encrypted. More specifically, contrary to many distributed software, it is impossible in Garage to have clear-text RPC. We use the kuska handshake library which implements a protocol that has been clearly reviewed, Secure ScuttleButt's Secret Handshake protocol. This is why setting a rpc_secret is mandatory, and that's also why your nodes have super long identifiers.

HTTP API endpoints provided by Garage are in clear text

Adding TLS support built into Garage is not currently planned.

Garage stores data in plain text on the filesystem or encrypted using customer keys (SSE-C)

For standard S3 API requests, Garage does not encrypt data at rest by itself. For the most generic at rest encryption of data, we recommend setting up your storage partitions on encrypted LUKS devices.

If you are developping your own client software that makes use of S3 storage, we recommend implementing data encryption directly on the client side and never transmitting plaintext data to Garage. This makes it easy to use an external untrusted storage provider if necessary.

Garage does support SSE-C encryption, 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) 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

Encrypting traffic between a Garage node and your client

You have multiple options to have encryption between your client and a node:

• Setup a reverse proxy with TLS / ACME / Let's encrypt
• Setup a Garage gateway locally, and only contact the garage daemon on localhost
• Only contact your Garage daemon over a secure, encrypted overlay network such as Wireguard

Encrypting data at rest

Protects against the following threats:

• Stolen HDD

Crucially, does not protect againt malicious sysadmins or remote attackers that might gain access to your servers.

Methods include full-disk encryption with tools such as LUKS.

Encrypting data on the client side

Protects againt the following threats:

• A honest-but-curious administrator
• A malicious administrator that tries to corrupt your data
• A remote attacker that can read your server's data

Implementations are very specific to the various applications. Examples:

• Matrix: uses the OLM protocol for E2EE of user messages. Media files stored in Matrix are probably encrypted using symmetric encryption, with a key that is distributed in the end-to-end encrypted message that contains the link to the object.

• XMPP: clients normally support either OMEMO / OpenPGP for the E2EE of user messages. Media files are encrypted per XEP-0454.

• Aerogramme: use the user's password as a key to decrypt data in the user's bucket

• Cyberduck: comes with support for Cryptomator which allows users to create client-side vaults to encrypt files in before they are uploaded to a cloud storage endpoint.