1############################################# 2Initial Attestation Service Integration Guide 3############################################# 4 5************ 6Introduction 7************ 8TF-M Initial Attestation Service allows the application to prove the device 9identity during an authentication process to a verification entity. The initial 10attestation service can create a token on request, which contains a fix set of 11device specific data. 12 13TF-M Initial Attestation Service by default enables asymmetric key algorithm 14based attestation (*asymmetric attestation* for short). Symmetric key algorithm 15based attestation (*symmetric attestation* for short) can be enabled instead by 16selecting build option ``SYMMETRIC_INITIAL_ATTESTATION``. 17 18 - In asymmetric attestation, device must contain an attestation key pair, 19 which is unique per device. The token is signed with the private part of 20 attestation key pair. The public part of the key pair is known by the 21 verification entity. The public key is used to verify the token 22 authenticity. 23 - In symmetric attestation, device should contain a symmetric attestation 24 key to generate the authentication tag of token content. The verification 25 entity uses the same symmetric key to verify the token authenticity. 26 27The data items in the token used to verify the device integrity and assess its 28trustworthiness. Attestation key provisioning is out of scope for the 29attestation service and is expected to take part during manufacturing of the 30device. 31 32*************************************** 33Claims in the initial attestation token 34*************************************** 35The initial attestation token is formed of claims. A claim is a data item, 36which is represented in a key - value structure. The following fixed set of 37claims are included in the token: 38 39 - **Auth challenge**: Input object from caller. Can be a single nonce from 40 server or hash of nonce and attested data. It is intended to provide 41 freshness to report and the caller has responsibility to arrange 42 this. Allowed length: 32, 48, 64 bytes. The claim is modeled to be 43 eventually represented by the EAT standard claim nonce. Until such a 44 time as that standard exists, the claim will be represented by a custom 45 claim. Value is encoded as byte string. 46 47 - **Instance ID**: It represents the unique identifier of the instance. 48 In the PSA definition it is: 49 50 - a hash of the public attestation key of the instance in asymmetric 51 attestation. 52 - hashes of the symmetric attestation key of the instance in symmetric 53 attestation. 54 55 The claim is modeled to be eventually represented by the EAT standard 56 claim UEID of type GUID. Until such a time as that standard exists, the 57 claim will be represented by a custom claim Value is encoded as byte 58 string. 59 60 - **Verification service indicator**: Optional, recommended claim. It 61 is used by a Relying Party to locate a validation service for the 62 token. The value is a text string that can be used to locate the service 63 or a URL specifying the address of the service. The claim is modelled to 64 be eventually represented by the EAT standard claim origination. Until 65 such a time as that standard exists, the claim will be represented by 66 a custom claim. Value is encoded as text string. 67 68 - **Profile definition**: Optional, recommended claim. It contains the 69 name of a document that describes the 'profile' of the token, being 70 a full description of the claims, their usage, verification and token 71 signing. The document name may include versioning. Custom claim with a 72 value encoded as text string. 73 74 - **Implementation ID**: Uniquely identifies the underlying immutable PSA 75 RoT. A verification service can use this claim to locate the details of 76 the verification process. Such details include the implementation's origin 77 and associated certification state. Custom claim with a value encoded as 78 byte string. 79 80 - **Client ID**: The partition ID of that secure partition or non-secure 81 thread who called the initial attestation API. Custom claim with a value 82 encoded as a `signed` integer. Negative number represents non-secure 83 caller, positive numbers represents secure callers, zero is invalid. 84 85 - **Security lifecycle**: It represents the current lifecycle state of 86 the instance. Custom claim with a value encoded as an integer. 87 88 - **Hardware version**: Optional claim. Globally unique number in EAN-13 89 format identifying the GDSII that went to fabrication, HW and ROM. It can 90 be used to reference the security level of the PSA-ROT via a certification 91 website. Custom claim with a value is encoded as text string. 92 93 - **Boot seed**: It represents a random value created at system boot 94 time that will allow differentiation of reports from different system 95 sessions. The size is 32 bytes. Custom claim with a value is encoded as 96 byte string. 97 98 - **Software components**: Optional, but required in order to be compliant 99 with the PSA-SM. It represents the software state of the system. The value 100 of the claim is an array of CBOR map entries, with one entry per software 101 component within the device. Each map contains multiple claims that 102 describe evidence about the details of the software component. 103 104 - **No software measurements**: Optional, but required if no software 105 component claims are made. In the event that the implementation does not 106 contain any software measurements then it is mandatory to include this 107 claim to indicate this is a deliberate state. Custom claim with a value 108 encoded as an unsigned integer set to 1. 109 110Each software component claim can include the following properties. Any property 111that is not optional must be included: 112 113 - **Measurement type**: Optional claim. It represents the role of the 114 software component. Value is encoded as short(!) text string. 115 116 - **Measurement value**: It represents a hash of the invariant software 117 component in memory at start-up time. The value must be a cryptographic 118 hash of 256 bits or stronger. Value is encoded as byte string. 119 120 - **Version**: Optional claim. It represents the issued software 121 version. Value is encoded as text string. 122 123 - **Signer ID**: Optional claim, but required in order to be compliant with 124 the PSA-SM. It represents the hash of a signing authority public key. 125 Value is encoded as byte string. 126 127 - **Measurement description**: Optional claim. It represents the way in 128 which the measurement value of the software component is computed. Value 129 is encoded as text string containing an abbreviated description (name) 130 of the measurement method. 131 132********************************************* 133Initial attestation token (IAT) data encoding 134********************************************* 135The initial attestation token is planned to be aligned with future version of 136`Entity Attestation Token <https://tools.ietf.org/html/draft-mandyam-eat-01>`__ 137format. The token is encoded according to the 138`CBOR <https://tools.ietf.org/html/rfc7049>`__ format and signed according to 139`COSE <https://tools.ietf.org/html/rfc8152>`__ standard. 140 141************** 142Code structure 143************** 144The PSA interface for the Initial Attestation Service is located in 145``interface/include``. The only header to be included by applications that want 146to use functions from the PSA API is ``psa/initial_attestation.h``. 147 148The TF-M Initial Attestation Service source files are located in 149``secure_fw/partitions/initial_attestation``. 150 151Service source files 152==================== 153- CBOR library 154 - ``lib/ext/qcbor`` This library is used to create a proper CBOR token. 155 It can be used on 32-bit and 64-bit machines. It was designed to suite 156 constrained devices with low memory usage and without dynamic memory 157 allocation. 158 Its source code is fetched automatically during the build configuration 159 step from an external repository: `QCBOR library <https://github.com/laurencelundblade/QCBOR>`__. 160 - ``<qcbor_src>/inc/qcbor/qcbor_encode.h``: Public API documentation of 161 CBOR library (encoding). 162 - ``<qcbor_src>/inc/qcbor/qcbor_decode.h``: Public API documentation of 163 CBOR library (decoding). 164 165- COSE library: 166 - ``lib/ext/t_cose``: This library is used to sign a CBOR token and create 167 the COSE header and signature around the initial attestation token. Only 168 a subset of the `COSE <https://tools.ietf.org/html/rfc8152>`__ standard 169 is implemented. The COSE_Sign1 and COSE_Mac0 (only available in TF-M fork) 170 signature schemas are supported. 171 - It is a fork of this external `t_cose library <https://github.com/laurencelundblade/t_cose>`__. 172 - ``lib/ext/t_cose/src/t_cose_crypto.h``: Expose an API to bind ``t_cose`` 173 library with available crypto library in the device. 174 - ``lib/ext/t_cose/crypto_adapters/t_cose_psa_crypto.c``: Implements the 175 exposed API and ports ``t_cose`` to the PSA Crypto API. 176- Initial Attestation Service: 177 - ``attest_core.c`` : Implements core functionalities such as implementation 178 of APIs, retrieval of claims and token creation. 179 - ``attest_token_encode.c``: Implements the token creation functions such as 180 start and finish token creation and adding claims to the token. 181 - ``attest_asymmetric_key.c``: Calculate the Instance ID value based on 182 asymmetric initial attestation key. 183 - ``tfm_attest.c``: Implements the SPM abstraction layer, and bind the 184 attestation service to the SPM implementation in TF-M project. 185 - ``tfm_attest_req_mngr.c``: Includes the initialization entry of 186 attestation service and handles attestation service requests in IPC 187 model. 188 - ``attest_symmetric_key.c``: Calculate the Instance ID value based on 189 symmetric initial attestation key. 190 191Service interface definitions 192============================= 193- **Boot loader interface**: The attestation service might include data 194 in the token about the distinct software components in the device. This data 195 is provided by the boot loader and must be encoded in the TLV format, 196 definition is described below in the boot loader interface paragraph. Possible 197 claims in the boot status are describe above in the software components 198 paragraph. 199- **Hardware abstraction layer**: 200 - Headers are located in ``platform/include`` folder. 201 - ``tfm_attest_hal.h``: Expose an API to get the following claims: 202 security lifecycle, verification service indicator, profile definition. 203 - ``tfm_plat_boot_seed.h``: Expose an API to get the boot seed claim. 204 - ``tfm_plat_device_id.h``: Expose an API to get the following claims: 205 implementation ID, hardware version. 206- **SPM interface**: 207 - ``attestation.h``: Expose an API to bind attestation service to an SPM 208 implementation. 209- **PSA interface**: 210 - ``psa/initial_attestation.h``: Public API definition of initial 211 attestation service. 212- **Crypto interface**: 213 - ``t_cose_crypto.h``: Expose an API to bind the ``t_cose`` implementation 214 to any cryptographic library. 215 216PSA interface 217============= 218The TF-M Initial Attestation Service exposes the following PSA 219interface: 220 221.. code-block:: c 222 223 psa_status_t 224 psa_initial_attest_get_token(const uint8_t *auth_challenge, 225 size_t challenge_size, 226 uint8_t *token_buf, 227 size_t token_buf_size, 228 size_t *token_size); 229 230 psa_status_t 231 psa_initial_attest_get_token_size(size_t challenge_size, 232 size_t *token_size); 233 234The caller must allocate a large enough buffer, where the token is going to be 235created by Initial Attestation Service. The size of the created token is highly 236dependent on the number of software components in the system and the provided 237attributes of these. The ``psa_initial_attest_get_token_size()`` function can be 238called to get the exact size of the created token. 239 240System integrators might need to port these interfaces to a custom secure 241partition manager implementation (SPM). Implementations in TF-M project can be 242found here: 243 244- ``interface/src/tfm_attest_api.c``: interface implementation. 245 246Secure Partition Manager (SPM) interface 247======================================== 248The Initial Attestation Service defines the following interface towards the 249secure partition manager (SPM). System integrators **must** port this interface 250according to their SPM implementation. 251 252.. code:: c 253 254 enum psa_attest_err_t 255 attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len); 256 257 enum psa_attest_err_t 258 attest_get_caller_client_id(int32_t *caller_id); 259 260- ``attest_get_boot_data()``: Service can retrieve the relevant data from shared 261 memory area between boot loader and runtime software. It might be the case 262 that only SPM has direct access to the shared memory area, therefore this 263 function can be used to copy the service related data from shared memory to 264 a local memory buffer. In TF-M implementation this function must be called 265 during service initialization phase, because the shared memory region is 266 deliberately overlapping with secure main stack to spare some memory and reuse 267 this area during execution. If boot loader is not available in the system to 268 provide attributes of software components then this function must be 269 implemented in a way that just initialize service's memory buffer to: 270 271 .. code-block:: c 272 273 struct shared_data_tlv_header *tlv_header = (struct shared_data_tlv_header *)ptr; 274 tlv_header->tlv_magic = 2016; 275 tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header); 276 277- ``attest_get_caller_client_id()``: Retrieves the ID of the caller thread. 278- ``tfm_client.h``: Service relies on the following external definitions, which 279 must be present or included in this header file: 280 281 .. code-block:: c 282 283 typedef struct psa_invec { 284 const void *base; 285 size_t len; 286 } psa_invec; 287 288 typedef struct psa_outvec { 289 void *base; 290 size_t len; 291 } psa_outvec; 292 293Hardware abstraction layer 294========================== 295The following API definitions are intended to retrieve the platform specific 296claims. System integrators **must** implement these interface according to their 297SoC and software design. Detailed definition of the claims are above 298in the claims in the initial attestation token paragraph. 299 300- ``tfm_attest_hal_get_security_lifecycle()``: Get the security lifecycle of the 301 device. 302- ``tfm_attest_hal_get_verification_service()``: Get the verification 303 service indicator for initial attestation. 304- ``tfm_attest_hal_get_profile_definition()``: Get the name of the profile 305 definition document for initial attestation. 306- ``tfm_plat_get_boot_seed()``: Get the boot seed, which is a constant random 307 number during a boot cycle. 308- ``tfm_plat_get_implementation_id``: Get the implementation ID of the 309 device. 310- ``tfm_plat_get_cert_ref``: Get the hardware version of the device. 311 312Boot loader interface 313===================== 314It is **recommended** to have a secure boot loader in the boot chain, which is 315capable of measuring the runtime firmware components (calculates the hash value 316of firmware images) and provide other attributes of these (version, type, etc). 317If the used boot loader is not capable of sharing these information with the 318runtime software then the ``BOOT_DATA_AVAILABLE`` compiler flag **must** be 319set to OFF (see `Related compile time options`_). 320 321The shared data between boot loader and runtime software is TLV encoded. The 322definition of TLV structure is described in ``bl2/include/tfm_boot_status.h``. 323The shared data is stored in a well known location in secure internal memory 324and this is a contract between boot loader and runtime SW. 325 326The structure of shared data must be the following: 327 328- At the beginning there must be a header: ``struct shared_data_tlv_header`` 329 This contains a magic number and a size field which covers the entire size 330 of the shared data area including this header. 331 332 .. code-block:: c 333 334 struct shared_data_tlv_header { 335 uint16_t tlv_magic; 336 uint16_t tlv_tot_len; 337 }; 338 339- The header is followed by the entries which are composed from an 340 entry header structure: ``struct shared_data_tlv_entry`` and the data. In 341 the entry header there is a type and a length field. The ``tlv_type`` field 342 identifies the consumer of the entry in the runtime software and specify the 343 subtype of that data item. The ``tlv_len`` field covers the length of the 344 data (not including the size of the entry header). 345 346 After the entry header structure comes the actual data. 347 348 .. code-block:: c 349 350 struct shared_data_tlv_entry { 351 uint16_t tlv_type; 352 uint16_t tlv_len; 353 }; 354 355- Arbitrary number and size of data entry can be in the shared memory 356 area. 357 358The figure below gives of overview about the ``tlv_type`` field in the entry 359header. The ``tlv_type`` always composed from a major and minorbnumber. Major 360number identifies the addressee in runtime software, which the databentry is 361sent to. Minor number used to encode more info about the data entry. The actual 362definition of minor number could change per major number. In case of boot 363status data, which is going to be processed by initial attestation service 364the minor number is split further to two part: ``sw_module`` and ``claim``. The 365``sw_module`` identifies the SW component in the system which the data item 366belongs to and the ``claim`` part identifies the exact type of the data. 367 368``tlv_type`` description:: 369 370 |------------------------------------------------ | 371 | tlv_type (16 bits) | 372 |-------------------------------------------------| 373 | tlv_major(4 bits) | tlv_minor(12 bits) | 374 |-------------------------------------------------| 375 | MAJOR_IAS | sw_module(6 bits) | claim(6 bits) | 376 |-------------------------------------------------| 377 | MAJOR_CORE | TBD | 378 |-------------------------------------------------| 379 380Overall structure of shared data:: 381 382 --------------------------------------------------------------- 383 | Magic number(uint16_t) | Shared data total length(uint16_t) | 384 --------------------------------------------------------------- 385 | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) | 386 --------------------------------------------------------------- 387 | Raw data | 388 --------------------------------------------------------------- 389 | . | 390 | . | 391 | . | 392 --------------------------------------------------------------- 393 | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) | 394 --------------------------------------------------------------- 395 | Raw data | 396 --------------------------------------------------------------- 397 398Crypto interface 399================ 400 401Asymmetric key algorithm based attestation 402------------------------------------------ 403Device **must** contain an asymmetric key pair. The private part of it is used 404to sign the initial attestation token. Current implementation supports only the 405ECDSA P256 signature over SHA256. The public part of the key pair is used to 406create the key identifier (kid) in the unprotected part of the COSE header. The 407kid is used by verification entity to look up the corresponding public key to 408verify the signature in the token. The `t_cose` part of the initial attestation 409service implements the signature generation and kid creation. But the actual 410calculation of token's hash and signature is done by the Crypto service in the 411device. System integrators might need to re-implement the following functions 412if they want to use initial attestation service with a different cryptographic 413library than Crypto service: 414 415- ``t_cose_crypto_pub_key_sign()``: Calculates the signature over a hash value. 416- ``t_cose_crypto_get_ec_pub_key()``: Get the public key to create the key 417 identifier. 418- ``t_cose_crypto_hash_start()``: Start a multipart hash operation. 419- ``t_cose_crypto_hash_update()``: Add a message fragment to a multipart hash 420 operation. 421- ``t_cose_crypto_hash_finish()``:Finish the calculation of the hash of a 422 message. 423 424Interface needed by verification code: 425 426- ``t_cose_crypto_pub_key_verify()``: Verify the signature over a hash value. 427 428Key handling 429^^^^^^^^^^^^ 430The provisioning of the initial attestation key is out of scope of the service 431and this document. It is assumed that device maker provisions the unique 432asymmetric key pair during the manufacturing process. Software integrators 433**must** make sure that ``TFM_BUILTIN_KEY_SLOT_IAK`` is available via the Crypto 434service, which will then be used by the Attestation partition to perform the 435required signing operations via the PSA crypto interface. 436 437Symmetric key algorithm based attestation 438----------------------------------------- 439Device **must** contain a symmetric key to generate the authentication tag of 440the initial attestation token. A key identifier (kid) can be encoded in the 441unprotected part of the COSE header. It helps verification entity look up the 442symmetric key to verify the authentication tag in the token. 443 444The `t_cose` part of the initial attestation service implements the 445authentication tag generation. The authentication tag generation is done by the 446Crypto service. System integrators might need to re-implement the following 447functions if platforms provide a different cryptographic library than Crypto 448service: 449 450- ``t_cose_crypto_hmac_sign_setup()``: Set up a multi-part HMAC calculation 451 operation. 452- ``t_cose_crypto_hmac_update()``: Add a message fragment to a multi-part HMAC 453 operation. 454- ``t_cose_crypto_hmac_sign_finish()``: Finish the calculation of the HMAC of a 455 message. 456 457Interface needed by verification code: 458 459- ``t_cose_crypto_hmac_verify_setup()``: Set up a multi-part HMAC verification 460 operation. 461- ``t_cose_crypto_hmac_verify_finish()``: Finish the verification of the HMAC of 462 a message. 463 464It also requires the same hash operations as listed in asymmetric key algorithm 465based initial attestation above, in attestation test cases. 466 467Key handling 468^^^^^^^^^^^^ 469The provisioning of the initial attestation key is out of scope of the service 470and this document. It is assumed that device maker provisions the symmetric key 471during the manufacturing process. The following API is defined to retrieve the 472symmetric attestation key from platform layer. Software integrators **must** 473port this interface according to their SoC design and make sure that key is 474available by Crypto service: 475 476- ``tfm_plat_get_symmetric_iak()``: Get the symmetric initial attestation key 477 raw data. 478- ``tfm_plat_get_symmetric_iak_id()``: Get the key identifier of the symmetric 479 initial attestation key. The key identifier can be used as ``kid`` parameter 480 in COSE header. Optional. 481 482.. note:: 483 484 Asymmetric initial attestation and symmetric initial attestation may share 485 the same HAL APIs in future development. 486 487Initial Attestation Service compile time options 488================================================ 489There is a defined set of flags that can be used to compile in/out certain 490service features. The ``CommonConfig.cmake`` file sets the default values of 491those flags. The list of flags are: 492 493- ``ATTEST_INCLUDE_OPTIONAL_CLAIMS``: Include also the optional claims to the 494 attestation token. Default value: ON in base configure and profile large while 495 OFF in profile small and medium. 496- ``ATTEST_INCLUDE_COSE_KEY_ID``: COSE key-id is an optional field in the COSE 497 unprotected header. Key-id is calculated and added to the COSE header based 498 on the value of this flag. Default value: OFF. 499- ``ATTEST_CLAIM_VALUE_CHECK``: Check attestation claims against hard-coded 500 values found in ``platform/ext/common/template/attest_hal.c``. Default value 501 is OFF. Set to ON in a platform's CMake file if the attest HAL is not yet 502 properly ported to it. 503- ``SYMMETRIC_INITIAL_ATTESTATION``: Select symmetric initial attestation. 504 Default value: OFF. 505- ``ATTEST_INCLUDE_TEST_CODE``: The initial attestation implementation is 506 instrumented with additional test code. This is required in order to run 507 some of the initial attestation regression tests. 508 These tests are not required to be run by platform integrators, and are 509 only meant to be used for development or modification of the initial 510 attestation implementation. 511 Enabling this option enables T_COSE_DISABLE_SHORT_CIRCUIT_SIGN which will 512 short circuit the signing operation. 513 Default value: OFF. 514- ``ATTEST_STACK_SIZE``- Defines the stack size of the Initial Attestation Partition. 515 This value mainly depends on the build type(debug, release and minisizerel) and 516 compiler. 517 518Related compile time options 519---------------------------- 520- ``BOOT_DATA_AVAILABLE``: The boot data is expected to be present in the shared 521 data area between the boot loader and the runtime firmware when it's ON. 522 Otherwise, when it's OFF does not check the content of the shared data area 523 but instead assumes that the TLV header is present and valid (the magic number 524 is correct) and there are no data entries. Its default value depends on the 525 BL2 flag. 526 527*************************************************************************** 528Comparison of asymmetric and symmetric algorithm based token authentication 529*************************************************************************** 530The symmetric key based authentication requires a more complex infrastructure 531for key management. Symmetric keys must be kept secret because they are 532sensitive asset, like the private key in case of asymmetric cryptographic 533algorithms. The main difference is that private keys are only stored on 534device, with proper hardware protection against external access, but symmetric 535keys must be known by both party (device and verifier), so they must also be 536stored in a central server of a relying party (who verifies the tokens). 537If keys are revealed then devices can be impersonated. If the database with 538the symmetric keys becomes compromised then all corresponding devices become 539untrusted. Since a centralised database of symmetric keys may need to be network 540connected, this can be considered to be a valuable target for attackers. The 541advantage of ECDSA based token authentication is that sensitive assets is only 542stored one place (in the device) and only one unique key per device. So if a 543device is compromised then only that single device become untrusted. In this 544case, the database of the relying party contains the corresponding public keys, 545which are not considered to be a confidential assets, so they can be shared with 546anybody. This shows the main advantage of asymmetric based authentication, 547because verification of attestation tokens can be done by a third party, 548such as cloud service providers (CSP). Thus Device Maker (DM) or Chip Maker (CM) 549does not need to operate such a service. 550 551+-------------------------+-----------------------------------------+-----------------------------------------+ 552| | Symmetric | Asymmetric | 553+=========================+=========================================+=========================================+ 554| Authentication mode | HMAC over SHA256 | ECDSA P256 over SHA256 | 555+-------------------------+-----------------------------------------+-----------------------------------------+ 556| Crypto key type in HW | Symmetric key | ECDSA private key (secp256r1) | 557+-------------------------+-----------------------------------------+-----------------------------------------+ 558| Secrets are stored | Device and database | Device only | 559+-------------------------+-----------------------------------------+-----------------------------------------+ 560| Verification database | Same symmetric key | Public keys | 561| contains | | | 562+-------------------------+-----------------------------------------+-----------------------------------------+ 563| COSE authentication tag | COSE_Mac0 | COSE_Sign1 | 564| in the token | | | 565+-------------------------+-----------------------------------------+-----------------------------------------+ 566| Verification entity | CM or DM, who provisioned the | Can be anybody: third party provisioning| 567| | symmetric key | service, cloud service provider, CM, DM | 568+-------------------------+-----------------------------------------+-----------------------------------------+ 569 570************ 571Verification 572************ 573 574Regression test 575=============== 576 577The initial attestation token is verified by the attestation test suite in 578``test/secure_fw/suites/attestation``. The test suite is responsible for 579verifying the token signature and parsing the token to verify its encoding and 580the presence of the mandatory claims. This test suite can be executed on the 581device. It is part of the regression test suite. The test suite is configurable 582in the ``test/secure_fw/suites/attestation/attest_token_test_values.h`` header 583file. In this file there are two attributes for each claim which are 584configurable (more details in the header file): 585 586 - Requirements of presence: optional or mandatory 587 - Expected value: Value check can be disabled or expected value can be provided 588 here. 589 590For initial attestation tests, the built-in IAK is used. 591Initial attestation regression test verifies the IAT generated by initial 592attestation service with the exported public key. 593 594iat-verifier 595============ 596 597There is another possibility to verify the attestation token. This addresses 598the off-device testing when the token is already retrieved from the device and 599verification is done on the requester side. There is a Python script for this 600purpose in the `tf-m-tools`_ repo called `iat-verifier`_. It does the same 601checking as the attestation test suite. The following steps describe how to 602simulate an off-device token verification on a host computer. It is described 603how to retrieve an initial attestation token when TF-M code is executed on FVP 604and how to use the iat-verifier script to check the token. This example assumes 605that user has license for DS-5 and FVP models: 606 607.. _tf-m-tools: https://git.trustedfirmware.org/TF-M/tf-m-tools.git 608 609.. _iat-verifier: https://git.trustedfirmware.org/TF-M/tf-m-tools.git/tree/ 610 iat-verifier 611 612 - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations 613 for MPS2 AN521 platform. More info in 614 :doc:`tfm_build_instruction </building/tfm_build_instruction>`. 615 - Lunch FVP model in DS-5. More info in 616 :doc:`Run TF-M examples on Arm platforms </building/run_tfm_examples_on_arm_platforms>`. 617 - Set a breakpoint in ``test/secure_fw/suites/attestation/attest_token_test.c`` 618 in ``decode_test_internal(..)`` after the ``token_main_alt(..)`` returned, 619 i.e. on line 859. Execute the code in the model until the breakpoint hits 620 second time. At this point the console prints the test case name: 621 622 - For asymmetric initial attestation, the console prints 623 ``ECDSA signature test of attest token``. 624 - For symmetric initial attestation, the console prints 625 ``Symmetric key algorithm based Initial Attestation test``. 626 627 - At this point the token resides in the model memory and can be dumped to host 628 computer. 629 - The ADDRESS and SIZE attributes of the initial attestation token is stored in 630 the ``completed_token`` local variable. Their value can be extracted in the 631 ``(x)=Variables`` debug window. 632 - Apply commands below in the ``Commands`` debug window to dump the token in 633 binary format to the host computer: 634 635 - For asymmetric initial attestation 636 ``dump memory <PATH>/iat_01.cbor <ADDRESS> +<SIZE>`` 637 - For symmetric initial attestation 638 ``dump memory <PATH>/iat_hmac_02.cbor <ADDRESS> +<SIZE>`` 639 640 - Execute commands below on the host computer to verify the token: 641 642 - For asymmetric initial attestation 643 ``check_iat -p -K -k platform/ext/common/template/tfm_initial_attestation_key.pem <PATH>/iat_01.cbor`` 644 - For symmetric initial attestation 645 ``check_iat -m mac -p -K -k platform/ext/common/template/tfm_symmetric_iak.key <PATH>/iat_hmac_02.cbor`` 646 647 - Documentation of the iat-verifier can be found in the 648 :doc:`tf-m-tools-iat-verifer<TF-M-Tools:iat-verifier>`. 649 650-------------- 651 652*Copyright (c) 2018-2022, Arm Limited. All rights reserved.* 653
