idnits 2.17.1 draft-ietf-teep-protocol-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 160 instances of too long lines in the document, the longest one being 140 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (7 March 2022) is 753 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-22) exists of draft-ietf-rats-architecture-15 ** Downref: Normative reference to an Informational draft: draft-ietf-rats-architecture (ref. 'I-D.ietf-rats-architecture') == Outdated reference: A later version (-25) exists of draft-ietf-rats-eat-12 == Outdated reference: A later version (-25) exists of draft-ietf-suit-manifest-16 ** Downref: Normative reference to an Informational draft: draft-moran-suit-report (ref. 'I-D.moran-suit-report') ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 8152 (Obsoleted by RFC 9052, RFC 9053) == Outdated reference: A later version (-19) exists of draft-ietf-teep-architecture-16 Summary: 5 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TEEP H. Tschofenig 3 Internet-Draft Arm Ltd. 4 Intended status: Standards Track M. Pei 5 Expires: 8 September 2022 Broadcom 6 D. Wheeler 7 Amazon 8 D. Thaler 9 Microsoft 10 A. Tsukamoto 11 AIST 12 7 March 2022 14 Trusted Execution Environment Provisioning (TEEP) Protocol 15 draft-ietf-teep-protocol-08 17 Abstract 19 This document specifies a protocol that installs, updates, and 20 deletes Trusted Components in a device with a Trusted Execution 21 Environment (TEE). This specification defines an interoperable 22 protocol for managing the lifecycle of Trusted Components. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on 8 September 2022. 41 Copyright Notice 43 Copyright (c) 2022 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 48 license-info) in effect on the date of publication of this document. 49 Please review these documents carefully, as they describe your rights 50 and restrictions with respect to this document. Code Components 51 extracted from this document must include Revised BSD License text as 52 described in Section 4.e of the Trust Legal Provisions and are 53 provided without warranty as described in the Revised BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 3. Message Overview . . . . . . . . . . . . . . . . . . . . . . 4 60 4. Detailed Messages Specification . . . . . . . . . . . . . . . 6 61 4.1. Creating and Validating TEEP Messages . . . . . . . . . . 6 62 4.1.1. Creating a TEEP message . . . . . . . . . . . . . . . 6 63 4.1.2. Validating a TEEP Message . . . . . . . . . . . . . . 6 64 4.2. QueryRequest Message . . . . . . . . . . . . . . . . . . 7 65 4.3. QueryResponse Message . . . . . . . . . . . . . . . . . . 9 66 4.3.1. Evidence and Attestation Results . . . . . . . . . . 12 67 4.4. Update Message . . . . . . . . . . . . . . . . . . . . . 13 68 4.4.1. Example 1: Having one SUIT Manifest pointing to a URI 69 of a Trusted Component Binary . . . . . . . . . . . . 15 70 4.4.2. Example 2: Having a SUIT Manifest include the Trusted 71 Component Binary . . . . . . . . . . . . . . . . . . 17 72 4.4.3. Example 3: Supplying Personalization Data for the 73 Trusted Component Binary . . . . . . . . . . . . . . 18 74 4.4.4. Example 4: Unlinking Trusted Component . . . . . . . 20 75 4.5. Success Message . . . . . . . . . . . . . . . . . . . . . 21 76 4.6. Error Message . . . . . . . . . . . . . . . . . . . . . . 22 77 5. EAT Profile . . . . . . . . . . . . . . . . . . . . . . . . . 25 78 6. Mapping of TEEP Message Parameters to CBOR Labels . . . . . . 27 79 7. Behavior Specification . . . . . . . . . . . . . . . . . . . 29 80 7.1. TAM Behavior . . . . . . . . . . . . . . . . . . . . . . 29 81 7.2. TEEP Agent Behavior . . . . . . . . . . . . . . . . . . . 30 82 8. Ciphersuites . . . . . . . . . . . . . . . . . . . . . . . . 31 83 9. Freshness Mechanisms . . . . . . . . . . . . . . . . . . . . 32 84 10. Security Considerations . . . . . . . . . . . . . . . . . . . 33 85 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 86 11.1. Media Type Registration . . . . . . . . . . . . . . . . 35 87 11.2. Freshness Mechanism Registry . . . . . . . . . . . . . . 36 88 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 89 12.1. Normative References . . . . . . . . . . . . . . . . . . 36 90 12.2. Informative References . . . . . . . . . . . . . . . . . 38 91 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 39 92 B. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39 93 C. Complete CDDL . . . . . . . . . . . . . . . . . . . . . . . . 39 94 D. Examples of Diagnostic Notation and Binary Representation . . 43 95 D.1. QueryRequest Message . . . . . . . . . . . . . . . . . . 43 96 D.1.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 43 97 D.1.2. CBOR Binary Representation . . . . . . . . . . . . . 44 98 D.2. Entity Attestation Token . . . . . . . . . . . . . . . . 44 99 D.2.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 44 100 D.3. QueryResponse Message . . . . . . . . . . . . . . . . . . 45 101 D.3.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 45 102 D.3.2. CBOR Binary Representation . . . . . . . . . . . . . 46 103 D.4. Update Message . . . . . . . . . . . . . . . . . . . . . 47 104 D.4.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 47 105 D.4.2. CBOR Binary Representation . . . . . . . . . . . . . 47 106 D.5. Success Message . . . . . . . . . . . . . . . . . . . . . 48 107 D.5.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 48 108 D.5.2. CBOR Binary Representation . . . . . . . . . . . . . 48 109 D.6. Error Message . . . . . . . . . . . . . . . . . . . . . . 48 110 D.6.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 48 111 D.6.2. CBOR binary Representation . . . . . . . . . . . . . 49 112 E. Examples of SUIT Manifests . . . . . . . . . . . . . . . . . 49 113 Example 1: SUIT Manifest pointing to URI of the Trusted Component 114 Binary . . . . . . . . . . . . . . . . . . . . . . . . . 50 115 CBOR Diagnostic Notation of SUIT Manifest . . . . . . . . . . 50 116 CBOR Binary Representation . . . . . . . . . . . . . . . . . 51 117 CBOR Binary in Hex . . . . . . . . . . . . . . . . . . . . . 52 118 Example 2: SUIT Manifest including the Trusted Component 119 Binary . . . . . . . . . . . . . . . . . . . . . . . . . 53 120 CBOR Diagnostic Notation of SUIT Manifest . . . . . . . . . . 53 121 CBOR Binary Representation . . . . . . . . . . . . . . . . . 54 122 CBOR Binary in Hex . . . . . . . . . . . . . . . . . . . . . 56 123 Example 3: Supplying Personalization Data for Trusted Component 124 Binary . . . . . . . . . . . . . . . . . . . . . . . . . 56 125 CBOR Diagnostic Notation of SUIT Manifest . . . . . . . . . . 56 126 CBOR Binary Represenation . . . . . . . . . . . . . . . . . . 58 127 CBOR Binary in Hex . . . . . . . . . . . . . . . . . . . . . 60 128 E.4. Example 4: Unlink a Trusted Component . . . . . . . . . . 60 129 CBOR Diagnostic Notation of SUIT Manifest . . . . . . . . . . 60 130 CBOR Binary Representation . . . . . . . . . . . . . . . . . 61 131 CBOR Binary in Hex . . . . . . . . . . . . . . . . . . . . . 63 132 F. Examples of SUIT Reports . . . . . . . . . . . . . . . . . . 63 133 F.1. Example 1: Success . . . . . . . . . . . . . . . . . . . 63 134 F.2. Example 2: Faiure . . . . . . . . . . . . . . . . . . . . 64 135 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65 137 1. Introduction 139 The Trusted Execution Environment (TEE) concept has been designed to 140 separate a regular operating system, also referred as a Rich 141 Execution Environment (REE), from security-sensitive applications. 142 In a TEE ecosystem, device vendors may use different operating 143 systems in the REE and may use different types of TEEs. When Trusted 144 Component Developers or Device Administrators use Trusted Application 145 Managers (TAMs) to install, update, and delete Trusted Applications 146 and their dependencies on a wide range of devices with potentially 147 different TEEs then an interoperability need arises. 149 This document specifies the protocol for communicating between a TAM 150 and a TEEP Agent. 152 The Trusted Execution Environment Provisioning (TEEP) architecture 153 document [I-D.ietf-teep-architecture] provides design guidance and 154 introduces the necessary terminology. 156 2. Terminology 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 160 "OPTIONAL" in this document are to be interpreted as described in 161 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 162 capitals, as shown here. 164 This specification re-uses the terminology defined in 165 [I-D.ietf-teep-architecture]. 167 As explained in Section 4.4 of that document, the TEEP protocol 168 treats each Trusted Application (TA), any dependencies the TA has, 169 and personalization data as separate components that are expressed in 170 SUIT manifests, and a SUIT manifest might contain or reference 171 multiple binaries (see [I-D.ietf-suit-manifest] for more details). 173 As such, the term Trusted Component (TC) in this document refers to a 174 set of binaries expressed in a SUIT manifest, to be installed in a 175 TEE. Note that a Trusted Component may include one or more TAs and/ 176 or configuration data and keys needed by a TA to operate correctly. 178 Each Trusted Component is uniquely identified by a SUIT Component 179 Identifier (see [I-D.ietf-suit-manifest] Section 8.7.2.2). 181 3. Message Overview 183 The TEEP protocol consists of messages exchanged between a TAM and a 184 TEEP Agent. The messages are encoded in CBOR and designed to provide 185 end-to-end security. TEEP protocol messages are signed by the 186 endpoints, i.e., the TAM and the TEEP Agent, but Trusted Applications 187 may also be encrypted and signed by a Trusted Component Developer or 188 Device Administrator. The TEEP protocol not only uses CBOR but also 189 the respective security wrapper, namely COSE [RFC8152]. Furthermore, 190 for software updates the SUIT manifest format 191 [I-D.ietf-suit-manifest] is used, and for attestation the Entity 192 Attestation Token (EAT) [I-D.ietf-rats-eat] format is supported 193 although other attestation formats are also permitted. 195 This specification defines five messages: QueryRequest, 196 QueryResponse, Update, Success, and Error. 198 A TAM queries a device's current state with a QueryRequest message. 199 A TEEP Agent will, after authenticating and authorizing the request, 200 report attestation information, list all Trusted Components, and 201 provide information about supported algorithms and extensions in a 202 QueryResponse message. An error message is returned if the request 203 could not be processed. A TAM will process the QueryResponse message 204 and determine whether to initiate subsequent message exchanges to 205 install, update, or delete Trusted Applications. 207 +------------+ +-------------+ 208 | TAM | |TEEP Agent | 209 +------------+ +-------------+ 211 QueryRequest -------> 213 QueryResponse 215 <------- or 217 Error 219 With the Update message a TAM can instruct a TEEP Agent to install 220 and/or delete one or more Trusted Components. The TEEP Agent will 221 process the message, determine whether the TAM is authorized and 222 whether the Trusted Component has been signed by an authorized 223 Trusted Component Signer. A Success message is returned when the 224 operation has been completed successfully, or an Error message 225 otherwise. 227 +------------+ +-------------+ 228 | TAM | |TEEP Agent | 229 +------------+ +-------------+ 231 Update ----> 233 Success 235 <---- or 237 Error 239 4. Detailed Messages Specification 241 TEEP messages are protected by the COSE_Sign1 structure. The TEEP 242 protocol messages are described in CDDL format [RFC8610] below. 244 { 245 teep-message => (query-request / 246 query-response / 247 update / 248 teep-success / 249 teep-error ), 250 } 252 4.1. Creating and Validating TEEP Messages 254 4.1.1. Creating a TEEP message 256 To create a TEEP message, the following steps are performed. 258 1. Create a TEEP message according to the description below and 259 populate it with the respective content. TEEP messages sent by 260 TAMs (QueryRequest and Update) can include a "token". The TAM 261 can decide, in any implementation-specific way, whether to 262 include a token in a message. The first usage of a token 263 generated by a TAM MUST be randomly created. Subsequent token 264 values MUST be different for each subsequent message created by a 265 TAM. 267 2. Create a COSE Header containing the desired set of Header 268 Parameters. The COSE Header MUST be valid per the [RFC8152] 269 specification. 271 3. Create a COSE_Sign1 object using the TEEP message as the 272 COSE_Sign1 Payload; all steps specified in [RFC8152] for creating 273 a COSE_Sign1 object MUST be followed. 275 4.1.2. Validating a TEEP Message 277 When TEEP message is received (see the ProcessTeepMessage conceptual 278 API defined in [I-D.ietf-teep-architecture] section 6.2.1), the 279 following validation steps are performed. If any of the listed steps 280 fail, then the TEEP message MUST be rejected. 282 1. Verify that the received message is a valid CBOR object. 284 2. Verify that the message contains a COSE_Sign1 structure. 286 3. Verify that the resulting COSE Header includes only parameters 287 and values whose syntax and semantics are both understood and 288 supported or that are specified as being ignored when not 289 understood. 291 4. Follow the steps specified in Section 4 of [RFC8152] ("Signing 292 Objects") for validating a COSE_Sign1 object. The COSE_Sign1 293 payload is the content of the TEEP message. 295 5. Verify that the TEEP message is a valid CBOR map and verify the 296 fields of the TEEP message according to this specification. 298 4.2. QueryRequest Message 300 A QueryRequest message is used by the TAM to learn information from 301 the TEEP Agent, such as the features supported by the TEEP Agent, 302 including ciphersuites and protocol versions. Additionally, the TAM 303 can selectively request data items from the TEEP Agent via the 304 request parameter. Currently, the following features are supported: 306 * Request for attestation information, 308 * Listing supported extensions, 310 * Querying installed Trusted Components, and 312 * Listing supported SUIT commands. 314 Like other TEEP messages, the QueryRequest message is signed, and the 315 relevant CDDL snippet is shown below. The complete CDDL structure is 316 shown in Appendix C. 318 query-request = [ 319 type: TEEP-TYPE-query-request, 320 options: { 321 ? token => bstr .size (8..64), 322 ? supported-cipher-suites => [ + suite ], 323 ? supported-freshness-mechanisms => [ + freshness-mechanism ], 324 ? challenge => bstr .size (8..512), 325 ? versions => [ + version ], 326 * $$query-request-extensions 327 * $$teep-option-extensions 328 }, 329 data-item-requested: data-item-requested 330 ] 332 The message has the following fields: 334 type 335 The value of (1) corresponds to a QueryRequest message sent from 336 the TAM to the TEEP Agent. 338 token 339 The value in the token parameter is used to match responses to 340 requests. This is particularly useful when a TAM issues multiple 341 concurrent requests to a TEEP Agent. The token MUST be present if 342 and only if the attestation bit is clear in the data-item- 343 requested value. The size of the token is at least 8 bytes (64 344 bits) and maximum of 64 bytes, which is the same as in an EAT 345 Nonce Claim (see [I-D.ietf-rats-eat] Section 3.3). The first 346 usage of a token generated by a TAM MUST be randomly created. 347 Subsequent token values MUST be different for each request message 348 to distinguish the correct response from multiple requests. The 349 token value MUST NOT be used for other purposes, such as a TAM to 350 identify the devices and/or a device to identify TAMs or Trusted 351 Components. The TAM SHOULD set an expiration time for each token 352 and MUST ignore any messages with expired tokens. The TAM MUST 353 expire the token value after receiving the first response 354 containing the token value and ignore any subsequent messages that 355 have the same token value. 357 data-item-requested 358 The data-item-requested parameter indicates what information the 359 TAM requests from the TEEP Agent in the form of a bitmap. Each 360 value in the bitmap corresponds to an IANA registered information 361 element. This specification defines the following initial set of 362 information elements: 364 attestation (1) With this value the TAM requests the TEEP Agent 365 to return attestation evidence (e.g., an EAT) in the response. 367 trusted-components (2) With this value the TAM queries the TEEP 368 Agent for all installed Trusted Components. 370 extensions (4) With this value the TAM queries the TEEP Agent for 371 supported capabilities and extensions, which allows a TAM to 372 discover the capabilities of a TEEP Agent implementation. 374 Further values may be added in the future via IANA registration. 376 supported-cipher-suites 377 The supported-cipher-suites parameter lists the ciphersuites 378 supported by the TAM. If this parameter is not present, it is to 379 be treated the same as if it contained all ciphersuites defined in 380 this document that are listed as "MUST". Details about the 381 ciphersuite encoding can be found in Section 8. 383 supported-freshness-mechanisms 384 The supported-freshness-mechanisms parameter lists the freshness 385 mechanism(s) supported by the TAM. Details about the encoding can 386 be found in Section 9. If this parameter is absent, it means only 387 the nonce mechanism is supported. 389 challenge 390 The challenge field is an optional parameter used for ensuring the 391 freshness of the attestation evidence returned with a 392 QueryResponse message. It MUST be absent if the attestation bit 393 is clear (since the token is used instead in that case). When a 394 challenge is provided in the QueryRequest and an EAT is returned 395 with a QueryResponse message then the challenge contained in this 396 request MUST be used to generate the EAT, such as by copying the 397 challenge into the nonce claim found in the EAT if using the Nonce 398 freshness mechanism. For more details see Section 9. If any 399 format other than EAT is used, it is up to that format to define 400 the use of the challenge field. 402 versions 403 The versions parameter enumerates the TEEP protocol version(s) 404 supported by the TAM. A value of 0 refers to the current version 405 of the TEEP protocol. If this field is not present, it is to be 406 treated the same as if it contained only version 0. 408 4.3. QueryResponse Message 410 The QueryResponse message is the successful response by the TEEP 411 Agent after receiving a QueryRequest message. As discussed in 412 Section 7.2, it can also be sent unsolicited if the contents of the 413 QueryRequest are already known and do not vary per message. 415 Like other TEEP messages, the QueryResponse message is signed, and 416 the relevant CDDL snippet is shown below. The complete CDDL 417 structure is shown in Appendix C. 419 query-response = [ 420 type: TEEP-TYPE-query-response, 421 options: { 422 ? token => bstr .size (8..64), 423 ? selected-cipher-suite => suite, 424 ? selected-version => version, 425 ? evidence-format => text, 426 ? evidence => bstr, 427 ? tc-list => [ + tc-info ], 428 ? requested-tc-list => [ + requested-tc-info ], 429 ? unneeded-tc-list => [ + SUIT_Component_Identifier ], 430 ? ext-list => [ + ext-info ], 431 * $$query-response-extensions, 432 * $$teep-option-extensions 433 } 434 ] 436 tc-info = { 437 component-id => SUIT_Component_Identifier, 438 ? tc-manifest-sequence-number => .within uint .size 8 439 } 441 requested-tc-info = { 442 component-id => SUIT_Component_Identifier, 443 ? tc-manifest-sequence-number => .within uint .size 8 444 ? have-binary => bool 445 } 447 The QueryResponse message has the following fields: 449 type 450 The value of (2) corresponds to a QueryResponse message sent from 451 the TEEP Agent to the TAM. 453 token 454 The value in the token parameter is used to match responses to 455 requests. The value MUST correspond to the value received with 456 the QueryRequest message if one was present, and MUST be absent if 457 no token was present in the QueryRequest. 459 selected-cipher-suite 460 The selected-cipher-suite parameter indicates the selected 461 ciphersuite. Details about the ciphersuite encoding can be found 462 in Section 8. 464 selected-version 465 The selected-version parameter indicates the TEEP protocol version 466 selected by the TEEP Agent. The absense of this parameter 467 indicates the same as if it was present with a value of 0. 469 evidence-format 470 The evidence-format parameter indicates the IANA Media Type of the 471 attestation evidence contained in the evidence parameter. It MUST 472 be present if the evidence parameter is present and the format is 473 not an EAT. 475 evidence 476 The evidence parameter contains the attestation evidence. This 477 parameter MUST be present if the QueryResponse is sent in response 478 to a QueryRequest with the attestation bit set. If the evidence- 479 format parameter is absent, the attestation evidence contained in 480 this parameter MUST be an Entity Attestation Token following the 481 encoding defined in [I-D.ietf-rats-eat]. See Section 4.3.1 for 482 further discussion. 484 tc-list 485 The tc-list parameter enumerates the Trusted Components installed 486 on the device in the form of tc-info objects. This parameter MUST 487 be present if the QueryResponse is sent in response to a 488 QueryRequest with the trusted-components bit set. 490 requested-tc-list 491 The requested-tc-list parameter enumerates the Trusted Components 492 that are not currently installed in the TEE, but which are 493 requested to be installed, for example by an installer of an 494 Untrusted Application that has a TA as a dependency, or by a 495 Trusted Application that has another Trusted Component as a 496 dependency. Requested Trusted Components are expressed in the 497 form of requested-tc-info objects. A TEEP Agent can get this 498 information from the RequestTA conceptual API defined in 499 [I-D.ietf-teep-architecture] section 6.2.1. 501 unneeded-tc-list 502 The unneeded-tc-list parameter enumerates the Trusted Components 503 that are currently installed in the TEE, but which are no longer 504 needed by any other application. The TAM can use this information 505 in determining whether a Trusted Component can be deleted. Each 506 unneeded Trusted Component is identified by its SUIT Component 507 Identifier. A TEEP Agent can get this information from the 508 UnrequestTA conceptual API defined in [I-D.ietf-teep-architecture] 509 section 6.2.1. 511 ext-list 512 The ext-list parameter lists the supported extensions. This 513 document does not define any extensions. This parameter MUST be 514 present if the QueryResponse is sent in response to a QueryRequest 515 with the extensions bit set. 517 The tc-info object has the following fields: 519 component-id 520 A SUIT Component Identifier. 522 tc-manifest-sequence-number 523 The suit-manifest-sequence-number value from the SUIT manifest for 524 the Trusted Component, if a SUIT manifest was used. 526 The requested-tc-info message has the following fields: 528 component-id 529 A SUIT Component Identifier. 531 tc-manifest-sequence-number 532 The minimum suit-manifest-sequence-number value from a SUIT 533 manifest for the Trusted Component. If not present, indicates 534 that any sequence number will do. 536 have-binary 537 If present with a value of true, indicates that the TEEP agent 538 already has the Trusted Component binary and only needs an Update 539 message with a SUIT manifest that authorizes installing it. If 540 have-binary is true, the tc-manifest-sequence-number field MUST be 541 present. 543 4.3.1. Evidence and Attestation Results 545 Section 7 of [I-D.ietf-teep-architecture] lists information that may 546 appear in evidence depending on the circumstance. However, the 547 evidence is opaque to the TEEP protocol and there are no formal 548 requirements on the contents of evidence. 550 TAMs however consume Attestation Results and do need enough 551 information therein to make decisions on how to remediate a TEE that 552 is out of compliance, or update a TEE that is requesting an 553 authorized change. To do so, the information in Section 7 of 554 [I-D.ietf-teep-architecture] is often required depending on the 555 policy. When an Entity Attestation Token is used, the following 556 claims can be used to meet those requirements: 558 +=============+==================+=================================+ 559 | Requirement | Claim | Reference | 560 +=============+==================+=================================+ 561 | Device | ueid | [I-D.ietf-rats-eat] section 3.4 | 562 | unique | | | 563 | identifier | | | 564 +-------------+------------------+---------------------------------+ 565 | Vendor of | oemid | [I-D.ietf-rats-eat] section 3.6 | 566 | the device | | | 567 +-------------+------------------+---------------------------------+ 568 | Class of | class-identifier | [I-D.birkholz-rats-suit-claims] | 569 | the device | | section 3.1.2 | 570 +-------------+------------------+---------------------------------+ 571 | TEE | chip-version | [I-D.ietf-rats-eat] section 3.7 | 572 | hardware | | | 573 | type | | | 574 +-------------+------------------+---------------------------------+ 575 | TEE | chip-version | [I-D.ietf-rats-eat] section 3.7 | 576 | hardware | | | 577 | version | | | 578 +-------------+------------------+---------------------------------+ 579 | TEE | sw-name | [I-D.ietf-rats-eat] section 3.9 | 580 | firmware | | | 581 | type | | | 582 +-------------+------------------+---------------------------------+ 583 | TEE | sw-version | [I-D.ietf-rats-eat] section | 584 | firmware | | 3.10 | 585 | version | | | 586 +-------------+------------------+---------------------------------+ 587 | Freshness | nonce | [I-D.ietf-rats-eat] section 3.3 | 588 | proof | | | 589 +-------------+------------------+---------------------------------+ 591 Table 1 593 4.4. Update Message 595 The Update message is used by the TAM to install and/or delete one or 596 more Trusted Components via the TEEP Agent. 598 Like other TEEP messages, the Update message is signed, and the 599 relevant CDDL snippet is shown below. The complete CDDL structure is 600 shown in Appendix C. 602 update = [ 603 type: TEEP-TYPE-update, 604 options: { 605 ? token => bstr .size (8..64), 606 ? manifest-list => [ + bstr .cbor SUIT_Envelope ], 607 * $$update-extensions, 608 * $$teep-option-extensions 609 } 610 ] 612 The Update message has the following fields: 614 type 615 The value of (3) corresponds to an Update message sent from the 616 TAM to the TEEP Agent. In case of successful processing, a 617 Success message is returned by the TEEP Agent. In case of an 618 error, an Error message is returned. Note that the Update message 619 is used for initial Trusted Component installation as well as for 620 updates and deletes. 622 token 623 The value in the token field is used to match responses to 624 requests. 626 manifest-list 627 The manifest-list field is used to convey one or multiple SUIT 628 manifests to install. A manifest is a bundle of metadata about a 629 Trusted Component, such as where to find the code, the devices to 630 which it applies, and cryptographic information protecting the 631 manifest. The manifest may also convey personalization data. 632 Trusted Component binaries and personalization data can be signed 633 and encrypted by the same Trusted Component Signer. Other 634 combinations are, however, possible as well. For example, it is 635 also possible for the TAM to sign and encrypt the personalization 636 data and to let the Trusted Component Developer sign and/or 637 encrypt the Trusted Component binary. 639 Note that an Update message carrying one or more SUIT manifests will 640 inherently involve multiple signatures, one by the TAM in the TEEP 641 message and one from a Trusted Component Signer inside each manifest. 642 This is intentional as they are for different purposes. 644 The TAM is what authorizes apps to be installed, updated, and deleted 645 on a given TEE and so the TEEP signature is checked by the TEEP Agent 646 at protocol message processing time. (This same TEEP security 647 wrapper is also used on messages like QueryRequest so that Agents 648 only send potentially sensitive data such as evidence to trusted 649 TAMs.) 650 The Trusted Component signer on the other hand is what authorizes the 651 Trusted Component to actually run, so the manifest signature could be 652 checked at install time or load (or run) time or both, and this 653 checking is done by the TEE independent of whether TEEP is used or 654 some other update mechanism. See section 5 of 655 [I-D.ietf-teep-architecture] for further discussion. 657 The Update Message has a SUIT_Envelope containing SUIT manifests. 658 Following are some examples of using SUIT manifests in the Update 659 Message. 661 4.4.1. Example 1: Having one SUIT Manifest pointing to a URI of a 662 Trusted Component Binary 664 In this example, a SUIT Manifest has a URI pointing to a Trusted 665 Component Binary. 667 A Trusted Component Developer creates a new Trusted Component Binary 668 and hosts it at a Trusted Component Developer's URI. Then the 669 Trusted Component Developer generates an associated SUIT manifest 670 with the filename "tc-uuid.suit" that contains the URI. The filename 671 "tc-uuid.suit" is used in Example 3 later. 673 The TAM receives the latest SUIT manifest from the Trusted Component 674 Developer, and the URI it contains will not be changeable by the TAM 675 since the SUIT manifest is signed by the Trusted Component Developer. 677 Pros: 679 * The Trusted Component Developer can ensure that the intact Trusted 680 Component Binary is downloaded by devices 682 * The TAM does not have to send large Update messages containing the 683 Trusted Component Binary 685 Cons: 687 * The Trusted Component Developer must host the Trusted Component 688 Binary server 690 * The device must fetch the Trusted Component Binary in another 691 connection after receiving an Update message 692 +------------+ +-------------+ 693 | TAM | | TEEP Agent | 694 +------------+ +-------------+ 696 Update ----> 698 +=================== teep-protocol(TAM) ==================+ 699 | TEEP_Message([ | 700 | TEEP-TYPE-update, | 701 | options: { | 702 | manifest-list: [ | 703 | += suit-manifest "tc-uuid.suit" (TC Developer) =+ | 704 | | SUIT_Envelope({ | | 705 | | manifest: { | | 706 | | install: { | | 707 | | set-parameter: { | | 708 | | uri: "https://example.org/tc-uuid.ta" | | 709 | | }, | | 710 | | fetch | | 711 | | } | | 712 | | } | | 713 | | }) | | 714 | +===============================================+ | 715 | ] | 716 | } | 717 | ]) | 718 +=========================================================+ 720 and then, 722 +-------------+ +--------------+ 723 | TEEP Agent | | TC Developer | 724 +-------------+ +--------------+ 726 <---- 728 fetch "https://example.org/tc-uuid.ta" 730 +======= tc-uuid.ta =======+ 731 | 48 65 6C 6C 6F 2C 20 ... | 732 +==========================+ 734 Figure 1: URI of the Trusted Component Binary 736 For the full SUIT Manifest example binary, see Appendix "Example 1: 737 SUIT Manifest pointing to URI of the Trusted Component Binary". 739 4.4.2. Example 2: Having a SUIT Manifest include the Trusted Component 740 Binary 742 In this example, the SUIT manifest contains the entire Trusted 743 Component Binary using the integrated-payload (see 744 [I-D.ietf-suit-manifest] Section 7.6). 746 A Trusted Component Developer delegates to the TAM the task of 747 delivering the Trusted Component Binary in the SUIT manifest. The 748 Trusted Component Developer creates a SUIT manifest and embeds the 749 Trusted Component Binary, which is referenced in the URI parameter 750 with identifier "#tc". The Trusted Component Developer provides the 751 SUIT manifest to the TAM. 753 The TAM serves the SUIT manifest containing the Trusted Component 754 Binary to the device in an Update message. 756 Pros: 758 * The device can obtain the Trusted Component Binary and its SUIT 759 manifest together in one Update message 761 * The Trusted Component Developer does not have to host a server to 762 deliver the Trusted Component Binary directly to devices 764 Cons: 766 * The TAM must host the Trusted Component Binary itself, rather than 767 delegating such storage to the Trusted Component Developer 769 * The TAM must deliver Trusted Component Binaries in Update 770 messages, which result in increased Update message size 771 +------------+ +-------------+ 772 | TAM | | TEEP Agent | 773 +------------+ +-------------+ 775 Update ----> 777 +=========== teep-protocol(TAM) ============+ 778 | TEEP_Message([ | 779 | TEEP-TYPE-update, | 780 | options: { | 781 | manifest-list: [ | 782 | +== suit-manifest(TC Developer) ==+ | 783 | | SUIT_Envelope({ | | 784 | | "#tc": h'48 65 6C 6C ...', | | 785 | | manifest: { | | 786 | | install: { | | 787 | | set-parameter: { | | 788 | | uri: "#tc" | | 789 | | }, | | 790 | | fetch | | 791 | | } | | 792 | | } | | 793 | | }) | | 794 | +=================================+ | 795 | ] | 796 | } | 797 | ]) | 798 +===========================================+ 800 Figure 2: Integrated Payload with Trusted Component Binary 802 For the full SUIT Manifest example binary, see Appendix "Example 2: 803 SUIT Manifest including the Trusted Component Binary". 805 4.4.3. Example 3: Supplying Personalization Data for the Trusted 806 Component Binary 808 In this example, Personalization Data is associated with the Trusted 809 Component Binary "tc-uuid.suit" from Example 1. 811 The Trusted Component Developer places Personalization Data in a file 812 named "config.json" and hosts it on an HTTPS server. The Trusted 813 Component Developer then creates a SUIT manifest with the URI, 814 specifying which Trusted Component Binary it correlates to in the 815 parameter 'dependency-resolution', and signs the SUIT manifest. 817 The TAM delivers the SUIT manifest of the Personalization Data which 818 depends on the Trusted Component Binary from Example 1. 820 +------------+ +-------------+ 821 | TAM | | TEEP Agent | 822 +------------+ +-------------+ 824 Update ----> 826 +================= teep-protocol(TAM) ======================+ 827 | TEEP_Message([ | 828 | TEEP-TYPE-update, | 829 | options: { | 830 | manifest-list: [ | 831 | +======== suit-manifest(TC Developer) ============+ | 832 | | SUIT_Envelope({ | | 833 | | manifest: { | | 834 | | common: { | | 835 | | dependencies: [ | | 836 | | {{digest-of-tc.suit}} | | 837 | | ] | | 838 | | } | | 839 | | dependency-resolution: { | | 840 | | set-parameter: { | | 841 | | uri: "https://example.org/tc-uuid.suit" | | 842 | | } | | 843 | | fetch | | 844 | | } | | 845 | | install: { | | 846 | | set-parameter: { | | 847 | | uri: "https://example.org/config.json" | | 848 | | }, | | 849 | | fetch | | 850 | | set-dependency-index | | 851 | | process-dependency | | 852 | | } | | 853 | | } | | 854 | | }) | | 855 | +=================================================+ | 856 | ] | 857 | } | 858 | ]) | 859 +===========================================================+ 861 and then, 863 +-------------+ +--------------+ 864 | TEEP Agent | | TC Developer | 865 +-------------+ +--------------+ 867 <---- 869 fetch "https://example.org/config.json" 871 +=======config.json========+ 872 | 7B 22 75 73 65 72 22 ... | 873 +==========================+ 875 Figure 3: Personalization Data 877 For the full SUIT Manifest example binary, see Appendix "Example 3: 878 Supplying Personalization Data for Trusted Component Binary". 880 4.4.4. Example 4: Unlinking Trusted Component 882 This subsection shows an example deleting the Trusted Component 883 Binary in the TEEP Device. 885 A Trusted Component Developer can also generate SUIT Manifest which 886 unlinks the installed Trusted Component. The TAM deliver it when the 887 TAM want to uninstall the component. 889 The directive-unlink (see [I-D.moran-suit-trust-domains] Section- 890 6.5.4) is located in the manifest to delete the Trusted Component. 891 Note that in case other Trusted Components depend on it, i.e. the 892 reference count is not zero, the TEEP Device SHOULD NOT delete it 893 immediately. 895 +------------+ +-------------+ 896 | TAM | | TEEP Agent | 897 +------------+ +-------------+ 899 Update ----> 901 +=========== teep-protocol(TAM) ============+ 902 | TEEP_Message([ | 903 | TEEP-TYPE-update, | 904 | options: { | 905 | manifest-list: [ | 906 | +== suit-manifest(TC Developer) ==+ | 907 | | SUIT_Envelope({ | | 908 | | manifest: { | | 909 | | install: [ | | 910 | | unlink | | 911 | | ] | | 912 | | } | | 913 | | }) | | 914 | +=================================+ | 915 | ] | 916 | } | 917 | ]) | 918 +===========================================+ 920 Figure 4: Unlink Trusted Component example (summary) 922 For the full SUIT Manifest example binary, see Appendix E. SUIT 923 Example 4 (Appendix "E.4. Example 4: Unlink a Trusted Component") 925 4.5. Success Message 927 The Success message is used by the TEEP Agent to return a success in 928 response to an Update message. 930 Like other TEEP messages, the Success message is signed, and the 931 relevant CDDL snippet is shown below. The complete CDDL structure is 932 shown in Appendix C. 934 teep-success = [ 935 type: TEEP-TYPE-teep-success, 936 options: { 937 ? token => bstr .size (8..64), 938 ? msg => text .size (1..128), 939 ? suit-reports => [ + suit-report ], 940 * $$teep-success-extensions, 941 * $$teep-option-extensions 942 } 943 ] 945 The Success message has the following fields: 947 type 948 The value of (5) corresponds to corresponds to a Success message 949 sent from the TEEP Agent to the TAM. 951 token 952 The value in the token parameter is used to match responses to 953 requests. It MUST match the value of the token parameter in the 954 Update message the Success is in response to, if one was present. 955 If none was present, the token MUST be absent in the Success 956 message. 958 msg 959 The msg parameter contains optional diagnostics information 960 encoded in UTF-8 [RFC3629] using Net-Unicode form [RFC5198] with 961 max 128 bytes returned by the TEEP Agent. 963 suit-reports 964 If present, the suit-reports parameter contains a set of SUIT 965 Reports as defined in Section 4 of [I-D.moran-suit-report]. If a 966 token parameter was present in the Update message the Success 967 message is in response to, the suit-report-nonce field MUST be 968 present in the SUIT Report with a value matching the token 969 parameter in the Update message. 971 4.6. Error Message 973 The Error message is used by the TEEP Agent to return an error in 974 response to an Update message. 976 Like other TEEP messages, the Error message is signed, and the 977 relevant CDDL snippet is shown below. The complete CDDL structure is 978 shown in Appendix C. 980 teep-error = [ 981 type: TEEP-TYPE-teep-error, 982 options: { 983 ? token => bstr .size (8..64), 984 ? err-msg => text .size (1..128), 985 ? supported-cipher-suites => [ + suite ], 986 ? supported-freshness-mechanisms => [ + freshness-mechanism ], 987 ? versions => [ + version ], 988 ? suit-reports => [ + suit-report ], 989 * $$teep-error-extensions, 990 * $$teep-option-extensions 991 }, 992 err-code: uint (0..23) 993 ] 995 The Error message has the following fields: 997 type 998 The value of (6) corresponds to an Error message sent from the 999 TEEP Agent to the TAM. 1001 token 1002 The value in the token parameter is used to match responses to 1003 requests. It MUST match the value of the token parameter in the 1004 Update message the Success is in response to, if one was present. 1005 If none was present, the token MUST be absent in the Error 1006 message. 1008 err-msg 1009 The err-msg parameter is human-readable diagnostic text that MUST 1010 be encoded using UTF-8 [RFC3629] using Net-Unicode form [RFC5198] 1011 with max 128 bytes. 1013 supported-cipher-suites 1014 The supported-cipher-suites parameter lists the ciphersuite(s) 1015 supported by the TEEP Agent. Details about the ciphersuite 1016 encoding can be found in Section 8. This otherwise optional 1017 parameter MUST be returned if err-code is 1018 ERR_UNSUPPORTED_CIPHER_SUITES. 1020 supported-freshness-mechanisms 1021 The supported-freshness-mechanisms parameter lists the freshness 1022 mechanism(s) supported by the TEEP Agent. Details about the 1023 encoding can be found in Section 9. This otherwise optional 1024 parameter MUST be returned if err-code is 1025 ERR_UNSUPPORTED_FRESHNESS_MECHANISMS. 1027 versions 1028 The versions parameter enumerates the TEEP protocol version(s) 1029 supported by the TEEP Agent. This otherwise optional parameter 1030 MUST be returned if err-code is ERR_UNSUPPORTED_MSG_VERSION. 1032 suit-reports 1033 If present, the suit-reports parameter contains a set of SUIT 1034 Reports as defined in Section 4 of [I-D.moran-suit-report]. If a 1035 token parameter was present in the Update message the Error 1036 message is in response to, the suit-report-nonce field MUST be 1037 present in the SUIT Report with a value matching the token 1038 parameter in the Update message. 1040 err-code 1041 The err-code parameter contains one of the error codes listed 1042 below). Only selected values are applicable to each message. 1044 This specification defines the following initial error messages: 1046 ERR_PERMANENT_ERROR (1) 1047 The TEEP request contained incorrect fields or fields that are 1048 inconsistent with other fields. For diagnosis purposes it is 1049 RECOMMMENDED to identify the failure reason in the error message. 1050 A TAM receiving this error might refuse to communicate further 1051 with the TEEP Agent for some period of time until it has reason to 1052 believe it is worth trying again, but it should take care not to 1053 give up on communication when there is no attestation evidence 1054 indicating that the error is genuine. In contrast, 1055 ERR_TEMPORARY_ERROR is an indication that a more agressive retry 1056 is warranted. 1058 ERR_UNSUPPORTED_EXTENSION (2) 1059 The TEEP Agent does not support an extension included in the 1060 request message. For diagnosis purposes it is RECOMMMENDED to 1061 identify the unsupported extension in the error message. A TAM 1062 receiving this error might retry the request without using 1063 extensions. 1065 ERR_UNSUPPORTED_FRESHNESS_MECHANISMS (3) 1066 The TEEP Agent does not support any freshness algorithm mechanisms 1067 in the request message. A TAM receiving this error might retry 1068 the request using a different set of supported freshness 1069 mechanisms in the request message. 1071 ERR_UNSUPPORTED_MSG_VERSION (4) 1072 The TEEP Agent does not support the TEEP protocol version 1073 indicated in the request message. A TAM receiving this error 1074 might retry the request using a different TEEP protocol version. 1076 ERR_UNSUPPORTED_CIPHER_SUITES (5) 1077 The TEEP Agent does not support any ciphersuites indicated in the 1078 request message. A TAM receiving this error might retry the 1079 request using a different set of supported ciphersuites in the 1080 request message. 1082 ERR_BAD_CERTIFICATE (6) 1083 Processing of a certificate failed. For diagnosis purposes it is 1084 RECOMMMENDED to include information about the failing certificate 1085 in the error message. For example, the certificate was of an 1086 unsupported type, or the certificate was revoked by its signer. A 1087 TAM receiving this error might attempt to use an alternate 1088 certificate. 1090 ERR_CERTIFICATE_EXPIRED (9) 1091 A certificate has expired or is not currently valid. A TAM 1092 receiving this error might attempt to renew its certificate before 1093 using it again. 1095 ERR_TEMPORARY_ERROR (10) 1096 A miscellaneous temporary error, such as a memory allocation 1097 failure, occurred while processing the request message. A TAM 1098 receiving this error might retry the same request at a later point 1099 in time. 1101 ERR_MANIFEST_PROCESSING_FAILED (17) 1102 The TEEP Agent encountered one or more manifest processing 1103 failures. If the suit-reports parameter is present, it contains 1104 the failure details. A TAM receiving this error might still 1105 attempt to install or update other components that do not depend 1106 on the failed manifest. 1108 New error codes should be added sparingly, not for every 1109 implementation error. That is the intent of the err-msg field, which 1110 can be used to provide details meaningful to humans. New error codes 1111 should only be added if the TAM is expected to do something 1112 behaviorally different upon receipt of the error message, rather than 1113 just logging the event. Hence, each error code is responsible for 1114 saying what the behavioral difference is expected to be. 1116 5. EAT Profile 1118 The TEEP protocol operates between a TEEP Agent and a TAM. While the 1119 TEEP protocol does not require use of EAT, use of EAT is encouraged 1120 and Section 4.3 explicitly defines a way to carry an Entity 1121 Attestation Token evidence in a QueryResponse. 1123 As discussed in Section 4.3.1, the content of attestation evidence is 1124 opaque to the TEEP architecture, but the content of Attestation 1125 Results is not, where Attestation Results flow between a Verifier and 1126 a TAM (as the Relying Party). Although Attestation Results required 1127 by a TAM are separable from the TEEP protocol per se, this section is 1128 included as part of the requirements for building a compliant TAM 1129 that uses EATs for Attestation Results. 1131 Section 7 of [I-D.ietf-rats-eat] defines the requirement for Entity 1132 Attestation Token profiles. This section defines an EAT profile for 1133 use with TEEP. 1135 * profile-label: The profile-label for this specification is the URI 1137 https://datatracker.ietf.org/doc/html/draft-ietf-teep-protocol-08 1138 (https://datatracker.ietf.org/doc/html/draft-ietf-teep-protocol-08). 1139 (RFC-editor: upon RFC publication, replace string with 1140 "https://www.rfc-editor.org/info/rfcXXXX" where XXXX is the RFC 1141 number of this document.) 1143 * Use of JSON, CBOR, or both: CBOR only. 1145 * CBOR Map and Array Encoding: Only definite length arrays and maps. 1147 * CBOR String Encoding: Only definite-length strings are allowed. 1149 * CBOR Preferred Serialization: Encoders must use preferred 1150 serialization, and decoders need not accept non-preferred 1151 serialization. 1153 * COSE/JOSE Protection: See Section 8. 1155 * Detached EAT Bundle Support: DEB use is permitted. 1157 * Verification Key Identification: COSE Key ID (kid) is used, where 1158 the key ID is the hash of a public key (where the public key may 1159 be used as a raw public key, or in a certificate). 1161 * Endorsement Identification: Optional, but semantics are the same 1162 as in Verification Key Identification. 1164 * Freshness: See Section 9. 1166 * Required Claims: None. 1168 * Prohibited Claims: None. 1170 * Additional Claims: Optional claims are those listed in 1171 Section 4.3.1. 1173 * Refined Claim Definition: None. 1175 * CBOR Tags: CBOT Tags are not used. 1177 * Manifests and Software Evidence Claims: The sw-name claim for a 1178 Trusted Component holds the URI of the SUIT manifest for that 1179 component. 1181 6. Mapping of TEEP Message Parameters to CBOR Labels 1183 In COSE, arrays and maps use strings, negative integers, and unsigned 1184 integers as their keys. Integers are used for compactness of 1185 encoding. Since the word "key" is mainly used in its other meaning, 1186 as a cryptographic key, this specification uses the term "label" for 1187 this usage as a map key. 1189 This specification uses the following mapping: 1191 +================================+=======+ 1192 | Name | Label | 1193 +================================+=======+ 1194 | supported-cipher-suites | 1 | 1195 +--------------------------------+-------+ 1196 | challenge | 2 | 1197 +--------------------------------+-------+ 1198 | version | 3 | 1199 +--------------------------------+-------+ 1200 | selected-cipher-suite | 5 | 1201 +--------------------------------+-------+ 1202 | selected-version | 6 | 1203 +--------------------------------+-------+ 1204 | evidence | 7 | 1205 +--------------------------------+-------+ 1206 | tc-list | 8 | 1207 +--------------------------------+-------+ 1208 | ext-list | 9 | 1209 +--------------------------------+-------+ 1210 | manifest-list | 10 | 1211 +--------------------------------+-------+ 1212 | msg | 11 | 1213 +--------------------------------+-------+ 1214 | err-msg | 12 | 1215 +--------------------------------+-------+ 1216 | evidence-format | 13 | 1217 +--------------------------------+-------+ 1218 | requested-tc-list | 14 | 1219 +--------------------------------+-------+ 1220 | unneeded-tc-list | 15 | 1221 +--------------------------------+-------+ 1222 | component-id | 16 | 1223 +--------------------------------+-------+ 1224 | tc-manifest-sequence-number | 17 | 1225 +--------------------------------+-------+ 1226 | have-binary | 18 | 1227 +--------------------------------+-------+ 1228 | suit-reports | 19 | 1229 +--------------------------------+-------+ 1230 | token | 20 | 1231 +--------------------------------+-------+ 1232 | supported-freshness-mechanisms | 21 | 1233 +--------------------------------+-------+ 1235 Table 2 1237 7. Behavior Specification 1239 Behavior is specified in terms of the conceptual APIs defined in 1240 section 6.2.1 of [I-D.ietf-teep-architecture]. 1242 7.1. TAM Behavior 1244 When the ProcessConnect API is invoked, the TAM sends a QueryRequest 1245 message. 1247 When the ProcessTeepMessage API is invoked, the TAM first does 1248 validation as specified in Section 4.1.2, and drops the message if it 1249 is not valid. Otherwise, it proceeds as follows. 1251 If the message includes a token, it can be used to match the response 1252 to a request previously sent by the TAM. The TAM MUST expire the 1253 token value after receiving the first response from the device that 1254 has a valid signature and ignore any subsequent messages that have 1255 the same token value. The token value MUST NOT be used for other 1256 purposes, such as a TAM to identify the devices and/or a device to 1257 identify TAMs or Trusted Components. 1259 If a QueryResponse message is received that contains evidence, the 1260 evidence is passed to an attestation Verifier (see 1261 [I-D.ietf-rats-architecture]) to determine whether the Agent is in a 1262 trustworthy state. Based on the results of attestation, and the 1263 lists of installed, requested, and unneeded Trusted Components 1264 reported in the QueryResponse, the TAM determines, in any 1265 implementation specific manner, which Trusted Components need to be 1266 installed, updated, or deleted, if any. If any Trusted Components 1267 need to be installed, updated, or deleted, the TAM sends an Update 1268 message containing SUIT Manifests with command sequences to do the 1269 relevant installs, updates, or deletes. It is important to note that 1270 the TEEP Agent's Update Procedure requires resolving and installing 1271 any dependencies indicated in the manifest, which may take some time, 1272 and the resulting Success or Error message is generated only after 1273 completing the Update Procedure. Hence, depending on the freshness 1274 mechanism in use, the TAM may need to store data (e.g., a nonce) for 1275 some time. 1277 If a Success or Error message is received containing one or more SUIT 1278 Reports, the TAM also validates that the nonce in any SUIT Report 1279 matches the token sent in the Update message, and drops the message 1280 if it does not match. Otherwise, the TAM handles the update in any 1281 implementation specific way, such as updating any locally cached 1282 information about the state of the TEEP Agent, or logging the 1283 results. 1285 If any other Error message is received, the TAM can handle it in any 1286 implementation specific way, but Section 4.6 provides recommendations 1287 for such handling. 1289 7.2. TEEP Agent Behavior 1291 When the RequestTA API is invoked, the TEEP Agent first checks 1292 whether the requested TA is already installed. If it is already 1293 installed, the TEEP Agent passes no data back to the caller. 1294 Otherwise, if the TEEP Agent chooses to initiate the process of 1295 requesting the indicated TA, it determines (in any implementation 1296 specific way) the TAM URI based on any TAM URI provided by the 1297 RequestTA caller and any local configuration, and passes back the TAM 1298 URI to connect to. It MAY also pass back a QueryResponse message if 1299 all of the following conditions are true: 1301 * The last QueryRequest message received from that TAM contained no 1302 token or challenge, 1304 * The ProcessError API was not invoked for that TAM since the last 1305 QueryResponse message was received from it, and 1307 * The public key or certificate of the TAM is cached and not 1308 expired. 1310 When the RequestPolicyCheck API is invoked, the TEEP Agent decides 1311 whether to initiate communication with any trusted TAMs (e.g., it 1312 might choose to do so for a given TAM unless it detects that it has 1313 already communicated with that TAM recently). If so, it passes back 1314 a TAM URI to connect to. If the TEEP Agent has multiple TAMs it 1315 needs to connect with, it just passes back one, with the expectation 1316 that RequestPolicyCheck API will be invoked to retrieve each one 1317 successively until there are no more and it can pass back no data at 1318 that time. Thus, once a TAM URI is returned, the TEEP Agent can 1319 remember that it has already initiated communication with that TAM. 1321 When the ProcessError API is invoked, the TEEP Agent can handle it in 1322 any implementation specific way, such as logging the error or using 1323 the information in future choices of TAM URI. 1325 When the ProcessTeepMessage API is invoked, the Agent first does 1326 validation as specified in Section 4.1.2, and drops the message if it 1327 is not valid. Otherwise, processing continues as follows based on 1328 the type of message. 1330 When a QueryRequest message is received, the Agent responds with a 1331 QueryResponse message if all fields were understood, or an Error 1332 message if any error was encountered. 1334 When an Update message is received, the Agent attempts to update the 1335 Trusted Components specified in the SUIT manifests by following the 1336 Update Procedure specified in [I-D.ietf-suit-manifest], and responds 1337 with a Success message if all SUIT manifests were successfully 1338 installed, or an Error message if any error was encountered. It is 1339 important to note that the Update Procedure requires resolving and 1340 installing any dependencies indicated in the manifest, which may take 1341 some time, and the Success or Error message is generated only after 1342 completing the Update Procedure. 1344 8. Ciphersuites 1346 The TEEP protocol uses COSE for protection of TEEP messages. After a 1347 QueryResponse is received, the selected cryptographic algorithm is 1348 used in subsequent TEEP messages (Install, Success, and Error). To 1349 negotiate cryptographic mechanisms and algorithms, the TEEP protocol 1350 defines the following ciphersuite structure. 1352 ciphersuite = [ 1353 teep-cose-sign-algs / nil, 1354 teep-cose-encrypt-algs / nil , 1355 teep-cose-mac-algs / nil 1356 ] 1358 The ciphersuite structure is used to present the combination of 1359 mechanisms and cryptographic algorithms. Each suite value 1360 corresponds with a COSE-type defined in Section 2 of [RFC8152]. 1362 supported-cipher-suites = [ + suite ] 1364 Cryptographic algorithm values are defined in the COSE Algorithms 1365 registry [COSE.Algorithm]. A TAM MUST support both of the following 1366 ciphersuites. A TEEP Agent MUST support at least one of the two but 1367 can choose which one. For example, a TEEP Agent might choose a given 1368 ciphersuite if it has hardware support for it. 1370 teep-cose-sign-algs /= cose-alg-es256, 1371 teep-cose-sign-algs /= cose-alg-eddsa 1373 A TAM or TEEP Agent MUST also support the following algorithms: 1375 teep-cose-encrypt-algs /= cose-alg-accm-16-64-128 1377 teep-cose-mac-algs /= cose-alg-hmac-256 1379 A TAM or TEEP Agent MAY also support one or more of the following 1380 algorithms: 1382 teep-cose-sign-algs /= cose-alg-ps256, 1383 teep-cose-sign-algs /= cose-alg-ps384, 1384 teep-cose-sign-algs /= cose-alg-ps512, 1385 teep-cose-sign-algs /= cose-alg-rsa-oaep-256, 1386 teep-cose-sign-algs /= cose-alg-rsa-oaep-512 1388 Any ciphersuites without confidentiality protection can only be added 1389 if the associated specification includes a discussion of security 1390 considerations and applicability, since manifests may carry sensitive 1391 information. For example, Section 6 of [I-D.ietf-teep-architecture] 1392 permits implementations that terminate transport security inside the 1393 TEE and if the transport security provides confidentiality then 1394 additional encryption might not be needed in the manifest for some 1395 use cases. For most use cases, however, manifest confidentiality 1396 will be needed to protect sensitive fields from the TAM as discussed 1397 in Section 9.8 of [I-D.ietf-teep-architecture]. 1399 9. Freshness Mechanisms 1401 A freshness mechanism determines how a TAM can tell whether evidence 1402 provided in a Query Response is fresh. There are multiple ways this 1403 can be done as discussed in Section 10 of 1404 [I-D.ietf-rats-architecture]. 1406 Each freshness mechanism is identified with an integer value, which 1407 corresponds to an IANA registered freshness mechanism (see 1408 Section 11.2. This document defines the following freshness 1409 mechanisms: 1411 +=======+=====================+ 1412 | Value | Freshness mechanism | 1413 +=======+=====================+ 1414 | 1 | Nonce | 1415 +-------+---------------------+ 1416 | 2 | Timestamp | 1417 +-------+---------------------+ 1418 | 3 | Epoch ID | 1419 +-------+---------------------+ 1421 Table 3 1423 In the Nonce mechanism, the evidence MUST include a nonce provided in 1424 the QueryRequest challenge. In other mechanisms, a timestamp or 1425 epoch ID determined via mechanisms outside the TEEP protocol is used, 1426 and the challenge is only needed in the QueryRequest message if a 1427 challenge is needed in generating evidence for reasons other than 1428 freshness. 1430 If a TAM supports multiple freshness mechanisms that require 1431 different challenge formats, the QueryRequest message can currently 1432 only send one such challenge. This situation is expected to be rare, 1433 but should it occur, the TAM can choose to prioritize one of them and 1434 exclude the other from the supported-freshness-mechanisms in the 1435 QueryRequest, and resend the QueryRequest with the other mechanism if 1436 an ERR_UNSUPPORTED_FRESHNESS_MECHANISMS Error is received that 1437 indicates the TEEP Agent supports the other mechanism. 1439 10. Security Considerations 1441 This section summarizes the security considerations discussed in this 1442 specification: 1444 Cryptographic Algorithms 1445 TEEP protocol messages exchanged between the TAM and the TEEP 1446 Agent are protected using COSE. This specification relies on the 1447 cryptographic algorithms provided by COSE. Public key based 1448 authentication is used by the TEEP Agent to authenticate the TAM 1449 and vice versa. 1451 Attestation 1452 A TAM can rely on the attestation evidence provided by the TEEP 1453 Agent. To sign the attestation evidence, it is necessary for the 1454 device to possess a public key (usually in the form of a 1455 certificate [RFC5280]) along with the corresponding private key. 1456 Depending on the properties of the attestation mechanism, it is 1457 possible to uniquely identify a device based on information in the 1458 attestation evidence or in the certificate used to sign the 1459 attestation evidence. This uniqueness may raise privacy concerns. 1460 To lower the privacy implications the TEEP Agent MUST present its 1461 attestation evidence only to an authenticated and authorized TAM 1462 and when using EATS, it SHOULD use encryption as discussed in 1463 [I-D.ietf-rats-eat], since confidentiality is not provided by the 1464 TEEP protocol itself and the transport protocol under the TEEP 1465 protocol might be implemented outside of any TEE. If any 1466 mechanism other than EATs is used, it is up to that mechanism to 1467 specify how privacy is provided. 1469 Trusted Component Binaries 1470 Each Trusted Component binary is signed by a Trusted Component 1471 Signer. It is the responsibility of the TAM to relay only 1472 verified Trusted Components from authorized Trusted Component 1473 Signers. Delivery of a Trusted Component to the TEEP Agent is 1474 then the responsibility of the TAM, using the security mechanisms 1475 provided by the TEEP protocol. To protect the Trusted Component 1476 binary, the SUIT manifest format is used and it offers a variety 1477 of security features, including digitial signatures and symmetric 1478 encryption. 1480 Personalization Data 1481 A Trusted Component Signer or TAM can supply personalization data 1482 along with a Trusted Component. This data is also protected by a 1483 SUIT manifest. Personalization data signed and encrypted by a 1484 Trusted Component Signer other than the TAM is opaque to the TAM. 1486 TEEP Broker 1487 As discussed in section 6 of [I-D.ietf-teep-architecture], the 1488 TEEP protocol typically relies on a TEEP Broker to relay messages 1489 between the TAM and the TEEP Agent. When the TEEP Broker is 1490 compromised it can drop messages, delay the delivery of messages, 1491 and replay messages but it cannot modify those messages. (A 1492 replay would be, however, detected by the TEEP Agent.) A 1493 compromised TEEP Broker could reorder messages in an attempt to 1494 install an old version of a Trusted Component. Information in the 1495 manifest ensures that TEEP Agents are protected against such 1496 downgrade attacks based on features offered by the manifest 1497 itself. 1499 Trusted Component Signer Compromise 1500 A TAM is responsible for vetting a Trusted Component and before 1501 distributing them to TEEP Agents. 1503 It is RECOMMENDED to provide a way to update the trust anchor 1504 store used by the TEE, for example using a firmware update 1505 mechanism. Thus, if a Trusted Component Signer is later 1506 compromised, the TAM can update the trust anchor store used by the 1507 TEE, for example using a firmware update mechanism. 1509 CA Compromise 1510 The CA issuing certificates to a TEE or a Trusted Component Signer 1511 might get compromised. It is RECOMMENDED to provide a way to 1512 update the trust anchor store used by the TEE, for example using a 1513 firmware update mechanism. If the CA issuing certificates to 1514 devices gets compromised then these devices might be rejected by a 1515 TAM, if revocation is available to the TAM. 1517 TAM Certificate Expiry 1518 The integrity and the accuracy of the clock within the TEE 1519 determines the ability to determine an expired TAM certificate, if 1520 certificates are used. 1522 Compromised Time Source 1523 As discussed above, certificate validity checks rely on comparing 1524 validity dates to the current time, which relies on having a 1525 trusted source of time, such as [RFC8915]. A compromised time 1526 source could thus be used to subvert such validity checks. 1528 11. IANA Considerations 1530 11.1. Media Type Registration 1532 IANA is requested to assign a media type for application/teep+cbor. 1534 Type name: application 1536 Subtype name: teep+cbor 1538 Required parameters: none 1540 Optional parameters: none 1542 Encoding considerations: Same as encoding considerations of 1543 application/cbor. 1545 Security considerations: See Security Considerations Section of this 1546 document. 1548 Interoperability considerations: Same as interoperability 1549 considerations of application/cbor as specified in [RFC7049]. 1551 Published specification: This document. 1553 Applications that use this media type: TEEP protocol implementations 1555 Fragment identifier considerations: N/A 1557 Additional information: Deprecated alias names for this type: N/A 1559 Magic number(s): N/A 1561 File extension(s): N/A 1563 Macintosh file type code(s): N/A 1565 Person to contact for further information: teep@ietf.org 1567 Intended usage: COMMON 1569 Restrictions on usage: none 1571 Author: See the "Authors' Addresses" section of this document 1573 Change controller: IETF 1575 11.2. Freshness Mechanism Registry 1577 IANA is also requested to create a new registry for freshness 1578 mechanisms. 1580 Name of registry: TEEP Freshness Mechanisms 1582 Policy: Specification Required [RFC8126] 1584 Additional requirements: The specification must document relevant 1585 security considerations. 1587 Initial values: 1589 +=======+=====================+===================+ 1590 | Value | Freshness mechanism | Specification | 1591 +=======+=====================+===================+ 1592 | 1 | Nonce | RFC TBD Section 9 | 1593 +-------+---------------------+-------------------+ 1594 | 2 | Timestamp | RFC TBD Section 9 | 1595 +-------+---------------------+-------------------+ 1596 | 3 | Epoch ID | RFC TBD Section 9 | 1597 +-------+---------------------+-------------------+ 1599 Table 4 1601 (RFC Editor: please replace TBD above with the number assigned to 1602 this document.) 1604 12. References 1606 12.1. Normative References 1608 [COSE.Algorithm] 1609 IANA, "COSE Algorithms", n.d., 1610 . 1613 [I-D.ietf-rats-architecture] 1614 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and 1615 W. Pan, "Remote Attestation Procedures Architecture", Work 1616 in Progress, Internet-Draft, draft-ietf-rats-architecture- 1617 15, 8 February 2022, . 1620 [I-D.ietf-rats-eat] 1621 Lundblade, L., Mandyam, G., and J. O'Donoghue, "The Entity 1622 Attestation Token (EAT)", Work in Progress, Internet- 1623 Draft, draft-ietf-rats-eat-12, 24 February 2022, 1624 . 1627 [I-D.ietf-suit-manifest] 1628 Moran, B., Tschofenig, H., Birkholz, H., and K. Zandberg, 1629 "A Concise Binary Object Representation (CBOR)-based 1630 Serialization Format for the Software Updates for Internet 1631 of Things (SUIT) Manifest", Work in Progress, Internet- 1632 Draft, draft-ietf-suit-manifest-16, 25 October 2021, 1633 . 1636 [I-D.moran-suit-report] 1637 Moran, B., "Secure Reporting of Update Status", Work in 1638 Progress, Internet-Draft, draft-moran-suit-report-01, 22 1639 February 2021, . 1642 [I-D.moran-suit-trust-domains] 1643 Moran, B., "SUIT Manifest Extensions for Multiple Trust 1644 Domains", Work in Progress, Internet-Draft, draft-moran- 1645 suit-trust-domains-00, 25 October 2021, 1646 . 1649 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1650 Requirement Levels", BCP 14, RFC 2119, 1651 DOI 10.17487/RFC2119, March 1997, 1652 . 1654 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1655 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1656 2003, . 1658 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 1659 Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, 1660 . 1662 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1663 Housley, R., and W. Polk, "Internet X.509 Public Key 1664 Infrastructure Certificate and Certificate Revocation List 1665 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1666 . 1668 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1669 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1670 October 2013, . 1672 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1673 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1674 . 1676 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1677 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1678 May 2017, . 1680 12.2. Informative References 1682 [I-D.birkholz-rats-suit-claims] 1683 Birkholz, H. and B. Moran, "Trustworthiness Vectors for 1684 the Software Updates of Internet of Things (SUIT) Workflow 1685 Model", Work in Progress, Internet-Draft, draft-birkholz- 1686 rats-suit-claims-03, 12 January 2022, 1687 . 1690 [I-D.ietf-teep-architecture] 1691 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 1692 "Trusted Execution Environment Provisioning (TEEP) 1693 Architecture", Work in Progress, Internet-Draft, draft- 1694 ietf-teep-architecture-16, 28 February 2022, 1695 . 1698 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1699 Writing an IANA Considerations Section in RFCs", BCP 26, 1700 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1701 . 1703 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1704 Definition Language (CDDL): A Notational Convention to 1705 Express Concise Binary Object Representation (CBOR) and 1706 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1707 June 2019, . 1709 [RFC8915] Franke, D., Sibold, D., Teichel, K., Dansarie, M., and R. 1710 Sundblad, "Network Time Security for the Network Time 1711 Protocol", RFC 8915, DOI 10.17487/RFC8915, September 2020, 1712 . 1714 A. Contributors 1716 We would like to thank Brian Witten (Symantec), Tyler Kim (Solacia), 1717 Nick Cook (Arm), and Minho Yoo (IoTrust) for their contributions to 1718 the Open Trust Protocol (OTrP), which influenced the design of this 1719 specification. 1721 B. Acknowledgements 1723 We would like to thank Eve Schooler for the suggestion of the 1724 protocol name. 1726 We would like to thank Kohei Isobe (TRASIO/SECOM), Ken Takayama 1727 (SECOM) Kuniyasu Suzaki (TRASIO/AIST), Tsukasa Oi (TRASIO), and 1728 Yuichi Takita (SECOM) for their valuable implementation feedback. 1730 We would also like to thank Carsten Bormann and Henk Birkholz for 1731 their help with the CDDL. 1733 C. Complete CDDL 1735 Valid TEEP messages MUST adhere to the following CDDL data 1736 definitions, except that SUIT_Envelope and SUIT_Component_Identifier 1737 are specified in [I-D.ietf-suit-manifest]. 1739 teep-message = $teep-message-type .within teep-message-framework 1741 SUIT_Envelope = any 1743 teep-message-framework = [ 1744 type: uint (0..23) / $teep-type-extension, 1745 options: { * teep-option }, 1746 * uint; further integers, e.g., for data-item-requested 1747 ] 1749 teep-option = (uint => any) 1751 ; messages defined below: 1752 $teep-message-type /= query-request 1753 $teep-message-type /= query-response 1754 $teep-message-type /= update 1755 $teep-message-type /= teep-success 1756 $teep-message-type /= teep-error 1757 ; message type numbers, uint (0..23) 1758 TEEP-TYPE-query-request = 1 1759 TEEP-TYPE-query-response = 2 1760 TEEP-TYPE-update = 3 1761 TEEP-TYPE-teep-success = 5 1762 TEEP-TYPE-teep-error = 6 1764 version = .within uint .size 4 1765 ext-info = .within uint .size 4 1767 ; data items as bitmaps 1768 data-item-requested = $data-item-requested .within uint .size 8 1769 attestation = 1 1770 $data-item-requested /= attestation 1771 trusted-components = 2 1772 $data-item-requested /= trusted-components 1773 extensions = 4 1774 $data-item-requested /= extensions 1776 query-request = [ 1777 type: TEEP-TYPE-query-request, 1778 options: { 1779 ? token => bstr .size (8..64), 1780 ? supported-cipher-suites => [ + suite ], 1781 ? supported-freshness-mechanisms => [ + freshness-mechanism ], 1782 ? challenge => bstr .size (8..512), 1783 ? versions => [ + version ], 1784 * $$query-request-extensions 1785 * $$teep-option-extensions 1786 }, 1787 data-item-requested: data-item-requested 1788 ] 1790 ; ciphersuites 1791 suite = [ 1792 teep-cose-sign-algs / nil, 1793 teep-cose-encrypt-algs / nil, 1794 teep-cose-mac-algs / nil 1795 ] 1797 teep-cose-sign-algs /= cose-alg-es256, 1798 teep-cose-sign-algs /= cose-alg-eddsa 1799 teep-cose-sign-algs /= cose-alg-ps256, 1800 teep-cose-sign-algs /= cose-alg-ps384, 1801 teep-cose-sign-algs /= cose-alg-ps512, 1802 teep-cose-sign-algs /= cose-alg-rsa-oaep-256, 1803 teep-cose-sign-algs /= cose-alg-rsa-oaep-512 1804 teep-cose-encrypt-algs /= cose-alg-accm-16-64-128 1806 teep-cose-mac-algs /= cose-alg-hmac-256 1808 ; algorithm identifiers defined in the IANA COSE Algorithms Registry 1809 cose-alg-es256 = -7 1810 cose-alg-eddsa = -8 1811 cose-alg-ps256 = -37 1812 cose-alg-ps384 = -38 1813 cose-alg-ps512 = -39 1814 cose-alg-rsa-oaep-256 = -41 1815 cose-alg-rsa-oaep-512 = -42 1816 cose-alg-accm-16-64-128 = 10 1817 cose-alg-hmac-256 = 5 1819 ; freshness-mechanisms 1821 freshness-mechanism = $TEEP-freshness-mechanism .within uint .size 4 1823 FRESHNESS_NONCE = 0 1824 FRESHNESS_TIMESTAMP = 1 1825 FRESHNESS_EPOCH_ID = 2 1827 $TEEP-freshness-mechanism /= FRESHNESS_NONCE 1828 $TEEP-freshness-mechanism /= FRESHNESS_TIMESTAMP 1829 $TEEP-freshness-mechanism /= FRESHNESS_EPOCH_ID 1831 query-response = [ 1832 type: TEEP-TYPE-query-response, 1833 options: { 1834 ? token => bstr .size (8..64), 1835 ? selected-cipher-suite => suite, 1836 ? selected-version => version, 1837 ? evidence-format => text, 1838 ? evidence => bstr, 1839 ? tc-list => [ + tc-info ], 1840 ? requested-tc-list => [ + requested-tc-info ], 1841 ? unneeded-tc-list => [ + SUIT_Component_Identifier ], 1842 ? ext-list => [ + ext-info ], 1843 * $$query-response-extensions, 1844 * $$teep-option-extensions 1845 } 1846 ] 1848 tc-info = { 1849 component-id => SUIT_Component_Identifier, 1850 ? tc-manifest-sequence-number => .within uint .size 8 1851 } 1852 requested-tc-info = { 1853 component-id => SUIT_Component_Identifier, 1854 ? tc-manifest-sequence-number => .within uint .size 8 1855 ? have-binary => bool 1856 } 1858 update = [ 1859 type: TEEP-TYPE-update, 1860 options: { 1861 ? token => bstr .size (8..64), 1862 ? manifest-list => [ + bstr .cbor SUIT_Envelope ], 1863 * $$update-extensions, 1864 * $$teep-option-extensions 1865 } 1866 ] 1868 teep-success = [ 1869 type: TEEP-TYPE-teep-success, 1870 options: { 1871 ? token => bstr .size (8..64), 1872 ? msg => text .size (1..128), 1873 ? suit-reports => [ + suit-report ], 1874 * $$teep-success-extensions, 1875 * $$teep-option-extensions 1876 } 1877 ] 1879 teep-error = [ 1880 type: TEEP-TYPE-teep-error, 1881 options: { 1882 ? token => bstr .size (8..64), 1883 ? err-msg => text .size (1..128), 1884 ? supported-cipher-suites => [ + suite ], 1885 ? supported-freshness-mechanisms => [ + freshness-mechanism ], 1886 ? versions => [ + version ], 1887 ? suit-reports => [ + suit-report ], 1888 * $$teep-error-extensions, 1889 * $$teep-option-extensions 1890 }, 1891 err-code: uint (0..23) 1892 ] 1894 ; The err-code parameter, uint (0..23) 1895 ERR_PERMANENT_ERROR = 1 1896 ERR_UNSUPPORTED_EXTENSION = 2 1897 ERR_UNSUPPORTED_FRESHNESS_MECHANISMS = 3 1898 ERR_UNSUPPORTED_MSG_VERSION = 4 1899 ERR_UNSUPPORTED_CIPHER_SUITES = 5 1900 ERR_BAD_CERTIFICATE = 6 1901 ERR_CERTIFICATE_EXPIRED = 9 1902 ERR_TEMPORARY_ERROR = 10 1903 ERR_MANIFEST_PROCESSING_FAILED = 17 1905 ; labels of mapkey for teep message parameters, uint (0..23) 1906 supported-cipher-suites = 1 1907 challenge = 2 1908 versions = 3 1909 selected-cipher-suite = 5 1910 selected-version = 6 1911 evidence = 7 1912 tc-list = 8 1913 ext-list = 9 1914 manifest-list = 10 1915 msg = 11 1916 err-msg = 12 1917 evidence-format = 13 1918 requested-tc-list = 14 1919 unneeded-tc-list = 15 1920 component-id = 16 1921 tc-manifest-sequence-number = 17 1922 have-binary = 18 1923 suit-reports = 19 1924 token = 20 1925 supported-freshness-mechanisms = 21 1927 D. Examples of Diagnostic Notation and Binary Representation 1929 This section includes some examples with the following assumptions: 1931 * The device will have two TCs with the following SUIT Component 1932 Identifiers: 1934 - [ 0x000102030405060708090a0b0c0d0e0f ] 1936 - [ 0x100102030405060708090a0b0c0d0e0f ] 1938 * SUIT manifest-list is set empty only for example purposes (see 1939 Appendix E for actual manifest examples) 1941 D.1. QueryRequest Message 1943 D.1.1. CBOR Diagnostic Notation 1944 / query-request = / 1945 [ 1946 1, / type : TEEP-TYPE-query-request = 1 (uint (0..23)) / 1947 / options : / 1948 { 1949 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 1950 / token = 20 (mapkey) : 1951 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 1952 generated by TAM / 1953 1 : [ 1 ], / supported-cipher-suites = 1 (mapkey) : 1954 TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 1955 [ 1 ] (array of .within uint .size 4) / 1956 3 : [ 0 ] / version = 3 (mapkey) : 1957 [ 0 ] (array of .within uint .size 4) / 1958 }, 1959 3 / data-item-requested : 1960 attestation | trusted-components = 3 (.within uint .size 8) / 1961 ] 1963 D.1.2. CBOR Binary Representation 1965 83 # array(3) 1966 01 # unsigned(1) uint (0..23) 1967 A4 # map(4) 1968 14 # unsigned(20) uint (0..23) 1969 4F # bytes(16) (8..64) 1970 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 1971 01 # unsigned(1) uint (0..23) 1972 81 # array(1) 1973 01 # unsigned(1) within uint .size 4 1974 03 # unsigned(3) uint (0..23) 1975 81 # array(1) 1976 00 # unsigned(0) within uint .size 4 1977 04 # unsigned(4) uint (0..23) 1978 43 # bytes(3) 1979 010203 # "\x01\x02\x03" 1980 03 # unsigned(3) .within uint .size 8 1982 D.2. Entity Attestation Token 1984 This is shown below in CBOR diagnostic form. Only the payload signed 1985 by COSE is shown. 1987 D.2.1. CBOR Diagnostic Notation 1988 / eat-claim-set = / 1989 { 1990 / issuer / 1: "joe", 1991 / timestamp (iat) / 6: 1(1526542894) 1992 / nonce / 10: h'948f8860d13a463e8e', 1993 / secure-boot / 15: true, 1994 / debug-status / 16: 3, / disabled-permanently / 1995 / security-level / 14: 3, / secure-restricted / 1996 / device-identifier / : h'e99600dd921649798b013e9752dcf0c5', 1997 / vendor-identifier / : h'2b03879b33434a7ca682b8af84c19fd4', 1998 / class-identifier / : h'9714a5796bd245a3a4ab4f977cb8487f', 1999 / chip-version / 26: [ "MyTEE", 1 ], 2000 / component-identifier / : h'60822887d35e43d5b603d18bcaa3f08d', 2001 / version / : "v0.1" 2002 } 2004 D.3. QueryResponse Message 2006 D.3.1. CBOR Diagnostic Notation 2007 / query-response = / 2008 [ 2009 2, / type : TEEP-TYPE-query-response = 2 (uint (0..23)) / 2010 / options : / 2011 { 2012 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 2013 / token = 20 (mapkey) : 2014 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 2015 given from TAM's QueryRequest message / 2016 5 : 1, / selected-cipher-suite = 5 (mapkey) : 2017 TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 2018 1 (.within uint .size 4) / 2019 6 : 0, / selected-version = 6 (mapkey) : 2020 0 (.within uint .size 4) / 2021 7 : ... / evidence = 7 (mapkey) : 2022 Entity Attestation Token / 2023 8 : [ / tc-list = 8 (mapkey) : (array of tc-info) / 2024 { 2025 16 : [ 0x000102030405060708090a0b0c0d0e0f ] / component-id = 2026 16 (mapkey) : [ h'000102030405060708090a0b0c0d0e0f' ] 2027 (SUIT_Component_Identifier = [* bstr]) / 2028 }, 2029 { 2030 16 : [ 0x100102030405060708090a0b0c0d0e0f ] / component-id = 2031 16 (mapkey) : [ h'100102030405060708090a0b0c0d0e0f' ] 2032 (SUIT_Component_Identifier = [* bstr]) / 2033 } 2034 ] 2035 } 2036 ] 2038 D.3.2. CBOR Binary Representation 2039 82 # array(2) 2040 02 # unsigned(2) uint (0..23) 2041 A5 # map(5) 2042 14 # unsigned(20) uint (0..23) 2043 4F # bytes(16) (8..64) 2044 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 2045 05 # unsigned(5) uint (0..23) 2046 01 # unsigned(1) .within uint .size 4 2047 06 # unsigned(6) uint (0..23) 2048 00 # unsigned(0) .within uint .size 4 2049 07 # unsigned(7) uint (0..23) 2050 ... # Entity Attestation Token 2051 08 # unsigned(8) uint (0..23) 2052 82 # array(2) 2053 81 # array(1) 2054 4F # bytes(16) 2055 000102030405060708090A0B0C0D0E0F 2056 81 # array(1) 2057 4F # bytes(16) 2058 100102030405060708090A0B0C0D0E0F 2060 D.4. Update Message 2062 D.4.1. CBOR Diagnostic Notation 2064 / update = / 2065 [ 2066 3, / type : TEEP-TYPE-update = 3 (uint (0..23)) / 2067 / options : / 2068 { 2069 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 2070 / token = 20 (mapkey) : 2071 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 2072 generated by TAM / 2073 10 : [ ] / manifest-list = 10 (mapkey) : 2074 [ ] (array of bstr wrapped SUIT_Envelope(any)) / 2075 / empty, example purpose only / 2076 } 2077 ] 2079 D.4.2. CBOR Binary Representation 2080 82 # array(2) 2081 03 # unsigned(3) uint (0..23) 2082 A3 # map(3) 2083 14 # unsigned(20) uint (0..23) 2084 4F # bytes(16) (8..64) 2085 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 2086 0A # unsigned(10) uint (0..23) 2087 80 # array(0) 2089 D.5. Success Message 2091 D.5.1. CBOR Diagnostic Notation 2093 / teep-success = / 2094 [ 2095 5, / type : TEEP-TYPE-teep-success = 5 (uint (0..23)) / 2096 / options : / 2097 { 2098 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 2099 / token = 20 (mapkey) : 2100 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 2101 given from TAM's Update message / 2102 } 2103 ] 2105 D.5.2. CBOR Binary Representation 2107 82 # array(2) 2108 05 # unsigned(5) uint (0..23) 2109 A1 # map(1) 2110 14 # unsigned(20) uint (0..23) 2111 4F # bytes(16) (8..64) 2112 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 2114 D.6. Error Message 2116 D.6.1. CBOR Diagnostic Notation 2117 / teep-error = / 2118 [ 2119 6, / type : TEEP-TYPE-teep-error = 6 (uint (0..23)) / 2120 / options : / 2121 { 2122 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 2123 / token = 20 (mapkey) : 2124 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 2125 given from TAM's Update message / 2126 12 : "disk-full" / err-msg = 12 (mapkey) : 2127 "disk-full" (text .size (1..128)) / 2128 }, 2129 17, / err-code : ERR_MANIFEST_PROCESSING_FAILED = 17 (uint (0..23)) / 2130 ] 2132 D.6.2. CBOR binary Representation 2134 83 # array(3) 2135 06 # unsigned(6) uint (0..23) 2136 A2 # map(2) 2137 14 # unsigned(20) uint (0..23) 2138 4F # bytes(16) (8..64) 2139 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 2140 0C # unsigned(12) uint (0..23) 2141 69 # text(9) (1..128) 2142 6469736B2D66756C6C # "disk-full" 2143 11 # unsigned(17) uint (0..23) 2145 E. Examples of SUIT Manifests 2147 This section shows some examples of SUIT manifests described in 2148 Section 4.4. 2150 The examples are signed using the following ECDSA secp256r1 key with 2151 SHA256 as the digest function. 2153 COSE_Sign1 Cryptographic Key: 2155 -----BEGIN PRIVATE KEY----- 2156 MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC 2157 CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv 2158 P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW 2159 -----END PRIVATE KEY----- 2161 The corresponding public key can be used to verify these examples: 2163 -----BEGIN PUBLIC KEY----- 2164 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb 2165 bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== 2166 -----END PUBLIC KEY----- 2168 Example 1: SUIT Manifest pointing to URI of the Trusted Component Binary 2170 CBOR Diagnostic Notation of SUIT Manifest 2172 / SUIT_Envelope_Tagged / 107( { 2173 / suit-authentication-wrapper / 2: << [ 2174 << [ 2175 / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, 2176 / suit-digest-bytes: / h'DB601ADE73092B58532CA03FBB663DE49532435336F1558B49BB622726A2FEDD' 2177 ] >>, 2178 << / COSE_Sign1_Tagged / 18( [ 2179 / protected: / << { 2180 / algorithm-id / 1: -7 / ES256 / 2181 } >>, 2182 / unprotected: / {}, 2183 / payload: / null, 2184 / signature: / h'5B2D535A2B6D5E3C585C1074F414DA9E10BD285C99A33916DADE3ED38812504817AC48B62B8E984EC622785BD1C411888BE531B1B594507816B201F6F28579A4' 2185 ] ) >> 2186 ] >>, 2187 / suit-manifest / 3: << { 2188 / suit-manifest-version / 1: 1, 2189 / suit-manifest-sequence-number / 2: 3, 2190 / suit-common / 3: << { 2191 / suit-components / 2: [ 2192 [ 2193 h'544545502D446576696365', / "TEEP-Device" / 2194 h'5365637572654653', / "SecureFS" / 2195 h'8D82573A926D4754935332DC29997F74', / tc-uuid / 2196 h'7461' / "ta" / 2197 ] 2198 ], 2199 / suit-common-sequence / 4: << [ 2200 / suit-directive-override-parameters / 20, { 2201 / suit-parameter-vendor-identifier / 1: h'C0DDD5F15243566087DB4F5B0AA26C2F', 2202 / suit-parameter-class-identifier / 2: h'DB42F7093D8C55BAA8C5265FC5820F4E', 2203 / suit-parameter-image-digest / 3: << [ 2204 / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, 2205 / suit-digest-bytes: / h'8CF71AC86AF31BE184EC7A05A411A8C3A14FD9B77A30D046397481469468ECE8' 2206 ] >>, 2207 / suit-parameter-image-size / 14: 20 2208 }, 2209 / suit-condition-vendor-identifier / 1, 15, 2210 / suit-condition-class-identifier / 2, 15 2212 ] >> 2213 } >>, 2214 / suit-install / 9: << [ 2215 / suit-directive-override-parameters / 20, { 2216 / suit-parameter-uri / 21: "https://example.org/8d82573a-926d-4754-9353-32dc29997f74.ta" 2217 }, 2218 / suit-directive-fetch / 21, 15, 2219 / suit-condition-image-match / 3, 15 2220 ] >> 2221 } >> 2222 } ) 2224 CBOR Binary Representation 2226 D8 6B # tag(107) / SUIT_Envelope_Tagged / 2227 A2 # map(2) 2228 02 # unsigned(2) / suit-authentication-wrapper / 2229 58 73 # bytes(115) 2230 82 # array(2) 2231 58 24 # bytes(36) 2232 82 # array(2) 2233 2F # negative(15) / -16 = suit-cose-alg-sha256 / 2234 58 20 # bytes(32) 2235 DB601ADE73092B58532CA03FBB663DE49532435336F1558B49BB622726A2FEDD 2236 58 4A # bytes(74) 2237 D2 # tag(18) / COSE_Sign1_Tagged / 2238 84 # array(4) 2239 43 # bytes(3) 2240 A1 # map(1) 2241 01 # unsigned(1) / algorithm-id / 2242 26 # negative(6) / -7 = ES256 / 2243 A0 # map(0) 2244 F6 # primitive(22) / null / 2245 58 40 # bytes(64) 2246 5B2D535A2B6D5E3C585C1074F414DA9E10BD285C99A33916DADE3ED38812504817AC48B62B8E984EC622785BD1C411888BE531B1B594507816B201F6F28579A4 2247 03 # unsigned(3) / suit-manifest: / 2248 58 D4 # bytes(212) 2249 A4 # map(4) 2250 01 # unsigned(1) / suit-manifest-version: / 2251 01 # unsigned(1) 2252 02 # unsigned(2) / suit-manifest-sequence-number: / 2253 03 # unsigned(3) 2254 03 # unsigned(3) / suit-common: / 2255 58 84 # bytes(132) 2256 A2 # map(2) 2257 02 # unsigned(2) / suit-components: / 2258 81 # array(1) 2259 84 # array(4) 2260 4B # bytes(11) 2261 544545502D446576696365 # "TEEP-Device" 2262 48 # bytes(8) 2263 5365637572654653 # "SecureFS" 2264 50 # bytes(16) 2265 8D82573A926D4754935332DC29997F74 # tc-uuid 2266 42 # bytes(2) 2267 7461 # "ta" 2268 04 # unsigned(4) / suit-common-sequence: / 2269 58 54 # bytes(84) 2270 86 # array(6) 2271 14 # unsigned(20) / suit-directive-override-parameters: / 2272 A4 # map(4) 2273 01 # unsigned(1) / suit-parameter-vendor-identifier: / 2274 50 # bytes(16) 2275 C0DDD5F15243566087DB4F5B0AA26C2F 2276 02 # unsigned(2) / suit-parameter-class-identifier: / 2277 50 # bytes(16) 2278 DB42F7093D8C55BAA8C5265FC5820F4E 2279 03 # unsigned(3) / suit-parameter-image-digest: / 2280 58 24 # bytes(36) 2281 82 # array(2) 2282 2F # negative(15) / -16 = suit-cose-alg-sha256 / 2283 58 20 # bytes(32) 2284 8CF71AC86AF31BE184EC7A05A411A8C3A14FD9B77A30D046397481469468ECE8 2285 0E # unsigned(14) / suit-parameter-image-size: / 2286 14 # unsigned(20) 2287 01 # unsigned(1) / suit-condition-vendor-identifier: / 2288 0F # unsigned(15) 2289 02 # unsigned(2) / suit-condition-class-identifier: / 2290 0F # unsigned(15) 2291 09 # unsigned(9) / suit-install: / 2292 58 45 # bytes(69) 2293 86 # array(6) 2294 14 # unsigned(20) / suit-directive-override-parameters: / 2295 A1 # map(1) 2296 15 # unsigned(21) / suit-parameter-uri: / 2297 78 3B # text(59) 2298 68747470733A2F2F6578616D706C652E6F72672F38643832353733612D393236642D343735342D393335332D3332646332393939376637342E7461 # "https://example.org/8d82573a-926d-4754-9353-32dc29997f74.ta" 2299 15 # unsigned(21) / suit-directive-fetch: / 2300 0F # unsigned(15) 2301 03 # unsigned(3) / suit-condition-image-match: / 2302 0F # unsigned(15) 2304 CBOR Binary in Hex 2305 D86BA2025873825824822F5820DB601ADE73092B58532CA03FBB663DE495 2306 32435336F1558B49BB622726A2FEDD584AD28443A10126A0F658405B2D53 2307 5A2B6D5E3C585C1074F414DA9E10BD285C99A33916DADE3ED38812504817 2308 AC48B62B8E984EC622785BD1C411888BE531B1B594507816B201F6F28579 2309 A40358D4A401010203035884A20281844B544545502D4465766963654853 2310 65637572654653508D82573A926D4754935332DC29997F74427461045854 2311 8614A40150C0DDD5F15243566087DB4F5B0AA26C2F0250DB42F7093D8C55 2312 BAA8C5265FC5820F4E035824822F58208CF71AC86AF31BE184EC7A05A411 2313 A8C3A14FD9B77A30D046397481469468ECE80E14010F020F0958458614A1 2314 15783B68747470733A2F2F6578616D706C652E6F72672F38643832353733 2315 612D393236642D343735342D393335332D3332646332393939376637342E 2316 7461150F030F 2318 Example 2: SUIT Manifest including the Trusted Component Binary 2320 CBOR Diagnostic Notation of SUIT Manifest 2322 / SUIT_Envelope_Tagged / 107( { 2323 / suit-authentication-wrapper / 2: << [ 2324 << [ 2325 / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, 2326 / suit-digest-bytes: / h'14A98BE957DE38FAE37376EA491FD6CAD9BFBD3C90051C8F5B017D7A496C3B05' 2327 ] >>, 2328 << / COSE_Sign1_Tagged / 18( [ 2329 / protected: / << { 2330 / algorithm-id / 1: -7 / ES256 / 2331 } >>, 2332 / unprotected: / {}, 2333 / payload: / null, 2334 / signature: / h'4093B323953785981EB607C8BA61B21E5C4F85726A2AF48C1CB05BD4401B1B1565070728FDA38E6496D631E1D23F966CFF7805EDE721D48507D9192993DA8722' 2335 ] ) >> 2336 ] >>, 2337 / suit-integrated-payload / "#tc": h'48656C6C6F2C2053656375726520576F726C6421', / "Hello, Secure World!" / 2338 / suit-manifest / 3: << { 2339 / suit-manifest-version / 1: 1, 2340 / suit-manifest-sequence-number / 2: 3, 2341 / suit-common / 3: << { 2342 / suit-components / 2: [ 2343 [ 2344 h'544545502D446576696365', / "TEEP-Device" / 2345 h'5365637572654653', / "SecureFS" / 2346 h'8D82573A926D4754935332DC29997F74', / tc-uuid / 2347 h'7461' / "ta" / 2348 ] 2349 ], 2350 / suit-common-sequence / 4: << [ 2351 / suit-directive-override-parameters / 20, { 2352 / suit-parameter-vendor-identifier / 1: h'C0DDD5F15243566087DB4F5B0AA26C2F', 2353 / suit-parameter-class-identifier / 2: h'DB42F7093D8C55BAA8C5265FC5820F4E', 2354 / suit-parameter-image-digest / 3: << [ 2355 / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, 2356 / suit-digest-bytes: / h'8CF71AC86AF31BE184EC7A05A411A8C3A14FD9B77A30D046397481469468ECE8' 2357 ] >>, 2358 / suit-parameter-image-size / 14: 20 2359 }, 2360 / suit-condition-vendor-identifier / 1, 15, 2361 / suit-condition-class-identifier / 2, 15 2362 ] >> 2363 } >>, 2364 / suit-install / 9: << [ 2365 / suit-directive-override-parameters / 20, { 2366 / suit-parameter-uri / 21: "#tc" 2367 }, 2368 / suit-directive-fetch / 21, 15, 2369 / suit-condition-image-match / 3, 15 2370 ] >> 2371 } >> 2372 } ) 2374 CBOR Binary Representation 2376 D8 6B # tag(107) / SUIT_Envelope_Tagged / 2377 A3 # map(3) 2378 02 # unsigned(2) / suit-authentication-wrapper / 2379 58 73 # bytes(115) 2380 82 # array(2) 2381 58 24 # bytes(36) 2382 82 # array(2) 2383 2F # negative(15) / -16 = suit-cose-alg-sha256 / 2384 58 20 # bytes(32) 2385 14A98BE957DE38FAE37376EA491FD6CAD9BFBD3C90051C8F5B017D7A496C3B05 2386 58 4A # bytes(74) 2387 D2 # tag(18) / COSE_Sign1_Tagged / 2388 84 # array(4) 2389 43 # bytes(3) 2390 A1 # map(1) 2391 01 # unsigned(1) / algorithm-id / 2392 26 # negative(6) / -7 = ES256 / 2393 A0 # map(0) 2394 F6 # primitive(22) / null / 2395 58 40 # bytes(64) 2396 4093B323953785981EB607C8BA61B21E5C4F85726A2AF48C1CB05BD4401B1B1565070728FDA38E6496D631E1D23F966CFF7805EDE721D48507D9192993DA8722 2397 63 # text(3) / suit-integrated-payload / 2398 237463 # "#tc" 2399 54 # bytes(20) 2400 48656C6C6F2C2053656375726520576F726C6421 # "Hello, Secure World!" 2402 03 # unsigned(3) / suit-manifest: / 2403 58 9A # bytes(154) 2404 A4 # map(4) 2405 01 # unsigned(1) / suit-manifest-version: / 2406 01 # unsigned(1) 2407 02 # unsigned(2) / suit-manifest-sequence-number: / 2408 03 # unsigned(3) 2409 03 # unsigned(3) / suit-common: / 2410 58 84 # bytes(132) 2411 A2 # map(2) 2412 02 # unsigned(2) / suit-components: / 2413 81 # array(1) 2414 84 # array(4) 2415 4B # bytes(11) 2416 544545502D446576696365 # "TEEP-Device" 2417 48 # bytes(8) 2418 5365637572654653 # "SecureFS" 2419 50 # bytes(16) 2420 8D82573A926D4754935332DC29997F74 # tc-uuid 2421 42 # bytes(2) 2422 7461 # "ta" 2423 04 # unsigned(4) / suit-common-sequence: / 2424 58 54 # bytes(84) 2425 86 # array(6) 2426 14 # unsigned(20) / suit-directive-override-parameters: / 2427 A4 # map(4) 2428 01 # unsigned(1) / suit-parameter-vendor-identifier: / 2429 50 # bytes(16) 2430 C0DDD5F15243566087DB4F5B0AA26C2F 2431 02 # unsigned(2) / suit-parameter-class-identifier: / 2432 50 # bytes(16) 2433 DB42F7093D8C55BAA8C5265FC5820F4E 2434 03 # unsigned(3) / suit-parameter-image-digest: / 2435 58 24 # bytes(36) 2436 82 # array(2) 2437 2F # negative(15) / -16 = suit-cose-alg-sha256 / 2438 58 20 # bytes(32) 2439 8CF71AC86AF31BE184EC7A05A411A8C3A14FD9B77A30D046397481469468ECE8 2440 0E # unsigned(14) / suit-parameter-image-size: / 2441 14 # unsigned(20) 2442 01 # unsigned(1) / suit-condition-vendor-identifier: / 2443 0F # unsigned(15) 2444 02 # unsigned(2) / suit-condition-class-identifier: / 2445 0F # unsigned(15) 2446 09 # unsigned(9) / suit-install: / 2447 4C # bytes(12) 2448 86 # array(6) 2449 14 # unsigned(20) / suit-directive-override-parameters: / 2450 A1 # map(1) 2451 15 # unsigned(21) / suit-parameter-uri: / 2452 63 # text(3) 2453 237463 # "#tc" 2454 15 # unsigned(21) / suit-directive-fetch: / 2455 0F # unsigned(15) 2456 03 # unsigned(3) / suit-condition-image-match: / 2457 0F # unsigned(15) 2459 CBOR Binary in Hex 2461 D86BA3025873825824822F582014A98BE957DE38FAE37376EA491FD6CAD9 2462 BFBD3C90051C8F5B017D7A496C3B05584AD28443A10126A0F658404093B3 2463 23953785981EB607C8BA61B21E5C4F85726A2AF48C1CB05BD4401B1B1565 2464 070728FDA38E6496D631E1D23F966CFF7805EDE721D48507D9192993DA87 2465 22632374635448656C6C6F2C2053656375726520576F726C642103589AA4 2466 01010203035884A20281844B544545502D44657669636548536563757265 2467 4653508D82573A926D4754935332DC29997F744274610458548614A40150 2468 C0DDD5F15243566087DB4F5B0AA26C2F0250DB42F7093D8C55BAA8C5265F 2469 C5820F4E035824822F58208CF71AC86AF31BE184EC7A05A411A8C3A14FD9 2470 B77A30D046397481469468ECE80E14010F020F094C8614A1156323746315 2471 0F030F 2473 Example 3: Supplying Personalization Data for Trusted Component Binary 2475 CBOR Diagnostic Notation of SUIT Manifest 2477 / SUIT_Envelope_Tagged / 107( { 2478 / suit-authentication-wrapper / 2: << [ 2479 << [ 2480 / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, 2481 / suit-digest-bytes: / h'CE596D785169B72712560B3A246AA98F814498EA3625EEBB72CED9AF273E7FFD' 2482 ] >>, 2483 << / COSE_Sign1_Tagged / 18( [ 2484 / protected: / << { 2485 / algorithm-id / 1: -7 / ES256 / 2486 } >>, 2487 / unprotected: / {}, 2488 / payload: / null, 2489 / signature: / h'E9083AA71D2BFCE48253037B9C3116A5EDF23BE0F4B4357A8A835F724660DA7482C64345B4C73DE95F05513BD09FC2E58BD2CC865CC851AD797513A9A951A3CA' 2490 ] ) >> 2491 ] >>, 2492 / suit-manifest / 3: << { 2493 / suit-manifest-version / 1: 1, 2494 / suit-manifest-sequence-number / 2: 3, 2495 / suit-common / 3: << { 2496 / suit-dependencies / 1: [ 2497 { 2498 / suit-dependency-digest / 1: [ 2499 / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, 2500 / suit-digest-bytes: / h'F8690E5A86D010BF2B5348ABB99F2254DB7B608D0D626B98DB51AB3ECFC51907' 2501 ] 2502 } 2503 ], 2504 / suit-components / 2: [ 2505 [ 2506 h'544545502D446576696365', / "TEEP-Device" / 2507 h'5365637572654653', / "SecureFS" / 2508 h'636F6E6669672E6A736F6E' / "config.json" / 2509 ] 2510 ], 2511 / suit-common-sequence / 4: << [ 2512 / suit-directive-set-component-index / 12, 0, 2513 / suit-directive-override-parameters / 20, { 2514 / suit-parameter-vendor-identifier / 1: h'C0DDD5F15243566087DB4F5B0AA26C2F', 2515 / suit-parameter-class-identifier / 2: h'DB42F7093D8C55BAA8C5265FC5820F4E', 2516 / suit-parameter-image-digest / 3: << [ 2517 / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, 2518 / suit-digest-bytes: / h'AAABCCCDEEEF00012223444566678889ABBBCDDDEFFF01112333455567778999' 2519 ] >>, 2520 / suit-parameter-image-size / 14: 64 2521 }, 2522 / suit-condition-vendor-idnetifier / 1, 15, 2523 / suit-condition-class-identifier / 2, 15 2524 ] >> 2525 } >>, 2526 / suit-dependency-resolution / 7: << [ 2527 / suit-directive-set-dependency-index / 13, 0, 2528 / suit-directive-override-parameters / 20, { 2529 / suit-parameter-uri / 21: "https://example.org/8d82573a-926d-4754-9353-32dc29997f74.suit" 2530 }, 2531 / suit-directive-fetch / 21, 2, 2532 / suit-condition-image-match / 3, 15 2533 ] >>, 2534 / suit-install / 9: << [ 2535 / suit-directive-set-dependency-index / 13, 0, 2536 / suit-directive-process-dependency / 18, 0, 2537 / suit-directive-set-component-index / 12, 0, 2538 / suit-directive-override-parameters / 20, { 2539 / suit-parameter-uri / 21: "https://example.org/config.json" 2540 }, 2541 / suit-directive-fetch / 21, 2, 2542 / suit-condition-image-match / 3, 15 2543 ] >>, 2544 / suit-validate / 10: << [ 2545 / suit-directive-set-component-index / 12, 0, 2546 / suit-condition-image-match/ 3, 15 2547 ] >> 2548 } >> 2549 } ) 2551 CBOR Binary Represenation 2553 D8 6B # tag(107) / SUIT_Envelope_Tagged / 2554 A2 # map(2) 2555 02 # unsigned(2) / suit-authentication-wrapper: / 2556 58 73 # bytes(115) 2557 82 # array(2) 2558 58 24 # bytes(36) 2559 82 # array(2) 2560 2F # negative(15) / -16 = suit-cose-alg-sha256 / 2561 58 20 # bytes(32) 2562 CE596D785169B72712560B3A246AA98F814498EA3625EEBB72CED9AF273E7FFD 2563 58 4A # bytes(74) 2564 D2 # tag(18) / COSE_Sign1_Tagged / 2565 84 # array(4) 2566 43 # bytes(3) 2567 A1 # map(1) 2568 01 # unsigned(1) / algorithm-id / 2569 26 # negative(6) / -7 = ES256 / 2570 A0 # map(0) 2571 F6 # primitive(22) / null / 2572 58 40 # bytes(64) 2573 E9083AA71D2BFCE48253037B9C3116A5EDF23BE0F4B4357A8A835F724660DA7482C64345B4C73DE95F05513BD09FC2E58BD2CC865CC851AD797513A9A951A3CA 2574 03 # unsigned(3) / suit-manifest: / 2575 59 0134 # bytes(308) 2576 A6 # map(6) 2577 01 # unsigned(1) / suit-manifest-version: / 2578 01 # unsigned(1) 2579 02 # unsigned(2) / suit-manifest-sequence-number: / 2580 03 # unsigned(3) 2581 03 # unsigned(3) / suit-common: / 2582 58 A7 # bytes(167) 2583 A3 # map(3) 2584 01 # unsigned(1) / suit-dependencies: / 2585 81 # array(1) 2586 A1 # map(1) 2587 01 # unsigned(1) suit-dependency-digest: / 2588 82 # array(2) 2589 2F # negative(15) / -16 = suit-cose-alg-sha256 / 2590 58 20 # bytes(32) 2591 F8690E5A86D010BF2B5348ABB99F2254DB7B608D0D626B98DB51AB3ECFC51907 2592 02 # unsigned(2) / suit-components: / 2593 81 # array(1) 2594 83 # array(3) 2595 4B # bytes(11) 2596 544545502D446576696365 # "TEEP-Device" 2597 48 # bytes(8) 2598 5365637572654653 # "SecureFS" 2599 4B # bytes(11) 2600 636F6E6669672E6A736F6E # "config.json" 2601 04 # unsigned(4) / suit-common-sequence: / 2602 58 57 # bytes(87) 2603 88 # array(8) 2604 0C # unsigned(12) / suit-directive-set-component-index: / 2605 00 # unsigned(0) 2606 14 # unsigned(20) / suit-directive-override-parameters: / 2607 A4 # map(4) 2608 01 # unsigned(1) / suit-parameter-vendor-identifier: / 2609 50 # bytes(16) 2610 C0DDD5F15243566087DB4F5B0AA26C2F 2611 02 # unsigned(2) / suit-parameter-class-identifier: / 2612 50 # bytes(16) 2613 DB42F7093D8C55BAA8C5265FC5820F4E 2614 03 # unsigned(3) / suit-parameter-image-digest: / 2615 58 24 # bytes(36) 2616 82 # array(2) 2617 2F # negative(15) / -16 = suit-cose-alg-sha256 / 2618 58 20 # bytes(32) 2619 AAABCCCDEEEF00012223444566678889ABBBCDDDEFFF01112333455567778999 2620 0E # unsigned(14) / suit-parameter-image-size: / 2621 18 40 # unsigned(64) 2622 01 # unsigned(1) / suit-condition-vendor-identifier: / 2623 0F # unsigned(15) 2624 02 # unsigned(2) / suit-condition-class-identifier: / 2625 0F # unsigned(15) 2626 07 # unsigned(7) / suit-dependency-resolution: / 2627 58 49 # bytes(73) 2628 88 # array(8) 2629 0D # unsigned(13) / suit-directive-set-dependency-index: / 2630 00 # unsigned(0) 2631 14 # unsigned(20) / suit-directive-override-parameters: / 2632 A1 # map(1) 2633 15 # unsigned(21) / suit-parameter-uri: / 2634 78 3D # text(61) 2635 68747470733A2F2F6578616D706C652E6F72672F38643832353733612D393236642D343735342D393335332D3332646332393939376637342E73756974 # "https://example.org/8d82573a-926d-4754-9353-32dc29997f74.suit" 2636 15 # unsigned(21) / suit-directive-fetch: / 2637 02 # unsigned(2) 2638 03 # unsigned(3) / suit-condition-image-match: / 2639 0F # unsigned(15) 2640 09 # unsigned(9) / suit-install: / 2641 58 2F # bytes(47) 2642 8C # array(12) 2643 0D # unsigned(13) / suit-directive-set-dependency-index: / 2644 00 # unsigned(0) 2645 12 # unsigned(18) / suit-directive-process-dependency: / 2646 00 # unsigned(0) 2647 0C # unsigned(12) / suit-directive-set-component-index: / 2648 00 # unsigned(0) 2649 14 # unsigned(20) / suit-directive-override-parameters: / 2650 A1 # map(1) 2651 15 # unsigned(21) / suit-parameter-uri: / 2652 78 1F # text(31) 2653 68747470733A2F2F6578616D706C652E6F72672F636F6E6669672E6A736F6E # "https://example.org/config.json" 2654 15 # unsigned(21) / suit-directive-fetch: / 2655 02 # unsigned(2) 2656 03 # unsigned(3) / suit-condition-image-match: / 2657 0F # unsigned(15) 2658 0A # unsigned(10) / suit-validate: / 2659 45 # bytes(5) 2660 84 # array(4) 2661 0C # unsigned(12) / suit-directive-set-component-index: / 2662 00 2663 03 # unsigned(3) / suit-condition-image-match: / 2664 0F # unsigned(15) 2666 CBOR Binary in Hex 2668 D86BA2025873825824822F5820CE596D785169B72712560B3A246AA98F81 2669 4498EA3625EEBB72CED9AF273E7FFD584AD28443A10126A0F65840E9083A 2670 A71D2BFCE48253037B9C3116A5EDF23BE0F4B4357A8A835F724660DA7482 2671 C64345B4C73DE95F05513BD09FC2E58BD2CC865CC851AD797513A9A951A3 2672 CA03590134A6010102030358A7A30181A101822F5820DB601ADE73092B58 2673 532CA03FBB663DE49532435336F1558B49BB622726A2FEDD0281834B5445 2674 45502D4465766963654853656375726546534B636F6E6669672E6A736F6E 2675 045857880C0014A40150C0DDD5F15243566087DB4F5B0AA26C2F0250DB42 2676 F7093D8C55BAA8C5265FC5820F4E035824822F5820AAABCCCDEEEF000122 2677 23444566678889ABBBCDDDEFFF011123334555677789990E1840010F020F 2678 075849880D0014A115783D68747470733A2F2F6578616D706C652E6F7267 2679 2F38643832353733612D393236642D343735342D393335332D3332646332 2680 393939376637342E737569741502030F09582F8C0D0012000C0014A11578 2681 1F68747470733A2F2F6578616D706C652E6F72672F636F6E6669672E6A73 2682 6F6E1502030F0A45840C00030F 2684 E.4. Example 4: Unlink a Trusted Component 2686 CBOR Diagnostic Notation of SUIT Manifest 2687 / SUIT_Envelope_Tagged / 107( { 2688 / suit-authentication-wrapper / 2: << [ 2689 << [ 2690 / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, 2691 / suit-digest-bytes: / h'632454F19A9440A5B83493628A7EF8704C8A0205A62C34E425BAA34C71341F42' 2692 ] >>, 2693 << / COSE_Sign1_Tagged / 18( [ 2694 / protected / << { 2695 / algorithm-id / 1: -7 / ES256 / 2696 } >>, 2697 / unprotected: / {}, 2698 / payload: / null, 2699 / signature: / h'A32CDB7C1D089C27408CED3C79087220EB0D77F105BB5330912875F4D94AD108D7658C650463AEB7E1CCA5084F22B2F3993176E8B3529A3202ED735E4D39BBBF' 2700 ] ) >> 2701 ] >>, 2702 / suit-manifest / 3: << { 2703 / suit-manifest-version / 1: 1, 2704 / suit-manifest-sequence-number / 2: 18446744073709551615 / UINT64_MAX /, 2705 / suit-common / 3: << { 2706 / suit-components / 2: [ 2707 [ 2708 h'544545502D446576696365', / "TEEP-Device" / 2709 h'5365637572654653', / "SecureFS" / 2710 h'8D82573A926D4754935332DC29997F74', / tc-uuid / 2711 h'7461' / "ta" / 2712 ] 2713 ], 2714 / suit-common-sequence / 4: << [ 2715 / suit-directive-override-parameters / 20, { 2716 / suit-parameter-vendor-identifier / 1: h'C0DDD5F15243566087DB4F5B0AA26C2F', 2717 / suit-parameter-class-identifier / 2: h'DB42F7093D8C55BAA8C5265FC5820F4E' 2718 }, 2719 / suit-condition-vendor-identifier / 1, 15, 2720 / suit-condition-class-identifier / 2, 15 2721 ] >> 2722 } >>, 2723 / suit-install / 9: << [ 2724 / suit-directive-set-component-index: / 12, 0, 2725 / suit-directive-unlink: / 33, 0 2726 ] >> 2727 } >> 2728 } ) 2730 CBOR Binary Representation 2731 D8 6B # tag(107) / SUIT_Envelope_Tagged / 2732 A2 # map(2) 2733 02 # unsigned(2) / suit-authentication-wrapper / 2734 58 73 # bytes(115) 2735 82 # array(2) 2736 58 24 # bytes(36) 2737 82 # array(2) 2738 2F # negative(15) / -16 = suit-cose-alg-sha256 / 2739 58 20 # bytes(32) 2740 632454F19A9440A5B83493628A7EF8704C8A0205A62C34E425BAA34C71341F42 2741 58 4A # bytes(74) 2742 D2 # tag(18) / COSE_Sign1_Tagged / 2743 84 # array(4) 2744 43 # bytes(3) 2745 A1 # map(1) 2746 01 # unsigned(1) / algorithm-id / 2747 26 # negative(6) / -7 = ES256 / 2748 A0 # map(0) 2749 F6 # primitive(22) / null / 2750 58 40 # bytes(64) 2751 A32CDB7C1D089C27408CED3C79087220EB0D77F105BB5330912875F4D94AD108D7658C650463AEB7E1CCA5084F22B2F3993176E8B3529A3202ED735E4D39BBBF 2752 03 # unsigned(3) / suit-manifest: / 2753 58 73 # bytes(115) 2754 A4 # map(4) 2755 01 # unsigned(1) / suit-manifest-version: / 2756 01 # unsigned(1) 2757 02 # unsigned(2) / suit-manifest-sequence-number: / 2758 1B FFFFFFFFFFFFFFFF # unsigned(18446744073709551615) 2759 03 # unsigned(3) / suit-common: / 2760 58 5B # bytes(91) 2761 A2 # map(2) 2762 02 # unsigned(2) / suit-components: / 2763 81 # array(1) 2764 84 # array(4) 2765 4B # bytes(11) 2766 544545502D446576696365 # "TEEP-Device" 2767 48 # bytes(8) 2768 5365637572654653 # "SecureFS" 2769 50 # bytes(16) 2770 8D82573A926D4754935332DC29997F74 # tc-uuid 2771 42 # bytes(2) 2772 7461 # "ta" 2773 04 # unsigned(4) / suit-common-sequence: / 2774 58 2B # bytes(84) 2775 86 # array(6) 2776 14 # unsigned(20) / suit-directive-override-parameters: / 2777 A2 # map(2) 2778 01 # unsigned(1) / suit-parameter-vendor-identifier: / 2779 50 # bytes(16) 2780 C0DDD5F15243566087DB4F5B0AA26C2F 2781 02 # unsigned(2) / suit-parameter-class-identifier: / 2782 50 # bytes(16) 2783 DB42F7093D8C55BAA8C5265FC5820F4E 2784 01 # unsigned(1) / suit-condition-vendor-identifier: / 2785 0F # unsigned(15) 2786 02 # unsigned(2) / suit-condition-class-identifier: / 2787 0F # unsigned(15) 2788 09 # unsigned(9) / suit-install: / 2789 46 # bytes(6) 2790 84 # array(4) 2791 0C # unsigned(12) / suit-directive-set-component-index: / 2792 00 # unsigned(0) 2793 18 21 # unsigned(33) / suit-directive-unlink: / 2794 00 # unsigned(0) 2796 CBOR Binary in Hex 2798 D86BA2025873825824822F5820632454F19A9440A5B83493628A7EF8704C 2799 8A0205A62C34E425BAA34C71341F42584AD28443A10126A0F65840A32CDB 2800 7C1D089C27408CED3C79087220EB0D77F105BB5330912875F4D94AD108D7 2801 658C650463AEB7E1CCA5084F22B2F3993176E8B3529A3202ED735E4D39BB 2802 BF035873A40101021BFFFFFFFFFFFFFFFF03585BA20281844B544545502D 2803 446576696365485365637572654653508D82573A926D4754935332DC2999 2804 7F7442746104582B8614A20150C0DDD5F15243566087DB4F5B0AA26C2F02 2805 50DB42F7093D8C55BAA8C5265FC5820F4E010F020F0946840C00182100 2807 F. Examples of SUIT Reports 2809 This section shows some examples of SUIT reports. 2811 F.1. Example 1: Success 2813 SUIT Reports have no records if no conditions have failed. The URI 2814 in this example is the reference URI provided in the SUIT manifest. 2816 { 2817 / suit-report-manifest-digest / 1:<<[ 2818 / algorithm-id / -16 / "sha256" /, 2819 / digest-bytes / h'a7fd6593eac32eb4be578278e6540c5c' 2820 h'09cfd7d4d234973054833b2b93030609' 2821 ]>>, 2822 / suit-report-manifest-uri / 2: "tam.teep.example/personalisation.suit", 2823 / suit-report-records / 4: [] 2824 } 2825 F.2. Example 2: Faiure 2827 { 2828 / suit-report-manifest-digest / 1:<<[ 2829 / algorithm-id / -16 / "sha256" /, 2830 / digest-bytes / h'a7fd6593eac32eb4be578278e6540c5c09cfd7d4d234973054833b2b93030609' 2831 ]>>, 2832 / suit-report-manifest-uri / 2: "tam.teep.example/personalisation.suit", 2833 / suit-report-records / 4: [ 2834 { 2835 / suit-record-manifest-id / 1:[], 2836 / suit-record-manifest-section / 2: 7 / dependency-resolution /, 2837 / suit-record-section-offset / 3: 66, 2838 / suit-record-dependency-index / 5: 0, 2839 / suit-record-failure-reason / 6: 404 2840 } 2841 ] 2842 } 2844 where the dependency-resolution refers to: 2846 107({ 2847 authentication-wrapper, 2848 / manifest / 3:<<{ 2849 / manifest-version / 1:1, 2850 / manifest-sequence-number / 2:3, 2851 common, 2852 dependency-resolution, 2853 install, 2854 validate, 2855 run, 2856 text 2857 }>>, 2858 }) 2860 and the suit-record-section-offset refers to: 2862 <<[ 2863 / directive-set-dependency-index / 13,0 , 2864 / directive-set-parameters / 19,{ 2865 / uri / 21:'tam.teep.example/' 2866 'edd94cd8-9d9c-4cc8-9216-b3ad5a2d5b8a.suit', 2867 } , 2868 / directive-fetch / 21,2 , 2869 / condition-image-match / 3,15 2870 ]>>, 2872 Authors' Addresses 2874 Hannes Tschofenig 2875 Arm Ltd. 2876 6067 Absam 2877 Austria 2878 Email: hannes.tschofenig@arm.com 2880 Mingliang Pei 2881 Broadcom 2882 350 Ellis St 2883 Mountain View, CA 94043 2884 United States of America 2885 Email: mingliang.pei@broadcom.com 2887 David Wheeler 2888 Amazon 2889 United States of America 2890 Email: davewhee@amazon.com 2892 Dave Thaler 2893 Microsoft 2894 United States of America 2895 Email: dthaler@microsoft.com 2897 Akira Tsukamoto 2898 AIST 2899 Japan 2900 Email: akira.tsukamoto@aist.go.jp