diff --git a/end-to-end/walkthrough.md b/end-to-end/walkthrough.md index 1af8b3e8..f4cad531 100644 --- a/end-to-end/walkthrough.md +++ b/end-to-end/walkthrough.md @@ -451,7 +451,7 @@ 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, a device that supports this functionality (like an Arm v8-M development board). To install the code, run @@ -474,7 +474,7 @@ 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 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/ +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` is 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. @@ -541,7 +541,7 @@ If successful, it will return the list of claims: 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. +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 creates the PSA attestation token on-the-fly. @@ -555,7 +555,7 @@ evcli psa verify-as relying-party \ The response will be an Attestation Result encoded as a JWT, which is signed with a JSON Web Signature (JWS). -For example, the follow JWT is an example response returned by the Verifier. It is a string consisting of three values separated by '.'. The first part is the header containing the signing algorithm and other information. The second part is the signed payload, and the last part is the digital signature itself. +For example, the following JWT is an example response returned by the Verifier. It is a string consisting of three values separated by '.'. The first part is the header containing the signing algorithm and other information. The second part is the signed payload, and the last part is the digital signature itself. ~~~ eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJlYXIudmVyaWZpZXItaWQiOnsiYnVpbGQiOiJOL0EiLCJkZXZlbG9wZXIiOiJWZXJhaXNvbiBQcm9qZWN0In0sImVhdF9ub25jZSI6IkZlaUJMMFlzMHl2WGlCYkFGTXMxT0hEWFh0dzA4UkdxX1NFU0pkU2FYUHNLazJBOF9BcnVMNDVaOFFxdWtUOG8iLCJlYXRfcHJvZmlsZSI6InRhZzpnaXRodWIuY29tLDIwMjM6dmVyYWlzb24vZWFyIiwiaWF0IjoxNzA2MDIzOTc5LCJzdWJtb2RzIjp7IlBTQV9JT1QiOnsiZWFyLmFwcHJhaXNhbC1wb2xpY3ktaWQiOiJwb2xpY3k6UFNBX0lPVCIsImVhci5zdGF0dXMiOiJhZmZpcm1pbmciLCJlYXIudHJ1c3R3b3J0aGluZXNzLXZlY3RvciI6eyJjb25maWd1cmF0aW9uIjowLCJleGVjdXRhYmxlcyI6MiwiZmlsZS1zeXN0ZW0iOjAsImhhcmR3YXJlIjoyLCJpbnN0YW5jZS1pZGVudGl0eSI6MiwicnVudGltZS1vcGFxdWUiOjIsInNvdXJjZWQtZGF0YSI6MCwic3RvcmFnZS1vcGFxdWUiOjJ9LCJlYXIudmVyYWlzb24uYW5ub3RhdGVkLWV2aWRlbmNlIjp7ImVhdC1wcm9maWxlIjoiaHR0cDovL2FybS5jb20vcHNhLzIuMC4wIiwicHNhLWJvb3Qtc2VlZCI6IjNxMis3OTZ0dnUvZXJiN3YzcTIrNzk2dHZ1L2VyYjd2M3EyKzc5NnR2dTg9IiwicHNhLWNsaWVudC1pZCI6MSwicHNhLWltcGxlbWVudGF0aW9uLWlkIjoiWVdOdFpTMXBiWEJzWlcxbGJuUmhkR2x2YmkxcFpDMHdNREF3TURBd01ERT0iLCJwc2EtaW5zdGFuY2UtaWQiOiJBYzdycm51Sko2TWlmbE1EejE0UEgzczB1MVFxMXlVS3dEKzgzamJzTHhVSSIsInBzYS1ub25jZSI6IkZlaUJMMFlzMHl2WGlCYkFGTXMxT0hEWFh0dzA4UkdxL1NFU0pkU2FYUHNLazJBOC9BcnVMNDVaOFFxdWtUOG8iLCJwc2Etc2VjdXJpdHktbGlmZWN5Y2xlIjoxMjI4OCwicHNhLXNvZnR3YXJlLWNvbXBvbmVudHMiOlt7Im1lYXN1cmVtZW50LXR5cGUiOiJCTCIsIm1lYXN1cmVtZW50LXZhbHVlIjoiaDBLUHhTS0FQVEVHWG52T1BQQS81SFVKWmpIbDRIdTllZy9lWU1UUEpjYz0iLCJzaWduZXItaWQiOiJyTHNSeCtUYUlYSUZVanpremhva1d1R2lPYTQ4YS8yZWVISDM1ZGk2NkdzPSIsInZlcnNpb24iOiIyLjEuMCJ9LHsibWVhc3VyZW1lbnQtdHlwZSI6IlBSb1QiLCJtZWFzdXJlbWVudC12YWx1ZSI6IkFtT0NtWW0yL1pWUGNycXZMOFpMd3VMd0hXa3RUZWNwaHVxQWoyNlpnVDg9Iiwic2lnbmVyLWlkIjoickxzUngrVGFJWElGVWp6a3pob2tXdUdpT2E0OGEvMmVlSEgzNWRpNjZHcz0iLCJ2ZXJzaW9uIjoiMS4zLjUifSx7Im1lYXN1cmVtZW50LXR5cGUiOiJBUm9UIiwibWVhc3VyZW1lbnQtdmFsdWUiOiJvNlhuRmZETVYwcHp3L20rdTJ2Q1R6TC8xYlo3T0hKRXdza0oybmVhRkhnPSIsInNpZ25lci1pZCI6InJMc1J4K1RhSVhJRlVqemt6aG9rV3VHaU9hNDhhLzJlZUhIMzVkaTY2R3M9IiwidmVyc2lvbiI6IjAuMS40In1dLCJwc2EtdmVyaWZpY2F0aW9uLXNlcnZpY2UtaW5kaWNhdG9yIjoiaHR0cHM6Ly9wc2EtdmVyaWZpZXIub3JnIn19fX0.r85Kv2iRZvQ2mIn70YKKfYF4apv7lhXdoiqao0Z6UlltXifDig9mPDLMvI4JKXKhlumzRZN3kCR54pcJBuCasw @@ -565,19 +565,19 @@ The attestation result can be processed by a dedicated command line tool called First, install the tool with the following command: -~~~ +~~~bash go install github.com/veraison/ear/arc@latest ~~~ To obtain the public key for verifying the attestation result fetch it from .well-known using the following command: -~~~ -wget http://localhost:8080/.well-known/veraison/verification +~~~curl +wget http://localhost:8080/.well-known/veraison/verification ~~~ The result may be something like this: -~~~ +~~~json { "ear-verification-key": { "alg": "ES256", @@ -603,9 +603,9 @@ The result may be something like this: } ~~~ -Store the public key from the structure above in a separate file and verify the attestation result using 'arc' using the following command. We assume that the attestation result is stored in ar.txt. +Store the public key from the structure above in a separate file and verify the attestation result using `arc` using the following command. We assume that the attestation result is stored in `ar.txt`. -~~~ +~~~bash arc verify --pkey=public_key.json --verbose --alg=ES256 ar.txt ~~~ @@ -681,11 +681,11 @@ Storage Opaque [affirming]: the Attester encrypts all secrets in persistent stor Sourced Data [none]: The Evidence received is insufficient to make a conclusion. ~~~ -Alternatively, it is also possible to display the attestation result using an online tool, for example https://jwt.io. There are also many command line tools available to parse JWTs. +Alternatively, it is also possible to display the attestation result using an online tool, for example, https://jwt.io. There are also many command line tools available to parse JWTs. Once parsed, the header shows the digital signature algorithm that was used to protect the claims of the JWT -~~~ +~~~json { "alg": "ES256", "typ": "JWT" @@ -694,7 +694,7 @@ Once parsed, the header shows the digital signature algorithm that was used to p The header is followed by this payload: -~~~ +~~~json { "ear.verifier-id": { "build": "N/A", @@ -752,17 +752,17 @@ The header is followed by this payload: } ~~~ -The claims contained in this Attestation Result are described in https://datatracker.ietf.org/doc/draft-fv-rats-ear/. The trustworthiness vector shows the processing of the evaluation result. The overall appraisal status for the attester is found in the ear.status field. The values for these claims are re-used from another specification, namely from A4SI (see https://datatracker.ietf.org/doc/draft-ietf-rats-ar4si/). +The claims contained in this Attestation Result are described in https://datatracker.ietf.org/doc/draft-fv-rats-ear/. The trustworthiness vector shows the processing of the evaluation result. The overall appraisal status for the attester is found in the `ear.status` field. The values for these claims are re-used from another specification, namely from AR4SI (see https://datatracker.ietf.org/doc/draft-ietf-rats-ar4si/). To use the Attester mode, use the following command assuming the private key is available in JWK format and has been copied into the same directory where the two input files are located. -~~~ +~~~bash evcli psa verify-as attester \ --api-server=http://verification-service:8080/challenge-response/v1/newSession \ --claims=psa-evidence-without-nonce.json \ --key=jwk.json ~~~ -The content of psa-evidence-without-nonce.json corresponds to the content of the previously used file psa-evidence.json but with the nonce claim omitted. +The content of `psa-evidence-without-nonce.json` corresponds to the content of the previously used file `psa-evidence.json` but with the nonce claim omitted. If successful, this protocol interaction will produce an attestation result as a JWT.