docs: add new page to document s3proxy

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).

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'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:
+
+```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 certificate trust store.
+Not doing this 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`

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 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.
+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.
+
+## 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`
+
+s3proxy is now deployed.
+If you want to run a demo application, checkout the [Filestash with s3proxy](../getting-started/examples/filstash-s3proxy.md) example.
+
+
+## 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 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 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.
+
+### 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.
+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.

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'
+            },
           ]
         },
       ],
@@ -165,6 +170,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',

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