Merge pull request #1737 from paulhowardarm/phVeraisonAWS

Create an Arm CCA attestation verifier in AWS with Veraison

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/cca-veraison-aws/_index.md

@@ -0,0 +1,60 @@
+---
+title: Build a CCA Attestation Service in AWS with Veraison
+
+draft: true
+cascade:
+    draft: true
+
+minutes_to_complete: 90
+
+who_is_this_for: This Learning Path is for developers who understand the basics of CCA attestation and the Veraison project, and who wish to progress onto creating a more scalable deployment of a CCA attestation verifier service in the cloud.
+
+
+learning_objectives:
+    - Create an attestation service in the AWS cloud using components from the Veraison project.
+    - Prepare the Veraison service to act as a verifier for Arm CCA attestation tokens by provisioning CCA platform endorsements.
+
+
+prerequisites:
+    - An [AWS account](/learning-paths/servers-and-cloud-computing/csp/aws/) for accessing AWS cloud services.
+    - An x86 computer running Ubuntu or Arch Linux, which is authorised to use the AWS account. Other build environments might be possible, but will require the configuration of toolchains for cross-compilation.
+
+
+author: Paul Howard
+
+### Tags
+skilllevels: Advanced
+subjects: Performance and Architecture
+armips:
+    - Cortex-A
+operatingsystems:
+    - Linux
+tools_software_languages:
+    - CCA
+    - Runbook
+
+
+
+
+further_reading:
+    - resource:
+        title: RATS architecture (RFC 9334) 
+        link: https://datatracker.ietf.org/doc/rfc9334/
+        type: documentation
+    - resource:
+        title: The Realm Management Monitor Specification
+        link: https://developer.arm.com/documentation/den0137/latest/
+        type: documentation
+    - resource:
+        title: The Attestation Results for Secure Interactions (AR4SI) 
+        link: https://datatracker.ietf.org/doc/draft-ietf-rats-ar4si/
+        type: documentation
+
+
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

content/learning-paths/servers-and-cloud-computing/cca-veraison-aws/_next-steps.md

@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       FIXED, DO NOT MODIFY THIS FILE
+# ================================================================================
+weight: 21                  # Set to always be larger than the content in this path to be at the end of the navigation.
+title: "Next Steps"         # Always the same, html page title.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---

content/learning-paths/servers-and-cloud-computing/cca-veraison-aws/aws-account-prep.md

@@ -0,0 +1,69 @@
+---
+title: Prepare AWS Account
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Prepare Your AWS Account
+For this learning path, you will need an active AWS account. If you do not have an AWS account, please refer to the [AWS documentation](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-creating.html).
+
+This learning path assumes that you have administrator level privileges for your AWS account.
+
+## Install the AWS Command-Line Tools
+For this section, you will need the AWS Command-Line (CLI) tools. Please refer to the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) for the steps needed to install the latest version of the AWS CLI.
+
+## Set Up Authentication
+You will need to configure your local environment to authenticate with the AWS cloud in order to build the Veraison deployment.
+
+The recommended way to do this is using Single Sign-On (SSO). The steps to do this are documented in Veraison's documentation [here](https://github.com/veraison/services/tree/main/deployments/aws#aws-account).
+
+It is important to ensure that authentication is configured correctly. The best way to do this is to run a simple command-line operation such as the following:
+
+```bash
+aws ec2 describe-availability-zones
+```
+
+You should see output similar to the following (depending on which AWS region you are using):
+
+```output
+{
+    "AvailabilityZones": [
+        {
+            "OptInStatus": "opt-in-not-required",
+            "Messages": [],
+            "RegionName": "eu-west-1",
+            "ZoneName": "eu-west-1a",
+            "ZoneId": "euw1-az1",
+            "GroupName": "eu-west-1-zg-1",
+            "NetworkBorderGroup": "eu-west-1",
+            "ZoneType": "availability-zone",
+            "State": "available"
+        },
+        {
+            "OptInStatus": "opt-in-not-required",
+            "Messages": [],
+            "RegionName": "eu-west-1",
+            "ZoneName": "eu-west-1b",
+            "ZoneId": "euw1-az2",
+            "GroupName": "eu-west-1-zg-1",
+            "NetworkBorderGroup": "eu-west-1",
+            "ZoneType": "availability-zone",
+            "State": "available"
+        },
+        {
+            "OptInStatus": "opt-in-not-required",
+            "Messages": [],
+            "RegionName": "eu-west-1",
+            "ZoneName": "eu-west-1c",
+            "ZoneId": "euw1-az3",
+            "GroupName": "eu-west-1-zg-1",
+            "NetworkBorderGroup": "eu-west-1",
+            "ZoneType": "availability-zone",
+            "State": "available"
+        }
+    ]
+}
+```
+If this operation fails, please do not attempt to proceed with the next steps of this learning path. Refer to [AWS documentation](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-authentication.html) for help with troubleshooting this step.

