Attestation Evidence manipulation tool

Installing and configuring

To install the evcli command, do:

go install github.com/veraison/[email protected]

To configure auto-completion, use the completion subcommand. For example, if bash is your shell, you would do something like:

evcli completion bash > ~/.bash_completion.d/evcli
. ~/.bash_completion

If instead you are using zsh managed via ohmyzsh:

evcli completion zsh > ~/.oh-my-zsh/completions/_evcli
. ~/.zshrc

For more help on completion:

evcli completion --help

PSA attestation tokens manipulation

The psa subcommand allows you to create, check and verify PSA attestation tokens.

Create

Use the psa create subcommand to create a PSA attestation token from the supplied claims in JSON format and IAK in JSON Web Key (JWK) format1.

evcli psa create \
    --claims=psa-claims-profile-2.json \
    --key=ec256.json

On success, you should see the following printed to stdout:

>> "psa-claims-profile-2.cbor" successfully created

The CBOR-encoded PSA token is stored in the current working directory with a name derived from the claims file you supplied. If you want, you can specify a different name using the --token command line switch (abbrev. -t).

For example:

evcli psa create \
    --claims=psa-claims-profile-2.json \
    --key=ec256.json \
    --token=my.cbor

By default, PSA tokens are created according to the “http://arm.com/psa/2.0.0” profile. If you are using the legacy “PSA_IOT_PROFILE_1” instead, you will need to explicitly pass it via the command line using the --profile switch (abbrev. -p):

evcli psa create \
    --claims=psa-claims-profile-1.json \
    --key=ec256.json \
    --profile=PSA_IOT_PROFILE_1

Check

Use the psa check subcommand to verify the cryptographic signature over the supplied PSA attestation token as well as checking whether its claim set is well-formed.

To check the PSA attestation token in my.cbor using the public key in es256.json:

evcli psa check \
    --token=my.cbor \
    --key=es256.json

A message will indicate whether the signature has been successfully verified:

>> "my.cbor" verified

In such case, the claim set is printed to stdout in JSON format:

{
  "profile": "http://arm.com/psa/2.0.0",
  "partition-id": 1,
  "security-life-cycle": 12288,
  "implementation-id": "UFFSU1RVVldQUVJTVFVWV1BRUlNUVVZXUFFSU1RVVlc=",
  "boot-seed": "3q2+796tvu/erb7v3q2+796tvu/erb7v3q2+796tvu8=",
  "hardware-version": "1234567890123",
  "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="
    }
  ],
  "nonce": "AAECAwABAgMAAQIDAAECAwABAgMAAQIDAAECAwABAgM=",
  "instance-id": "AaChoqOgoaKjoKGio6ChoqOgoaKjoKGio6ChoqOgoaKj",
  "verification-service-indicator": "https://psa-verifier.org",
  "_partition-id-desc": "spe",
  "_security-lifecycle-desc": "secured"
}

The claim set can also be saved to a file using the --claims switch (abbrev. -c), as in:

evcli psa check \
    --token=my.cbor \
    --key=es256.json \
    --claims=output-claims.json

Verify

The psa verify-as subcommand allows you to interact with the Veraison Verifier (or another Attestation Verifier implementing the Veraison challenge-response API).

There are two modes of operation corresponding to the emulated roles: Attester or Relying Party. (For background, see RATS architecture.)

Attester

The attester subcommand implements the “attester mode” of a challenge-response interaction, where the verifier is the protocol challenger. Therefore, the nonce is provided by the Veraison API server and the PSA attestation token needs to be created on the fly based on the attester’s claims and signing IAK.

evcli psa verify-as attester \
    --api-server=https://veraison.example/challenge-response/v1 \
    --claims=psa-claims-profile-2-without-nonce.json \
    --key=es256.json

Note that the supplied claims file must not include a nonce claim.

By default, the command will request 48 bytes nonce from the server. If needed, a different value can be requested using the --nonce-size (abbrev. -n) switch. Available nonce sizes are 32, 48 or 64 bytes, as per PSA attestation token specification.

evcli psa verify-as attester \
    --api-server=https://veraison.example/challenge-response/v1 \
    --claims=psa-claims-profile-2-without-nonce.json \
    --key=es256.json \
    --nonce-size=32

Relying Party

The relying-party subcommand implements the “relying party mode” of a challenge-response interaction, where the relying party was the original challenger, and therefore the nonce is provided by the caller implicitly in an already well-formed and signed PSA attestation token, possibly produced by a previous invocation to evcli psa create.

evcli psa verify-as relying-party \
    --api-server=https://veraison.example/challenge-response/v1 \
    --token=my.cbor

1: Examples of PSA claims, signing keys, etc., can be found in the misc folder.

GitHub

View Github