Update docs to new measurement format (#660)

* Remove fetch-measurements from create workflow

* Explain new measurements format in docs

Signed-off-by: Daniel Weiße <dw@edgeless.systems>

.github/docs/release.md

@@ -93,20 +93,23 @@ This checklist will prepare `v1.3.0` from `v1.2.0`. Adjust your version numbers
            gh workflow run generate-measurements.yml --ref release/v$minor -F osImage=v$ver -F isDebugImage=false -F signMeasurements=true
         ```
 
-    13. Create a new tag on this release branch
+    13. Update expected measurements in [`measurements.go`](/internal/attestation/measurements/measurements.go) using the generated measurements from step 12 and **push your changes**.
+
+    14. Create a new tag on this release branch.
 
         ```sh
         git tag v$ver
         git tags --push
         ```
 
-        * Run [Release CLI](https://github.com/edgelesssys/constellation/actions/workflows/release-cli.yml) action on the tag
+    15. Run [Release CLI](https://github.com/edgelesssys/constellation/actions/workflows/release-cli.yml) action on the tag.
 
         ```sh
         gh workflow run release-cli.yml --ref v$ver
         ```
 
         * The previous step will create a draft release. Check build output for link to draft release. Review & approve.
+
 6. Export, download and make image available in S3 for trusted launch users. To achieve this:
 
     ```sh

CHANGELOG.md

@@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Constellation operators are now deployed using Helm.
 - Updated the config version to v2. Check [how to migrate your config](https://constellation-docs.edgeless.systems/constellation/next/reference/config-migration).
 - OS images are now configured globally in the `images` field of the configuration file.
+- The `measurements` entry in the CLI now uses an updated format, merging `enforcedMeasurements` and old `measurements` into one
+- Expected measurements in the config and Constellation's Cluster-ID are now hex encoded by default. Base64 is still supported.
 
 ### Deprecated
 <!-- For soon-to-be removed features. -->

docs/docs/getting-started/first-steps.md

@@ -232,15 +232,7 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step
 
     :::
 
-3. Download the trusted measurements for your configured image.
+3. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml`.
-
-    ```bash
-    constellation config fetch-measurements
-    ```
-
-    For details, see the [verification section](../workflows/verify-cluster.md).
-
-4. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml`.
 
     :::tip
 
@@ -259,7 +251,7 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step
     Your Constellation cluster was created successfully.
     ```
 
-5. Initialize the cluster
+4. Initialize the cluster
 
     ```bash
     constellation init
@@ -290,7 +282,7 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step
 
     :::
 
-6. Configure kubectl
+5. Configure kubectl
 
     ```bash
     export KUBECONFIG="$PWD/constellation-admin.conf"

docs/docs/reference/config-migration.md

@@ -4,7 +4,7 @@ This document describes breaking changes in the configuration file format betwee
 
 ## Migrating from CLI versions < 2.3
 
-- The `sshUsers` was deprecated in v2.2 and now has been eventually removed from the configuration in v2.3.
+- The `sshUsers` was deprecated in v2.2 and has now been removed from the configuration in v2.3.
   As an alternative for SSH, check the workflow section [Connect to nodes](https://constellation-docs.edgeless.systems/constellation/workflows/troubleshooting#connect-to-nodes).
 - The `image` field for each cloud service provider has been replaced with a global `image` field. Use the following mapping to migrate your configuration:
     <details>
@@ -37,3 +37,20 @@ This document describes breaking changes in the configuration file format betwee
     | GCP   | `projects/constellation-images/global/images/constellation-v2-1-0`                                                                                                                    | `v2.1.0`  |
     | GCP   | `projects/constellation-images/global/images/constellation-v2-0-0`                                                                                                                    | `v2.0.0`  |
     </details>
+- The `enforcedMeasurements` field has been removed and merged with the `measurements` field.
+  - To migrate your config containing a new image (`v2.3` or greater), remove the old `measurements` and `enforcedMeasurements` entries from your config and run `constellation fetch-measurements`
+  - To migrate your config containing an image older than `v2.3`, remove the `enforcedMeasurements` entry and replace the entries in `measurements` as shown in the example below:
+
+    ```diff
+    measurements:
+    -    0: DzXCFGCNk8em5ornNZtKi+Wg6Z7qkQfs5CfE3qTkOc8=
+    +    0:
+    +        expected: DzXCFGCNk8em5ornNZtKi+Wg6Z7qkQfs5CfE3qTkOc8=
+    +        warnOnly: true
+    -    8: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+    +    8:
+    +        expected: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+    +        warnOnly: false
+    -enforcedMeasurements:
+    -    - 8
+    ```

docs/docs/workflows/create.md

@@ -45,14 +45,6 @@ constellation config generate aws
 
 This creates the file `constellation-conf.yaml` in the current directory. [Fill in your CSP-specific information](../getting-started/first-steps.md#create-a-cluster) before you continue.
 
-Next, download the trusted measurements for your configured image.
-
-```bash
-constellation config fetch-measurements
-```
-
-For details, see the [verification section](../workflows/verify-cluster.md).
-
 ### Create
 
 Choose the initial size of your cluster.

docs/docs/workflows/verify-cluster.md

@@ -11,18 +11,57 @@ constellation config fetch-measurements
 ```
 
 This command performs the following steps:
+
 1. Download the signed measurements for the configured image. By default, this will use Edgeless Systems' public measurement registry.
 2. Verify the signature of the measurements. This will use Edgeless Systems' [public key](https://edgeless.systems/es.pub).
 3. Write measurements into configuration file.
 
-The configuration file then contains a list of key-value pairs (index, hash) under the `measurements` key and a list of indices under `enforcedMeasurements`.
+The configuration file then contains a list of `measurements` looking similar to the following:
-Not all keys under `measurements` will have a matching index under `enforcedMeasurements`.
+
+```yaml
+# ...
+measurements:
+    0:
+        expected: "0f35c214608d93c7a6e68ae7359b4a8be5a0e99eea9107ece427c4dea4e439cf"
+        warnOnly: false
+    4:
+        expected: "02c7a67c01ec70ffaf23d73a12f749ab150a8ac6dc529bda2fe1096a98bf42ea"
+        warnOnly: false
+    5:
+        expected: "e6949026b72e5045706cd1318889b3874480f7a3f7c5c590912391a2d15e6975"
+        warnOnly: true
+    8:
+        expected: "0000000000000000000000000000000000000000000000000000000000000000"
+        warnOnly: false
+    9:
+        expected: "f0a6e8601b00e2fdc57195686cd4ef45eb43a556ac1209b8e25d993213d68384"
+        warnOnly: false
+    11:
+        expected: "0000000000000000000000000000000000000000000000000000000000000000"
+        warnOnly: false
+    12:
+        expected: "da99eb6cf7c7fbb692067c87fd5ca0b7117dc293578e4fea41f95d3d3d6af5e2"
+        warnOnly: false
+    13:
+        expected: "0000000000000000000000000000000000000000000000000000000000000000"
+        warnOnly: false
+    14:
+        expected: "d7c4cc7ff7933022f013e03bdee875b91720b5b86cf1753cad830f95e791926f"
+        warnOnly: true
+    15:
+        expected: "0000000000000000000000000000000000000000000000000000000000000000"
+        warnOnly: false
+# ...
+```
+
+Each entry specifies the expected value of the Constellation, and whether the measurement should be enforced (`warnOnly: false`), or only a warning should be logged (`warnOnly: true`).
+
 This is because only a subset of the [available measurements](../architecture/attestation.md#runtime-measurements) can be locally reproduced and verified.
 
 During attestation, the validating side (CLI or [join service](../architecture/components.md#joinservice)) compares each measurement reported by the issuing side (first node or joining node) individually.
-For mismatching measurements that are only set under the `measurements` key a warning is emitted.
+For mismatching measurements that have set `warnOnly` to `true` only warning is emitted.
-For mismatching measurements that are additionally set under `enforcedMeasurements` an error is emitted and attestation fails.
+For mismatching measurements that have set `warnOnly` to `false` an error is emitted and attestation fails.
-If attestation fails, the new node can't join the cluster.
+If attestation fails for a new node, it isn't permitted to join the cluster.
 
 ## The *verify* command
 
@@ -37,6 +76,7 @@ constellation verify [--cluster-id ...]
 ```
 
 From the attestation statement, the command verifies the following properties:
+
 * The cluster is using the correct Confidential VM (CVM) type.
 * Inside the CVMs, the correct node images are running. The node images are identified through the measurements obtained in the previous step.
 * The unique ID of the cluster matches the one from your `constellation-id.json` file or passed in via `--cluster-id`.