From ac4f00fbc1535605df949f39c854637cc291e122 Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Fri, 6 Oct 2023 11:58:38 +0200 Subject: [PATCH 01/11] s3proxy: add new page to documentation --- docs/docs/workflows/s3proxy.md | 56 ++++++++++++++++++++++++++++++++++ docs/sidebars.js | 5 +++ 2 files changed, 61 insertions(+) create mode 100644 docs/docs/workflows/s3proxy.md diff --git a/docs/docs/workflows/s3proxy.md b/docs/docs/workflows/s3proxy.md new file mode 100644 index 0000000000..d1a6ce369e --- /dev/null +++ b/docs/docs/workflows/s3proxy.md @@ -0,0 +1,56 @@ +# Install s3proxy + +Constellation includes a transparent encryption proxy for [AWS S3](https://aws.amazon.com/de/s3/). +s3proxy will encrypt/decrypt objects when you send/retrieve objects to/from S3, without making changes to your application necessary. + +## Limitations + +:::caution +Using s3proxy outside Constellation is insecure as the connection between the key management service (KMS) and s3proxy is protected by Constellation's WireGuard VPN. +The VPN is a feature of Constellation and will not be present by default in other environments. +::: + +These limitations will be removed with future iterations of s3proxy. + +- Only `PutObject` and `GetObject` requests are encrypted/decrypted by s3proxy. +That means other requests are forwarded to S3 as-is. +For example, objects uploaded with `CreateMultipartUpload` are not encrypted. +- Using the [Range](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html#API_GetObject_RequestSyntax) header on `GetObject` is currently not supported and will result in an error. + +If you want to use s3proxy but these limitations stop you from doing so, please consider [opening](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&projects=&template=feature_request.yml) an issue. + +## Deployment + +- `git clone git@github.com:edgelesssys/constellation.git && cd constellation` +- Replace the values named `replaceme` in `s3proxy/deploy/deployment-s3proxy.yaml` with valid AWS credentials. These credentials are used by s3proxy to access your S3 buckets. +- `kubectl apply -f s3proxy/deploy/deployment-s3proxy.yaml` + +s3proxy is now deployed. +If you want to run a demo application you can checkout our [Deploy Filestash](https://github.com/edgelesssys/constellation/tree/main/s3proxy/deploy#deploying-filestash) instructions to deploy Filestash. +Filestash is a web frontend for different storage backends, including S3. + + +## Technical details + +### Encryption + +s3proxy relies on Google's [Tink Cryptographic Library](https://developers.google.com/tink) to implement cryptographic operations securely. +The used cryptographic primitives are [NIST SP 800 38f](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf) for keywrapping and [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)-[GCM](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Galois/counter_(GCM)) with 256 bit keys for data encryption. + +s3proxy uses [envelope encryption](https://cloud.google.com/kms/docs/envelope-encryption) to encrypt objects. +That means s3proxy uses a key encryption key (KEK) issued by the Constellation KMS to encrypt data encryption keys (DEK). +Each S3 object is encrypted with it's own DEK. +The encrypted DEK is then saved as metadata of the encrypted object. +This enables key rotation of the KEK without reencrypting the data in S3. +The approach also allows access to objects from different locations, as long as each location has access to the KEK. + +### Traffic interception + +To use s3proxy you have to redirect your outbound AWS S3 traffic to s3proxy. +This can either be done by modifying your client application or by changing the deployment of your application. + +The necessary deployment modifications are to add DNS redirection and a trusted TLS certificate to the client's trust store. +DNS redirection can be defined for each pod allowing you to test s3proxy for one application, without changing other applications in the same cluster. +Adding a trusted TLS certificate is necessary as clients communicate with s3proxy via HTTPS. +In order to have your client application trust s3proxy's TLS certificate, the certificate has to be added to the client's truststore. +The above [deployment example](#deployment) shows how all this can be done using cert-manager and the [hostAliases](https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/) key. diff --git a/docs/sidebars.js b/docs/sidebars.js index 5c206a43d2..a2fc44def0 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -165,6 +165,11 @@ const sidebars = { label: 'Install cert-manager', id: 'workflows/cert-manager', }, + { + type: 'doc', + label: 'Install s3proxy', + id: 'workflows/s3proxy', + }, { type: 'doc', label: 'Terminate your cluster', From 9a2f9ab3b8061b7b3c5418016ab100c66007a8ae Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Fri, 6 Oct 2023 12:55:05 +0200 Subject: [PATCH 02/11] adress vale comments --- docs/docs/workflows/s3proxy.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/workflows/s3proxy.md b/docs/docs/workflows/s3proxy.md index d1a6ce369e..1c2b7eb137 100644 --- a/docs/docs/workflows/s3proxy.md +++ b/docs/docs/workflows/s3proxy.md @@ -7,14 +7,14 @@ s3proxy will encrypt/decrypt objects when you send/retrieve objects to/from S3, :::caution Using s3proxy outside Constellation is insecure as the connection between the key management service (KMS) and s3proxy is protected by Constellation's WireGuard VPN. -The VPN is a feature of Constellation and will not be present by default in other environments. +The VPN is a feature of Constellation and won't be present by default in other environments. ::: These limitations will be removed with future iterations of s3proxy. - Only `PutObject` and `GetObject` requests are encrypted/decrypted by s3proxy. That means other requests are forwarded to S3 as-is. -For example, objects uploaded with `CreateMultipartUpload` are not encrypted. +For example, objects uploaded with `CreateMultipartUpload` aren't encrypted. - Using the [Range](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html#API_GetObject_RequestSyntax) header on `GetObject` is currently not supported and will result in an error. If you want to use s3proxy but these limitations stop you from doing so, please consider [opening](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&projects=&template=feature_request.yml) an issue. @@ -26,7 +26,7 @@ If you want to use s3proxy but these limitations stop you from doing so, please - `kubectl apply -f s3proxy/deploy/deployment-s3proxy.yaml` s3proxy is now deployed. -If you want to run a demo application you can checkout our [Deploy Filestash](https://github.com/edgelesssys/constellation/tree/main/s3proxy/deploy#deploying-filestash) instructions to deploy Filestash. +If you want to run a demo application you can checkout the [Deploy Filestash](https://github.com/edgelesssys/constellation/tree/main/s3proxy/deploy#deploying-filestash) instructions to deploy Filestash. Filestash is a web frontend for different storage backends, including S3. @@ -41,7 +41,7 @@ s3proxy uses [envelope encryption](https://cloud.google.com/kms/docs/envelope-en That means s3proxy uses a key encryption key (KEK) issued by the Constellation KMS to encrypt data encryption keys (DEK). Each S3 object is encrypted with it's own DEK. The encrypted DEK is then saved as metadata of the encrypted object. -This enables key rotation of the KEK without reencrypting the data in S3. +This enables key rotation of the KEK without re-encrypting the data in S3. The approach also allows access to objects from different locations, as long as each location has access to the KEK. ### Traffic interception @@ -52,5 +52,5 @@ This can either be done by modifying your client application or by changing the The necessary deployment modifications are to add DNS redirection and a trusted TLS certificate to the client's trust store. DNS redirection can be defined for each pod allowing you to test s3proxy for one application, without changing other applications in the same cluster. Adding a trusted TLS certificate is necessary as clients communicate with s3proxy via HTTPS. -In order to have your client application trust s3proxy's TLS certificate, the certificate has to be added to the client's truststore. +To have your client application trust s3proxy's TLS certificate, the certificate has to be added to the client's truststore. The above [deployment example](#deployment) shows how all this can be done using cert-manager and the [hostAliases](https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/) key. From 1f8227adc0878e788f4726fc7f02edf9b9fc4b6c Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Fri, 6 Oct 2023 16:31:56 +0200 Subject: [PATCH 03/11] use wget instead of git clone --- docs/docs/workflows/s3proxy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/workflows/s3proxy.md b/docs/docs/workflows/s3proxy.md index 1c2b7eb137..e21eea3b72 100644 --- a/docs/docs/workflows/s3proxy.md +++ b/docs/docs/workflows/s3proxy.md @@ -21,9 +21,9 @@ If you want to use s3proxy but these limitations stop you from doing so, please ## Deployment -- `git clone git@github.com:edgelesssys/constellation.git && cd constellation` -- Replace the values named `replaceme` in `s3proxy/deploy/deployment-s3proxy.yaml` with valid AWS credentials. These credentials are used by s3proxy to access your S3 buckets. -- `kubectl apply -f s3proxy/deploy/deployment-s3proxy.yaml` +- `wget https://raw.githubusercontent.com/edgelesssys/constellation/main/s3proxy/deploy/deployment-s3proxy.yaml` +- Replace the values named `replaceme` in `deployment-s3proxy.yaml` with valid AWS credentials. These credentials are used by s3proxy to access your S3 buckets. +- `kubectl apply -f deployment-s3proxy.yaml` s3proxy is now deployed. If you want to run a demo application you can checkout the [Deploy Filestash](https://github.com/edgelesssys/constellation/tree/main/s3proxy/deploy#deploying-filestash) instructions to deploy Filestash. From 074daae83ef47a8b275f6bf06ba47df12d14b1bd Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Fri, 6 Oct 2023 16:51:51 +0200 Subject: [PATCH 04/11] Add filestash as example --- .../examples/filstash-s3proxy.md | 69 +++++++++++++++++++ docs/docs/workflows/s3proxy.md | 3 +- docs/sidebars.js | 5 ++ 3 files changed, 75 insertions(+), 2 deletions(-) create mode 100644 docs/docs/getting-started/examples/filstash-s3proxy.md diff --git a/docs/docs/getting-started/examples/filstash-s3proxy.md b/docs/docs/getting-started/examples/filstash-s3proxy.md new file mode 100644 index 0000000000..888ae7bc32 --- /dev/null +++ b/docs/docs/getting-started/examples/filstash-s3proxy.md @@ -0,0 +1,69 @@ + +# Deploying Filestash + +Filestash is a web frontend for different storage backends, including S3. +It is a useful application to showcase s3proxy in action. + +1. Deploy s3proxy as described in [Deployment](../../workflows/s3proxy.md#deployment). +2. Create a deployment file for Filestash with one pod: + +```sh +cat << EOF > "deployment-filestash.yaml" +apiVersion: apps/v1 +kind: Deployment +metadata: + name: filestash +spec: + replicas: 1 + selector: + matchLabels: + app: filestash + template: + metadata: + labels: + app: filestash + spec: + imagePullSecrets: + - name: regcred + hostAliases: + - ip: $(kubectl get svc s3proxy-service -o=jsonpath='{.spec.clusterIP}') + hostnames: + - "s3.eu-west-1.amazonaws.com" + containers: + - name: filestash + image: machines/filestash:latest + ports: + - containerPort: 8334 + volumeMounts: + - name: ca-cert + mountPath: /etc/ssl/certs/kube-ca.crt + subPath: kube-ca.crt + volumes: + - name: ca-cert + secret: + secretName: s3proxy-tls + items: + - key: ca.crt + path: kube-ca.crt +EOF +``` + +The pod spec includes the `hostAliases` key, which adds an entry to the pod's `/etc/hosts`. +The entry forwards all requests for `s3.eu-west-1.amazonaws.com` to the kubernetes service `s3proxy-service`. +If you followed the s3proxy [Deployment](../../workflows/s3proxy.md#deployment) guide, this service points to a s3proxy pod. + +To use other regions than `eu-west-1`, add more entries to `hostAliases` for all regions you require. +Use the same IP for those entries. For example to add `us-east-1` add: +```yaml +- ip: $(kubectl get svc s3proxy-service -o=jsonpath='{.spec.clusterIP}') + hostnames: + - "s3.us-east-1.amazonaws.com" +``` + +The spec also includes a volume mount for the TLS certificate and adds it to the pod's truststore. +Not doing this will result in TLS authentication errors. + +3. Apply the file: `kubectl apply -f deployment-filestash.yaml` + +Afterwards you can use a port forward to access the Filestash pod: +`kubectl port-forward pod/$(kubectl get pod --selector='app=filestash' -o=jsonpath='{.items[*].metadata.name}') 8443:8443` diff --git a/docs/docs/workflows/s3proxy.md b/docs/docs/workflows/s3proxy.md index e21eea3b72..948fca33b0 100644 --- a/docs/docs/workflows/s3proxy.md +++ b/docs/docs/workflows/s3proxy.md @@ -26,8 +26,7 @@ If you want to use s3proxy but these limitations stop you from doing so, please - `kubectl apply -f deployment-s3proxy.yaml` s3proxy is now deployed. -If you want to run a demo application you can checkout the [Deploy Filestash](https://github.com/edgelesssys/constellation/tree/main/s3proxy/deploy#deploying-filestash) instructions to deploy Filestash. -Filestash is a web frontend for different storage backends, including S3. +If you want to run a demo application, checkout the [Filestash with s3proxy](../getting-started/examples/filstash-s3proxy.md) example. ## Technical details diff --git a/docs/sidebars.js b/docs/sidebars.js index a2fc44def0..203e9007bd 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -119,6 +119,11 @@ const sidebars = { label: 'Horizontal Pod Autoscaling', id: 'getting-started/examples/horizontal-scaling' }, + { + type: 'doc', + label: 'Filestash with s3proxy', + id: 'getting-started/examples/filstash-s3proxy' + }, ] }, ], From 2acf2e513e6d09a94e5183bf1767dec9ef8eb939 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Mon, 9 Oct 2023 08:11:44 +0200 Subject: [PATCH 05/11] Update vocab --- docs/styles/Vocab/constellation/accept.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/styles/Vocab/constellation/accept.txt b/docs/styles/Vocab/constellation/accept.txt index 1709702844..31b6e437c1 100644 --- a/docs/styles/Vocab/constellation/accept.txt +++ b/docs/styles/Vocab/constellation/accept.txt @@ -22,6 +22,7 @@ Dynatrace [Ee]mojivoto etcd Filebeat +Filestash Filestore Fluentd Fulcio @@ -54,6 +55,7 @@ sigstore [Ss]uperset Syft systemd +Tink [Uu]nencrypted unspoofable updatable From 1034605542a4f26caae458023d9dc3917182e578 Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Mon, 9 Oct 2023 14:36:17 +0200 Subject: [PATCH 06/11] Moritz feedback --- docs/docs/architecture/encrypted-storage.md | 6 ++++++ docs/docs/getting-started/examples/filstash-s3proxy.md | 8 ++++---- docs/docs/workflows/s3proxy.md | 8 ++++---- 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/docs/architecture/encrypted-storage.md b/docs/docs/architecture/encrypted-storage.md index 4288ddac27..03d060b4c8 100644 --- a/docs/docs/architecture/encrypted-storage.md +++ b/docs/docs/architecture/encrypted-storage.md @@ -55,3 +55,9 @@ For encryption Constellation uses AES in XTS-Plain64. The key size is 512 bit. To interact with the dm-integrity kernel module, Constellation uses [libcryptsetup](https://gitlab.com/cryptsetup/cryptsetup/). When enabled, the used data integrity algorithm is [HMAC](https://datatracker.ietf.org/doc/html/rfc2104) with SHA256 as the hash function. The tag size is 32 Bytes. + +# Encrypted AWS S3 storage + +Constellation comes with an encryption service that can be used to transparently retrofit encryption to existing applications that rely on S3 for storage. +Prerequisite is that your application is running inside a Constellation cluster. +To learn more checkout the [s3proxy documentation](../workflows/s3proxy.md). diff --git a/docs/docs/getting-started/examples/filstash-s3proxy.md b/docs/docs/getting-started/examples/filstash-s3proxy.md index 888ae7bc32..8de959b9cc 100644 --- a/docs/docs/getting-started/examples/filstash-s3proxy.md +++ b/docs/docs/getting-started/examples/filstash-s3proxy.md @@ -2,7 +2,7 @@ # Deploying Filestash Filestash is a web frontend for different storage backends, including S3. -It is a useful application to showcase s3proxy in action. +It's a useful application to showcase s3proxy in action. 1. Deploy s3proxy as described in [Deployment](../../workflows/s3proxy.md#deployment). 2. Create a deployment file for Filestash with one pod: @@ -49,7 +49,7 @@ EOF ``` The pod spec includes the `hostAliases` key, which adds an entry to the pod's `/etc/hosts`. -The entry forwards all requests for `s3.eu-west-1.amazonaws.com` to the kubernetes service `s3proxy-service`. +The entry forwards all requests for `s3.eu-west-1.amazonaws.com` to the Kubernetes service `s3proxy-service`. If you followed the s3proxy [Deployment](../../workflows/s3proxy.md#deployment) guide, this service points to a s3proxy pod. To use other regions than `eu-west-1`, add more entries to `hostAliases` for all regions you require. @@ -60,10 +60,10 @@ Use the same IP for those entries. For example to add `us-east-1` add: - "s3.us-east-1.amazonaws.com" ``` -The spec also includes a volume mount for the TLS certificate and adds it to the pod's truststore. +The spec also includes a volume mount for the TLS certificate and adds it to the pod's certificate trust store. Not doing this will result in TLS authentication errors. 3. Apply the file: `kubectl apply -f deployment-filestash.yaml` -Afterwards you can use a port forward to access the Filestash pod: +Afterward, you can use a port forward to access the Filestash pod: `kubectl port-forward pod/$(kubectl get pod --selector='app=filestash' -o=jsonpath='{.items[*].metadata.name}') 8443:8443` diff --git a/docs/docs/workflows/s3proxy.md b/docs/docs/workflows/s3proxy.md index 948fca33b0..e681a3f8ca 100644 --- a/docs/docs/workflows/s3proxy.md +++ b/docs/docs/workflows/s3proxy.md @@ -34,11 +34,11 @@ If you want to run a demo application, checkout the [Filestash with s3proxy](../ ### Encryption s3proxy relies on Google's [Tink Cryptographic Library](https://developers.google.com/tink) to implement cryptographic operations securely. -The used cryptographic primitives are [NIST SP 800 38f](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf) for keywrapping and [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)-[GCM](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Galois/counter_(GCM)) with 256 bit keys for data encryption. +The used cryptographic primitives are [NIST SP 800 38f](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf) for key wrapping and [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)-[GCM](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Galois/counter_(GCM)) with 256 bit keys for data encryption. s3proxy uses [envelope encryption](https://cloud.google.com/kms/docs/envelope-encryption) to encrypt objects. That means s3proxy uses a key encryption key (KEK) issued by the Constellation KMS to encrypt data encryption keys (DEK). -Each S3 object is encrypted with it's own DEK. +Each S3 object is encrypted with its own DEK. The encrypted DEK is then saved as metadata of the encrypted object. This enables key rotation of the KEK without re-encrypting the data in S3. The approach also allows access to objects from different locations, as long as each location has access to the KEK. @@ -49,7 +49,7 @@ To use s3proxy you have to redirect your outbound AWS S3 traffic to s3proxy. This can either be done by modifying your client application or by changing the deployment of your application. The necessary deployment modifications are to add DNS redirection and a trusted TLS certificate to the client's trust store. -DNS redirection can be defined for each pod allowing you to test s3proxy for one application, without changing other applications in the same cluster. +DNS redirection can be defined for each pod, allowing you to test s3proxy for one application without changing other applications in the same cluster. Adding a trusted TLS certificate is necessary as clients communicate with s3proxy via HTTPS. -To have your client application trust s3proxy's TLS certificate, the certificate has to be added to the client's truststore. +To have your client application trust s3proxy's TLS certificate, the certificate has to be added to the client's certificate trust store. The above [deployment example](#deployment) shows how all this can be done using cert-manager and the [hostAliases](https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/) key. From 4f0b823a9d1c1a299a53243ac3e9a5f0c38c261a Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Mon, 9 Oct 2023 14:44:36 +0200 Subject: [PATCH 07/11] Adjust s3proxy docs to mention allow-multipart --- docs/docs/workflows/s3proxy.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs/workflows/s3proxy.md b/docs/docs/workflows/s3proxy.md index e681a3f8ca..dae63957cb 100644 --- a/docs/docs/workflows/s3proxy.md +++ b/docs/docs/workflows/s3proxy.md @@ -13,8 +13,9 @@ The VPN is a feature of Constellation and won't be present by default in other e These limitations will be removed with future iterations of s3proxy. - Only `PutObject` and `GetObject` requests are encrypted/decrypted by s3proxy. -That means other requests are forwarded to S3 as-is. -For example, objects uploaded with `CreateMultipartUpload` aren't encrypted. +By default s3proxy will block requests that may leak data to S3 (e.g. UploadPart). +The `allow-multipart` flag disables request blocking for testing. +Using this flag will leak data if your application uses multipart uploads. - Using the [Range](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html#API_GetObject_RequestSyntax) header on `GetObject` is currently not supported and will result in an error. If you want to use s3proxy but these limitations stop you from doing so, please consider [opening](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&projects=&template=feature_request.yml) an issue. From 28e9238119ee81318380cd4d72ff53fd3d0010a0 Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Tue, 10 Oct 2023 09:04:02 +0200 Subject: [PATCH 08/11] Thomas suggestions Co-authored-by: Thomas Tendyck --- docs/docs/architecture/encrypted-storage.md | 7 ++-- .../examples/filstash-s3proxy.md | 4 +- docs/docs/workflows/s3proxy.md | 42 ++++++++++--------- 3 files changed, 28 insertions(+), 25 deletions(-) diff --git a/docs/docs/architecture/encrypted-storage.md b/docs/docs/architecture/encrypted-storage.md index 03d060b4c8..09818ada59 100644 --- a/docs/docs/architecture/encrypted-storage.md +++ b/docs/docs/architecture/encrypted-storage.md @@ -56,8 +56,7 @@ To interact with the dm-integrity kernel module, Constellation uses [libcryptset When enabled, the used data integrity algorithm is [HMAC](https://datatracker.ietf.org/doc/html/rfc2104) with SHA256 as the hash function. The tag size is 32 Bytes. -# Encrypted AWS S3 storage +# Encrypted S3 object storage -Constellation comes with an encryption service that can be used to transparently retrofit encryption to existing applications that rely on S3 for storage. -Prerequisite is that your application is running inside a Constellation cluster. -To learn more checkout the [s3proxy documentation](../workflows/s3proxy.md). +Constellation comes with a service that you can use to transparently retrofit client-side encryption to existing applications that use S3 (AWS or compatible) for storage. +To learn more, check out the [s3proxy documentation](../workflows/s3proxy.md). diff --git a/docs/docs/getting-started/examples/filstash-s3proxy.md b/docs/docs/getting-started/examples/filstash-s3proxy.md index 8de959b9cc..c3cabca439 100644 --- a/docs/docs/getting-started/examples/filstash-s3proxy.md +++ b/docs/docs/getting-started/examples/filstash-s3proxy.md @@ -61,7 +61,9 @@ Use the same IP for those entries. For example to add `us-east-1` add: ``` The spec also includes a volume mount for the TLS certificate and adds it to the pod's certificate trust store. -Not doing this will result in TLS authentication errors. +The volume is called `ca-cert`. +The key `ca.crt` of that volume is mounted to `/etc/ssl/certs/kube-ca.crt`, which is the default certificate trust store location for that container's OpenSSL library. +Not adding the CA certificate will result in TLS authentication errors. 3. Apply the file: `kubectl apply -f deployment-filestash.yaml` diff --git a/docs/docs/workflows/s3proxy.md b/docs/docs/workflows/s3proxy.md index dae63957cb..ad78708504 100644 --- a/docs/docs/workflows/s3proxy.md +++ b/docs/docs/workflows/s3proxy.md @@ -1,33 +1,35 @@ # Install s3proxy -Constellation includes a transparent encryption proxy for [AWS S3](https://aws.amazon.com/de/s3/). -s3proxy will encrypt/decrypt objects when you send/retrieve objects to/from S3, without making changes to your application necessary. +Constellation includes a transparent client-side encryption proxy for [AWS S3](https://aws.amazon.com/de/s3/) and compatible stores. +s3proxy encrypts objects before sending them to S3 and automatically decrypts them on retrieval, without requiring changes to your application. +With s3proxy, you can use S3 for storage in a confidential way without having to trust the storage provider. ## Limitations -:::caution -Using s3proxy outside Constellation is insecure as the connection between the key management service (KMS) and s3proxy is protected by Constellation's WireGuard VPN. -The VPN is a feature of Constellation and won't be present by default in other environments. -::: - -These limitations will be removed with future iterations of s3proxy. - +Currently, s3proxy has the following limitations: - Only `PutObject` and `GetObject` requests are encrypted/decrypted by s3proxy. -By default s3proxy will block requests that may leak data to S3 (e.g. UploadPart). -The `allow-multipart` flag disables request blocking for testing. -Using this flag will leak data if your application uses multipart uploads. +By default, s3proxy will block requests that may expose unencrypted data to S3 (e.g. UploadPart). +The `allow-multipart` flag disables request blocking for evaluation purposes. - Using the [Range](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html#API_GetObject_RequestSyntax) header on `GetObject` is currently not supported and will result in an error. -If you want to use s3proxy but these limitations stop you from doing so, please consider [opening](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&projects=&template=feature_request.yml) an issue. +These limitations will be removed with future iterations of s3proxy. +If you want to use s3proxy but these limitations stop you from doing so, consider [opening an issue](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&projects=&template=feature_request.yml). ## Deployment -- `wget https://raw.githubusercontent.com/edgelesssys/constellation/main/s3proxy/deploy/deployment-s3proxy.yaml` -- Replace the values named `replaceme` in `deployment-s3proxy.yaml` with valid AWS credentials. These credentials are used by s3proxy to access your S3 buckets. -- `kubectl apply -f deployment-s3proxy.yaml` +You can add the s3proxy to your Constellation cluster as follows: +1. Download the deployment manifest: + ```bash + wget https://raw.githubusercontent.com/edgelesssys/constellation/main/s3proxy/deploy/deployment-s3proxy.yaml + ``` +2. Replace the values named `replaceme` in `deployment-s3proxy.yaml` with valid AWS credentials. These credentials are used by s3proxy to access your S3 buckets. +3. Deploy s3proxy: + ```bash + kubectl apply -f deployment-s3proxy.yaml + ``` s3proxy is now deployed. -If you want to run a demo application, checkout the [Filestash with s3proxy](../getting-started/examples/filstash-s3proxy.md) example. +If you want to run a demo application, check out the [Filestash with s3proxy](../getting-started/examples/filstash-s3proxy.md) example. ## Technical details @@ -38,7 +40,7 @@ s3proxy relies on Google's [Tink Cryptographic Library](https://developers.googl The used cryptographic primitives are [NIST SP 800 38f](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf) for key wrapping and [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)-[GCM](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Galois/counter_(GCM)) with 256 bit keys for data encryption. s3proxy uses [envelope encryption](https://cloud.google.com/kms/docs/envelope-encryption) to encrypt objects. -That means s3proxy uses a key encryption key (KEK) issued by the Constellation KMS to encrypt data encryption keys (DEK). +This means s3proxy uses a key encryption key (KEK) issued by the [KeyService](../architecture/microservices.md#keyservice) to encrypt data encryption keys (DEKs). Each S3 object is encrypted with its own DEK. The encrypted DEK is then saved as metadata of the encrypted object. This enables key rotation of the KEK without re-encrypting the data in S3. @@ -46,11 +48,11 @@ The approach also allows access to objects from different locations, as long as ### Traffic interception -To use s3proxy you have to redirect your outbound AWS S3 traffic to s3proxy. +To use s3proxy, you have to redirect your outbound S3 traffic to s3proxy. This can either be done by modifying your client application or by changing the deployment of your application. The necessary deployment modifications are to add DNS redirection and a trusted TLS certificate to the client's trust store. DNS redirection can be defined for each pod, allowing you to test s3proxy for one application without changing other applications in the same cluster. Adding a trusted TLS certificate is necessary as clients communicate with s3proxy via HTTPS. To have your client application trust s3proxy's TLS certificate, the certificate has to be added to the client's certificate trust store. -The above [deployment example](#deployment) shows how all this can be done using cert-manager and the [hostAliases](https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/) key. +The [Filestash with s3proxy](../getting-started/examples/filstash-s3proxy.md) example shows how this is realized using an example. From a8768d4a08ac1832e949702ae861b9bbd283cf90 Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Tue, 10 Oct 2023 13:36:39 +0200 Subject: [PATCH 09/11] Update to release image --- s3proxy/deploy/deployment-s3proxy.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/s3proxy/deploy/deployment-s3proxy.yaml b/s3proxy/deploy/deployment-s3proxy.yaml index c3a5f38d96..49ca522ac4 100644 --- a/s3proxy/deploy/deployment-s3proxy.yaml +++ b/s3proxy/deploy/deployment-s3proxy.yaml @@ -24,7 +24,7 @@ spec: - "s3.eu-west-1.amazonaws.com" issuerRef: name: selfsigned-issuer - kind: ClusterIssuer + kind: Issuer group: cert-manager.io --- apiVersion: apps/v1 @@ -47,7 +47,7 @@ spec: - name: regcred containers: - name: s3proxy - image: ghcr.io/edgelesssys/constellation/s3proxy:v2.12.0-pre.0.20231009141917-226cb427d0b1 + image: ghcr.io/edgelesssys/constellation/s3proxy:v2.12.0 args: - "--level=-1" ports: From d6bd27df6b31c67c68d9f969c834ee9899868741 Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Tue, 10 Oct 2023 13:37:22 +0200 Subject: [PATCH 10/11] fix port forward port --- docs/docs/getting-started/examples/filstash-s3proxy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started/examples/filstash-s3proxy.md b/docs/docs/getting-started/examples/filstash-s3proxy.md index c3cabca439..6dd67f28c0 100644 --- a/docs/docs/getting-started/examples/filstash-s3proxy.md +++ b/docs/docs/getting-started/examples/filstash-s3proxy.md @@ -68,4 +68,4 @@ Not adding the CA certificate will result in TLS authentication errors. 3. Apply the file: `kubectl apply -f deployment-filestash.yaml` Afterward, you can use a port forward to access the Filestash pod: -`kubectl port-forward pod/$(kubectl get pod --selector='app=filestash' -o=jsonpath='{.items[*].metadata.name}') 8443:8443` +`kubectl port-forward pod/$(kubectl get pod --selector='app=filestash' -o=jsonpath='{.items[*].metadata.name}') 8334:8334` From 1d456c8d0532413d06400d0ca188e4c2dc823b87 Mon Sep 17 00:00:00 2001 From: Otto Bittner Date: Tue, 10 Oct 2023 15:25:09 +0200 Subject: [PATCH 11/11] more feedback --- docs/docs/architecture/encrypted-storage.md | 2 +- docs/docs/workflows/s3proxy.md | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/docs/architecture/encrypted-storage.md b/docs/docs/architecture/encrypted-storage.md index 09818ada59..f047fa4a9d 100644 --- a/docs/docs/architecture/encrypted-storage.md +++ b/docs/docs/architecture/encrypted-storage.md @@ -56,7 +56,7 @@ To interact with the dm-integrity kernel module, Constellation uses [libcryptset When enabled, the used data integrity algorithm is [HMAC](https://datatracker.ietf.org/doc/html/rfc2104) with SHA256 as the hash function. The tag size is 32 Bytes. -# Encrypted S3 object storage +## Encrypted S3 object storage Constellation comes with a service that you can use to transparently retrofit client-side encryption to existing applications that use S3 (AWS or compatible) for storage. To learn more, check out the [s3proxy documentation](../workflows/s3proxy.md). diff --git a/docs/docs/workflows/s3proxy.md b/docs/docs/workflows/s3proxy.md index ad78708504..9c228c98e1 100644 --- a/docs/docs/workflows/s3proxy.md +++ b/docs/docs/workflows/s3proxy.md @@ -28,7 +28,6 @@ You can add the s3proxy to your Constellation cluster as follows: kubectl apply -f deployment-s3proxy.yaml ``` -s3proxy is now deployed. If you want to run a demo application, check out the [Filestash with s3proxy](../getting-started/examples/filstash-s3proxy.md) example. @@ -52,7 +51,7 @@ To use s3proxy, you have to redirect your outbound S3 traffic to s3proxy. This can either be done by modifying your client application or by changing the deployment of your application. The necessary deployment modifications are to add DNS redirection and a trusted TLS certificate to the client's trust store. -DNS redirection can be defined for each pod, allowing you to test s3proxy for one application without changing other applications in the same cluster. +DNS redirection can be defined for each pod, allowing you to use s3proxy for one application without changing other applications in the same cluster. Adding a trusted TLS certificate is necessary as clients communicate with s3proxy via HTTPS. To have your client application trust s3proxy's TLS certificate, the certificate has to be added to the client's certificate trust store. -The [Filestash with s3proxy](../getting-started/examples/filstash-s3proxy.md) example shows how this is realized using an example. +The [Filestash with s3proxy](../getting-started/examples/filstash-s3proxy.md) example shows how to do this.