From cda77f85b7c5e111d35c0cf48eacf32633498c25 Mon Sep 17 00:00:00 2001 From: Simon Ott Date: Tue, 4 Jun 2024 15:30:33 +0000 Subject: [PATCH] example-setup: refactoring Signed-off-by: Simon Ott --- README.md | 2 +- doc/ids-example-setup.md | 4 +- doc/manual-setup.md | 115 +++++++++++------- .../metadata-raw/app.description.json | 3 +- .../{setup-full-simple => setup-cmc} | 16 ++- .../{setup-full-ids => setup-cmc-ids} | 4 +- .../{sgx-setup-sample => setup-cmc-sgx} | 10 +- example-setup/{setup-pki-simple => setup-pki} | 2 +- example-setup/update-app-manifest | 2 +- example-setup/update-app-manifest-live | 2 +- .../{update-full-simple => update-platform} | 4 +- .../{update-full-ids => update-platform-ids} | 4 +- 12 files changed, 97 insertions(+), 71 deletions(-) rename example-setup/{setup-full-simple => setup-cmc} (71%) rename example-setup/{setup-full-ids => setup-cmc-ids} (91%) rename example-setup/{sgx-setup-sample => setup-cmc-sgx} (94%) rename example-setup/{setup-pki-simple => setup-pki} (95%) rename example-setup/{update-full-simple => update-platform} (97%) rename example-setup/{update-full-ids => update-platform-ids} (97%) diff --git a/README.md b/README.md index 5ff5ac5c..d07a0924 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ git clone https://github.com/Fraunhofer-AISEC/cmc.git ``` Create a demo PKI and all required metadata: ``` -./cmc/example-setup/setup-full-simple json +./cmc/example-setup/setup-cmc json ``` `` is the relative or absolute path to the cloned `cmc` repository. `` is an arbitrary folder that will be created and that will store metadata and diff --git a/doc/ids-example-setup.md b/doc/ids-example-setup.md index 1922306d..54e5685c 100644 --- a/doc/ids-example-setup.md +++ b/doc/ids-example-setup.md @@ -1,7 +1,7 @@ # Quick Demo Setup IDS Use Case The CMC repository contains a complete local example setup including a demo CA and all configurations and metadata matching the requirements for representing the certification scheme from the the International Data Spaces (IDS) . -The setup script `example-setup/setup-full-ids` sets up everything to quickly test remote attestation with the IDS specific roles and CAs. +The setup script `example-setup/setup-cmc-ids` sets up everything to quickly test remote attestation with the IDS specific roles and CAs. It was tested on Ubuntu 22.04 LTS. ## Setup @@ -9,7 +9,7 @@ It was tested on Ubuntu 22.04 LTS. ```sh git clone https://github.com/Fraunhofer-AISEC/cmc.git -/example-setup/setup-full-ids +/example-setup/setup-cmc-ids ``` with `` as the relative or absolute path to the cloned `cmc` repository and `` as an arbitrary folder where metadata and configuration files are stored. diff --git a/doc/manual-setup.md b/doc/manual-setup.md index badb8bc1..65039d7c 100644 --- a/doc/manual-setup.md +++ b/doc/manual-setup.md @@ -31,17 +31,14 @@ Install the [EGo framework](https://github.com/edgelesssys/ego). ## Build and Install the CMC and Tools ```sh -# 1. Setup a folder for the cmc workspace (e.g. in your home directory) -CMC_ROOT=$HOME/cmc-workspace +# Clone the CMC repo +git clone https://github.com/Fraunhofer-AISEC/cmc -# 2. Clone the CMC repo -git clone https://github.com/Fraunhofer-AISEC/cmc $CMC_ROOT/cmc - -# 3. Build CMC -cd $CMC_ROOT/cmc +# Build CMC +cd cmc go build ./... -# 4. Install CMC $GOPATH/bin (export PATH=$PATH:$HOME/go/bin -> .profile/.bashrc) +# Install CMC $GOPATH/bin (export PATH=$PATH:$HOME/go/bin -> .profile/.bashrc) go install ./... ``` @@ -49,22 +46,26 @@ go install ./... ### 1. Create a folder for your CMC configuration +Do this outside the repository: ```sh -mkdir -p $CMC_ROOT/cmc-data +mkdir -p cmc-data ``` ### 2. Copy and adjust the example metadata templates For the example, it is sufficient to copy the templates. For information on how to adjust the metadata, see [Generating Metadata and Setup Alternatives](#generating-metadata-and-setup-alternatives) ```sh -cp -r $CMC_ROOT/cmc/example-setup/* $CMC_ROOT/cmc-data +cp -r cmc/example-setup/* cmc-data ``` +Generate a PKI suitable for your needs. A minimal PKI can be setup as follows: ```sh -# 3. Generate a PKI suitable for your needs. You can use the simple PKI example-setup for testing: -$CMC_ROOT/cmc-data/setup-simple-pki -i $CMC_ROOT/cmc-data -o $CMC_ROOT/cmc-data/pki +# Generate example PKI +./cmc-data/setup-pki -i ./cmc-data -o ./cmc-data/pki ``` +For a more complex PKI, have a look at the [IDS-Setup](./ids-example-setup.md). + ### 3. Generate metadata The example setup (folder `cmc/example-setup`) contains templates for the required metadata files @@ -77,7 +78,9 @@ components - **app.manifest.json**: Contains the reference values for an app on the system - **company.description.json**: Optional, metadata describing the operater of the computing platform - **device.description.json**: Metadata describing the overall platform, contains links to -RTM Manifest, OS Manifest and App Manifests +RTM Manifest, OS Manifest +- **app.description.json**: Metadata describing an application, links to an App Manifest. Must be +embedded in to the `appDescriptions` property of the device description. - **device.config.json**: Signed local device configuration, contains e.g. the parameters for the Certificate Signing Requests for the attestation and identity keys @@ -85,7 +88,7 @@ the Certificate Signing Requests for the attestation and identity keys The attestation report can be serialized to JSON and signed via JSON Web signatures (JWS), or to CBOR and signed via CBOR Object Signing and Encryption (COSE). This must be specified in the -configuration of the *cmcd* (see [CMCD Configuration](#cmcd-configuration) and the +configuration of the *cmcd* (see [CMCD Configuration](#cmcd-configuration)) and the provisioning server (see [Provisioning Server Configuration](#provisioning-server-configuration)) As CBOR is a binary serialization format, the serialized data is not human-readable. Therefore, the @@ -94,7 +97,7 @@ to CBOR before signing them. To convert a metadata file from JSON to CBOR: ```sh # Convert JSON to CBOR using the converter-tool -$CMC_ROOT/cmc/tools/cmc-converter/cmc-converter -in .json -out -inform json -outform cbor +cmc/tools/cmc-converter/cmc-converter -in .json -out -inform json -outform cbor ``` #### Reference Values @@ -113,42 +116,60 @@ within a build-system such as *Yocto* or *Buildroot*). Tools for parsing and cal are available as open source [tpm-pcr-tools](). **Parsing the reference values on a good reference platform and inserting them into the manifest** + +Parse the values of the RTM PCRs from the kernel's binary bios measurement log ```sh -# Parse the values of the RTM PCRs from the kernel's binary bios measurement log -ements as reference values -referenceValues=$(sudo parse-srtm-pcrs -p 0,1,2,3,4,5,6,7 -f json) -# Delete existing reference values in the RTM Manifest -jq 'del(.referenceValues[])' $CMC_ROOT/cmc-data/metadata-raw/rtm.manifest.json | sponge $CMC_ROOT/cmc-data/metadata-raw/rtm.manifest.json -# Add new reference values to the RTM Manifest -jq --argjson ver "$referenceValues" '.referenceValues += $ver' $CMC_ROOT/cmc-data/metadata-raw/rtm.manifest.json | sponge $CMC_ROOT/cmc-data/metadata-raw/rtm.manifest.json +sudo parse-srtm-pcrs -p 0,1,2,3,4,5,6,7 -f json +``` +Then insert those values into the json `referenceValues` array in the RTM manifest. + +Parse the values of the OS PCRs from the kernel's binary bios measurement log: +```sh +sudo parse-srtm-pcrs -p 8,9,11,12,14,15 -f json +``` +Then insert those values into the json `referenceValues` array in the OS manifest. -# Parse the values of the OS PCRs from the kernel's binary bios measurement log -referenceValues=$(sudo parse-srtm-pcrs -p 8,9 -f json) -# Delete existing reference values in the OS Manifest -jq 'del(.referenceValues[])' $CMC_ROOT/cmc-data/metadata-raw/os.manifest.json | sponge $CMC_ROOT/cmc-data/metadata-raw/os.manifest.json -# Add new reference values to the OS Manifest -jq --argjson ver "$referenceValues" '.referenceValues += $ver' $CMC_ROOT/cmc-data/metadata-raw/os.manifest.json | sponge $CMC_ROOT/cmc-data/metadata-raw/os.manifest.json +For the host applications, if the kernel's Integrity Measurement Architecture (IMA) is activated: +```sh +sudo parse-ima-pcr ``` +Then insert those values into the json `referenceValues` array in an app manifest. **Calculating the reference values based on software artifacts** -This currently only works for QEMU VMs with OVMF and a Linux kernel +This currently only works for QEMU VMs with OVMF and a Linux kernel. it is recommended to use +the parsing alternative. + +Calculate the RTM Manifest reference values: ```sh -# Calculate reference values for the RTM Manifest -referenceValues=$($(calculate-srtm-pcrs \ +calculate-srtm-pcrs \ --format json \ --pcrs 0,1,2,3,6,7 \ --eventlog \ --kernel "linux-kernel.bzImage" \ --ovmf "OVMF.fd" \ --config "calculate-pcrs.cfg" \ - ) +``` +Then insert those values into the json `referenceValues` array in the RTM Manifest. -# Delete all existing reference values in the RTM manifest -jq 'del(.referenceValues[])' $CMC_ROOT/cmc-data/metadata-raw/rtm.manifest.json | sponge $CMC_ROOT/cmc-data/metadata-raw/rtm.manifest.json -# Insert new reference values to the RTM Manifest -jq --argjson ver "$referenceValues" '.referenceValues += $ver' $CMC_ROOT/cmc-data/metadata-raw/rtm.manifest.json | sponge $CMC_ROOT/cmc-data/metadata-raw/rtm.manifest.json +Calculate the OS Manifest reference values: +```sh +calculate-srtm-pcrs \ + --kernel "linux-kernel.bzImage" \ + --cmdline "linux-commandline" \ + --ovmf "OVMF.fd" \ + --format json \ + --pcrs "4,5,8,9,11,12,13,14,15" \ + --eventlog \ +``` +Then insert those values into the json `referenceValues` array in the OS Manifest. + +For the host applications, if the kernel's Integrity Measurement Architecture (IMA) is activated: +```sh +# In this case, use PCR10 and the IMA ima-ng template for all folders containing binaries and libs +sudo calculate-ima-pcr -t 10 -i ima-ng -p /usr/bin -p /usr/sbin -p /usr/lib ``` +Then insert those values into an app manifest. ##### AMD SNP Reference Values @@ -163,7 +184,7 @@ tbd The reference values for Intel SGX consist of a fingerprint of the Intel Root CA certificate, the TCB Info and QE Identity structures, the enclave product ID (ISV Prod ID), the security version of the enclave (ISVSVN), expected enclave attributes (e.g. DEBUG, Mode64Bit, etc.), a hash of the enclave measurement (MRENCLAVE) and a hash of the enclave signing key (MRSIGNER). The Root CA certificate, TCB Info and QE Identity structures can be retrieved from the [Intel API](https://api.portal.trustedservices.intel.com/content/documentation.html). ISV SVN and ISV Prod ID are assigned by the enclave author. The EGo framework sets these values to 1 by default. -The MRENCLAVE and MRSIGNER values for an enclave can be retrieved via the EGo CLI tool with the commands ```ego uniqueid $ENCLAVE_PROGRAM``` and ```ego signerid $ENCLAVE_PROGRAM```. +The MRENCLAVE and MRSIGNER values for an enclave can be retrieved via the EGo CLI tool with the commands `ego uniqueid $ENCLAVE_PROGRAM` and `ego signerid $ENCLAVE_PROGRAM`. ### 4. Sign the metadata @@ -171,10 +192,10 @@ This example uses JSON/JWS as serialization format. For different formats see [Serialization Format](#serialization-format) ```sh -IN=$CMC_ROOT/cmc-data/metadata-raw -OUT=$CMC_ROOT/cmc-data/metadata-signed -KEY=$CMC_ROOT/cmc-data/pki/signing-cert-key.pem -CHAIN=$CMC_ROOT/cmc-data/pki/signing-cert.pem,$CMC_ROOT/cmc-data/pki/ca.pem +IN=cmc-data/metadata-raw +OUT=cmc-data/metadata-signed +KEY=cmc-data/pki/signing-cert-key.pem +CHAIN=cmc-data/pki/signing-cert.pem,cmc-data/pki/ca.pem mkdir -p $OUT @@ -195,14 +216,14 @@ Adjust the configuration files for the tools as required according to ```sh # Start the EST server that supplies the certificates and metadata for the cmcd -./estserver -config $CMC_ROOT/cmc-data/est-server-conf.json +./estserver -config cmc-data/est-server-conf.json ``` #### Run the cmcd ```sh # Build and run the cmcd -./cmcd -config $CMC_ROOT/cmc-data/cmcd-conf.json +./cmcd -config cmc-data/cmcd-conf.json ``` #### Generate and Verify Attestation Reports @@ -212,7 +233,7 @@ Adjust the configuration files for the tools as required according to ./testtool -mode generate # Run the testtool to verify the attestation report (stored in current folder unless otherwise specified) -./testtool -mode verify -ca $CMC_ROOT/cmc-data/pki/ca.pem +./testtool -mode verify -ca cmc-data/pki/ca.pem ``` #### Establish Attested TLS Connections @@ -220,17 +241,17 @@ Adjust the configuration files for the tools as required according to ```sh # Run an attested TLS server -./testtool -mode listen -addr 0.0.0.0:4443 -ca $CMC_ROOT/cmc-data/pki/ca.pem -mtls +./testtool -mode listen -addr 0.0.0.0:4443 -ca cmc-data/pki/ca.pem -mtls # Run an attested TLS client estblishing a mutually attested TLS connection to the server -./testtool -mode dial -addr localhost:4443 -ca $CMC_ROOT/cmc-data/pki/ca.pem -mtls +./testtool -mode dial -addr localhost:4443 -ca cmc-data/pki/ca.pem -mtls ``` #### Establish Attested HTTPS Connections ```sh # Run two attested HTTPS servers -./testtool -config $CMC_ROOT/testtool-config.json -addr 0.0.0.0:8081 -mode serve +./testtool -config testtool-config.json -addr 0.0.0.0:8081 -mode serve # Perform multiple user-specified attested HTTPS requests to both servers. Each connection is # attested, while multiple requests to the same server use the established attested TLS connections diff --git a/example-setup/metadata-raw/app.description.json b/example-setup/metadata-raw/app.description.json index 96883e2d..6c8ef8da 100644 --- a/example-setup/metadata-raw/app.description.json +++ b/example-setup/metadata-raw/app.description.json @@ -3,5 +3,6 @@ "name": "de.test.app-description.example", "version": "2024-02-22T15:36:34Z", "appManifest": "de.test.app.example", - "externalConnections": [] + "externalConnections": [], + "environment": [] } \ No newline at end of file diff --git a/example-setup/setup-full-simple b/example-setup/setup-cmc similarity index 71% rename from example-setup/setup-full-simple rename to example-setup/setup-cmc index b89ffe71..94de4c24 100755 --- a/example-setup/setup-full-simple +++ b/example-setup/setup-cmc @@ -8,7 +8,7 @@ source "${dir}/utils.sh" export PATH=${PATH}:${HOME}/go/bin if [[ "$#" -ne 3 ]]; then - echo "Usage: ./setup-full-simple " + echo "Usage: ./setup-cmc " exit fi @@ -53,8 +53,14 @@ go install ./... # Copy metadata templates cp -r "${cmc}/example-setup/"* "${data}" -# Generate a PKI suitable for your needs. You can use the simple PKI example-setup for testing: -"${data}/setup-pki-simple" -i "${data}" -o "${data}/pki" +# Generate a PKI +"${data}/setup-pki" -i "${data}" -o "${data}/pki" -# Update and sign metadata -"${data}/update-full-simple" "${data}" "${ser}" +# Generate and sign platform (RTM and OS) metadata +"${data}/update-platform" "${data}" "${ser}" + +# Generate example manifest for host apps +"${data}/update-app-manifest-live" "${data}" "${ser}" + +# Generate container example manifest +"${data}/update-container-manifest-live" docker.io/library/ubuntu:22.04 "${data}" "${cmc}" "${ser}" \ No newline at end of file diff --git a/example-setup/setup-full-ids b/example-setup/setup-cmc-ids similarity index 91% rename from example-setup/setup-full-ids rename to example-setup/setup-cmc-ids index ab9a80c5..4d9f5ed2 100755 --- a/example-setup/setup-full-ids +++ b/example-setup/setup-cmc-ids @@ -8,7 +8,7 @@ source "${dir}/utils.sh" export PATH=${PATH}:${HOME}/go/bin if [[ "$#" -ne 3 ]]; then - echo "Usage: ./setup-full-ids " + echo "Usage: ./setup-cmc-ids " exit 1 fi @@ -57,6 +57,6 @@ cp -r "${cmc}/example-setup/"* "${data}" "${data}/setup-pki-ids" -i "${data}/pki-input-ids" -o "${data}/pki" # Update and sign metadata -"${data}/update-full-ids" "${data}" "${ser}" +"${data}/update-platform-ids" "${data}" "${ser}" diff --git a/example-setup/sgx-setup-sample b/example-setup/setup-cmc-sgx similarity index 94% rename from example-setup/sgx-setup-sample rename to example-setup/setup-cmc-sgx index 57dc043c..1bac689f 100755 --- a/example-setup/sgx-setup-sample +++ b/example-setup/setup-cmc-sgx @@ -7,8 +7,8 @@ dir="$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd -P)" source "${dir}/utils.sh" export PATH=${PATH}:${HOME}/go/bin -if [[ "$#" -ne 5 ]]; then - echo "Usage: ./setup-full-simple " +if [[ "$#" -ne 3 ]]; then + echo "Usage: ./setup-cmc-sgx " exit fi @@ -16,8 +16,6 @@ fi cmc="$(abs_path "${1}")" data="$(abs_path "${2}")" ser="${3}" -mrenclave="${4}" -mrsigner="${5}" if [[ ! -d "$cmc" ]]; then echo "cmc directory does not exist. Did you clone the repository? Abort.." @@ -54,8 +52,8 @@ mrsigner=$(echo "$(ego signerid testtool)" | awk 'NR==1') # Copy metadata templates cp -r "${cmc}/example-setup/"* "${data}" -# Generate a PKI suitable for your needs. You can use the simple PKI example-setup for testing: -"${data}/setup-pki-simple" -i "${data}" -o "${data}/pki" +# Generate a PKI +"${data}/setup-pki" -i "${data}" -o "${data}/pki" cd "${data}" diff --git a/example-setup/setup-pki-simple b/example-setup/setup-pki similarity index 95% rename from example-setup/setup-pki-simple rename to example-setup/setup-pki index 3ee993c3..bf3298b5 100755 --- a/example-setup/setup-pki-simple +++ b/example-setup/setup-pki @@ -10,7 +10,7 @@ input="${cmc}/example-setup" out="${dir}" print_usage() { - printf "Usage: ./setup-pki-simple [-i ] [-o ] [-o " + echo "Usage: ./update-platform " exit 1 fi @@ -19,7 +19,7 @@ out="${data}/metadata-signed" ser="${2}" if [[ ! -d "${data}" ]]; then - echo "Data directory ${1} does not exist. Did you run the setup-full-simple script? Abort.." + echo "Data directory ${1} does not exist. Did you run the setup-cmc script? Abort.." exit 1 fi diff --git a/example-setup/update-full-ids b/example-setup/update-platform-ids similarity index 97% rename from example-setup/update-full-ids rename to example-setup/update-platform-ids index b7cc1761..7740cc78 100755 --- a/example-setup/update-full-ids +++ b/example-setup/update-platform-ids @@ -8,7 +8,7 @@ source "${dir}/utils.sh" export PATH=${PATH}:${HOME}/go/bin if [[ "$#" -ne 2 ]]; then - echo "Usage: ./update-full-ids " + echo "Usage: ./update-platform-ids " exit 1 fi @@ -19,7 +19,7 @@ out="${data}/metadata-signed" ser="$2" if [[ ! -d "${data}" ]]; then - echo "Data directory ${data} does not exist. Did you run the setup-full-ids script? Abort.." + echo "Data directory ${data} does not exist. Did you run the setup-cmc-ids script? Abort.." exit 1 fi