content/learning-paths/servers-and-cloud-computing/cca-veraison-aws/cert-validation-and-algorithm.png

@@ -0,0 +1,74 @@
+---
+title: Create the Veraison Deployment
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Create the Veraison Deployment
+Now that your AWS account, internet domain and certificate are prepared, you are ready to deploy the Veraison services into AWS.
+
+This process is highly automated, but it takes some time, because a number of resources need to be created in AWS. Be prepared for this step to take from 30 to 60 minutes, although there won't be too much for you to do during this time. You will just run a command to kick off the process.
+
+The deployment process is documented in [Veraison's GitHub repository](https://github.com/veraison/services/blob/main/deployments/aws/README.md). 
+
+You can follow the instructions below to deploy the Veraison services into AWS:
+
+Use the [Bootstrap](https://github.com/veraison/services/tree/main/deployments/aws#bootstrap) process first to clone the Veraison source code from GitHub and set up your build environment. This will take care of installing the dependencies that you need on your development machine.
+
+```bash
+cd $HOME
+git clone https://github.com/veraison/services.git
+cd services/deployments/aws
+make bootstrap
+```
+Once your build environment is bootstrapped, you will use the [Quickstart](https://github.com/veraison/services/tree/main/deployments/aws#quickstart) procedure to provide some AWS configuration and create the deployment.
+
+You need to provide your AWS account-specific configuration that specifies the IDs of the VPC and subnets that will be used for the deployment as well as the CIDR that will be granted access to the deployment. In this deployment you will use `misc/arm.cfg` file for example. Make sure you update `VERAISON_AWS_REGION` to the same region where you created your AWS Certificate for your new domain.`VERAISON_AWS_DNS_NAME` will need to match the domain name you chose. 
+
+Once the account-specific config file is created, define `AWS_ACCOUNT_CFG` environment variable to point to it and then create the deployment.
+
+```bash
+source env/env.bash
+export AWS_ACCOUNT_CFG=misc/arm.cfg  # replace with path to your config
+make deploy
+```
+
+You do not need to use the end-to-end flow as described in the document. Later in this learning path, you will perform some additional steps to prepare and use the Veraison services.
+
+The rest of the document provides additional information about how to manage the deployment, but you don't need this now.
+
+## Check the Deployment Status
+In the command shell where you ran the steps above, run the following command:
+
+```bash
+veraison status
+```
+This command will output a status report for the deployment. If successful, it will include information about:-
+
+- The Amazon Machine Images (AMIs) that have been used for the servers.
+- The status of the VPC stack, support stack and services stack. All of these should read as `created`.
+- Information about RDS, ElastiCache and EC2 resources in the deployment.
+- The version of the Veraison software that is running.
+- The public part of the key that is used to sign attestation results (known as the EAR Verification Key).
+- A list of media types that Veraison will accept as attestation evidence.
+- A list of media types that Veraison will accept as endorsements.
+
+Use the following command to test the REST API endpoint of the verification service. Remember to substitute `example-veraison.com` with the domain name that you used in the initial step, but you will need to keep the `services` prefix as shown.
+
+```bash
+curl https://services.example-veraison.com:8443/.well-known/veraison/verification
+```
+
+If it succeeds, this command produces some JSON output, including the EAR verification key.
+
+Use the following command to test the REST API endpoint of the endorsement provisioning service. Remember to substitute `example-veraison.com` with the domain name that you used in the initial step.
+
+```bash
+curl https://services.example-veraison.com:9443/.well-known/veraison/provisioning
+```
+
+This command will produce JSON output containing the list of supported media types for endorsement.
+
+Your Veraison services are now deployed and working, and you can proceed to the next step.

content/learning-paths/servers-and-cloud-computing/cca-veraison-aws/create-domain.png

@@ -0,0 +1,57 @@
+---
+title: Create the Domain and Certificate
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Create Your Domain in Route53
+Veraison provides cloud services for attestation. These services are published on the internet and are accessible via HTTPS using RESTful APIs. Like all cloud services, they require a suitable internet domain that allows the consumers of those services to locate them. Domains are named using string labels separated by dots (full stops). You will be familiar with domain names such as `www.amazon.com` - they allow public internet resources to be located conveniently and routed using shared internet infrastructure such as DNS.
+
+[Route53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html) is an AWS service that allows you to register and manage domains. In order to create your Veraison deployment in AWS, you will first need to choose a domain name and register it with Route53.
+
+Your domain name _must_ be unique and specific to your Veraison deployment. Remember that this domain name will be used to create public internet services, so it cannot clash with any other domains that exist on the public internet. In this learning path, we will use `example-veraison.com` as an illustrative example of a domain name. However, _do not_ use this name for your own deployment. Choose your own name, and use it in place of the example as you progress through the learning path.
+
+The easiest way to create your domain is using the Route53 dashboard in the AWS Management Console. Using your web browser and AWS account credentials, sign into the console and search for the Route53 service. This will take you to the Route53 dashboard. Locate the domain registration option, which will look something like the image below. Remember to use your own domain name where highlighted, not the `example-veraison.com` domain.
+
+**Note:** If you have an existing domain and you wish to transfer it into Route53, instead of creating a new domain, you can use this option as well as shown below. Otherwise, the instructions here assume that you are creating a new domain.
+
+![Register Domain](./create-domain.png)
+
+Route53 will check the domain name for you to ensure that it doesn't clash with others on the internet. Provided that there isn't a clash, Route53 will give you the option of registering your chosen domain name, or some alternatives. For example, it might suggest you could use `example-veraison.net` or `example-veraison.org`.
+
+Route53 will charge an annual fee for the domain registration, and the size of this fee can differ depending on your name choice. Choose the name that you would like to use, and proceed to complete the registration process using the on-screen instructions in your browser.
+
+## Request Your Domain Certificate
+Veraison publishes secure cloud services that can be reached on the internet using HTTPs. This means that you will need a certificate for your registered domain. A certificate will allow consumers of your Veraison services to trust those services and connect with them securely.
+
+The [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) can be used to issue a certificate for your domain. Navigate to this service within the AWS Management Console in your web browser.
+
+Select "Request Certificate" from the menu on the left as shown.
+
+![Request Certificate](./request-certificate.png)
+
+On the first page of the certificate wizard, select the option to request a **public certificate** as shown below and click **Next**.
+
+![Request Public Certificate](./request-public-certificate.png)
+
+The next page of the wizard will be used to set other properties of the certificate, starting with the domain name. The primary domain name of the certificate must precisely match the domain name that you registered with Route53 in the previous step. However, the Veraison deployment will also create a number of named services nested within that primary domain. In order for the certificate to adequately cover all of those named services, you need to give the certificate an additional name, which uses an asterisk (*) wildcard as shown below. Remember, once again, substitute your chosen domain name to use in place of `example-veraison.com`.
+
+Use the **Add another name to this certificate** button to create the secondary name with the wildcard.
+
+![Set Certificate Names](./set-cert-names.png)
+
+For the validation method, you should use **DNS validation**, which will be the recommended default. You can also use the default **RSA 2048** for the certificate key algorithm as shown below.
+
+![Certificate Validation and Key Algorithm](./cert-validation-and-algorithm.png)
+
+Now click **Request** to request the certificate from the Certificate Manager.
+
+Before AWS can issue the certificate, it will need to check that you own the domain. Since you have registered the domain in Route53 in the previous step, this will be straightforward.
+
+Use the ACM dashboard to view the certificate. You will see that it has a status of "Pending Validation". You will also see the two associated domains: `example-veraison.com` and `*.example-veraison.com`, or whatever your chosen domain name is.
+
+Click the button that says **Create records in Route 53**. This will allow AWS to prove that you own the domain, at which point it will issue the certificate, and the status will change from "Pending Validation" to "Issued". Be aware that this process can take up to about half an hour.
+
+Once your domain and certificate are prepared, you are ready to create your Veraison deployment.