docs: add more detailed information about Marble<->Coordinator attest…

…ation (#606)

Signed-off-by: Daniel Weiße <[email protected]>

docs/docs/architecture/security.md

@@ -65,7 +65,6 @@ Depending on the Marble's runtime, the certificate can be used [manually](../wor
 
 ![PKI Certificate chain](../_media/cert-chain.svg)
 
-
 ## Attested TLS (aTLS)
 
 In a confidential computing environment, attested TLS (aTLS) can establish secure connections between two parties using the remote attestation features of the confidential computing components.
@@ -74,7 +73,6 @@ For example, it embeds the certificate's public key into the attestation stateme
 Instead of relying on a certificate authority, aTLS uses this attestation statement to establish trust in the certificate.
 The protocol can be used by clients to verify a server certificate, by a server to verify a client certificate, or for mutual verification (mutual aTLS).
 
-
 ## Encryption of state
 
 The Coordinator holds MarbleRun's state, which consists of the [manifest](../features/manifest.md), the [managed secrets](../features/secrets-management.md), and the [certificates for its CA](../features/attestation.md).
@@ -99,13 +97,11 @@ Every recovery party is defined in the manifest with its own public RSA key.
 The Coordinator generates a share of the recovery secret for every party and encrypts it with the corresponding RSA key.
 During a recovery event, every party will upload their share of the secret, which are all XORed together by the Coordinator to receive the combined key for decrypting the DEK.
 
-
 ### Distributed Coordinator
 
-The [distributed Coordinator](../features/recovery.md#distributed-coordinator) works similarly. However, all Coordinators share the same state stored encrypted in the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) called *marble-state*.
+The [distributed Coordinator](../features/recovery.md#distributed-coordinator) works similarly. However, all Coordinators share the same state stored encrypted in the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) called *marblerun-state*.
 In contrast to the single instance, the KEK is generated at start-up by the first instance.
 The existing Coordinators authenticate every new Coordinator instance via remote attestation, and the KEK is subsequently shared via the secure and attested TLS connection.
-Every Coordinator instance uses its own SGX Product (Sealing) Key to seal the KEK into a Kubernetes [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) structure called "KEK."
-
+Every Coordinator instance uses its own SGX Product (Sealing) Key to seal the KEK into a Kubernetes [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) called *marblerun-sealed-kek*.
 
 ![Encrypted state distributed](../_media/enc-state-distributed.svg)

docs/docs/features/attestation.md

@@ -21,7 +21,14 @@ The [manifest](../workflows/define-manifest.md) describes which Marbles (service
 
 The Coordinator enforces the manifest and only admits the desired Marbles to the cluster.
 Each Marble registers itself with a quote via gRPC to the Coordinator. This quote is tied to the TLS session of the gRPC call. It contains the Marble's measurements. The Coordinator compares them to the manifest to ensure the Marble's identity and integrity.
-The [Marble's TLS credentials](../features/secrets-management.md) are generated by the Coordinator and signed with the intermediate certificate.
+
+More specifically, the Marble generates an [ECDSA](https://www.secg.org/sec1-v2.pdf#page=49) private key using curve [P256](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf#page=111), and a self-signed TLS certificate.
+It then hashes the certificate using SHA-256 and creates an SGX quote over the hash.
+The Marble uses this certificate to establish a TLS connection with the Coordinator and send the quote.
+The Coordinator verifies the Marble's measurements contained in the quote against the manifest and makes sure the Marble's TLS certificate matches the quote.
+If all checks pass, the Marble is admitted into the cluster.
+
+The Coordinator now generates new [Marble TLS credentials](../features/secrets-management.md#certificates) and signs them with the intermediate certificate.
 The Coordinator's certificate chain and the freshly generated Marble certificate are then delivered to the Marble.
 
 ![Marble deployment](../_media/marble_deployment.svg)

docs/docs/features/secrets-management.md

@@ -7,6 +7,7 @@ The generation and the management of cryptographic keys and certificates for Mar
 * [User-defined secrets](#user-defined-secrets)
 
 ## Symmetric keys
+
 MarbleRun allows you to define symmetric keys that are generated by the Coordinator and distributed to your Marbles.
 Such keys can either be shared among Marbles or individually generated for each instance.
 This is useful whenever data needs to leave the protected memory of your enclave, hence, needs to be encrypted. For example, when sharing data between multiple Marbles or storing data on the disk.
@@ -16,6 +17,7 @@ To pass the generated keys to your application, you can use a template placehold
 If you use one key throughout multiple Marbles, care has to be taken to not repeat nonces between Marbles when using shared keys with AES-GCM or similar encryption algorithms.
 
 ## Certificates
+
 Upon launch of a Marble, the Coordinator will generate TLS credentials for each new Marble in the form of a private key and a corresponding X.509 certificate. The certificate is signed with the Coordinator's intermediate CA. These TLS credentials represent [the notion of identity used for authentication in MarbleRun](../features/attestation.md). Marbles can use this certificate to establish secure communication channels with other Marbles and external clients (i.e., users of your app). Clients only need to verify the Coordinator's root CA once before they can securely communicate with any Marble, as is described in more detail in our [verification hands-on](../workflows/verification.md). By default, they're available to your application via the environment variables `MARBLE_PREDEFINED_MARBLE_CERTIFICATE_CHAIN` and `MARBLE_PREDEFINED_PRIVATE_KEY`. In addition, you can expose them via custom environment variables or files by defining template placeholders such as `{{ pem .MarbleRun.MarbleCert.Cert }}` or `{{ pem .MarbleRun.MarbleCert.Private }}` in the manifest.
 
 Next to the default credentials, you can use `Secrets` to define custom certificates in your manifest. These are also generated upon each launch of your Marble and signed by the Coordinator's intermediate CA. You can include them into environment variables or files via placeholders such as `{{ pem .Secrets.MySecretCertificate }}` in your manifest.

docs/versioned_docs/version-1.1/features/attestation.md

@@ -21,7 +21,14 @@ The [manifest](../workflows/define-manifest.md) describes which Marbles (service
 
 The Coordinator enforces the manifest and only admits the desired Marbles to the cluster.
 Each Marble registers itself with a quote via gRPC to the Coordinator. This quote is tied to the TLS session of the gRPC call. It contains the Marble's measurements. The Coordinator compares them to the manifest to ensure the Marble's identity and integrity.
-The [Marble's TLS credentials](../features/secrets-management.md) are generated by the Coordinator and signed with the intermediate certificate.
+
+More specifically, the Marble generates an [ECDSA](https://www.secg.org/sec1-v2.pdf#page=49) private key using curve [P256](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf#page=111), and a self-signed TLS certificate.
+It then hashes the certificate using SHA-256 and creates an SGX quote over the hash.
+The Marble uses this certificate to establish a TLS connection with the Coordinator and send the quote.
+The Coordinator verifies the Marble's measurements contained in the quote against the manifest and makes sure the Marble's TLS certificate matches the quote.
+If all checks pass, the Marble is admitted into the cluster.
+
+The [Marble's TLS credentials](../features/secrets-management.md#certificates) are generated by the Coordinator and signed with the intermediate certificate.
 The Coordinator's certificate chain as well as the freshly generated Marble certificate are then delivered to the Marble.
 
 ![Marble deployment](../_media/marble_deployment.svg)

docs/versioned_docs/version-1.2/architecture/security.md

@@ -65,7 +65,6 @@ Depending on the Marble's runtime, the certificate can be used [manually](../wor
 
 ![PKI Certificate chain](../_media/cert-chain.svg)
 
-
 ## Attested TLS (aTLS)
 
 In a confidential computing environment, attested TLS (aTLS) can establish secure connections between two parties using the remote attestation features of the confidential computing components.
@@ -74,7 +73,6 @@ For example, it embeds the certificate's public key into the attestation stateme
 Instead of relying on a certificate authority, aTLS uses this attestation statement to establish trust in the certificate.
 The protocol can be used by clients to verify a server certificate, by a server to verify a client certificate, or for mutual verification (mutual aTLS).
 
-
 ## Encryption of state
 
 The Coordinator holds MarbleRun's state, which consists of the [manifest](../features/manifest.md), the [managed secrets](../features/secrets-management.md), and the [certificates for its CA](../features/attestation.md).
@@ -99,13 +97,11 @@ Every recovery party is defined in the manifest with its own public RSA key.
 The Coordinator generates a share of the recovery secret for every party and encrypts it with the corresponding RSA key.
 During a recovery event, every party will upload their share of the secret, which are all XORed together by the Coordinator to receive the combined key for decrypting the DEK.
 
-
 ### Distributed Coordinator
 
-The [distributed Coordinator](../features/recovery.md#distributed-coordinator) works similarly. However, all Coordinators share the same state stored encrypted in the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) called *marble-state*.
+The [distributed Coordinator](../features/recovery.md#distributed-coordinator) works similarly. However, all Coordinators share the same state stored encrypted in the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) called *marblerun-state*.
 In contrast to the single instance, the KEK is generated at start-up by the first instance.
 The existing Coordinators authenticate every new Coordinator instance via remote attestation, and the KEK is subsequently shared via the secure and attested TLS connection.
-Every Coordinator instance uses its own SGX Product (Sealing) Key to seal the KEK into a Kubernetes [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) structure called "KEK."
-
+Every Coordinator instance uses its own SGX Product (Sealing) Key to seal the KEK into a Kubernetes [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) called *marblerun-sealed-kek*.
 
 ![Encrypted state distributed](../_media/enc-state-distributed.svg)

docs/versioned_docs/version-1.2/features/attestation.md

@@ -21,7 +21,14 @@ The [manifest](../workflows/define-manifest.md) describes which Marbles (service
 
 The Coordinator enforces the manifest and only admits the desired Marbles to the cluster.
 Each Marble registers itself with a quote via gRPC to the Coordinator. This quote is tied to the TLS session of the gRPC call. It contains the Marble's measurements. The Coordinator compares them to the manifest to ensure the Marble's identity and integrity.
-The [Marble's TLS credentials](../features/secrets-management.md) are generated by the Coordinator and signed with the intermediate certificate.
+
+More specifically, the Marble generates an [ECDSA](https://www.secg.org/sec1-v2.pdf#page=49) private key using curve [P256](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf#page=111), and a self-signed TLS certificate.
+It then hashes the certificate using SHA-256 and creates an SGX quote over the hash.
+The Marble uses this certificate to establish a TLS connection with the Coordinator and send the quote.
+The Coordinator verifies the Marble's measurements contained in the quote against the manifest and makes sure the Marble's TLS certificate matches the quote.
+If all checks pass, the Marble is admitted into the cluster.
+
+The [Marble's TLS credentials](../features/secrets-management.md#certificates) are generated by the Coordinator and signed with the intermediate certificate.
 The Coordinator's certificate chain and the freshly generated Marble certificate are then delivered to the Marble.
 
 ![Marble deployment](../_media/marble_deployment.svg)

docs/versioned_docs/version-1.3/architecture/security.md

@@ -65,7 +65,6 @@ Depending on the Marble's runtime, the certificate can be used [manually](../wor
 
 ![PKI Certificate chain](../_media/cert-chain.svg)
 
-
 ## Attested TLS (aTLS)
 
 In a confidential computing environment, attested TLS (aTLS) can establish secure connections between two parties using the remote attestation features of the confidential computing components.
@@ -74,7 +73,6 @@ For example, it embeds the certificate's public key into the attestation stateme
 Instead of relying on a certificate authority, aTLS uses this attestation statement to establish trust in the certificate.
 The protocol can be used by clients to verify a server certificate, by a server to verify a client certificate, or for mutual verification (mutual aTLS).
 
-
 ## Encryption of state
 
 The Coordinator holds MarbleRun's state, which consists of the [manifest](../features/manifest.md), the [managed secrets](../features/secrets-management.md), and the [certificates for its CA](../features/attestation.md).
@@ -99,13 +97,11 @@ Every recovery party is defined in the manifest with its own public RSA key.
 The Coordinator generates a share of the recovery secret for every party and encrypts it with the corresponding RSA key.
 During a recovery event, every party will upload their share of the secret, which are all XORed together by the Coordinator to receive the combined key for decrypting the DEK.
 
-
 ### Distributed Coordinator
 
-The [distributed Coordinator](../features/recovery.md#distributed-coordinator) works similarly. However, all Coordinators share the same state stored encrypted in the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) called *marble-state*.
+The [distributed Coordinator](../features/recovery.md#distributed-coordinator) works similarly. However, all Coordinators share the same state stored encrypted in the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) called *marblerun-state*.
 In contrast to the single instance, the KEK is generated at start-up by the first instance.
 The existing Coordinators authenticate every new Coordinator instance via remote attestation, and the KEK is subsequently shared via the secure and attested TLS connection.
-Every Coordinator instance uses its own SGX Product (Sealing) Key to seal the KEK into a Kubernetes [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) structure called "KEK."
-
+Every Coordinator instance uses its own SGX Product (Sealing) Key to seal the KEK into a Kubernetes [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) called *marblerun-sealed-kek*.
 
 ![Encrypted state distributed](../_media/enc-state-distributed.svg)

docs/versioned_docs/version-1.3/features/attestation.md

@@ -21,7 +21,14 @@ The [manifest](../workflows/define-manifest.md) describes which Marbles (service
 
 The Coordinator enforces the manifest and only admits the desired Marbles to the cluster.
 Each Marble registers itself with a quote via gRPC to the Coordinator. This quote is tied to the TLS session of the gRPC call. It contains the Marble's measurements. The Coordinator compares them to the manifest to ensure the Marble's identity and integrity.
-The [Marble's TLS credentials](../features/secrets-management.md) are generated by the Coordinator and signed with the intermediate certificate.
+
+More specifically, the Marble generates an [ECDSA](https://www.secg.org/sec1-v2.pdf#page=49) private key using curve [P256](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf#page=111), and a self-signed TLS certificate.
+It then hashes the certificate using SHA-256 and creates an SGX quote over the hash.
+The Marble uses this certificate to establish a TLS connection with the Coordinator and send the quote.
+The Coordinator verifies the Marble's measurements contained in the quote against the manifest and makes sure the Marble's TLS certificate matches the quote.
+If all checks pass, the Marble is admitted into the cluster.
+
+The [Marble's TLS credentials](../features/secrets-management.md#certificates) are generated by the Coordinator and signed with the intermediate certificate.
 The Coordinator's certificate chain and the freshly generated Marble certificate are then delivered to the Marble.
 
 ![Marble deployment](../_media/marble_deployment.svg)

docs/versioned_docs/version-1.4/architecture/security.md

@@ -65,7 +65,6 @@ Depending on the Marble's runtime, the certificate can be used [manually](../wor
 
 ![PKI Certificate chain](../_media/cert-chain.svg)
 
-
 ## Attested TLS (aTLS)
 
 In a confidential computing environment, attested TLS (aTLS) can establish secure connections between two parties using the remote attestation features of the confidential computing components.
@@ -74,7 +73,6 @@ For example, it embeds the certificate's public key into the attestation stateme
 Instead of relying on a certificate authority, aTLS uses this attestation statement to establish trust in the certificate.
 The protocol can be used by clients to verify a server certificate, by a server to verify a client certificate, or for mutual verification (mutual aTLS).
 
-
 ## Encryption of state
 
 The Coordinator holds MarbleRun's state, which consists of the [manifest](../features/manifest.md), the [managed secrets](../features/secrets-management.md), and the [certificates for its CA](../features/attestation.md).
@@ -99,13 +97,11 @@ Every recovery party is defined in the manifest with its own public RSA key.
 The Coordinator generates a share of the recovery secret for every party and encrypts it with the corresponding RSA key.
 During a recovery event, every party will upload their share of the secret, which are all XORed together by the Coordinator to receive the combined key for decrypting the DEK.
 
-
 ### Distributed Coordinator
 
-The [distributed Coordinator](../features/recovery.md#distributed-coordinator) works similarly. However, all Coordinators share the same state stored encrypted in the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) called *marble-state*.
+The [distributed Coordinator](../features/recovery.md#distributed-coordinator) works similarly. However, all Coordinators share the same state stored encrypted in the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) called *marblerun-state*.
 In contrast to the single instance, the KEK is generated at start-up by the first instance.
 The existing Coordinators authenticate every new Coordinator instance via remote attestation, and the KEK is subsequently shared via the secure and attested TLS connection.
-Every Coordinator instance uses its own SGX Product (Sealing) Key to seal the KEK into a Kubernetes [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) structure called "KEK."
-
+Every Coordinator instance uses its own SGX Product (Sealing) Key to seal the KEK into a Kubernetes [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) called *marblerun-sealed-kek*.
 
 ![Encrypted state distributed](../_media/enc-state-distributed.svg)