Tools: update iat-verifier README and samples
Update the README for iat-verifier to describe the compile_token and
decompile_token scripts, and update the samples to include a YAML token
description that can be used with compile_token.
Change-Id: Ibf8a88c6ca57fa5a76d05f552ad657db665d7cf5
Signed-off-by: Sergei Trofimov <sergei.trofimov@arm.com>
diff --git a/tools/iat-verifier/README.rst b/tools/iat-verifier/README.rst
index 82def37..39f3fa0 100644
--- a/tools/iat-verifier/README.rst
+++ b/tools/iat-verifier/README.rst
@@ -1,10 +1,22 @@
############################
Initial Attestation Verifier
############################
-This is a parser and verifier script for an Initial Attestation Token,
-the structure of which is described here:
+This is a set of utility scripts for working with PSA Initial Attestation
+Token, the structure of which is described here:
-https://tools.ietf.org/html/draft-tschofenig-rats-psa-token-01
+ https://tools.ietf.org/html/draft-tschofenig-rats-psa-token-05
+
+The following utilities are provided:
+
+check_iat
+ Verifies the structure, and optionally the signature, of a token.
+
+compile_token
+ Creates a (optionally, signed) token from a YAML descriptions of the claims.
+
+decompile_token
+ Generates a YAML descriptions of the claims contained within a token. (Note:
+ this description can then be compiled back into a token using compile_token.)
************
@@ -15,7 +27,7 @@
.. code:: bash
# Inside the directory containg this README
- pip install .
+ pip3 install .
This should automatically install all the required dependencies. Please
see ``setup.py`` for the list of said dependencies.
@@ -23,7 +35,14 @@
*****
Usage
*****
-After installing, you should have check_iat script in your PATH. The
+
+.. note::
+ You can use ``-h`` flag with any of the scripts to see their usage help.
+
+check_iat
+---------
+
+After installing, you should have ``check_iat`` script in your ``PATH``. The
script expects a single parameter – a path to the signed IAT in COSE
format.
@@ -35,7 +54,7 @@
.. code:: bash
- $ check_iat sample/iat.cbor
+ $ check_iat sample/cbor/iat.cbor
Token format OK
If you want the script to verify the signature, you need to specify the
@@ -44,7 +63,7 @@
::
- $ check_iat -k sample/key.pem sample/iat.cbor
+ $ check_iat -k sample/key.pem sample/cbor/iat.cbor
Signature OK
Token format OK
@@ -90,6 +109,74 @@
]
}
+compile_token
+-------------
+
+You can use this script to compile a YAML claims description into a COSE-wrapped
+CBOR token:
+
+.. code:: bash
+
+ $ compile_token -k sample/key.pem sample/yaml/iat.yaml > sample_token.cbor
+
+*No validation* is performed as part of this, so there is no guarantee that a
+valid IAT will be produced.
+
+You can omit the ``-k`` option, in which case, the resulting token will not be
+signed, however it will still be wrapped in COSE "envelope". If you would like
+to produce a pure CBOR encoding of the claims without a COSE wrapper, you can
+use ``-r`` flag.
+
+
+decompile_token
+---------------
+
+Decompile an IAT (or any COSE-wrapped CBOR object -- *no validation* is performed
+as part of this) into a YAML description of its claims.
+
+
+.. code:: bash
+
+ $decompile_token sample/cbor/iat.cbor
+ boot_seed: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ challenge: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ client_id: 2
+ implementation_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ instance_id: !!binary |
+ AQcGBQQDAgEADw4NDAsKCQgXFhUUExIREB8eHRwbGhkY
+ profile_id: http://example.com
+ security_lifecycle: SL_SECURED
+ sw_components:
+ - measurement_description: TF-M_SHA256MemPreXIP
+ measurement_value: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ signer_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ sw_component_type: BL
+ sw_component_version: 3.4.2
+ - measurement_value: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ signer_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ sw_component_type: M1
+ sw_component_version: 1.2
+ - measurement_value: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ signer_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ sw_component_type: M2
+ sw_component_version: 1.2.3
+ - measurement_value: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ signer_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ sw_component_type: M3
+ sw_component_version: 1
+
+This description can then be compiled back into CBOR using ``compile_token``.
***********
@@ -140,6 +227,9 @@
Generate a sample token, signing it with the specified key, and writing
the output to the specified file.
+.. note::
+ This script is deprecated -- use ``compile_token`` (see above) instead.
+
--------------
*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/tools/iat-verifier/sample/badsig.cbor b/tools/iat-verifier/sample/cbor/badsig.cbor
similarity index 100%
rename from tools/iat-verifier/sample/badsig.cbor
rename to tools/iat-verifier/sample/cbor/badsig.cbor
Binary files differ
diff --git a/tools/iat-verifier/sample/iat.cbor b/tools/iat-verifier/sample/cbor/iat.cbor
similarity index 100%
rename from tools/iat-verifier/sample/iat.cbor
rename to tools/iat-verifier/sample/cbor/iat.cbor
Binary files differ
diff --git a/tools/iat-verifier/sample/invalid-profile-id.cbor b/tools/iat-verifier/sample/cbor/invalid-profile-id.cbor
similarity index 100%
rename from tools/iat-verifier/sample/invalid-profile-id.cbor
rename to tools/iat-verifier/sample/cbor/invalid-profile-id.cbor
Binary files differ
diff --git a/tools/iat-verifier/sample/malformed.cbor b/tools/iat-verifier/sample/cbor/malformed.cbor
similarity index 100%
rename from tools/iat-verifier/sample/malformed.cbor
rename to tools/iat-verifier/sample/cbor/malformed.cbor
Binary files differ
diff --git a/tools/iat-verifier/sample/missing-claim.cbor b/tools/iat-verifier/sample/cbor/missing-claim.cbor
similarity index 100%
rename from tools/iat-verifier/sample/missing-claim.cbor
rename to tools/iat-verifier/sample/cbor/missing-claim.cbor
Binary files differ
diff --git a/tools/iat-verifier/sample/missing-sw-comps.cbor b/tools/iat-verifier/sample/cbor/missing-sw-comps.cbor
similarity index 100%
rename from tools/iat-verifier/sample/missing-sw-comps.cbor
rename to tools/iat-verifier/sample/cbor/missing-sw-comps.cbor
Binary files differ
diff --git a/tools/iat-verifier/sample/no-sw-measurements.cbor b/tools/iat-verifier/sample/cbor/no-sw-measurements.cbor
similarity index 100%
rename from tools/iat-verifier/sample/no-sw-measurements.cbor
rename to tools/iat-verifier/sample/cbor/no-sw-measurements.cbor
Binary files differ
diff --git a/tools/iat-verifier/sample/submod-missing-claim.cbor b/tools/iat-verifier/sample/cbor/submod-missing-claim.cbor
similarity index 100%
rename from tools/iat-verifier/sample/submod-missing-claim.cbor
rename to tools/iat-verifier/sample/cbor/submod-missing-claim.cbor
Binary files differ
diff --git a/tools/iat-verifier/sample/yaml/iat.yaml b/tools/iat-verifier/sample/yaml/iat.yaml
new file mode 100644
index 0000000..c71e962
--- /dev/null
+++ b/tools/iat-verifier/sample/yaml/iat.yaml
@@ -0,0 +1,37 @@
+boot_seed: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+challenge: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+client_id: 2
+implementation_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+instance_id: !!binary |
+ AQcGBQQDAgEADw4NDAsKCQgXFhUUExIREB8eHRwbGhkY
+profile_id: http://example.com
+security_lifecycle: SL_SECURED
+sw_components:
+- measurement_description: TF-M_SHA256MemPreXIP
+ measurement_value: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ signer_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ sw_component_type: BL
+ sw_component_version: 3.4.2
+- measurement_value: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ signer_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ sw_component_type: M1
+ sw_component_version: 1.2
+- measurement_value: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ signer_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ sw_component_type: M2
+ sw_component_version: 1.2.3
+- measurement_value: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ signer_id: !!binary |
+ BwYFBAMCAQAPDg0MCwoJCBcWFRQTEhEQHx4dHBsaGRg=
+ sw_component_type: M3
+ sw_component_version: 1