CCA on AWS with Veraison_JA to review

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

@@ -1,23 +1,23 @@
 ---
-title: Build a CCA Attestation Service in AWS with Veraison
+title: Build a CCA Attestation Service on 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.
+who_is_this_for: This Learning Path is for developers familiar with CCA attestation and the Veraison project. You'll learn how to deploy a scalable CCA attestation verifier service on AWS.
 
 
 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.
+    - Build an attestation service on AWS using the Veraison project's components.
+    - Set up Veraison 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 authorized to use the AWS account. Other build environments might be possible, but will require the configuration of toolchains for cross-compilation.
+    - An [AWS account](/learning-paths/servers-and-cloud-computing/csp/aws/) with access to AWS services.
+    - An x86 computer running Ubuntu or Arch Linux, authorized for AWS access. If you're using another build environment, you'll need to configure the toolchains for cross-compilation.
 
 
 author: Paul Howard

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

@@ -6,20 +6,21 @@ weight: 3
 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).
+## Prepare your AWS account
+You’ll need an active AWS account for this Learning Path. If you don't have one yet, 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.
+{{% notice Note %}}
+This Learning Path assumes that you have administrator-level privileges for your AWS account. {{% /notice %}}
 
-## 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.
+## Install AWS command-line tools
+You’ll need the AWS Command-Line Interface (CLI) installed for this section. Follow the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to install the latest version.
 
-## Set Up Authentication
-You will need to configure your local environment to authenticate with the AWS cloud in order to build the Veraison deployment.
+## Set up authentication
+You'll need to set up your local environment to authenticate with AWS before deploying Veraison.
 
-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).
+The recommended method is Single Sign-On (SSO). Follow the steps 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:
+To confirm authentication is configured correctly, run a simple command, such as:
 
 ```bash
 aws ec2 describe-availability-zones
@@ -66,4 +67,4 @@ You should see output similar to the following (depending on which AWS region yo
     ]
 }
 ```
-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.
+If this operation fails, pause here and troubleshoot using the [AWS documentation](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-authentication.html) before continuing.

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

@@ -9,7 +9,7 @@ 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.
+This process is highly automated, but will take between 30 to 60 minutes, as several resources need to be created in AWS.
 
 The deployment process is documented in [Veraison's GitHub repository](https://github.com/veraison/services/blob/main/deployments/aws/README.md). 
 
@@ -25,7 +25,7 @@ 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. 
+You'll provide AWS-specific settings, including the IDs for your VPC and subnets, and the CIDR block allowed 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` needs 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.
 
@@ -35,7 +35,7 @@ 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.
+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.
 
@@ -45,15 +45,15 @@ 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:-
+This command outputs a status report for the deployment. If successful, it includes 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.
+- A list of media types that Veraison accepts as attestation evidence.
+- A list of media types that Veraison accepts 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.
 
@@ -69,6 +69,6 @@ Use the following command to test the REST API endpoint of the endorsement provi
 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.
+This command produces 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.
+Your Veraison services are now successfully deployed - you're ready for the next step.

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

@@ -7,51 +7,72 @@ 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.
+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 need a domain so users can easily find and access them. Domains are named using string labels separated by dots. 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.
+### What is Route53?
 
-[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.
+[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 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.
+### Choosing Your Domain Name
 
-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.
+Your domain name must be unique and specific to your Veraison deployment. Remember that this domain name is for creating public internet services, so it cannot clash with any other domains that exist on the public internet. 
 
-**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.
+In this Learning Path, you 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.
+
+### Registering Your Domain with Route53
+
+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 takes you to the Route53 dashboard. 
+* Locate the domain registration option, which looks something like the image below. Remember to use your own domain name where highlighted, not the `example-veraison.com` domain.
+
+{{% notice Note %}}
+If you have an existing domain, you can transfer it into Route53 instead of registering a new one, as shown below. Otherwise, the instructions here assume that you are creating a new domain.
+{{% /notice %}}
 
 ![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 checks your domain name to make sure it’s unique on the internet. Provided that there isn't a clash, Route53 gives 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.
+Route53 charges an annual fee for domain registration, which varies depending on your chosen name. 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.
+### Why Do I Need a Domain Certificate?
+Veraison publishes secure cloud services that can be reached on the internet using HTTPs. You need a domain certificate so users can securely and confidently connect to your Veraison services.
 
-Select "Request Certificate" from the menu on the left as shown.
+### Requesting a Certificate with AWS Certificate Manager 
+You can use the [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) 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**.
+On the first page of the certificate wizard, select **Request a public certificate**, then 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`.
+The next page of the wizard is for setting 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 also creates 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.
+For the validation method, you should use **DNS validation**, which is 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.
+### Validating Your Domain Ownership
+
+Before AWS can issue the certificate, it checks that you own the domain. Since you registered the domain in Route53 earlier, this is 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.
+Click **Create records in Route 53** to confirm domain ownership. AWS then issues the certificate, and its status changes 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.