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_Sign, COSE_Sign1, COSE_Mac0 signature and the 170 COSE_Encrypt, COSE_Encrypt0 encryption schemes are supported. 171 Its source code is fetched automatically during the build configuration 172 step from an external repository: `t_cose library <https://github.com/laurencelundblade/t_cose>`__. 173 - ``<t_cose_src>/src/t_cose_crypto.h``: Expose an API to bind ``t_cose`` 174 library with available crypto library in the device. 175 - ``<t_cose_src>/crypto_adapters/t_cose_psa_crypto.c``: Implements the 176 exposed API and ports ``t_cose`` to the PSA Crypto API. 177 178- Initial Attestation Service: 179 - ``attest_core.c`` : Implements core functionalities such as implementation 180 of APIs, retrieval of claims and token creation. 181 - ``attest_boot_data.c`` : Implements core functionalities for measured 182 boot. 183 - ``attest_token_encode.c``: Implements the token creation functions such as 184 start and finish token creation and adding claims to the token. 185 - ``attest_asymmetric_key.c``: Calculate the Instance ID value based on 186 asymmetric initial attestation key. 187 - ``tfm_attest.c``: Implements the SPM abstraction layer, and bind the 188 attestation service to the SPM implementation in TF-M project. 189 - ``tfm_attest_req_mngr.c``: Includes the initialization entry of 190 attestation service and handles attestation service requests in IPC 191 model. 192 - ``attest_symmetric_key.c``: Calculate the Instance ID value based on 193 symmetric initial attestation key. 194 195Service interface definitions 196============================= 197- **Boot loader interface**: The attestation service might include data 198 in the token about the distinct software components in the device. This data 199 is provided by the boot loader and must be encoded in the TLV format, 200 definition is described below in the boot loader interface paragraph. Possible 201 claims in the boot status are described above in the software components 202 paragraph. 203- **Hardware abstraction layer**: 204 - Headers are located in ``platform/include`` folder. 205 - ``tfm_attest_hal.h``: Expose an API to get the following claims: 206 security lifecycle, verification service indicator, profile definition. 207 - ``tfm_plat_boot_seed.h``: Expose an API to get the boot seed claim. 208 - ``tfm_plat_device_id.h``: Expose an API to get the following claims: 209 implementation ID, hardware version. 210- **SPM interface**: 211 - ``attestation.h``: Expose an API to bind attestation service to an SPM 212 implementation. 213- **PSA interface**: 214 - ``psa/initial_attestation.h``: Public API definition of initial 215 attestation service. 216- **Crypto interface**: 217 - ``t_cose_crypto.h``: Expose an API to bind the ``t_cose`` implementation 218 to any cryptographic library. 219 220PSA interface 221============= 222The TF-M Initial Attestation Service exposes the following PSA 223interface: 224 225.. code-block:: c 226 227 psa_status_t 228 psa_initial_attest_get_token(const uint8_t *auth_challenge, 229 size_t challenge_size, 230 uint8_t *token_buf, 231 size_t token_buf_size, 232 size_t *token_size); 233 234 psa_status_t 235 psa_initial_attest_get_token_size(size_t challenge_size, 236 size_t *token_size); 237 238The caller must allocate a large enough buffer, where the token is going to be 239created by Initial Attestation Service. The size of the created token is highly 240dependent on the number of software components in the system and the provided 241attributes of these. The ``psa_initial_attest_get_token_size()`` function can be 242called to get the exact size of the created token. 243 244System integrators might need to port these interfaces to a custom secure 245partition manager implementation (SPM). Implementations in TF-M project can be 246found here: 247 248- ``interface/src/tfm_attest_api.c``: interface implementation. 249 250Secure Partition Manager (SPM) interface 251======================================== 252The Initial Attestation Service defines the following interface towards the 253secure partition manager (SPM). System integrators **must** port this interface 254according to their SPM implementation. 255 256.. code:: c 257 258 enum psa_attest_err_t 259 attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len); 260 261 enum psa_attest_err_t 262 attest_get_caller_client_id(int32_t *caller_id); 263 264- ``attest_get_boot_data()``: Service can retrieve the relevant data from shared 265 memory area between boot loader and runtime software. It might be the case 266 that only SPM has direct access to the shared memory area, therefore this 267 function can be used to copy the service related data from shared memory to 268 a local memory buffer. In TF-M implementation this function must be called 269 during service initialization phase, because the shared memory region is 270 deliberately overlapping with secure main stack to spare some memory and reuse 271 this area during execution. If boot loader is not available in the system to 272 provide attributes of software components then this function must be 273 implemented in a way that just initialize service's memory buffer to: 274 275 .. code-block:: c 276 277 struct shared_data_tlv_header *tlv_header = (struct shared_data_tlv_header *)ptr; 278 tlv_header->tlv_magic = 2016; 279 tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header); 280 281- ``attest_get_caller_client_id()``: Retrieves the ID of the caller thread. 282- ``tfm_client.h``: Service relies on the following external definitions, which 283 must be present or included in this header file: 284 285 .. code-block:: c 286 287 typedef struct psa_invec { 288 const void *base; 289 size_t len; 290 } psa_invec; 291 292 typedef struct psa_outvec { 293 void *base; 294 size_t len; 295 } psa_outvec; 296 297Hardware abstraction layer 298========================== 299The following API definitions are intended to retrieve the platform specific 300claims. System integrators **must** implement these interface according to their 301SoC and software design. Detailed definition of the claims are above 302in the claims in the initial attestation token paragraph. 303 304- ``tfm_attest_hal_get_security_lifecycle()``: Get the security lifecycle of the 305 device. 306- ``tfm_attest_hal_get_verification_service()``: Get the verification 307 service indicator for initial attestation. 308- ``tfm_attest_hal_get_profile_definition()``: Get the name of the profile 309 definition document for initial attestation. 310- ``tfm_plat_get_boot_seed()``: Get the boot seed, which is a constant random 311 number during a boot cycle. 312- ``tfm_plat_get_implementation_id``: Get the implementation ID of the 313 device. 314- ``tfm_plat_get_cert_ref``: Get the hardware version of the device. 315 316Boot loader interface 317===================== 318It is **recommended** to have a secure boot loader in the boot chain, which is 319capable of measuring the runtime firmware components (calculates the hash value 320of firmware images) and provide other attributes of these (version, type, etc). 321If the used boot loader is not capable of sharing these information with the 322runtime software then the ``BOOT_DATA_AVAILABLE`` compiler flag **must** be 323set to OFF (see `Related compile time options`_). 324 325The shared data between boot loader and runtime software is TLV encoded. The 326definition of TLV structure is described in ``bl2/include/tfm_boot_status.h``. 327The shared data is stored in a well known location in secure internal memory 328and this is a contract between boot loader and runtime SW. 329 330The structure of shared data must be the following: 331 332- At the beginning there must be a header: ``struct shared_data_tlv_header`` 333 This contains a magic number and a size field which covers the entire size 334 of the shared data area including this header. 335 336 .. code-block:: c 337 338 struct shared_data_tlv_header { 339 uint16_t tlv_magic; 340 uint16_t tlv_tot_len; 341 }; 342 343- The header is followed by the entries which are composed from an 344 entry header structure: ``struct shared_data_tlv_entry`` and the data. In 345 the entry header there is a type and a length field. The ``tlv_type`` field 346 identifies the consumer of the entry in the runtime software and specify the 347 subtype of that data item. The ``tlv_len`` field covers the length of the 348 data (not including the size of the entry header). 349 350 After the entry header structure comes the actual data. 351 352 .. code-block:: c 353 354 struct shared_data_tlv_entry { 355 uint16_t tlv_type; 356 uint16_t tlv_len; 357 }; 358 359- Arbitrary number and size of data entry can be in the shared memory 360 area. 361 362The figure below gives an overview about the ``tlv_type`` field in the entry 363header. The ``tlv_type`` is always composed from a major and a minor number. 364Major number identifies the addressee in runtime software, which the data entry 365is sent to. Minor number is used to encode more info about the data entry. The 366actual definition of minor number could change per major number. In case of boot 367status data, which is going to be processed by initial attestation service, 368the minor number is split further to two part: ``sw_module`` and ``claim``. The 369``sw_module`` identifies the SW component in the system which the data item 370belongs to and the ``claim`` part identifies the exact type of the data. 371 372``tlv_type`` description:: 373 374 |------------------------------------------------ | 375 | tlv_type (16 bits) | 376 |-------------------------------------------------| 377 | tlv_major(4 bits) | tlv_minor(12 bits) | 378 |-------------------------------------------------| 379 | MAJOR_IAS | sw_module(6 bits) | claim(6 bits) | 380 |-------------------------------------------------| 381 | MAJOR_CORE | TBD | 382 |-------------------------------------------------| 383 384Overall structure of shared data:: 385 386 --------------------------------------------------------------- 387 | Magic number(uint16_t) | Shared data total length(uint16_t) | 388 --------------------------------------------------------------- 389 | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) | 390 --------------------------------------------------------------- 391 | Raw data | 392 --------------------------------------------------------------- 393 | . | 394 | . | 395 | . | 396 --------------------------------------------------------------- 397 | Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) | 398 --------------------------------------------------------------- 399 | Raw data | 400 --------------------------------------------------------------- 401 402Crypto interface 403================ 404 405Asymmetric key algorithm based attestation 406------------------------------------------ 407Device **must** contain an asymmetric key pair. The private part of it is used 408to sign the initial attestation token. Current implementation supports only the 409ECDSA P256 signature over SHA256. The public part of the key pair is used to 410create the key identifier (kid) in the unprotected part of the COSE header. The 411kid is used by the verification entity to look up the corresponding public key 412to verify the signature in the token. The `t_cose` part of the initial 413attestation service implements the signature generation and kid creation. But 414the actual calculation of token's hash and signature is done by the Crypto 415service in the device. System integrators might need to re-implement the 416following functions if they want to use initial attestation service with a 417different cryptographic library than Crypto service: 418 419- ``t_cose_crypto_pub_key_sign()``: Calculates the signature over a hash value. 420- ``t_cose_crypto_get_ec_pub_key()``: Get the public key to create the key 421 identifier. 422- ``t_cose_crypto_hash_start()``: Start a multipart hash operation. 423- ``t_cose_crypto_hash_update()``: Add a message fragment to a multipart hash 424 operation. 425- ``t_cose_crypto_hash_finish()``:Finish the calculation of the hash of a 426 message. 427 428Interface needed by verification code: 429 430- ``t_cose_crypto_pub_key_verify()``: Verify the signature over a hash value. 431 432Key handling 433^^^^^^^^^^^^ 434The provisioning of the initial attestation key is out of scope of the service 435and this document. It is assumed that device maker provisions the unique 436asymmetric key pair during the manufacturing process. Software integrators 437**must** make sure that ``TFM_BUILTIN_KEY_SLOT_IAK`` is available via the Crypto 438service, which will then be used by the Attestation partition to perform the 439required signing operations via the PSA crypto interface. 440 441Symmetric key algorithm based attestation 442----------------------------------------- 443Device **must** contain a symmetric key to generate the authentication tag of 444the initial attestation token. A key identifier (kid) can be encoded in the 445unprotected part of the COSE header. It helps verification entity look up the 446symmetric key to verify the authentication tag in the token. 447 448The `t_cose` part of the initial attestation service implements the 449authentication tag generation. The authentication tag generation is done by the 450Crypto service. System integrators might need to re-implement the following 451functions if platforms provide a different cryptographic library than Crypto 452service: 453 454- ``t_cose_crypto_hmac_sign_setup()``: Set up a multi-part HMAC calculation 455 operation. 456- ``t_cose_crypto_hmac_update()``: Add a message fragment to a multi-part HMAC 457 operation. 458- ``t_cose_crypto_hmac_sign_finish()``: Finish the calculation of the HMAC of a 459 message. 460 461Interface needed by verification code: 462 463- ``t_cose_crypto_hmac_verify_setup()``: Set up a multi-part HMAC verification 464 operation. 465- ``t_cose_crypto_hmac_verify_finish()``: Finish the verification of the HMAC of 466 a message. 467 468It also requires the same hash operations as listed in asymmetric key algorithm 469based initial attestation above, in attestation test cases. 470 471Key handling 472^^^^^^^^^^^^ 473The provisioning of the initial attestation key is out of scope of the service 474and this document. It is assumed that device maker provisions the symmetric key 475during the manufacturing process. The following API is defined to retrieve the 476symmetric attestation key from platform layer. Software integrators **must** 477port this interface according to their SoC design and make sure that key is 478available by Crypto service: 479 480- ``tfm_plat_get_symmetric_iak()``: Get the symmetric initial attestation key 481 raw data. 482- ``tfm_plat_get_symmetric_iak_id()``: Get the key identifier of the symmetric 483 initial attestation key. The key identifier can be used as ``kid`` parameter 484 in COSE header. Optional. 485 486.. note:: 487 488 Asymmetric initial attestation and symmetric initial attestation may share 489 the same HAL APIs in future development. 490 491Initial Attestation Service compile time options 492================================================ 493There is a defined set of flags that can be used to compile in/out certain 494service features. The ``config_base.cmake`` file sets the default values of 495those flags. The list of flags are: 496 497- ``ATTEST_INCLUDE_OPTIONAL_CLAIMS``: Include also the optional claims to the 498 attestation token. Default value: ON in base configure and profile large while 499 OFF in profile small and medium. 500- ``ATTEST_INCLUDE_COSE_KEY_ID``: COSE key-id is an optional field in the COSE 501 unprotected header. Key-id is calculated and added to the COSE header based 502 on the value of this flag. Default value: OFF. 503- ``SYMMETRIC_INITIAL_ATTESTATION``: Select symmetric initial attestation. 504 Default value: OFF. 505- ``ATTEST_STACK_SIZE``- Defines the stack size of the Initial Attestation 506 Partition. This value mainly depends on the build type(debug, release and 507 minisizerel) and compiler. 508 Default value: Depends on the profile. 509- ``ATTEST_KEY_BITS`` Defines the size of the initial attestation key, in bits. 510 Default value: 256. 511- ``PSA_INITIAL_ATTEST_MAX_TOKEN_SIZE`` Defines the maximum possible size of a 512 token. 513 Default value: 0x250. 514 515Related compile time options 516---------------------------- 517- ``BOOT_DATA_AVAILABLE``: The boot data is expected to be present in the shared 518 data area between the boot loader and the runtime firmware when set to ``ON``. 519 Otherwise, when it's ``OFF`` TF-M does not check the content of the shared 520 data area but instead assumes that the TLV header is present and valid (the 521 magic number is correct) and there are no data entries. Its default value 522 depends on the BL2 flag. 523 524*************************************************************************** 525Comparison of asymmetric and symmetric algorithm based token authentication 526*************************************************************************** 527The symmetric key based authentication requires a more complex infrastructure 528for key management. Symmetric keys must be kept secret because they are 529sensitive asset, like the private key in case of asymmetric cryptographic 530algorithms. The main difference is that private keys are only stored on 531device, with proper hardware protection against external access, but symmetric 532keys must be known by both party (device and verifier), so they must also be 533stored in a central server of a relying party (who verifies the tokens). 534If keys are revealed then devices can be impersonated. If the database with 535the symmetric keys becomes compromised then all corresponding devices become 536untrusted. Since a centralised database of symmetric keys may need to be network 537connected, this can be considered to be a valuable target for attackers. The 538advantage of ECDSA based token authentication is that sensitive assets is only 539stored one place (in the device) and only one unique key per device. So if a 540device is compromised then only that single device become untrusted. In this 541case, the database of the relying party contains the corresponding public keys, 542which are not considered to be a confidential assets, so they can be shared with 543anybody. This shows the main advantage of asymmetric based authentication, 544because verification of attestation tokens can be done by a third party, 545such as cloud service providers (CSP). Thus Device Maker (DM) or Chip Maker (CM) 546does not need to operate such a service. 547 548+-------------------------+-----------------------------------------+-----------------------------------------+ 549| | Symmetric | Asymmetric | 550+=========================+=========================================+=========================================+ 551| Authentication mode | HMAC over SHA256 | ECDSA P256 over SHA256 | 552+-------------------------+-----------------------------------------+-----------------------------------------+ 553| Crypto key type in HW | Symmetric key | ECDSA private key (secp256r1) | 554+-------------------------+-----------------------------------------+-----------------------------------------+ 555| Secrets are stored | Device and database | Device only | 556+-------------------------+-----------------------------------------+-----------------------------------------+ 557| Verification database | Same symmetric key | Public keys | 558| contains | | | 559+-------------------------+-----------------------------------------+-----------------------------------------+ 560| COSE authentication tag | COSE_Mac0 | COSE_Sign1 | 561| in the token | | | 562+-------------------------+-----------------------------------------+-----------------------------------------+ 563| Verification entity | CM or DM, who provisioned the | Can be anybody: third party provisioning| 564| | symmetric key | service, cloud service provider, CM, DM | 565+-------------------------+-----------------------------------------+-----------------------------------------+ 566 567************ 568Verification 569************ 570 571Regression test 572=============== 573 574The initial attestation token is verified by the attestation test suite in 575``test/secure_fw/suites/attestation``. The test suite is responsible for 576verifying the token signature and parsing the token to verify its encoding and 577the presence of the mandatory claims. This test suite can be executed on the 578device. It is part of the regression test suite. The test suite is configurable 579in the ``test/secure_fw/suites/attestation/attest_token_test_values.h`` header 580file. In this file there are two attributes for each claim which are 581configurable (more details in the header file): 582 583 - Requirements of presence: optional or mandatory 584 - Expected value: Value check can be disabled or expected value can be provided 585 here. 586 587For initial attestation tests, the built-in IAK is used. 588Initial attestation regression test verifies the IAT generated by initial 589attestation service with the exported public key. 590 591iat-verifier 592============ 593 594There is another possibility to verify the attestation token. This addresses 595the off-device testing when the token is already retrieved from the device and 596verification is done on the requester side. There is a Python script for this 597purpose in the `tf-m-tools`_ repo called `iat-verifier`_. It does the same 598checking as the attestation test suite. The following steps describe how to 599simulate an off-device token verification on a host computer. It is described 600how to retrieve an initial attestation token when TF-M code is executed on FVP 601and how to use the iat-verifier script to check the token. This example assumes 602that user has license for DS-5 and FVP models: 603 604.. _tf-m-tools: https://git.trustedfirmware.org/TF-M/tf-m-tools.git 605 606.. _iat-verifier: https://git.trustedfirmware.org/TF-M/tf-m-tools.git/tree/ 607 iat-verifier 608 609 - Build TF-M with any of the ``ConfigRegression*.cmake`` build configurations 610 for MPS2 AN521 platform. More info in 611 :doc:`tfm_build_instruction </building/tfm_build_instruction>`. 612 - Lunch FVP model in DS-5. More info in 613 :doc:`Run TF-M examples on Arm platforms </building/run_tfm_examples_on_arm_platforms>`. 614 - Set a breakpoint in ``test/secure_fw/suites/attestation/attest_token_test.c`` 615 in ``decode_test_internal(..)`` after the ``token_main_alt(..)`` returned, 616 i.e. on line 859. Execute the code in the model until the breakpoint hits 617 second time. At this point the console prints the test case name: 618 619 - For asymmetric initial attestation, the console prints 620 ``ECDSA signature test of attest token``. 621 - For symmetric initial attestation, the console prints 622 ``Symmetric key algorithm based Initial Attestation test``. 623 624 - At this point the token resides in the model memory and can be dumped to host 625 computer. 626 - The ADDRESS and SIZE attributes of the initial attestation token is stored in 627 the ``completed_token`` local variable. Their value can be extracted in the 628 ``(x)=Variables`` debug window. 629 - Apply commands below in the ``Commands`` debug window to dump the token in 630 binary format to the host computer: 631 632 - For asymmetric initial attestation 633 ``dump memory <PATH>/iat_01.cbor <ADDRESS> +<SIZE>`` 634 - For symmetric initial attestation 635 ``dump memory <PATH>/iat_hmac_02.cbor <ADDRESS> +<SIZE>`` 636 637 - Execute commands below on the host computer to verify the token: 638 639 - For asymmetric initial attestation 640 ``check_iat -p -K -k platform/ext/common/template/tfm_initial_attestation_key.pem <PATH>/iat_01.cbor`` 641 - For symmetric initial attestation 642 ``check_iat -m mac -p -K -k platform/ext/common/template/tfm_symmetric_iak.key <PATH>/iat_hmac_02.cbor`` 643 644 - Documentation of the iat-verifier can be found in the 645 :doc:`tf-m-tools-iat-verifer<TF-M-Tools:iat-verifier>`. 646 647-------------- 648 649*SPDX-FileCopyrightText: Copyright The TrustedFirmware-M Contributors* 650 651*SPDX-License-Identifier: BSD-3-Clause* 652