diff options
Diffstat (limited to 'docs/integration_guide/services/tfm_attestation_integration_guide.rst')
-rw-r--r-- | docs/integration_guide/services/tfm_attestation_integration_guide.rst | 671 |
1 files changed, 671 insertions, 0 deletions
diff --git a/docs/integration_guide/services/tfm_attestation_integration_guide.rst b/docs/integration_guide/services/tfm_attestation_integration_guide.rst new file mode 100644 index 0000000000..2c43ea7bdc --- /dev/null +++ b/docs/integration_guide/services/tfm_attestation_integration_guide.rst @@ -0,0 +1,671 @@ +############################################# +Initial Attestation Service Integration Guide +############################################# + +************ +Introduction +************ +TF-M Initial Attestation Service allows the application to prove the device +identity during an authentication process to a verification entity. The initial +attestation service can create a token on request, which contains a fix set of +device specific data. + +TF-M Initial Attestation Service by default enables asymmetric key algorithm +based attestation (*asymmetric attestation* for short). Symmetric key algorithm +based attestation (*symmetric attestation* for short) can be enabled instead by +selecting build option ``SYMMETRIC_INITIAL_ATTESTATION``. + + - In asymmetric attestation, device must contain an attestation key pair, + which is unique per device. The token is signed with the private part of + attestation key pair. The public part of the key pair is known by the + verification entity. The public key is used to verify the token + authenticity. + - In symmetric attestation, device should contain a symmetric attestation + key to generate the authentication tag of token content. The verification + entity uses the same symmetric key to verify the token authenticity. + +The data items in the token used to verify the device integrity and assess its +trustworthiness. Attestation key provisioning is out of scope for the +attestation service and is expected to take part during manufacturing of the +device. + +*************************************** +Claims in the initial attestation token +*************************************** +The initial attestation token is formed of claims. A claim is a data item, +which is represented in a key - value structure. The following fixed set of +claims are included in the token: + + - **Auth challenge**: Input object from caller. Can be a single nonce from + server or hash of nonce and attested data. It is intended to provide + freshness to report and the caller has responsibility to arrange + this. Allowed length: 32, 48, 64 bytes. The claim is modeled to be + eventually represented by the EAT standard claim nonce. Until such a + time as that standard exists, the claim will be represented by a custom + claim. Value is encoded as byte string. + + - **Instance ID**: It represents the unique identifier of the instance. + In the PSA definition it is: + + - a hash of the public attestation key of the instance in asymmetric + attestation. + - hashes of the symmetric attestation key of the instance in symmetric + attestation. + + The claim is modeled to be eventually represented by the EAT standard + claim UEID of type GUID. Until such a time as that standard exists, the + claim will be represented by a custom claim Value is encoded as byte + string. + + - **Verification service indicator**: Optional, recommended claim. It + is used by a Relying Party to locate a validation service for the + token. The value is a text string that can be used to locate the service + or a URL specifying the address of the service. The claim is modelled to + be eventually represented by the EAT standard claim origination. Until + such a time as that standard exists, the claim will be represented by + a custom claim. Value is encoded as text string. + + - **Profile definition**: Optional, recommended claim. It contains the + name of a document that describes the 'profile' of the token, being + a full description of the claims, their usage, verification and token + signing. The document name may include versioning. Custom claim with a + value encoded as text string. + + - **Implementation ID**: Uniquely identifies the underlying immutable PSA + RoT. A verification service can use this claim to locate the details of + the verification process. Such details include the implementation's origin + and associated certification state. Custom claim with a value encoded as + byte string. + + - **Client ID**: The partition ID of that secure partition or non-secure + thread who called the initial attestation API. Custom claim with a value + encoded as a `signed` integer. Negative number represents non-secure + caller, positive numbers represents secure callers, zero is invalid. + + - **Security lifecycle**: It represents the current lifecycle state of + the instance. Custom claim with a value encoded as an integer. + + - **Hardware version**: Optional claim. Globally unique number in EAN-13 + format identifying the GDSII that went to fabrication, HW and ROM. It can + be used to reference the security level of the PSA-ROT via a certification + website. Custom claim with a value is encoded as text string. + + - **Boot seed**: It represents a random value created at system boot + time that will allow differentiation of reports from different system + sessions. The size is 32 bytes. Custom claim with a value is encoded as + byte string. + + - **Software components**: Optional, but required in order to be compliant + with the PSA-SM. It represents the software state of the system. The value + of the claim is an array of CBOR map entries, with one entry per software + component within the device. Each map contains multiple claims that + describe evidence about the details of the software component. + + - **No software measurements**: Optional, but required if no software + component claims are made. In the event that the implementation does not + contain any software measurements then it is mandatory to include this + claim to indicate this is a deliberate state. Custom claim with a value + encoded as an unsigned integer set to 1. + +Each software component claim can include the following properties. Any property +that is not optional must be included: + + - **Measurement type**: Optional claim. It represents the role of the + software component. Value is encoded as short(!) text string. + + - **Measurement value**: It represents a hash of the invariant software + component in memory at start-up time. The value must be a cryptographic + hash of 256 bits or stronger. Value is encoded as byte string. + + - **Version**: Optional claim. It represents the issued software + version. Value is encoded as text string. + + - **Signer ID**: Optional claim, but required in order to be compliant with + the PSA-SM. It represents the hash of a signing authority public key. + Value is encoded as byte string. + + - **Measurement description**: Optional claim. It represents the way in + which the measurement value of the software component is computed. Value + is encoded as text string containing an abbreviated description (name) + of the measurement method. + +********************************************* +Initial attestation token (IAT) data encoding +********************************************* +The initial attestation token is planned to be aligned with future version of +`Entity Attestation Token <https://tools.ietf.org/html/draft-mandyam-eat-01>`__ +format. The token is encoded according to the +`CBOR <https://tools.ietf.org/html/rfc7049>`__ format and signed according to +`COSE <https://tools.ietf.org/html/rfc8152>`__ standard. + +************** +Code structure +************** +The PSA interface for the Initial Attestation Service is located in +``interface/include``. The only header to be included by applications that want +to use functions from the PSA API is ``psa/initial_attestation.h``. + +The TF-M Initial Attestation Service source files are located in +``secure_fw/partitions/initial_attestation``. +The CBOR library is located in ``lib/ext/qcbor`` folder. + +Service source files +==================== +- CBOR library + - ``lib/ext/qcbor`` This library is used to create a proper CBOR token. + It can be used on 32-bit and 64-bit machines. It was designed to suite + constrained devices with low memory usage and without dynamic memory + allocation. + It is a fork of this external `QCBOR library <https://github.com/laurencelundblade/QCBOR>`__. + - ``lib/ext/qcbor/inc/qcbor.h``: Public API documentation of CBOR + library. + +- COSE library: + - ``lib/ext/t_cose``: This library is used to sign a CBOR token and create + the COSE header and signature around the initial attestation token. Only + a subset of the `COSE <https://tools.ietf.org/html/rfc8152>`__ standard + is implemented. The COSE_Sign1 and COSE_Mac0 (only available in TF-M fork) + signature schemas are supported. + - It is a fork of this external `t_cose library <https://github.com/laurencelundblade/t_cose>`__. + - ``lib/ext/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose`` + library with available crypto library in the device. + - ``lib/ext/t_cose/crypto_adapters/t_cose_psa_crypto.c``: Implements the + exposed API and ports ``t_cose`` to the PSA Crypto API. +- Initial Attestation Service: + - ``attest_core.c`` : Implements core functionalities such as implementation + of APIs, retrieval of claims and token creation. + - ``attest_token_encode.c``: Implements the token creation functions such as + start and finish token creation and adding claims to the token. + - ``attest_asymmetric_key.c``: Get the asymmetric attestation key from + platform layer and register it to the TF-M Crypto service for further + usage. + - ``tfm_attest.c``: Implements the SPM abstraction layer, and bind the + attestation service to the SPM implementation in TF-M project. + - ``tfm_attest_secure_api.c``: Implements the secure API layer to allow + other services in the secure domain to request functionalities + from the attestation service using the PSA API interface. + - ``tfm_attest_req_mngr.c``: Includes the initialization entry of + attestation service and handles attestation service requests in IPC + model. + - ``attest_symmetric_key.c``: Get the symmetric initial attestation key + from platform layer and register it into TF-M Crypto service for further + usage. Also calculate the Instance ID value based on symmetric initial + attestation key. + +Service interface definitions +============================= +- **Boot loader interface**: The attestation service might include data + in the token about the distinct software components in the device. This data + is provided by the boot loader and must be encoded in the TLV format, + definition is described below in the boot loader interface paragraph. Possible + claims in the boot status are describe above in the software components + paragraph. +- **Hardware abstraction layer**: + - Headers are located in ``platform/include`` folder. + - ``tfm_attest_hal.h``: Expose an API to get the following claims: + security lifecycle, verification service indicator, profile definition. + - ``tfm_plat_boot_seed.h``: Expose an API to get the boot seed claim. + - ``tfm_plat_device_id.h``: Expose an API to get the following claims: + implementation ID, hardware version. +- **SPM interface**: + - ``attestation.h``: Expose an API to bind attestation service to an SPM + implementation. +- **PSA interface**: + - ``psa/initial_attestation.h``: Public API definition of initial + attestation service. +- **Crypto interface**: + - ``t_cose_crypto.h``: Expose an API to bind the ``t_cose`` implementation + to any cryptographic library. + - ``tfm_plat_crypto_keys.h``: Expose an API to get the attestation key from + platform layer. + +PSA interface +============= +The TF-M Initial Attestation Service exposes the following PSA +interface: + +.. code-block:: c + + psa_status_t + psa_initial_attest_get_token(const uint8_t *auth_challenge, + size_t challenge_size, + uint8_t *token_buf, + size_t token_buf_size, + size_t *token_size); + + psa_status_t + psa_initial_attest_get_token_size(size_t challenge_size, + size_t *token_size); + + psa_status_t + tfm_initial_attest_get_public_key(uint8_t *public_key, + size_t public_key_buf_size, + size_t *public_key_len, + psa_ecc_family_t *elliptic_curve_type); + +The caller must allocate a large enough buffer, where the token is going to be +created by Initial Attestation Service. The size of the created token is highly +dependent on the number of software components in the system and the provided +attributes of these. The ``psa_initial_attest_get_token_size()`` function can be +called to get the exact size of the created token. + +System integrators might need to port these interfaces to a custom secure +partition manager implementation (SPM). Implementations in TF-M project can be +found here: + +- ``interface/src/tfm_initial_attestation_func_api.c``: non-secure interface + implementation for library model +- ``interface/src/tfm_initial_attestation_ipc_api.c``: non-secure interface + implementation for IPC model +- ``secure_fw/partitions/initial_attestation/tfm_attestation_secure_api.c``: + secure interface implementation + +Secure Partition Manager (SPM) interface +======================================== +The Initial Attestation Service defines the following interface towards the +secure partition manager (SPM). System integrators **must** port this interface +according to their SPM implementation. + +.. code:: c + + enum psa_attest_err_t + attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len); + + enum psa_attest_err_t + attest_get_caller_client_id(int32_t *caller_id); + +- ``attest_get_boot_data()``: Service can retrieve the relevant data from shared + memory area between boot loader and runtime software. It might be the case + that only SPM has direct access to the shared memory area, therefore this + function can be used to copy the service related data from shared memory to + a local memory buffer. In TF-M implementation this function must be called + during service initialization phase, because the shared memory region is + deliberately overlapping with secure main stack to spare some memory and reuse + this area during execution. If boot loader is not available in the system to + provide attributes of software components then this function must be + implemented in a way that just initialize service's memory buffer to: + + .. code-block:: c + + struct shared_data_tlv_header *tlv_header = (struct shared_data_tlv_header *)ptr; + tlv_header->tlv_magic = 2016; + tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header); + +- ``attest_get_caller_client_id()``: Retrieves the ID of the caller thread. +- ``tfm_client.h``: Service relies on the following external definitions, which + must be present or included in this header file: + + .. code-block:: c + + typedef struct psa_invec { + const void *base; + size_t len; + } psa_invec; + + typedef struct psa_outvec { + void *base; + size_t len; + } psa_outvec; + +Hardware abstraction layer +========================== +The following API definitions are intended to retrieve the platform specific +claims. System integrators **must** implement these interface according to their +SoC and software design. Detailed definition of the claims are above +in the claims in the initial attestation token paragraph. + +- ``tfm_attest_hal_get_security_lifecycle()``: Get the security lifecycle of the + device. +- ``tfm_attest_hal_get_verification_service()``: Get the verification + service indicator for initial attestation. +- ``tfm_attest_hal_get_profile_definition()``: Get the name of the profile + definition document for initial attestation. +- ``tfm_plat_get_boot_seed()``: Get the boot seed, which is a constant random + number during a boot cycle. +- ``tfm_plat_get_implementation_id``: Get the implementation ID of the + device. +- ``tfm_plat_get_hw_version``: Get the hardware version of the device. + +Boot loader interface +===================== +It is **recommended** to have a secure boot loader in the boot chain, which is +capable of measuring the runtime firmware components (calculates the hash value +of firmware images) and provide other attributes of these (version, type, etc). +If the used boot loader is not capable of sharing these information with the +runtime software then the ``BOOT_DATA_AVAILABLE`` compiler flag **must** be +set to OFF (see `Related compile time options`_). + +The shared data between boot loader and runtime software is TLV encoded. The +definition of TLV structure is described in ``bl2/include/tfm_boot_status.h``. +The shared data is stored in a well known location in secure internal memory +and this is a contract between boot loader and runtime SW. + +The structure of shared data must be the following: + +- At the beginning there must be a header: ``struct shared_data_tlv_header`` + This contains a magic number and a size field which covers the entire size + of the shared data area including this header. + + .. code-block:: c + + struct shared_data_tlv_header { + uint16_t tlv_magic; + uint16_t tlv_tot_len; + }; + +- After the header there come the entries which are composed from an + entry header structure: ``struct shared_data_tlv_entry`` and the data. In + the entry header is a type field ``tlv_type`` which identify the consumer of + the entry in the runtime software and specify the subtype of that data item. + + .. Note:: + + There is a size field ``tlv_len`` which has different definitions in the + upstream MCUboot repository and in its TF-M forked version: + + - Upstream MCUboot: Covers only the length of data but not the header + size. + - TF-M MCUboot: Covers the size of the entry header and the data + together. + + This difference is handled by TF-M code based on which bootloader is used + along with TF-M runtime. + + After the entry header structure comes the actual data. + + .. code-block:: c + + struct shared_data_tlv_entry { + uint16_t tlv_type; + uint16_t tlv_len; + }; + +- Arbitrary number and size of data entry can be in the shared memory + area. + +The figure below gives of overview about the ``tlv_type`` field in the entry +header. The ``tlv_type`` always composed from a major and minorbnumber. Major +number identifies the addressee in runtime software, which the databentry is +sent to. Minor number used to encode more info about the data entry. The actual +definition of minor number could change per major number. In case of boot +status data, which is going to be processed by initial attestation service +the minor number is split further to two part: ``sw_module`` and ``claim``. The +``sw_module`` identifies the SW component in the system which the data item +belongs to and the ``claim`` part identifies the exact type of the data. + +``tlv_type`` description:: + + |------------------------------------------------ | + | tlv_type (16 bits) | + |-------------------------------------------------| + | tlv_major(4 bits) | tlv_minor(12 bits) | + |-------------------------------------------------| + | MAJOR_IAS | sw_module(6 bits) | claim(6 bits) | + |-------------------------------------------------| + | MAJOR_CORE | TBD | + |-------------------------------------------------| + +Overall structure of shared data:: + + --------------------------------------------------------------- + | Magic number(uint16_t) | Shared data total length(uint16_t) | + --------------------------------------------------------------- + | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) | + --------------------------------------------------------------- + | Raw data | + --------------------------------------------------------------- + | . | + | . | + | . | + --------------------------------------------------------------- + | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) | + --------------------------------------------------------------- + | Raw data | + --------------------------------------------------------------- + +Crypto interface +================ + +Asymmetric key algorithm based attestation +------------------------------------------ +Device **must** contain an asymmetric key pair. The private part of it is used +to sign the initial attestation token. Current implementation supports only the +ECDSA P256 signature over SHA256. The public part of the key pair is used to +create the key identifier (kid) in the unprotected part of the COSE header. The +kid is used by verification entity to look up the corresponding public key to +verify the signature in the token. The `t_cose` part of the initial attestation +service implements the signature generation and kid creation. But the actual +calculation of token's hash and signature is done by the Crypto service in the +device. System integrators might need to re-implement the following functions +if they want to use initial attestation service with a different cryptographic +library than Crypto service: + +- ``t_cose_crypto_pub_key_sign()``: Calculates the signature over a hash value. +- ``t_cose_crypto_get_ec_pub_key()``: Get the public key to create the key + identifier. +- ``t_cose_crypto_hash_start()``: Start a multipart hash operation. +- ``t_cose_crypto_hash_update()``: Add a message fragment to a multipart hash + operation. +- ``t_cose_crypto_hash_finish()``:Finish the calculation of the hash of a + message. + +Interface needed by verification code: + +- ``t_cose_crypto_pub_key_verify()``: Verify the signature over a hash value. + +Key handling +^^^^^^^^^^^^ +The provisioning of the initial attestation key is out of scope of the service +and this document. It is assumed that device maker provisions the unique +asymmetric key pair during the manufacturing process. The following API is +defined to retrieve the attestation key pair from platform layer. Software +integrators **must** port this interface according to their SoC design and make +sure that key pair is available by Crypto service: + +- ``tfm_plat_get_initial_attest_key()``: Retrieve the initial attestation key + pair from platform layer. + +In TF-M project the attestation key is retrieved by initial attestation service. +The key is registered and unregistered to the Crypto service by attestation +service with ``psa_import_key()`` and ``psa_destroy_key()`` API calls for +further usage. See in ``attestation_key.c``. In other implementation if the +attestation key is directly retrieved by the Crypto service then this key +handling is not necessary. + +Symmetric key algorithm based attestation +----------------------------------------- +Device **must** contain a symmetric key to generate the authentication tag of +the initial attestation token. A key identifier (kid) can be encoded in the +unprotected part of the COSE header. It helps verification entity look up the +symmetric key to verify the authentication tag in the token. + +The `t_cose` part of the initial attestation service implements the +authentication tag generation. The authentication tag generation is done by the +Crypto service. System integrators might need to re-implement the following +functions if platforms provide a different cryptographic library than Crypto +service: + +- ``t_cose_crypto_hmac_sign_setup()``: Set up a multi-part HMAC calculation + operation. +- ``t_cose_crypto_hmac_update()``: Add a message fragment to a multi-part HMAC + operation. +- ``t_cose_crypto_hmac_sign_finish()``: Finish the calculation of the HMAC of a + message. + +Interface needed by verification code: + +- ``t_cose_crypto_hmac_verify_setup()``: Set up a multi-part HMAC verification + operation. +- ``t_cose_crypto_hmac_verify_finish()``: Finish the verification of the HMAC of + a message. + +It also requires the same hash operations as listed in asymmetric key algorithm +based initial attestation above, in attestation test cases. + +Key handling +^^^^^^^^^^^^ +The provisioning of the initial attestation key is out of scope of the service +and this document. It is assumed that device maker provisions the symmetric key +during the manufacturing process. The following API is defined to retrieve the +symmetric attestation key from platform layer. Software integrators **must** +port this interface according to their SoC design and make sure that key is +available by Crypto service: + +- ``tfm_plat_get_symmetric_iak()``: Get the symmetric initial attestation key + raw data. +- ``tfm_plat_get_symmetric_iak_id()``: Get the key identifier of the symmetric + initial attestation key. The key identifier can be used as ``kid`` parameter + in COSE header. Optional. + +.. note: + + Asymmetric initial attestation and symmetric initial attestation may share + the same HAL APIs in future development. + +Initial Attestation Service compile time options +================================================ +There is a defined set of flags that can be used to compile in/out certain +service features. The ``CommonConfig.cmake`` file sets the default values of +those flags. The list of flags are: + +- ``ATTEST_INCLUDE_OPTIONAL_CLAIMS``: Include also the optional claims to the + attestation token. Default value: ON. +- ``ATTEST_INCLUDE_TEST_CODE``: Test code is removed from COSE library and from + attestation test suite if it is OFF. Its default value depends on the build + type. It is ON if build type is ``Debug``, otherwise OFF (different kinds + of ``Release`` builds). +- ``ATTEST_INCLUDE_COSE_KEY_ID``: COSE key-id is an optional field in the COSE + unprotected header. Key-id is calculated and added to the COSE header based + on the value of this flag. Default value: OFF. +- ``ATTEST_CLAIM_VALUE_CHECK``: Check attestation claims against hard-coded + values found in ``platform/ext/common/template/attest_hal.c``. Default value + is OFF. Set to ON in a platform's CMake file if the attest HAL is not yet + properly ported to it. +- ``SYMMETRIC_INITIAL_ATTESTATION``: Select symmetric initial attestation. + Default value: OFF. + +Related compile time options +---------------------------- +- ``BOOT_DATA_AVAILABLE``: The boot data is expected to be present in the shared + data area between the boot loader and the runtime firmware when it's ON. + Otherwise, when it's OFF does not check the content of the shared data area. + Also assume that the TLV header is present and valid (the magic number is + correct) and there are no other data entries. Its default value depends on + the BL2 flag. + +*************************************************************************** +Comparison of asymmetric and symmetric algorithm based token authentication +*************************************************************************** +The symmetric key based authentication requires a more complex infrastructure +for key management. Symmetric keys must be kept secret because they are +sensitive asset, like the private key in case of asymmetric cryptographic +algorithms. The main difference is that private keys are only stored on +device, with proper hardware protection against external access, but symmetric +keys must be known by both party (device and verifier), so they must also be +stored in a central server of a relying party (who verifies the tokens). +If keys are revealed then devices can be impersonated. If the database with +the symmetric keys becomes compromised then all corresponding devices become +untrusted. Since a centralised database of symmetric keys may need to be network +connected, this can be considered to be a valuable target for attackers. The +advantage of ECDSA based token authentication is that sensitive assets is only +stored one place (in the device) and only one unique key per device. So if a +device is compromised then only that single device become untrusted. In this +case, the database of the relying party contains the corresponding public keys, +which are not considered to be a confidential assets, so they can be shared with +anybody. This shows the main advantage of asymmetric based authentication, +because verification of attestation tokens can be done by a third party, +such as cloud service providers (CSP). Thus Device Maker (DM) or Chip Maker (CM) +does not need to operate such a service. + ++-------------------------+-----------------------------------------+-----------------------------------------+ +| | Symmetric | Asymmetric | ++=========================+=========================================+=========================================+ +| Authentication mode | HMAC over SHA256 | ECDSA P256 over SHA256 | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Supported APIs | - psa_initial_attest_get_token(..) | - psa_initial_attest_get_token(..) | +| | - psa_initial_attest_get_token_size(..) | - psa_initial_attest_get_token_size(..) | +| | | - tfm_initial_attest_get_public_key(..) | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Crypto key type in HW | Symmetric key | ECDSA private key (secp256r1) | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Secrets are stored | Device and database | Device only | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Verification database | Same symmetric key | Public keys | +| contains | | | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| COSE authentication tag | COSE_Mac0 | COSE_Sign1 | +| in the token | | | ++-------------------------+-----------------------------------------+-----------------------------------------+ +| Verification entity | CM or DM, who provisioned the | Can be anybody: third party provisioning| +| | symmetric key | service, cloud service provider, CM, DM | ++-------------------------+-----------------------------------------+-----------------------------------------+ + +************ +Verification +************ +The initial attestation token is verified by the attestation test suite in +``test/suites/attestation``. The test suite is responsible for verifying the +token signature and parsing the token to verify its encoding and the presence of +the mandatory claims. This test suite can be executed on the device. It is part +of the regression test suite. When the user builds TF-M with any of the +``ConfigRegression*.cmake`` configurations then this test is executed +automatically. The test suite is configurable in the +``test/suites/attestation/attest_token_test_values.h`` header file. In this file +there are two attributes for each claim which are configurable (more details +in the header file): + + - Requirements of presence: optional or mandatory + - Expected value: Value check can be disabled or expected value can be provided + here. + +There is another possibility to verify the attestation token. This addresses +the off-device testing when the token is already retrieved from the device and +verification is done on the requester side. There is a Python script for this +purpose in ``tools/iat-verifier``. It does the same checking as the +attestation test suite. The following steps describe how to simulate an +off-device token verification on a host computer. It is described how to +retrieve an initial attestation token when TF-M code is executed on FVP +and how to use the iat_verifier script to check the token. This example assumes +that user has license for DS-5 and FVP models: + + - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations + for MPS2 AN521 platform. More info in + :doc:`tfm_build_instruction </docs/getting_started/tfm_build_instruction>`. + - Lunch FVP model in DS-5. More info in + :doc:`tfm_user_guide </docs/getting_started/tfm_user_guide>`. + - Set a breakpoint in ``test/suites/attestation/attest_token_test.c`` + in ``decode_test_internal(..)`` after the ``token_main_alt(..)`` returned, + i.e. on line 859. Execute the code in the model until the breakpoint hits + second time. At this point the console prints the test case name: + + - For asymmetric initial attestation, the console prints + ``ECDSA signature test of attest token``. + - For symmetric initial attestation, the console prints + ``Symmetric key algorithm based Initial Attestation test``. + + - At this point the token resides in the model memory and can be dumped to host + computer. + - The ADDRESS and SIZE attributes of the initial attestation token is stored in + the ``completed_token`` local variable. Their value can be extracted in the + ``(x)=Variables`` debug window. + - Apply commands below in the ``Commands`` debug window to dump the token in + binary format to the host computer: + + - For asymmetric initial attestation + ``dump memory <PATH>/iat_01.cbor <ADDRESS> +<SIZE>`` + - For symmetric initial attestation + ``dump memory <PATH>/iat_hmac_02.cbor <ADDRESS> +<SIZE>`` + + - Execute commands below on the host computer to verify the token: + + - For asymmetric initial attestation + ``check_iat -p -K -k platform/ext/common/template/tfm_initial_attestation_key.pem <PATH>/iat_01.cbor`` + - For symmetric initial attestation + ``check_iat -m mac -p -K -k platform/ext/common/template/tfm_symmetric_iak.key <PATH>/iat_hmac_02.cbor`` + + - Documentation of the iat-verifier can be found + :doc:`here </tools/iat-verifier/README>`. + +-------------- + +*Copyright (c) 2018-2020, Arm Limited. All rights reserved.* |