idnits 2.17.1 draft-ietf-teep-protocol-05.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 4 instances of too long lines in the document, the longest one being 2 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 (February 22, 2021) is 1158 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) == Missing Reference: 'CDDL' is mentioned on line 668, but not defined == Unused Reference: 'I-D.birkholz-rats-suit-claims' is defined on line 1145, but no explicit reference was found in the text == Unused Reference: 'RFC8126' is defined on line 1157, but no explicit reference was found in the text == Outdated reference: A later version (-22) exists of draft-ietf-rats-architecture-08 ** 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-06 == Outdated reference: A later version (-01) exists of draft-moran-suit-report-00 ** Downref: Normative reference to an Informational draft: draft-moran-suit-report (ref. 'I-D.moran-suit-report') ** Obsolete normative reference: RFC 2560 (Obsoleted by RFC 6960) ** 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 (-03) exists of draft-birkholz-rats-suit-claims-01 == Outdated reference: A later version (-19) exists of draft-ietf-teep-architecture-13 Summary: 6 errors (**), 0 flaws (~~), 9 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: August 26, 2021 Broadcom 6 D. Wheeler 7 Intel 8 D. Thaler 9 Microsoft 10 A. Tsukamoto 11 AIST 12 February 22, 2021 14 Trusted Execution Environment Provisioning (TEEP) Protocol 15 draft-ietf-teep-protocol-05 17 Abstract 19 This document specifies a protocol that installs, updates, and 20 deletes Trusted Applications (TAs) in a device with a Trusted 21 Execution Environment (TEE). This specification defines an 22 interoperable protocol for managing the lifecycle of TAs. 24 The protocol name is pronounced teepee. This conjures an image of a 25 wedge-shaped protective covering for one's belongings, which sort of 26 matches the intent of this protocol. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on August 26, 2021. 45 Copyright Notice 47 Copyright (c) 2021 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3. Message Overview . . . . . . . . . . . . . . . . . . . . . . 4 65 4. Detailed Messages Specification . . . . . . . . . . . . . . . 5 66 4.1. Creating and Validating TEEP Messages . . . . . . . . . . 6 67 4.1.1. Creating a TEEP message . . . . . . . . . . . . . . . 6 68 4.1.2. Validating a TEEP Message . . . . . . . . . . . . . . 6 69 4.2. QueryRequest Message . . . . . . . . . . . . . . . . . . 7 70 4.3. QueryResponse Message . . . . . . . . . . . . . . . . . . 9 71 4.3.1. Evidence . . . . . . . . . . . . . . . . . . . . . . 12 72 4.4. Update Message . . . . . . . . . . . . . . . . . . . . . 13 73 4.5. Success Message . . . . . . . . . . . . . . . . . . . . . 14 74 4.6. Error Message . . . . . . . . . . . . . . . . . . . . . . 15 75 5. Mapping of TEEP Message Parameters to CBOR Labels . . . . . . 18 76 6. Behavior Specification . . . . . . . . . . . . . . . . . . . 19 77 6.1. TAM Behavior . . . . . . . . . . . . . . . . . . . . . . 19 78 6.2. TEEP Agent Behavior . . . . . . . . . . . . . . . . . . . 20 79 7. Ciphersuites . . . . . . . . . . . . . . . . . . . . . . . . 21 80 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 81 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 82 9.1. Media Type Registration . . . . . . . . . . . . . . . . . 23 83 9.2. Ciphersuite Registry . . . . . . . . . . . . . . . . . . 24 84 9.3. CBOR Tag Registry . . . . . . . . . . . . . . . . . . . . 24 85 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 86 10.1. Normative References . . . . . . . . . . . . . . . . . . 25 87 10.2. Informative References . . . . . . . . . . . . . . . . . 26 88 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 26 89 B. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27 90 C. Complete CDDL . . . . . . . . . . . . . . . . . . . . . . . . 27 91 D. Examples of Diagnostic Notation and Binary Representation . . 30 92 D.1. Some assumptions in examples . . . . . . . . . . . . . . 30 93 D.2. QueryRequest Message . . . . . . . . . . . . . . . . . . 31 94 D.2.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 31 95 D.2.2. CBOR Binary Representation . . . . . . . . . . . . . 31 96 D.3. Entity Attestation Token . . . . . . . . . . . . . . . . 31 97 D.3.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 32 98 D.4. QueryResponse Message . . . . . . . . . . . . . . . . . . 32 99 D.4.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 32 100 D.4.2. CBOR Binary Representation . . . . . . . . . . . . . 33 101 D.5. Update Message . . . . . . . . . . . . . . . . . . . . . 34 102 D.5.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 34 103 D.5.2. CBOR Binary Representation . . . . . . . . . . . . . 35 104 D.6. Success Message . . . . . . . . . . . . . . . . . . . . . 35 105 D.6.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 35 106 D.6.2. CBOR Binary Representation . . . . . . . . . . . . . 35 107 D.7. Error Message . . . . . . . . . . . . . . . . . . . . . . 35 108 D.7.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 35 109 D.7.2. CBOR binary Representation . . . . . . . . . . . . . 36 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 112 1. Introduction 114 The Trusted Execution Environment (TEE) concept has been designed to 115 separate a regular operating system, also referred as a Rich 116 Execution Environment (REE), from security-sensitive applications. 117 In a TEE ecosystem, device vendors may use different operating 118 systems in the REE and may use different types of TEEs. When TA 119 Developers or Device Administrators use Trusted Application Managers 120 (TAMs) to install, update, and delete Trusted Applications (TAs) on a 121 wide range of devices with potentially different TEEs then an 122 interoperability need arises. 124 This document specifies the protocol for communicating between a TAM 125 and a TEEP Agent. 127 The Trusted Execution Environment Provisioning (TEEP) architecture 128 document [I-D.ietf-teep-architecture] provides design guidance and 129 introduces the necessary terminology. 131 2. Terminology 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL" in this document are to be interpreted as described in 136 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 137 capitals, as shown here. 139 This specification re-uses the terminology defined in 140 [I-D.ietf-teep-architecture]. 142 As explained in Section 4.4 of that document, the TEEP protocol 143 treats each TA, any dependencies the TA has, and personalization data 144 as separate components that are expressed in SUIT manifests, and a 145 SUIT manifest might contain or reference multiple binaries (see 146 [I-D.ietf-suit-manifest] for more details). 148 As such, the term Trusted Component in this document refers to a set 149 of binaries expressed in a SUIT manifest, to be installed in a TEE. 150 Note that a Trusted Component may include one or more TAs and/or 151 configuration data and keys needed by a TA to operate correctly. 153 Each Trusted Component is uniquely identified by a SUIT Component 154 Identifier (see [I-D.ietf-suit-manifest] Section 8.7.2.2). 156 3. Message Overview 158 The TEEP protocol consists of messages exchanged between a TAM and a 159 TEEP Agent. The messages are encoded in CBOR and designed to provide 160 end-to-end security. TEEP protocol messages are signed by the 161 endpoints, i.e., the TAM and the TEEP Agent, but Trusted Applications 162 may also be encrypted and signed by a TA Developer or Device 163 Administrator. The TEEP protocol not only uses CBOR but also the 164 respective security wrapper, namely COSE [RFC8152]. Furthermore, for 165 software updates the SUIT manifest format [I-D.ietf-suit-manifest] is 166 used, and for attestation the Entity Attestation Token (EAT) 167 [I-D.ietf-rats-eat] format is supported although other attestation 168 formats are also permitted. 170 This specification defines five messages. 172 A TAM queries a device's current state with a QueryRequest message. 173 A TEEP Agent will, after authenticating and authorizing the request, 174 report attestation information, list all Trusted Components, and 175 provide information about supported algorithms and extensions in a 176 QueryResponse message. An error message is returned if the request 177 could not be processed. A TAM will process the QueryResponse message 178 and determine whether to initiate subsequent message exchanges to 179 install, update, or delete Trusted Applications. 181 +------------+ +-------------+ 182 | TAM | |TEEP Agent | 183 +------------+ +-------------+ 185 QueryRequest -------> 187 QueryResponse 189 <------- or 191 Error 193 With the Update message a TAM can instruct a TEEP Agent to install 194 and/or delete one or more Trusted Components. The TEEP Agent will 195 process the message, determine whether the TAM is authorized and 196 whether the Trusted Component has been signed by an authorized TA 197 Signer. A Success message is returned when the operation has been 198 completed successfully, or an Error message otherwise. 200 +------------+ +-------------+ 201 | TAM | |TEEP Agent | 202 +------------+ +-------------+ 204 Update ----> 206 Success 208 <---- or 210 Error 212 4. Detailed Messages Specification 214 TEEP messages are protected by the COSE_Sign1 structure. The TEEP 215 protocol messages are described in CDDL format [RFC8610] below. 217 { 218 teep-message => (query-request / 219 query-response / 220 update / 221 teep-success / 222 teep-error ), 223 } 225 4.1. Creating and Validating TEEP Messages 227 4.1.1. Creating a TEEP message 229 To create a TEEP message, the following steps are performed. 231 1. Create a TEEP message according to the description below and 232 populate it with the respective content. 234 2. Create a COSE Header containing the desired set of Header 235 Parameters. The COSE Header MUST be valid per the [RFC8152] 236 specification. 238 3. Create a COSE_Sign1 object using the TEEP message as the 239 COSE_Sign1 Payload; all steps specified in [RFC8152] for creating 240 a COSE_Sign1 object MUST be followed. 242 4. Prepend the COSE object with the TEEP CBOR tag to indicate that 243 the CBOR-encoded message is indeed a TEEP message. 245 4.1.2. Validating a TEEP Message 247 When TEEP message is received (see the ProcessTeepMessage conceptual 248 API defined in [I-D.ietf-teep-architecture] section 6.2.1), the 249 following validation steps are performed. If any of the listed steps 250 fail, then the TEEP message MUST be rejected. 252 1. Verify that the received message is a valid CBOR object. 254 2. Remove the TEEP message CBOR tag and verify that one of the COSE 255 CBOR tags follows it. 257 3. Verify that the message contains a COSE_Sign1 structure. 259 4. Verify that the resulting COSE Header includes only parameters 260 and values whose syntax and semantics are both understood and 261 supported or that are specified as being ignored when not 262 understood. 264 5. Follow the steps specified in Section 4 of [RFC8152] ("Signing 265 Objects") for validating a COSE_Sign1 object. The COSE_Sign1 266 payload is the content of the TEEP message. 268 6. Verify that the TEEP message is a valid CBOR map and verify the 269 fields of the TEEP message according to this specification. 271 4.2. QueryRequest Message 273 A QueryRequest message is used by the TAM to learn information from 274 the TEEP Agent, such as the features supported by the TEEP Agent, 275 including ciphersuites, and protocol versions. Additionally, the TAM 276 can selectively request data items from the TEEP Agent via the 277 request parameter. Currently, the following features are supported: 279 o Request for attestation information, 281 o Listing supported extensions, 283 o Querying installed Trusted Components, and 285 o Listing supporting SUIT commands. 287 Like other TEEP messages, the QueryRequest message is signed, and the 288 relevant CDDL snippet is shown below. The complete CDDL structure is 289 shown in [CDDL]. 291 query-request = [ 292 type: TEEP-TYPE-query-request, 293 options: { 294 ? token => bstr .size (8..64), 295 ? supported-cipher-suites => [ + suite ], 296 ? challenge => bstr .size (8..64), 297 ? versions => [ + version ], 298 ? ocsp-data => bstr, 299 * $$query-request-extensions 300 * $$teep-option-extensions 301 }, 302 data-item-requested: data-item-requested 303 ] 305 The message has the following fields: 307 type 308 The value of (1) corresponds to a QueryRequest message sent from 309 the TAM to the TEEP Agent. 311 token 312 The value in the token parameter is used to match responses to 313 requests. This is particularly useful when a TAM issues multiple 314 concurrent requests to a TEEP Agent. The token is not needed when 315 the attestation bit is set in the data-item-requested value. The 316 size of the token is at least 8 bytes (64 bits) and maximum of 64 317 bytes, which is the same as in an EAT Nonce Claim (see 318 [I-D.ietf-rats-eat] Section 3.3). The first usage of a token 319 generated by a TAM MUST be randomly created. Subsequent token 320 values MUST be different for each request message to distinguish 321 the correct response from multiple requests. The token value MUST 322 NOT be used for other purposes, such as a TAM to identify the 323 devices and/or a device to identify TAMs or Trusted Components. 324 The TAM MUST expire the token value after receiving the first 325 responce from the device and ignore any subsequent messages that 326 have the same token value. 328 data-item-requested 329 The data-item-requested parameter indicates what information the 330 TAM requests from the TEEP Agent in the form of a bitmap. Each 331 value in the bitmap corresponds to an IANA registered information 332 element. This specification defines the following initial set of 333 information elements: 335 attestation (1) With this value the TAM requests the TEEP Agent 336 to return attestation evidence (e.g., an EAT) in the response. 338 trusted-components (2) With this value the TAM queries the TEEP 339 Agent for all installed Trusted Components. 341 extensions (4) With this value the TAM queries the TEEP Agent for 342 supported capabilities and extensions, which allows a TAM to 343 discover the capabilities of a TEEP Agent implementation. 345 suit-commands (8) With this value the TAM queries the TEEP Agent 346 for supported commands offered by the SUIT manifest 347 implementation. 349 Further values may be added in the future via IANA registration. 351 supported-cipher-suites 352 The supported-cipher-suites parameter lists the ciphersuite(s) 353 supported by the TAM. If this parameter is not present, it is to 354 be treated the same as if it contained both ciphersuites defined 355 in this document. Details about the ciphersuite encoding can be 356 found in Section 7. 358 challenge 359 The challenge field is an optional parameter used for ensuring the 360 refreshness of the attestation evidence returned with a 361 QueryResponse message. When a challenge is provided in the 362 QueryRequest and an EAT is returned with the QueryResponse message 363 then the challenge contained in this request MUST be copied into 364 the nonce claim found in the EAT. If any format other than EAT is 365 used, it is up to that format to define the use of the challenge 366 field. 368 versions 369 The versions parameter enumerates the TEEP protocol version(s) 370 supported by the TAM A value of 0 refers to the current version of 371 the TEEP protocol. If this field is not present, it is to be 372 treated the same as if it contained only version 0. 374 ocsp-data 375 The ocsp-data parameter contains a list of OCSP stapling data 376 respectively for the TAM certificate and each of the CA 377 certificates up to the root certificate. The TAM provides OCSP 378 data so that the TEEP Agent can validate the status of the TAM 379 certificate chain without making its own external OCSP service 380 call. OCSP data MUST be conveyed as a DER-encoded OCSP response 381 (using the ASN.1 type OCSPResponse defined in [RFC2560]). The use 382 of OCSP is OPTIONAL to implement for both the TAM and the TEEP 383 Agent. A TAM can query the TEEP Agent for the support of this 384 functionality via the capability discovery exchange, as described 385 above. 387 4.3. QueryResponse Message 389 The QueryResponse message is the successful response by the TEEP 390 Agent after receiving a QueryRequest message. 392 Like other TEEP messages, the QueryResponse message is signed, and 393 the relevant CDDL snippet is shown below. The complete CDDL 394 structure is shown in [CDDL]. 396 query-response = [ 397 type: TEEP-TYPE-query-response, 398 options: { 399 ? token => bstr .size (8..64), 400 ? selected-cipher-suite => suite, 401 ? selected-version => version, 402 ? evidence-format => text, 403 ? evidence => bstr, 404 ? tc-list => [ + tc-info ], 405 ? requested-tc-list => [ + requested-tc-info ], 406 ? unneeded-tc-list => [ + SUIT_Component_Identifier ], 407 ? ext-list => [ + ext-info ], 408 * $$query-response-extensions, 409 * $$teep-option-extensions 410 } 411 ] 413 tc-info = { 414 component-id => SUIT_Component_Identifier, 415 ? tc-manifest-sequence-number => .within uint .size 8 416 } 418 requested-tc-info = { 419 component-id => SUIT_Component_Identifier, 420 ? tc-manifest-sequence-number => .within uint .size 8 421 ? have-binary => bool 422 } 424 The QueryResponse message has the following fields: 426 type 427 The value of (2) corresponds to a QueryResponse message sent from 428 the TEEP Agent to the TAM. 430 token 431 The value in the token parameter is used to match responses to 432 requests. The value MUST correspond to the value received with 433 the QueryRequest message if one was present, and MUST be absent if 434 no token was present in the QueryRequest. 436 selected-cipher-suite 437 The selected-cipher-suite parameter indicates the selected 438 ciphersuite. Details about the ciphersuite encoding can be found 439 in Section 7. 441 selected-version 442 The selected-version parameter indicates the TEEP protocol version 443 selected by the TEEP Agent. The absense of this parameter 444 indicates the same as if it was present with a value of 0. 446 evidence-format 447 The evidence-format parameter indicates the IANA Media Type of the 448 attestation evidence contained in the evidence parameter. It MUST 449 be present if the evidence parameter is present and the format is 450 not an EAT. 452 evidence 453 The evidence parameter contains the attestation evidence. This 454 parameter MUST be present if the QueryResponse is sent in response 455 to a QueryRequest with the attestation bit set. If the evidence- 456 format parameter is absent, the attestation evidence contained in 457 this parameter MUST be an Entity Attestation Token following the 458 encoding defined in [I-D.ietf-rats-eat]. See Section 4.3.1 for 459 further discussion. 461 tc-list 462 The tc-list parameter enumerates the Trusted Components installed 463 on the device in the form of tc-info objects. This parameter MUST 464 be present if the QueryResponse is sent in response to a 465 QueryRequest with the trusted-components bit set. 467 requested-tc-list 468 The requested-tc-list parameter enumerates the Trusted Components 469 that are not currently installed in the TEE, but which are 470 requested to be installed, for example by an installer of an 471 Untrusted Application that has a TA as a dependency, or by a 472 Trusted Application that has another Trusted Component as a 473 dependency. Requested Trusted Components are expressed in the 474 form of requested-tc-info objects. A TEEP Agent can get this 475 information from the UnrequestTA conceptual API defined in 476 [I-D.ietf-teep-architecture] section 6.2.1. 478 unneeded-tc-list 479 The unneeded-tc-list parameter enumerates the Trusted Components 480 that are currently installed in the TEE, but which are no longer 481 needed by any other application. The TAM can use this information 482 in determining whether a Trusted Component can be deleted. Each 483 unneeded Trusted Component is identified by its SUIT Component 484 Identifier. A TEEP Agent can get this information from the 485 UnrequestTA conceptual API defined in [I-D.ietf-teep-architecture] 486 section 6.2.1. 488 ext-list 489 The ext-list parameter lists the supported extensions. This 490 document does not define any extensions. 492 The tc-info object has the following fields: 494 component-id 495 A SUIT Component Identifier. 497 tc-manifest-sequence-number 498 The suit-manifest-sequence-number value from the SUIT manifest for 499 the Trusted Component, if a SUIT manifest was used. 501 The requested-tc-info message has the following fields: 503 component-id 504 A SUIT Component Identifier. 506 tc-manifest-sequence-number 507 The minimum suit-manifest-sequence-number value from a SUIT 508 manifest for the Trusted Component. If not present, indicates 509 that any version will do. 511 have-binary 512 If present with a value of true, indicates that the TEEP agent 513 already has the Trusted Component binary and only needs an Update 514 message with a SUIT manifest that authorizes installing it. If 515 have-binary is true, the tc-manifest-sequence-number field MUST be 516 present. 518 4.3.1. Evidence 520 Section 7.1 of [I-D.ietf-teep-architecture] lists information that 521 may be required in the evidence depend on the circumstance. When an 522 Entity Attestation Token is used, the following claims can be used to 523 meet those requirements: 525 +------------+---------------------+--------------------------------+ 526 | Requiremen | Claim | Reference | 527 | t | | | 528 +------------+---------------------+--------------------------------+ 529 | Device | device-identifier | [I-D.birkholz-rats-suit-claims | 530 | unique | | ] section 3.1.3 | 531 | identifier | | | 532 | Vendor of | vendor-identifier | [I-D.birkholz-rats-suit-claims | 533 | the device | | ] section 3.1.1 | 534 | Class of | class-identifier | [I-D.birkholz-rats-suit-claims | 535 | the device | | ] section 3.1.2 | 536 | TEE | chip-version-scheme | [I-D.ietf-rats-eat] section | 537 | hardware | | 3.7 | 538 | type | | | 539 | TEE | chip-version-scheme | [I-D.ietf-rats-eat] section | 540 | hardware | | 3.7 | 541 | version | | | 542 | TEE | component- | [I-D.birkholz-rats-suit-claims | 543 | firmware | identifier | ] section 3.1.4 | 544 | type | | | 545 | TEE | version | [I-D.birkholz-rats-suit-claims | 546 | firmware | | ] section 3.1.8 | 547 | version | | | 548 | Freshness | nonce | [I-D.ietf-rats-eat] section | 549 | proof | | 3.3 | 550 +------------+---------------------+--------------------------------+ 552 4.4. Update Message 554 The Update message is used by the TAM to install and/or delete one or 555 more Trusted Components via the TEEP Agent. 557 Like other TEEP messages, the Update message is signed, and the 558 relevant CDDL snippet is shown below. The complete CDDL structure is 559 shown in [CDDL]. 561 update = [ 562 type: TEEP-TYPE-update, 563 options: { 564 ? token => bstr .size (8..64), 565 ? manifest-list => [ + bstr .cbor SUIT_Envelope ], 566 * $$update-extensions, 567 * $$teep-option-extensions 568 } 569 ] 571 The Update message has the following fields: 573 type 574 The value of (3) corresponds to an Update message sent from the 575 TAM to the TEEP Agent. In case of successful processing, a 576 Success message is returned by the TEEP Agent. In case of an 577 error, an Error message is returned. Note that the Update message 578 is used for initial Trusted Component installation as well as for 579 updates and deletes. 581 token 582 The value in the token field is used to match responses to 583 requests. 585 manifest-list 586 The manifest-list field is used to convey one or multiple SUIT 587 manifests to install. A manifest is a bundle of metadata about a 588 TA, such as where to find the code, the devices to which it 589 applies, and cryptographic information protecting the manifest. 590 The manifest may also convey personalization data. TA binaries 591 and personalization data can be signed and encrypted by the same 592 TA Signer. Other combinations are, however, possible as well. 593 For example, it is also possible for the TAM to sign and encrypt 594 the personalization data and to let the TA Developer sign and/or 595 encrypt the TA binary. 597 Note that an Update message carrying one or more SUIT manifests will 598 inherently involve multiple signatures, one by the TAM in the TEEP 599 message and one from a Trusted Component signer inside each manifest. 600 This is intentional as they are for different purposes. 602 The TAM is what authorizes apps to be installed, updated, and deleted 603 on a given TEE and so the TEEP signature is checked by the TEEP Agent 604 at protocol message processing time. (This same TEEP security 605 wrapper is also used on messages like QueryRequest so that Agents 606 only send potentially sensitive data such as evidence to trusted 607 TAMs.) 609 The Trusted Component signer on the other hand is what authorizes the 610 Trusted Component to actually run, so the manifest signature could be 611 checked at install time or load (or run) time or both, and this 612 checking is done by the TEE independent of whether TEEP is used or 613 some other update mechanism. See section 5 of 614 [I-D.ietf-teep-architecture] for further discussion. 616 4.5. Success Message 618 The Success message is used by the TEEP Agent to return a success in 619 response to an Update message. 621 Like other TEEP messages, the Success message is signed, and the 622 relevant CDDL snippet is shown below. The complete CDDL structure is 623 shown in [CDDL]. 625 teep-success = [ 626 type: TEEP-TYPE-teep-success, 627 options: { 628 ? token => bstr .size (8..64), 629 ? msg => text .size (1..128), 630 ? suit-reports => [ + suit-report ], 631 * $$teep-success-extensions, 632 * $$teep-option-extensions 633 } 634 ] 636 The Success message has the following fields: 638 type 639 The value of (5) corresponds to corresponds to a Success message 640 sent from the TEEP Agent to the TAM. 642 token 643 The value in the token parameter is used to match responses to 644 requests. It MUST match the value of the token parameter in the 645 Update message the Success is in response to, if one was present. 646 If none was present, the token MUST be absent in the Success 647 message. 649 msg 650 The msg parameter contains optional diagnostics information 651 encoded in UTF-8 [RFC3629] using Net-Unicode form [RFC5198] with 652 max 128 bytes returned by the TEEP Agent. 654 suit-reports 655 If present, the suit-reports parameter contains a set of SUIT 656 Reports as defined in Section 4 of [I-D.moran-suit-report]. If 657 the suit-report-nonce field is present in the SUIT Report, is 658 value MUST match the value of the token parameter in the Update 659 message the Success message is in response to. 661 4.6. Error Message 663 The Error message is used by the TEEP Agent to return an error in 664 response to an Update message. 666 Like other TEEP messages, the Error message is signed, and the 667 relevant CDDL snippet is shown below. The complete CDDL structure is 668 shown in [CDDL]. 670 teep-error = [ 671 type: TEEP-TYPE-teep-error, 672 options: { 673 ? token => bstr .size (8..64), 674 ? err-msg => text .size (1..128), 675 ? supported-cipher-suites => [ + suite ], 676 ? versions => [ + version ], 677 ? suit-reports => [ + suit-report ], 678 * $$teep-error-extensions, 679 * $$teep-option-extensions 680 }, 681 err-code: uint (0..23) 682 ] 684 The Error message has the following fields: 686 type 687 The value of (6) corresponds to an Error message sent from the 688 TEEP Agent to the TAM. 690 token 691 The value in the token parameter is used to match responses to 692 requests. It MUST match the value of the token parameter in the 693 Update message the Success is in response to, if one was present. 694 If none was present, the token MUST be absent in the Error 695 message. 697 err-msg 698 The err-msg parameter is human-readable diagnostic text that MUST 699 be encoded using UTF-8 [RFC3629] using Net-Unicode form [RFC5198] 700 with max 128 bytes. 702 supported-cipher-suites 703 The supported-cipher-suites parameter lists the ciphersuite(s) 704 supported by the TEEP Agent. Details about the ciphersuite 705 encoding can be found in Section 7. This field is optional but 706 MUST be returned with the ERR_UNSUPPORTED_CRYPTO_ALG error 707 message. 709 versions 710 The versions parameter enumerates the TEEP protocol version(s) 711 supported by the TEEP Agent. This otherwise optional parameter 712 MUST be returned with the ERR_UNSUPPORTED_MSG_VERSION error 713 message. 715 suit-reports 716 If present, the suit-reports parameter contains a set of SUIT 717 Reports as defined in Section 4 of [I-D.moran-suit-report]. If 718 the suit-report-nonce field is present in the SUIT Report, is 719 value MUST match the value of the token parameter in the Update 720 message the Error message is in response to. 722 err-code 723 The err-code parameter contains one of the error codes listed 724 below). Only selected values are applicable to each message. 726 This specification defines the following initial error messages: 728 ERR_PERMANENT_ERROR (1) 729 The TEEP request contained incorrect fields or fields that are 730 inconsistent with other fields. For diagnosis purposes it is 731 RECOMMMENDED to identify the failure reason in the error message. 732 A TAM receiving this error might refuse to communicate further 733 with the TEEP Agent for some period of time until it has reason to 734 believe it is worth trying again, but it should take care not to 735 give up on communication when there is no attestation evidence 736 indicating that the error is genuine. In contrast, 737 ERR_TEMPORARY_ERROR is an indication that a more agressive retry 738 is warranted. 740 ERR_UNSUPPORTED_EXTENSION (2) 741 The TEEP Agent does not support an extension included in the 742 request message. For diagnosis purposes it is RECOMMMENDED to 743 identify the unsupported extension in the error message. A TAM 744 receiving this error might retry the request without using 745 extensions. 747 ERR_UNSUPPORTED_MSG_VERSION (4) 748 The TEEP Agent does not support the TEEP protocol version 749 indicated in the request message. A TAM receiving this error 750 might retry the request using a different TEEP protocol version. 752 ERR_UNSUPPORTED_CRYPTO_ALG (5) 753 The TEEP Agent does not support the cryptographic algorithm 754 indicated in the request message. A TAM receiving this error 755 might retry the request using a different cryptographic algorithm. 757 ERR_BAD_CERTIFICATE (6) 758 Processing of a certificate failed. For diagnosis purposes it is 759 RECOMMMENDED to include information about the failing certificate 760 in the error message. For example, the certificate was of an 761 unsupported type, or the certificate was revoked by its signer. A 762 TAM receiving this error might attempt to use an alternate 763 certificate. 765 ERR_CERTIFICATE_EXPIRED (9) 766 A certificate has expired or is not currently valid. A TAM 767 receiving this error might attempt to renew its certificate before 768 using it again. 770 ERR_TEMPORARY_ERROR (10) 771 A miscellaneous temporary error, such as a memory allocation 772 failure, occurred while processing the request message. A TAM 773 receiving this error might retry the same request at a later point 774 in time. 776 ERR_MANIFEST_PROCESSING_FAILED (17) 777 The TEEP Agent encountered one or more manifest processing 778 failures. If the suit-reports parameter is present, it contains 779 the failure details. A TAM receiving this error might still 780 attempt to install or update other components that do not depend 781 on the failed manifest. 783 New error codes should be added sparingly, not for every 784 implementation error. That is the intent of the err-msg field, which 785 can be used to provide details meaningful to humans. New error codes 786 should only be added if the TAM is expected to do something 787 behaviorally different upon receipt of the error message, rather than 788 just logging the event. Hence, each error code is responsible for 789 saying what the behavioral difference is expected to be. 791 5. Mapping of TEEP Message Parameters to CBOR Labels 793 In COSE, arrays and maps use strings, negative integers, and unsigned 794 integers as their keys. Integers are used for compactness of 795 encoding. Since the word "key" is mainly used in its other meaning, 796 as a cryptographic key, this specification uses the term "label" for 797 this usage as a map key. 799 This specification uses the following mapping: 801 +-----------------------------+-------+ 802 | Name | Label | 803 +-----------------------------+-------+ 804 | supported-cipher-suites | 1 | 805 | challenge | 2 | 806 | version | 3 | 807 | ocsp-data | 4 | 808 | selected-cipher-suite | 5 | 809 | selected-version | 6 | 810 | evidence | 7 | 811 | tc-list | 8 | 812 | ext-list | 9 | 813 | manifest-list | 10 | 814 | msg | 11 | 815 | err-msg | 12 | 816 | evidence-format | 13 | 817 | requested-tc-list | 14 | 818 | unneeded-tc-list | 15 | 819 | component-id | 16 | 820 | tc-manifest-sequence-number | 17 | 821 | have-binary | 18 | 822 | suit-reports | 19 | 823 | token | 20 | 824 +-----------------------------+-------+ 826 6. Behavior Specification 828 Behavior is specified in terms of the conceptual APIs defined in 829 section 6.2.1 of [I-D.ietf-teep-architecture]. 831 6.1. TAM Behavior 833 When the ProcessConnect API is invoked, the TAM sends a QueryRequest 834 message. 836 When the ProcessTeepMessage API is invoked, the TAM first does 837 validation as specified in Section 4.1.2, and drops the message if it 838 is not valid. Otherwise, it proceeds as follows. 840 If a QueryResponse message is received that contains evidence, the 841 evidence is passed to an attestation Verifier (see 842 [I-D.ietf-rats-architecture]) to determine whether the Agent is in a 843 trustworthy state. Based on the results of attestation, and the 844 lists of installed, requested, and unneeded Trusted Components 845 reported in the QueryResponse, the TAM determines, in any 846 implementation specific manner, which Trusted Components need to be 847 installed, updated, or deleted, if any. If any Trusted Components 848 need to be installed, updated, or deleted, the TAM sends an Update 849 message containing SUIT Manifests with command sequences to do the 850 relevant installs, updates, or deletes. 852 If a Success or Error message is received, the TAM also validates 853 that the nonce in any SUIT Report matches the token sent in the 854 Update message, and drops the message if it does not match. 855 Otherwise, the TAM handles the update in any implementation specific 856 way, such as updating any locally cached information about the state 857 of the TEEP Agent, or logging the results. 859 If an Error message is received, the TAM can handle it in any 860 implementation specific way, but Section 4.6 provides recommendations 861 for such handling. 863 6.2. TEEP Agent Behavior 865 When the RequestTA API is invoked, the TEEP Agent first checks 866 whether the requested TA is already installed. If it is already 867 installed, the TEEP Agent passes no data back to the caller. 868 Otherwise, if the TEEP Agent chooses to initiate the process of 869 requesting the indicated TA, it determines (in any implementation 870 specific way) the TAM URI based on any TAM URI provided by the 871 RequestTA caller and any local configuration, and passes back the TAM 872 URI to connect to. 874 When the RequestPolicyCheck API is invoked, the TEEP Agent decides 875 whether to initiate communication with any trusted TAMs (e.g., it 876 might choose to do so for a given TAM unless it detects that it has 877 already communicated with that TAM recently). If so, it passes back 878 a TAM URI to connect to. If the TEEP Agent has multiple TAMs it 879 needs to connect with, it just passes back one, with the expectation 880 that RequestPolicyCheck API will be invoked to retrieve each one 881 successively until there are no more and it can pass back no data at 882 that time. Thus, once a TAM URI is returned, the TEEP Agent can 883 remember that it has already initiated communication with that TAM. 885 When the ProcessError API is invoked, the TEEP Agent can handle it in 886 any implementation specific way, such as logging the error or using 887 the information in future choices of TAM URI. 889 When the ProcessTeepMessage API is invoked, the Agent first does 890 validation as specified in Section 4.1.2, and drops the message if it 891 is not valid. Otherwise, processing continues as follows based on 892 the type of message. 894 When a QueryRequest message is received, the Agent responds with a 895 QueryResponse message. 897 When an Update message is received, the Agent attempts to update the 898 Trusted Components specified in the SUIT manifests by following the 899 Update Procedure specified in [I-D.ietf-suit-manifest], and responds 900 with a Success message if all SUIT manifests were successfully 901 installed, or an Error message if any error was encountered. 903 7. Ciphersuites 905 A ciphersuite consists of an AEAD algorithm, an HMAC algorithm, and a 906 signature algorithm. Each ciphersuite is identified with an integer 907 value, which corresponds to an IANA registered ciphersuite (see 908 Section 9.2. This document specifies two ciphersuites. 910 +-------+------------------------------------------------+ 911 | Value | Ciphersuite | 912 +-------+------------------------------------------------+ 913 | 1 | AES-CCM-16-64-128, HMAC 256/256, X25519, EdDSA | 914 | 2 | AES-CCM-16-64-128, HMAC 256/256, P-256, ES256 | 915 +-------+------------------------------------------------+ 917 A TAM MUST support both ciphersuites. A TEEP Agent MUST support at 918 least one of the two but can choose which one. For example, a TEEP 919 Agent might choose ciphersuite 2 if it has hardware support for it. 921 8. Security Considerations 923 This section summarizes the security considerations discussed in this 924 specification: 926 Cryptographic Algorithms 927 TEEP protocol messages exchanged between the TAM and the TEEP 928 Agent are protected using COSE. This specification relies on the 929 cryptographic algorithms provided by COSE. Public key based 930 authentication is used by the TEEP Agent to authenticate the TAM 931 and vice versa. 933 Attestation 934 A TAM can rely on the attestation evidence provided by the TEEP 935 Agent. To sign the attestation evidence, it is necessary for the 936 device to possess a public key (usually in the form of a 937 certificate) along with the corresponding private key. Depending 938 on the properties of the attestation mechanism, it is possible to 939 uniquely identify a device based on information in the attestation 940 evidence or in the certificate used to sign the attestation 941 evidence. This uniqueness may raise privacy concerns. To lower 942 the privacy implications the TEEP Agent MUST present its 943 attestation evidence only to an authenticated and authorized TAM 944 and when using EATS, it SHOULD use encryption as discussed in 946 [I-D.ietf-rats-eat], since confidentiality is not provided by the 947 TEEP protocol itself and the transport protocol under the TEEP 948 protocol might be implemented outside of any TEE. If any 949 mechanism other than EATs is used, it is up to that mechanism to 950 specify how privacy is provided. 952 TA Binaries 953 Each TA binary is signed by a TA Signer. It is the responsibility 954 of the TAM to relay only verified TAs from authorized TA Signers. 955 Delivery of a TA to the TEEP Agent is then the responsibility of 956 the TAM, using the security mechanisms provided by the TEEP 957 protocol. To protect the TA binary, the SUIT manifest format is 958 used and it offers a variety of security features, including 959 digitial signatures and symmetric encryption. 961 Personalization Data 962 A TA Signer or TAM can supply personalization data along with a 963 TA. This data is also protected by a SUIT manifest. 964 Personalization data signed and encrypted by a TA Signer other 965 than the TAM is opaque to the TAM. 967 TEEP Broker 968 As discussed in section 6 of [I-D.ietf-teep-architecture], the 969 TEEP protocol typically relies on a TEEP Broker to relay messages 970 between the TAM and the TEEP Agent. When the TEEP Broker is 971 compromised it can drop messages, delay the delivery of messages, 972 and replay messages but it cannot modify those messages. (A 973 replay would be, however, detected by the TEEP Agent.) A 974 compromised TEEP Broker could reorder messages in an attempt to 975 install an old version of a TA. Information in the manifest 976 ensures that TEEP Agents are protected against such downgrade 977 attacks based on features offered by the manifest itself. 979 TA Signer Compromise 980 The QueryRequest message from a TAM to the TEEP Agent can include 981 OCSP stapling data for the TAM's certificate and for intermediate 982 CA certificates up to the root certificate so that the TEEP Agent 983 can verify the certificate's revocation status. A certificate 984 revocation status check on a TA Signer certificate is OPTIONAL by 985 a TEEP Agent. A TAM is responsible for vetting a TA and before 986 distributing them to TEEP Agents, so TEEP Agents can instead 987 simply trust that a TA Signer certificate's status was done by the 988 TAM. 990 CA Compromise 991 The CA issuing certificates to a TAM or a TA Signer might get 992 compromised. A compromised intermediate CA certificate can be 993 detected by a TEEP Agent by using OCSP information, assuming the 994 revocation information is available. Additionally, it is 995 RECOMMENDED to provide a way to update the trust anchor store used 996 by the TEE, for example using a firmware update mechanism. If the 997 CA issuing certificates to devices gets compromised then these 998 devices might be rejected by a TAM, if revocation is available to 999 the TAM. 1001 Compromised TAM 1002 The TEEP Agent SHOULD use OCSP information to verify the validity 1003 of the TAM's certificate (as well as the validity of intermediate 1004 CA certificates). The integrity and the accuracy of the clock 1005 within the TEE determines the ability to determine an expired or 1006 revoked certificate. OCSP stapling data includes signature 1007 generation time, allowing certificate validity dates to be 1008 compared to the current time. 1010 Compromised Time Source 1011 As discussed above, certificate validity checks rely on comparing 1012 validity dates to the current time, which relies on having a 1013 trusted source of time, such as [RFC8915]. A compromised time 1014 source could thus be used to subvert such validity checks. 1016 9. IANA Considerations 1018 9.1. Media Type Registration 1020 IANA is requested to assign a media type for application/teep+cbor. 1022 Type name: application 1024 Subtype name: teep+cbor 1026 Required parameters: none 1028 Optional parameters: none 1030 Encoding considerations: Same as encoding considerations of 1031 application/cbor. 1033 Security considerations: See Security Considerations Section of this 1034 document. 1036 Interoperability considerations: Same as interoperability 1037 considerations of application/cbor as specified in [RFC7049]. 1039 Published specification: This document. 1041 Applications that use this media type: TEEP protocol implementations 1042 Fragment identifier considerations: N/A 1044 Additional information: 1046 Deprecated alias names for this type: N/A 1048 Magic number(s): N/A 1050 File extension(s): N/A 1052 Macintosh file type code(s): N/A 1054 Person to contact for further information: teep@ietf.org 1056 Intended usage: COMMON 1058 Restrictions on usage: none 1060 Author: See the "Authors' Addresses" section of this document 1062 Change controller: IETF 1064 9.2. Ciphersuite Registry 1066 IANA is also requested to create a new registry for ciphersuites, as 1067 defined in Section 7. 1069 9.3. CBOR Tag Registry 1071 IANA is requested to register a CBOR tag in the "CBOR Tags" registry 1072 for use with TEEP messages. 1074 The registry contents is: 1076 o CBOR Tag: TBD1 1078 o Data Item: TEEP Message 1080 o Semantics: TEEP Message, as defined in [[TBD: This RFC]] 1082 o Reference: [[TBD: This RFC]] 1084 o Point of Contact: TEEP working group (teep@ietf.org) 1086 10. References 1088 10.1. Normative References 1090 [I-D.ietf-rats-architecture] 1091 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and 1092 W. Pan, "Remote Attestation Procedures Architecture", 1093 draft-ietf-rats-architecture-08 (work in progress), 1094 December 2020. 1096 [I-D.ietf-rats-eat] 1097 Mandyam, G., Lundblade, L., Ballesteros, M., and J. 1098 O'Donoghue, "The Entity Attestation Token (EAT)", draft- 1099 ietf-rats-eat-06 (work in progress), December 2020. 1101 [I-D.ietf-suit-manifest] 1102 Moran, B., Tschofenig, H., Birkholz, H., and K. Zandberg, 1103 "A Concise Binary Object Representation (CBOR)-based 1104 Serialization Format for the Software Updates for Internet 1105 of Things (SUIT) Manifest", draft-ietf-suit-manifest-11 1106 (work in progress), December 2020. 1108 [I-D.moran-suit-report] 1109 Moran, B., "Secure Reporting of Update Status", draft- 1110 moran-suit-report-00 (work in progress), October 2020. 1112 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1113 Requirement Levels", BCP 14, RFC 2119, 1114 DOI 10.17487/RFC2119, March 1997, . 1117 [RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. 1118 Adams, "X.509 Internet Public Key Infrastructure Online 1119 Certificate Status Protocol - OCSP", RFC 2560, 1120 DOI 10.17487/RFC2560, June 1999, . 1123 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1124 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1125 2003, . 1127 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 1128 Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, 1129 . 1131 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1132 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1133 October 2013, . 1135 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1136 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1137 . 1139 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1140 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1141 May 2017, . 1143 10.2. Informative References 1145 [I-D.birkholz-rats-suit-claims] 1146 Birkholz, H. and B. Moran, "Trustworthiness Vectors for 1147 the Software Updates of Internet of Things (SUIT) Workflow 1148 Model", draft-birkholz-rats-suit-claims-01 (work in 1149 progress), January 2021. 1151 [I-D.ietf-teep-architecture] 1152 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 1153 "Trusted Execution Environment Provisioning (TEEP) 1154 Architecture", draft-ietf-teep-architecture-13 (work in 1155 progress), November 2020. 1157 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1158 Writing an IANA Considerations Section in RFCs", BCP 26, 1159 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1160 . 1162 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1163 Definition Language (CDDL): A Notational Convention to 1164 Express Concise Binary Object Representation (CBOR) and 1165 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1166 June 2019, . 1168 [RFC8915] Franke, D., Sibold, D., Teichel, K., Dansarie, M., and R. 1169 Sundblad, "Network Time Security for the Network Time 1170 Protocol", RFC 8915, DOI 10.17487/RFC8915, September 2020, 1171 . 1173 A. Contributors 1175 We would like to thank Brian Witten (Symantec), Tyler Kim (Solacia), 1176 Nick Cook (Arm), and Minho Yoo (IoTrust) for their contributions to 1177 the Open Trust Protocol (OTrP), which influenced the design of this 1178 specification. 1180 B. Acknowledgements 1182 We would like to thank Eve Schooler for the suggestion of the 1183 protocol name. 1185 We would like to thank Kohei Isobe (TRASIO/SECOM), Kuniyasu Suzaki 1186 (TRASIO/AIST), Tsukasa Oi (TRASIO), and Yuichi Takita (SECOM) for 1187 their valuable implementation feedback. 1189 We would also like to thank Carsten Bormann and Henk Birkholz for 1190 their help with the CDDL. 1192 C. Complete CDDL 1194 Valid TEEP messages MUST adhere to the following CDDL data 1195 definitions, except that "SUIT_Envelope" and 1196 "SUIT_Component_Identifier" are specified in 1197 [I-D.ietf-suit-manifest]. 1199 teep-message = $teep-message-type .within teep-message-framework 1201 SUIT_Envelope = any 1203 teep-message-framework = [ 1204 type: uint (0..23) / $teep-type-extension, 1205 options: { * teep-option }, 1206 * uint; further integers, e.g., for data-item-requested 1207 ] 1209 teep-option = (uint => any) 1211 ; messages defined below: 1212 $teep-message-type /= query-request 1213 $teep-message-type /= query-response 1214 $teep-message-type /= update 1215 $teep-message-type /= teep-success 1216 $teep-message-type /= teep-error 1218 ; message type numbers, uint (0..23) 1219 TEEP-TYPE-query-request = 1 1220 TEEP-TYPE-query-response = 2 1221 TEEP-TYPE-update = 3 1222 TEEP-TYPE-teep-success = 5 1223 TEEP-TYPE-teep-error = 6 1225 version = .within uint .size 4 1226 ext-info = .within uint .size 4 1227 ; data items as bitmaps 1228 data-item-requested = $data-item-requested .within uint .size 8 1229 attestation = 1 1230 $data-item-requested /= attestation 1231 trusted-components = 2 1232 $data-item-requested /= trusted-components 1233 extensions = 4 1234 $data-item-requested /= extensions 1235 suit-commands = 8 1236 $data-item-requested /= suit-commands 1238 query-request = [ 1239 type: TEEP-TYPE-query-request, 1240 options: { 1241 ? token => bstr .size (8..64), 1242 ? supported-cipher-suites => [ + suite ], 1243 ? challenge => bstr .size (8..64), 1244 ? versions => [ + version ], 1245 ? ocsp-data => bstr, 1246 * $$query-request-extensions 1247 * $$teep-option-extensions 1248 }, 1249 data-item-requested: data-item-requested 1250 ] 1252 ; ciphersuites 1253 suite = $TEEP-suite .within uint .size 4 1255 TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 1 1256 TEEP-AES-CCM-16-64-128-HMAC256--256-P-256-ES256 = 2 1258 $TEEP-suite /= TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA 1259 $TEEP-suite /= TEEP-AES-CCM-16-64-128-HMAC256--256-P-256-ES256 1261 query-response = [ 1262 type: TEEP-TYPE-query-response, 1263 options: { 1264 ? token => bstr .size (8..64), 1265 ? selected-cipher-suite => suite, 1266 ? selected-version => version, 1267 ? evidence-format => text, 1268 ? evidence => bstr, 1269 ? tc-list => [ + tc-info ], 1270 ? requested-tc-list => [ + requested-tc-info ], 1271 ? unneeded-tc-list => [ + SUIT_Component_Identifier ], 1272 ? ext-list => [ + ext-info ], 1273 * $$query-response-extensions, 1274 * $$teep-option-extensions 1276 } 1277 ] 1279 tc-info = { 1280 component-id => SUIT_Component_Identifier, 1281 ? tc-manifest-sequence-number => .within uint .size 8 1282 } 1284 requested-tc-info = { 1285 component-id => SUIT_Component_Identifier, 1286 ? tc-manifest-sequence-number => .within uint .size 8 1287 ? have-binary => bool 1288 } 1290 update = [ 1291 type: TEEP-TYPE-update, 1292 options: { 1293 ? token => bstr .size (8..64), 1294 ? unneeded-tc-list => [ + SUIT_Component_Identifier ], 1295 ? manifest-list => [ + bstr .cbor SUIT_Envelope ], 1296 * $$update-extensions, 1297 * $$teep-option-extensions 1298 } 1299 ] 1301 teep-success = [ 1302 type: TEEP-TYPE-teep-success, 1303 options: { 1304 ? token => bstr .size (8..64), 1305 ? msg => text .size (1..128), 1306 ? suit-reports => [ + suit-report ], 1307 * $$teep-success-extensions, 1308 * $$teep-option-extensions 1309 } 1310 ] 1312 teep-error = [ 1313 type: TEEP-TYPE-teep-error, 1314 options: { 1315 ? token => bstr .size (8..64), 1316 ? err-msg => text .size (1..128), 1317 ? supported-cipher-suites => [ + suite ], 1318 ? versions => [ + version ], 1319 ? suit-reports => [ + suit-report ], 1320 * $$teep-error-extensions, 1321 * $$teep-option-extensions 1322 }, 1323 err-code: uint (0..23) 1325 ] 1327 ; The err-code parameter, uint (0..23) 1328 ERR_PERMANENT_ERROR = 1 1329 ERR_UNSUPPORTED_EXTENSION = 2 1330 ERR_UNSUPPORTED_MSG_VERSION = 4 1331 ERR_UNSUPPORTED_CRYPTO_ALG = 5 1332 ERR_BAD_CERTIFICATE = 6 1333 ERR_CERTIFICATE_EXPIRED = 9 1334 ERR_TEMPORARY_ERROR = 10 1335 ERR_MANIFEST_PROCESSING_FAILED = 17 1337 ; labels of mapkey for teep message parameters, uint (0..23) 1338 supported-cipher-suites = 1 1339 challenge = 2 1340 versions = 3 1341 ocsp-data = 4 1342 selected-cipher-suite = 5 1343 selected-version = 6 1344 evidence = 7 1345 tc-list = 8 1346 ext-list = 9 1347 manifest-list = 10 1348 msg = 11 1349 err-msg = 12 1350 evidence-format = 13 1351 requested-tc-list = 14 1352 unneeded-tc-list = 15 1353 component-id = 16 1354 tc-manifest-sequence-number = 17 1355 have-binary = 18 1356 suit-reports = 19 1357 token = 20 1359 D. Examples of Diagnostic Notation and Binary Representation 1361 D.1. Some assumptions in examples 1363 o OCSP stapling data = h'010203' 1365 o TEEP Device will have 2 TAs with the following SUIT Component 1366 Identifiers: 1368 * [ 0x0102030405060708090a0b0c0d0e0f ] 1370 * [ 0x1102030405060708090a0b0c0d0e0f ] 1372 o SUIT manifest-list is set empty only for example purposes 1374 D.2. QueryRequest Message 1376 D.2.1. CBOR Diagnostic Notation 1378 / query-request = / 1379 [ 1380 1, / type : TEEP-TYPE-query-request = 1 (uint (0..23)) / 1381 / options : / 1382 { 1383 20 : 0xa0a1a2a3a4a5a6a7, 1384 / token = 20 (mapkey) : 1385 h'a0a1a2a3a4a5a6a7' (bstr .size (8..64)), 1386 generated by TAM / 1387 1 : [ 1 ], / supported-cipher-suites = 1 (mapkey) : 1388 TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 1389 [ 1 ] (array of .within uint .size 4) / 1390 3 : [ 0 ], / version = 3 (mapkey) : 1391 [ 0 ] (array of .within uint .size 4) / 1392 4 : h'010203' / ocsp-data = 4 (mapkey) : 0x010203 (bstr) / 1393 }, 1394 3 / data-item-requested : 1395 attestation | trusted-components = 3 (.within uint .size 8) / 1396 ] 1398 D.2.2. CBOR Binary Representation 1400 83 # array(3) 1401 01 # unsigned(1) uint (0..23) 1402 A4 # map(4) 1403 14 # unsigned(20) uint (0..23) 1404 48 # bytes(8) (8..64) 1405 A0A1A2A3A4A5A6A7 1406 01 # unsigned(1) uint (0..23) 1407 81 # array(1) 1408 01 # unsigned(1) within uint .size 4 1409 03 # unsigned(3) uint (0..23) 1410 81 # array(1) 1411 00 # unsigned(0) within uint .size 4 1412 04 # unsigned(4) uint (0..23) 1413 43 # bytes(3) 1414 010203 # "\x01\x02\x03" 1415 03 # unsigned(3) .within uint .size 8 1417 D.3. Entity Attestation Token 1419 This is shown below in CBOR diagnostic form. Only the payload signed 1420 by COSE is shown. 1422 D.3.1. CBOR Diagnostic Notation 1424 / eat-claim-set = / 1425 { 1426 / issuer / 1: "joe", 1427 / timestamp (iat) / 6: 1(1526542894) 1428 / nonce / 10: h'948f8860d13a463e8e', 1429 / secure-boot / 15: true, 1430 / debug-status / 16: 3, / disabled-permanently / 1431 / security-level / : 3, / secure-restricted / 1432 / device-identifier / : h'e99600dd921649798b013e9752dcf0c5', 1433 / vendor-identifier / : h'2b03879b33434a7ca682b8af84c19fd4', 1434 / class-identifier / : h'9714a5796bd245a3a4ab4f977cb8487f', 1435 / chip-version-scheme / : "MyTEE v1.0", 1436 / component-identifier / : h'60822887d35e43d5b603d18bcaa3f08d', 1437 / version / : "v0.1" 1438 } 1440 D.4. QueryResponse Message 1442 D.4.1. CBOR Diagnostic Notation 1443 / query-response = / 1444 [ 1445 2, / type : TEEP-TYPE-query-response = 2 (uint (0..23)) / 1446 / options : / 1447 { 1448 20 : 0xa0a1a2a3a4a5a6a7, 1449 / token = 20 (mapkey) : 1450 h'a0a1a2a3a4a5a6a7' (bstr .size (8..64)), 1451 given from TAM's QueryRequest message / 1452 5 : 1, / selected-cipher-suite = 5 (mapkey) : 1453 TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 1454 1 (.within uint .size 4) / 1455 6 : 0, / selected-version = 6 (mapkey) : 1456 0 (.within uint .size 4) / 1457 7 : ... / evidence = 7 (mapkey) : 1458 Entity Attestation Token / 1459 8 : [ / tc-list = 8 (mapkey) : (array of tc-info) / 1460 { 1461 16 : [ 0x0102030405060708090a0b0c0d0e0f ] / component-id = 1462 16 (mapkey) : [ h'0102030405060708090a0b0c0d0e0f' ] 1463 (SUIT_Component_Identifier = [* bstr]) / 1464 }, 1465 { 1466 16 : [ 0x1102030405060708090a0b0c0d0e0f ] / component-id = 1467 16 (mapkey) : [ h'1102030405060708090a0b0c0d0e0f' ] 1468 (SUIT_Component_Identifier = [* bstr]) / 1469 } 1470 ] 1471 } 1472 ] 1474 D.4.2. CBOR Binary Representation 1475 82 # array(2) 1476 02 # unsigned(2) uint (0..23) 1477 A5 # map(5) 1478 14 # unsigned(20) uint (0..23) 1479 48 # bytes(8) (8..64) 1480 A0A1A2A3A4A5A6A7 1481 05 # unsigned(5) uint (0..23) 1482 01 # unsigned(1) .within uint .size 4 1483 06 # unsigned(6) uint (0..23) 1484 00 # unsigned(0) .within uint .size 4 1485 07 # unsigned(7) uint (0..23) 1486 ... # Entity Attestation Token 1487 08 # unsigned(8) uint (0..23) 1488 82 # array(2) 1489 81 # array(1) 1490 4F # bytes(15) 1491 0102030405060708090A0B0C0D0E0F 1492 81 # array(1) 1493 4F # bytes(15) 1494 1102030405060708090A0B0C0D0E0F 1496 D.5. Update Message 1498 D.5.1. CBOR Diagnostic Notation 1500 / update = / 1501 [ 1502 3, / type : TEEP-TYPE-update = 3 (uint (0..23)) / 1503 / options : / 1504 { 1505 20 : 0xaba1a2a3a4a5a6a7, 1506 / token = 20 (mapkey) : 1507 h'aba1a2a3a4a5a6a7' (bstr .size (8..64)), 1508 generated by TAM / 1509 15 : [ [ h'0102030405060708090a0b0c0d0e0f' ] ] 1510 / unneeded-tc-list = 15 (mapkey) : 1511 [ [ h'0102030405060708090a0b0c0d0e0f' ] ] 1512 (array of SUIT_Component_Identifier = [* bstr]) / 1513 10 : [ ] / manifest-list = 10 (mapkey) : 1514 [ ] (array of bstr wrapped SUIT_Envelope(any)) / 1515 / empty, example purpose only / 1516 } 1517 ] 1519 D.5.2. CBOR Binary Representation 1521 82 # array(2) 1522 03 # unsigned(3) uint (0..23) 1523 A3 # map(3) 1524 14 # unsigned(20) uint (0..23) 1525 48 # bytes(8) (8..64) 1526 ABA1A2A3A4A5A6A7 1527 0F # unsigned(15) uint (0..23) 1528 81 # array(1) 1529 81 # array(1) 1530 4F # bytes(15) 1531 0102030405060708090A0B0C0D0E0F 1532 0A # unsigned(10) uint (0..23) 1533 80 # array(0) 1535 D.6. Success Message 1537 D.6.1. CBOR Diagnostic Notation 1539 / teep-success = / 1540 [ 1541 5, / type : TEEP-TYPE-teep-success = 5 (uint (0..23)) / 1542 / options : / 1543 { 1544 20 : 0xaba1a2a3a4a5a6a7, 1545 / token = 20 (mapkey) : 1546 h'aba1a2a3a4a5a6a7' (bstr .size (8..64)), 1547 given from TAM's Update message / 1548 } 1549 ] 1551 D.6.2. CBOR Binary Representation 1553 82 # array(2) 1554 05 # unsigned(5) uint (0..23) 1555 A1 # map(1) 1556 14 # unsigned(20) uint (0..23) 1557 48 # bytes(8) (8..64) 1558 ABA1A2A3A4A5A6A7 1560 D.7. Error Message 1562 D.7.1. CBOR Diagnostic Notation 1563 / teep-error = / 1564 [ 1565 6, / type : TEEP-TYPE-teep-error = 6 (uint (0..23)) / 1566 / options : / 1567 { 1568 20 : 0xaba1a2a3a4a5a6a7, 1569 / token = 20 (mapkey) : 1570 h'aba1a2a3a4a5a6a7' (bstr .size (8..64)), 1571 given from TAM's Update message / 1572 12 : "disk-full" / err-msg = 12 (mapkey) : 1573 "disk-full" (text .size (1..128)) / 1574 }, 1575 17, / err-code : ERR_MANIFEST_PROCESSING_FAILED = 17 (uint (0..23)) / 1576 ] 1578 D.7.2. CBOR binary Representation 1580 83 # array(3) 1581 06 # unsigned(6) uint (0..23) 1582 A2 # map(2) 1583 14 # unsigned(20) uint (0..23) 1584 48 # bytes(8) (8..64) 1585 ABA1A2A3A4A5A6A7 1586 0C # unsigned(12) uint (0..23) 1587 69 # text(9) (1..128) 1588 6469736b2d66756c6c # "disk-full" 1589 11 # unsigned(17) uint (0..23) 1591 Authors' Addresses 1593 Hannes Tschofenig 1594 Arm Ltd. 1595 Absam, Tirol 6067 1596 Austria 1598 Email: hannes.tschofenig@arm.com 1600 Mingliang Pei 1601 Broadcom 1602 350 Ellis St 1603 Mountain View, CA 94043 1604 USA 1606 Email: mingliang.pei@broadcom.com 1607 David Wheeler 1608 Intel 1609 US 1611 Email: david.m.wheeler@intel.com 1613 Dave Thaler 1614 Microsoft 1615 US 1617 Email: dthaler@microsoft.com 1619 Akira Tsukamoto 1620 AIST 1621 JP 1623 Email: akira.tsukamoto@aist.go.jp