typo fixes (1st batch)

end-to-end/walkthrough.md

@@ -17,7 +17,7 @@ The software depends at least on
 
 Veraison also has additional dependencies, which are described at https://github.com/veraison/services
 
-Important: Do not install Docker Desktop (at least on Ubuntu) since otherwise Veraison will fail.
+> **Important**: Do not install Docker Desktop (at least on Ubuntu) since otherwise Veraison build will fail.
 
 Use the following command to install the dependencies for Veraison on an Ubuntu OS:
 
@@ -27,11 +27,11 @@ sudo apt install git docker.io jq tmux docker-buildx
 
 ## Veraison
 
-This section provides details about the use of the Veraison docker image, which is meant to be used for demo purporses. The repository of Veraison can be found at https://github.com/veraison/services
+This section provides details about the use of the Veraison docker image, which is meant to be used for demo purposes. The repository of Veraison can be found at https://github.com/veraison/services
 
 In summary, the following steps need to be executed. Note that these steps assume the use of the bash shell.
 
-~~~
+~~~bash
 git clone https://github.com/veraison/services.git
 cd services
 make docker-deploy
@@ -42,68 +42,68 @@ veraison status
 
 If Veraison services are not running, then they need to be started with the following command:
 
-~~~
+~~~bash
 veraison start
 ~~~
 
 To check the status of the database use the following command:
 
-~~~
+~~~bash
 veraison check-stores
 ~~~
 
-Of course, after the initial installation the database will be empty. Provisioning of reference values, trust anchors and endosements will
-be explained below and those will be stored in the database. If you haven't created attestation keys yet, then first look at the next section otherwise skip it. 
+Of course, after the initial installation, the database will be empty. The provisioning of reference values, trust anchors and endosements will
+be explained below and those will be stored in the database. If you haven't created attestation keys yet, first look at the next section otherwise skip it. 
 
 In case of problems, use the following command (in a separate command line window) to see the log output.
 
-~~~
+~~~bash
 veraison follow <service-name>
 ~~~
 
-Replace <service-name> with one of the services available with Veraison, namely vts, provisioning, verification, management, or keycloak.
+Replace `<service-name>` with one of the services available with Veraison, namely `vts`, `provisioning`, `verification`, `management`, or `keycloak`.
 
-Debug output can be enabled by changing the log level inside deployments/docker/src/config.yaml.template prior to creating the deployment (i.e. running make docker-deploy; if a deployment already exists make really-clean should be done first). See also https://github.com/veraison/services/tree/main/deployments/docker#debugging for more detailed instruction on how to debug a specific service.
+Debug output can be enabled by changing the log level inside `deployments/docker/src/config.yaml.template` before creating the deployment (i.e. running `make docker-deploy`; if a deployment already exists `make really-clean` should be done first). See also https://github.com/veraison/services/tree/main/deployments/docker#debugging for more detailed instructions on how to debug a specific service.
 
-Sometimes it is necessary to remove the content of the database. In this case run the following command.
+Sometimes it is necessary to remove the content of the database. In this case, run the following command.
 
-~~~
+~~~bash
 veraison clear-stores
 ~~~
 
-To completely remove the deployment and remove the build artifacts using the following command. Note that this requires you to re-run 'make docker-deploy' if you want to use Veraison again.
+To completely remove the deployment and remove the build artifacts use the following command. Note that this requires you to re-run `make docker-deploy` if you want to use Veraison again.
 
-~~~
+~~~bash
 make -C ../deployments/docker really-clean
 ~~~
 
 ## Creating an Attestation Key for the Attester
 
-Attesters need to be in possession of an attestation key to sign attestation Evidence. If this key is not yet available, here are instructions for creating it.
+Attesters need to have an attestation key to sign attestation Evidence. If this key is not yet available, here are instructions for creating it.
 It is also necessary to convert the keys into the JSON Web Key (JWK) format and a separate tool is used for this transcoding. 
 
 To start, we create a private key in PEM format using the following command:
 
-~~~
+~~~bash
 openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:prime256v1 -out key.pem
 ~~~
 
-We use the go-pem2jwk tool to convert the PEM-encoded private key into a JWK. First, we need to obtain the tool.
+We use the `go-pem2jwk` tool to convert the PEM-encoded private key into a JWK. First, we need to obtain the tool.
 
-~~~
+~~~bash
 go install github.com/thomas-fossati/go-pem2jwk@latest
 ~~~
 
 The go-pem2jwk tool can convert a key in PEM format into a JWK using the following command:
 
-~~~
+~~~bash
 go-pem2jwk < key.pem > jwk.json
 ~~~
 
