From 6bd62f0f7ad6a970e09dd82f26acbd5d80b37671 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Wei=C3=9Fe?= <66256922+daniel-weisse@users.noreply.github.com> Date: Wed, 30 Nov 2022 08:29:17 +0100 Subject: [PATCH] Update docs to new measurement format (#660) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Remove fetch-measurements from create workflow * Explain new measurements format in docs Signed-off-by: Daniel Weiße --- .github/docs/release.md | 7 +++- CHANGELOG.md | 2 + docs/docs/getting-started/first-steps.md | 14 ++----- docs/docs/reference/config-migration.md | 19 ++++++++- docs/docs/workflows/create.md | 8 ---- docs/docs/workflows/verify-cluster.md | 50 +++++++++++++++++++++--- 6 files changed, 73 insertions(+), 27 deletions(-) diff --git a/.github/docs/release.md b/.github/docs/release.md index 9e81e2615..aa9a6bad9 100644 --- a/.github/docs/release.md +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b9cf72d0..4fa5f9a09 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/docs/getting-started/first-steps.md b/docs/docs/getting-started/first-steps.md index 3f94f9d6f..1f0eacae2 100644 --- a/docs/docs/getting-started/first-steps.md +++ b/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. - - ```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`. +3. 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" diff --git a/docs/docs/reference/config-migration.md b/docs/docs/reference/config-migration.md index d90eb1b57..a084f216c 100644 --- a/docs/docs/reference/config-migration.md +++ b/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:
@@ -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` |
+- 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 + ``` diff --git a/docs/docs/workflows/create.md b/docs/docs/workflows/create.md index f9593cd4d..50853c984 100644 --- a/docs/docs/workflows/create.md +++ b/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. diff --git a/docs/docs/workflows/verify-cluster.md b/docs/docs/workflows/verify-cluster.md index f9a98fe05..650b76274 100644 --- a/docs/docs/workflows/verify-cluster.md +++ b/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`. -Not all keys under `measurements` will have a matching index under `enforcedMeasurements`. +The configuration file then contains a list of `measurements` looking similar to the following: + +```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 are additionally set under `enforcedMeasurements` an error is emitted and attestation fails. -If attestation fails, the new node can't join the cluster. +For mismatching measurements that have set `warnOnly` to `true` only warning is emitted. +For mismatching measurements that have set `warnOnly` to `false` an error is emitted and attestation fails. +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`.