Skip to content

Latest commit

 

History

History
217 lines (175 loc) · 7.06 KB

README-PSA.md

File metadata and controls

217 lines (175 loc) · 7.06 KB
Raw

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-pub.json:

evcli psa check \
    --token=my.cbor \
    --key=es256-pub.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:

{
  "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-hardware-version": "1234567890123",
  "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": "AAECAwABAgMAAQIDAAECAwABAgMAAQIDAAECAwABAgM=",
  "psa-instance-id": "AaChoqOgoaKjoKGio6ChoqOgoaKjoKGio6ChoqOgoaKj",
  "psa-verification-service-indicator": "https://psa-verifier.org",
  "psa-certification-reference": "1234567890123-12345",
}

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-pub.json \
    --claims=output-claims.json

Print

Use the psa print subcommand to display the claims of a PSA attestation token as pretty-printed JSON, without performing any signature checks. This will perform the same well-formedness check as the check command, but will skip cryptographic operations, meaning that a token can be inspected on its own without providing any keys or other additional inputs. Structured JSON text will be written to standard output.

To print out the PSA attestation token in my.cbor:

evcli psa print --token=my.cbor

The claim set is printed to stdout in JSON format:

{
  "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-hardware-version": "1234567890123",
  "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": "AAECAwABAgMAAQIDAAECAwABAgMAAQIDAAECAwABAgM=",
  "psa-instance-id": "AaChoqOgoaKjoKGio6ChoqOgoaKjoKGio6ChoqOgoaKj",
  "psa-verification-service-indicator": "https://psa-verifier.org",
  "psa-certification-reference": "1234567890123-12345",
}

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/newSession \
    --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/newSession \
    --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/newSession \
    --token=my.cbor

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

Note on TLS

If the scheme in the API server URL is HTTPS, evcli will attempt to establish a TLS connection to the server, validating the server certificate using system CA certs. It is possible to disable server certificate validation with -i/--insecure flag. Alternatively, if the CA cert for the server is available but is not installed in the system, it may be specified using -E/--ca-cert flag.