-Github will complain if we show the PEM-encoded private key. Hence, we only print the JWT contain the private key for this example.
-You are obviously supposed to create your own private key for your example setup.
+GitHub will complain if we show the PEM-encoded private key. Hence, we only print the JWT containing the private key for this example.
+You are supposed to create your private key for your example setup.
 
-~~~
+~~~json
 {
   "crv": "P-256",
   "d": "-fVWtEiKGbVk1J92WRwCefa78RohjMUBVKRfKARMFSQ",
@@ -115,7 +115,7 @@ You are obviously supposed to create your own private key for your example setup
 
 Next, we create a public key based on the private key using the following command:
 
-~~~
+~~~bash
 openssl ec -in key.pem -pubout -outform pem -out cert.pub
 ~~~
 
@@ -134,9 +134,9 @@ We also convert the PEM-encoded public key to a JWK:
 go-pem2jwk < cert.pub > pub.json
 ~~~
 
-The result is show below:
+The result is shown below:
 
-~~~
+~~~json
 {
   "crv": "P-256",
   "kty": "EC",
@@ -147,15 +147,15 @@ The result is show below:
 
 ## Provisioning Trust Anchors, Reference Values and Endorsements
 
-The Verifier must be provisioned with trust anchors, reference values, and endorsements before it can be used. The cocli tool offers this functionality and supports a number of subcommands:
+The Verifier must be provisioned with trust anchors, reference values, and endorsements before it can be used. The `cocli` tool offers this functionality and supports several subcommands:
 
-- 'comid' to create, display and validate Concise Module Identifiers (CoMIDs)
-- 'cots' to create, display and validate Concise TA Stores (CoTSs)
-- 'corim' to create, display, sign, verify CoRIMs 
+- `comid` to create, display and validate Concise Module Identifiers (CoMIDs)
+- `cots` to create, display and validate Concise TA Stores (CoTSs)
+- `corim` to create, display, sign, and verify CoRIMs 
 
-https://github.com/veraison/corim/tree/main/cocli repository contains the detailed steps.
+See also the [detailed documentation](https://github.com/veraison/corim/tree/main/cocli#readme) on the `veraison/corim` repository.
 
-~~~
+~~~bash
 go install github.com/veraison/corim/cocli@latest
 ~~~
 
@@ -167,20 +167,20 @@ The concepts are described in separate IETF drafts, which are still work in prog
 
 The payloads are encoded in CBOR.
 
-It is useful to clone the Veraison/corim repository, which contains examples. The command is:
+It is useful to clone the `veraison/corim` repository, which contains examples. The command is:
 
-~~~
+~~~bash
 git clone https://github.com/veraison/corim.git
 ~~~
 
-In the subsequent steps we will create the CBOR-based payloads for submission to Veraison using a RESTful API.
+In the subsequent steps, we will create the CBOR-based payloads for submission to Veraison using a RESTful API.
 Hence, we will have to create a CoMID for the reference value and a CoTS for the trust anchor.
 
-The command line tool, cocli, uses so-called templates as an input to generate the CBOR files. For completeness,
+The command line tool, `cocli`, uses so-called templates as input to generate the CBOR files. For completeness,
 the JSON files are shown below.
 
 The first command creates a CoMID based on two input files, one for trust anchors and another one for reference values.
-The comid-psa-ta.json file contains information about the trust anchor(s) and the comid-psa-refval.json file contains
+The `comid-psa-ta.json` file contains information about the trust anchor(s) and the `comid-psa-refval.json` file contains
 the reference value(s).
 
 In our example, we need to provision the public key of the Attester to Veraison. This allows Veraison to verify the
@@ -190,20 +190,20 @@ The Evidence, which we will create later in this walkthrough, contains the hashe
 The details of these software components are explained in https://datatracker.ietf.org/doc/draft-tschofenig-rats-psa-token/
 The goal is to provision the "reference" or "golden values" of these hashes to the Verifier. This allows the Verifier to match the Evidence claims sent by the Attester with the expected values.
 
-~~~
+~~~bash
 cocli comid create --template comid-psa-ta.json \
                     --template comid-psa-refval.json \
                     --output-dir tmp                       
 ~~~
 
-The public key, which we previously created, has to be copied into the comid-psa-ta.json file of the 'verification-keys' field. Search for the "BEGIN PUBLIC KEY" section in the JSON file below.
-The UEID field contains information about the specific instance of the device and serves as a key identifier. Hence, this instance ID has to match the instance id claim in the Evidence.
-The Implementation ID claim uniquely identifies the implementation of the immutable PSA RoT. Veraison uses this claim to locate the details of the PSA RoT implementation. The implementation id is also
+The public key, which we previously created, has to be copied into the `comid-psa-ta.json` file of the `verification-keys` field. Search for the `BEGIN PUBLIC KEY` section in the JSON file below.
+The UEID field contains information about the specific instance of the device and serves as a key identifier. Hence, this instance ID has to match the Instance ID claim in the Evidence.
+The Implementation ID claim uniquely identifies the implementation of the immutable PSA RoT. Veraison uses this claim to locate the details of the PSA RoT implementation. The Implementation ID is also
 found in the Evidence claims.
 
 comid-psa-ta.json:
 
-~~~
+~~~json
 {
   "lang": "en-GB",
   "tag-identity": {
@@ -251,7 +251,7 @@ comid-psa-ta.json:
 }
 ~~~
 
-The reference values of the software contain the measurements with measurements for each component. The semantics of the reference values are described in https://datatracker.ietf.org/doc/html/draft-fdb-rats-psa-endorsements-03 (see Section 3.3), which is a measurement-map of a CoMID reference-triple-record. Because of the relationship to the software component complains in the Evidence
+The reference values of the software contain the measurements with measurements for each component. The semantics of the reference values are described in https://datatracker.ietf.org/doc/html/draft-fdb-rats-psa-endorsements-03 (see Section 3.3), which is a measurement-map of a CoMID reference-triple-record. Because of the relationship to the software component contained in the Evidence
 consult also Section 4.4.1 of https://datatracker.ietf.org/doc/draft-tschofenig-rats-psa-token/.
 
 Four fields are worth mentioning, namely 
@@ -264,7 +264,7 @@ Four fields are worth mentioning, namely
 
 comid-psa-refval.json:
 
-~~~
+~~~json
 {
   "lang": "en-GB",
   "tag-identity": {
@@ -348,18 +348,18 @@ comid-psa-refval.json:
 }
 ~~~
 
-Next, we combine the two previously generated files (comid-psa-refval.cbor and comid-psa-ta.cbor) into a CoRIM using the following command:
+Next, we combine the two previously generated files (`comid-psa-refval.cbor` and `comid-psa-ta.cbor`) into a CoRIM using the following command:
 
-~~~
+~~~bash
 cocli corim create --template corim-psa.json \
                     --comid tmp/comid-psa-refval.cbor \
                     --comid tmp/comid-psa-ta.cbor \
                     --output tmp/psa-corim.cbor
 ~~~
 
-The content of the corim-psa.json file is shown below. It indicates the attestation Evidence profile being used and other meta-data.
+The content of the `corim-psa.json` file is shown below. It indicates the attestation Evidence profile being used and other meta-data.
 
-~~~
+~~~json
 {
   "corim-id": "5c57e8f4-46cd-421b-91c9-08cf93e13cfc",
   "profiles": [
@@ -374,7 +374,7 @@ The content of the corim-psa.json file is shown below. It indicates the attestat
 
 The CoRIM file can be submitted to Veraison using the following command:
 
-~~~
+~~~bash
 cocli corim submit \
      --corim-file=tmp/psa-corim.cbor \
      --api-server=http://provisioning-service:8888/endorsement-provisioning/v1/submit \
@@ -383,7 +383,7 @@ cocli corim submit \
 
 By dumping the Veraison database with the "veraison stores" command we can see the correctly entered entries:
 
-~~~
+~~~json
 TRUST ANCHORS:
 --------------
 {
@@ -451,34 +451,34 @@ ENDORSEMENTS:
 
 ## Manually Creating Attestation Evidence
 
-We use the evcli tool to create attestation Evidence. Note that only two attestation formats are currently supported, namely the Arm PSA Token and Arm CCA. The repository can be found here: https://github.com/veraison/evcli/tree/main. In a more realistic setup we would be using either software that emulates an Attester or, even better, use a device that supports this functionality (like an Arm v8-M development board).
+We use the `evcli` tool to create attestation Evidence. Note that only two attestation formats are currently supported, namely the Arm PSA Token and Arm CCA. The repository can be found here: https://github.com/veraison/evcli/tree/main. In a more realistic setup, we would be using either software that emulates an Attester or, even better, use a device that supports this functionality (like an Arm v8-M development board).
 
 To install the code, run
 
-~~~
+~~~bash
 go install github.com/veraison/evcli/v2@latest
 ~~~
 
-Also clone the repository to re-use the examples:
+Also, clone the repository to re-use the examples:
 
-~~~
+~~~bash
 git clone https://github.com/veraison/evcli.git
 ~~~
 
 Note that we will re-use the previously created JWT in this example.
 
-The evcli repostory contains documentation for use of the PSA attestation token format, which can be found in https://github.com/veraison/evcli/blob/main/README-PSA.md
+The `evcli` repository contains documentation for the use of the PSA attestation token format, which can be found at https://github.com/veraison/evcli/blob/main/README-PSA.md
 
 Two inputs are necessary to create the PSA attestation token, namely 
 
 * A set of claims, and
 * A private key to sign the token.
 
-We are using the following claims, in JSON format, and encode them into a file psa-evidence.json. Note that the combination of the psa-instance-id and the psa-implementation-id are used to identify the key. The signer-id contains the hash of the public key used to sign the software/firmware. These concepts are described in https://datatracker.ietf.org/doc/draft-tschofenig-rats-psa-token/
+We are using the following claims, in JSON format, and encoding them into a file `psa-evidence.json`. Note that the combination of the `psa-instance-id` and the `psa-implementation-id` are used to identify the key. The `signer-id` contains the hash of the public key used to sign the software/firmware. These concepts are described in https://datatracker.ietf.org/doc/draft-tschofenig-rats-psa-token/
 
 Note that the content of the evidence needs to correspond to the endorsements. Omitting claims or software components will cause verification failures.
 
-~~~
+~~~json
 {
   "eat-profile": "http://arm.com/psa/2.0.0",
   "psa-client-id": 1,
@@ -514,7 +514,7 @@ Note that the content of the evidence needs to correspond to the endorsements. O
 
 To create a PSA attestation token from the supplied claims and an attestation key in JSON Web Key (JWK) format we use the following command. Follow the instructions in the previous sub-section to create the attestation key.
 
-~~~
+~~~bash
 evcli psa create \
     --claims=psa-evidence.json \
     --key=jwk.json \
@@ -523,11 +523,11 @@ evcli psa create \
 
 The specification of the PSA attestation token can be found at https://datatracker.ietf.org/doc/html/draft-tschofenig-rats-psa-token, which contains an explanation of the various claims and their semantics.
 
-The command above will produce the PSA attestation token in CBOR format and protects it using COSE_Sign1. The result is stored in my-token.cbor.
+The command above will produce the PSA attestation token in CBOR format and protect it using COSE_Sign1. The result is stored in `my-token.cbor`.
 
-To verify the Evidence locally, the token and the public key needs to be provided to the following command:
+To verify the Evidence locally, the token and the public key need to be provided to the following command:
 
-~~~
+~~~bash
 evcli psa check --token=my-token.cbor --key=pub.json
 ~~~
 
@@ -539,15 +539,15 @@ If successful, it will return the list of claims:
 {"eat-profile":http://arm.com/psa/2.0.0,"psa-client-id":1,"psa-security-lifecycle":12288,"psa-implementation-id":"UFFSU1RVVldQUVJTVFVWV1BRUlNUVVZXUFFSU1RVVlc=","psa-boot-seed":"3q2+796tvu/erb7v3q2+796tvu/erb7v3q2+796tvu8=","psa-software-components":[{"measurement-type":"BL","measurement-value":"AAECBAABAgQAAQIEAAECBAABAgQAAQIEAAECBAABAgQ=","signer-id":"UZIA/1GSAP9RkgD/UZIA/1GSAP9RkgD/UZIA/1GSAP8="},{"measurement-type":"PRoT","measurement-value":"BQYHCAUGBwgFBgcIBQYHCAUGBwgFBgcIBQYHCAUGBwg=","signer-id":"UZIA/1GSAP9RkgD/UZIA/1GSAP9RkgD/UZIA/1GSAP8="}],"psa-nonce":"QUp8F0FBs9DpodKK8xUg8NQimf6sQAfe2J1ormzZLxk=","psa-instance-id":"AaChoqOgoaKjoKGio6ChoqOgoaKjoKGio6ChoqOgoaKj","psa-verification-service-indicator":https://psa-verifier.org}
 ~~~
 
-The psa check subcommand verifies the digital signature over the supplied PSA attestation token and checks whether its claim set is well-formed.
+The `psa check` subcommand verifies the digital signature over the supplied PSA attestation token and checks whether its claim set is well-formed.
 
 To test it against the Verifier, the psa verify-as subcommand is used.
 
-It has two modes, namely one where the tool acts as an Attester and another mode where it acts as a Relying Party. The Relying Party mode uses the previously generated PSA token as input while the Attester mode created the PSA attestation token on-the-fly. 
+It has two modes, namely one where the tool acts as an Attester and another mode where it acts as a Relying Party. The Relying Party mode uses the previously generated PSA token as input while the Attester mode creates the PSA attestation token on-the-fly. 
 
 Below, we use the Relying Party mode:
 
-~~~
+~~~bash
 evcli psa verify-as relying-party \
     --api-server=http://verification-service:8080/challenge-response/v1/newSession \
     --token=my-token.cbor