idnits 2.17.1 draft-ietf-teep-protocol-06.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 12, 2021) is 1018 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) == Unused Reference: 'I-D.birkholz-rats-suit-claims' is defined on line 1232, but no explicit reference was found in the text == Unused Reference: 'RFC8126' is defined on line 1244, but no explicit reference was found in the text == Outdated reference: A later version (-22) exists of draft-ietf-rats-architecture-12 ** 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-10 ** 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 (-03) exists of draft-birkholz-rats-suit-claims-02 == Outdated reference: A later version (-19) exists of draft-ietf-teep-architecture-15 Summary: 4 errors (**), 0 flaws (~~), 7 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: January 13, 2022 Broadcom 6 D. Wheeler 7 Amazon 8 D. Thaler 9 Microsoft 10 A. Tsukamoto 11 AIST 12 July 12, 2021 14 Trusted Execution Environment Provisioning (TEEP) Protocol 15 draft-ietf-teep-protocol-06 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 January 13, 2022. 41 Copyright Notice 43 Copyright (c) 2021 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 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Message Overview . . . . . . . . . . . . . . . . . . . . . . 4 61 4. Detailed Messages Specification . . . . . . . . . . . . . . . 5 62 4.1. Creating and Validating TEEP Messages . . . . . . . . . . 5 63 4.1.1. Creating a TEEP message . . . . . . . . . . . . . . . 5 64 4.1.2. Validating a TEEP Message . . . . . . . . . . . . . . 6 65 4.2. QueryRequest Message . . . . . . . . . . . . . . . . . . 6 66 4.3. QueryResponse Message . . . . . . . . . . . . . . . . . . 9 67 4.3.1. Evidence . . . . . . . . . . . . . . . . . . . . . . 11 68 4.4. Update Message . . . . . . . . . . . . . . . . . . . . . 12 69 4.5. Success Message . . . . . . . . . . . . . . . . . . . . . 14 70 4.6. Error Message . . . . . . . . . . . . . . . . . . . . . . 15 71 5. Mapping of TEEP Message Parameters to CBOR Labels . . . . . . 17 72 6. Behavior Specification . . . . . . . . . . . . . . . . . . . 18 73 6.1. TAM Behavior . . . . . . . . . . . . . . . . . . . . . . 18 74 6.2. TEEP Agent Behavior . . . . . . . . . . . . . . . . . . . 19 75 7. Ciphersuites . . . . . . . . . . . . . . . . . . . . . . . . 20 76 8. Freshness Mechanisms . . . . . . . . . . . . . . . . . . . . 21 77 9. Security Considerations . . . . . . . . . . . . . . . . . . . 21 78 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 79 10.1. Media Type Registration . . . . . . . . . . . . . . . . 23 80 10.2. Ciphersuite Registry . . . . . . . . . . . . . . . . . . 24 81 10.3. Freshness Mechanism Registry . . . . . . . . . . . . . . 24 82 10.4. CBOR Tag Registry . . . . . . . . . . . . . . . . . . . 25 83 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 84 11.1. Normative References . . . . . . . . . . . . . . . . . . 25 85 11.2. Informative References . . . . . . . . . . . . . . . . . 26 86 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 27 87 B. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27 88 C. Complete CDDL . . . . . . . . . . . . . . . . . . . . . . . . 27 89 D. Examples of Diagnostic Notation and Binary Representation . . 31 90 D.1. Some assumptions in examples . . . . . . . . . . . . . . 31 91 D.2. QueryRequest Message . . . . . . . . . . . . . . . . . . 31 92 D.2.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 32 93 D.2.2. CBOR Binary Representation . . . . . . . . . . . . . 32 94 D.3. Entity Attestation Token . . . . . . . . . . . . . . . . 32 95 D.3.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 33 96 D.4. QueryResponse Message . . . . . . . . . . . . . . . . . . 33 97 D.4.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 33 98 D.4.2. CBOR Binary Representation . . . . . . . . . . . . . 34 99 D.5. Update Message . . . . . . . . . . . . . . . . . . . . . 35 100 D.5.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 35 101 D.5.2. CBOR Binary Representation . . . . . . . . . . . . . 35 102 D.6. Success Message . . . . . . . . . . . . . . . . . . . . . 36 103 D.6.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 36 104 D.6.2. CBOR Binary Representation . . . . . . . . . . . . . 36 105 D.7. Error Message . . . . . . . . . . . . . . . . . . . . . . 36 106 D.7.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 36 107 D.7.2. CBOR binary Representation . . . . . . . . . . . . . 37 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 110 1. Introduction 112 The Trusted Execution Environment (TEE) concept has been designed to 113 separate a regular operating system, also referred as a Rich 114 Execution Environment (REE), from security-sensitive applications. 115 In a TEE ecosystem, device vendors may use different operating 116 systems in the REE and may use different types of TEEs. When Trusted 117 Component Developers or Device Administrators use Trusted Application 118 Managers (TAMs) to install, update, and delete Trusted Applications 119 and their dependencies on a wide range of devices with potentially 120 different TEEs then an interoperability need arises. 122 This document specifies the protocol for communicating between a TAM 123 and a TEEP Agent. 125 The Trusted Execution Environment Provisioning (TEEP) architecture 126 document [I-D.ietf-teep-architecture] provides design guidance and 127 introduces the necessary terminology. 129 2. Terminology 131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 133 "OPTIONAL" in this document are to be interpreted as described in 134 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 135 capitals, as shown here. 137 This specification re-uses the terminology defined in 138 [I-D.ietf-teep-architecture]. 140 As explained in Section 4.4 of that document, the TEEP protocol 141 treats each Trusted Application (TA), any dependencies the TA has, 142 and personalization data as separate components that are expressed in 143 SUIT manifests, and a SUIT manifest might contain or reference 144 multiple binaries (see [I-D.ietf-suit-manifest] for more details). 146 As such, the term Trusted Component (TC) in this document refers to a 147 set of binaries expressed in a SUIT manifest, to be installed in a 148 TEE. Note that a Trusted Component may include one or more TAs and/ 149 or configuration data and keys needed by a TA to operate correctly. 151 Each Trusted Component is uniquely identified by a SUIT Component 152 Identifier (see [I-D.ietf-suit-manifest] Section 8.7.2.2). 154 3. Message Overview 156 The TEEP protocol consists of messages exchanged between a TAM and a 157 TEEP Agent. The messages are encoded in CBOR and designed to provide 158 end-to-end security. TEEP protocol messages are signed by the 159 endpoints, i.e., the TAM and the TEEP Agent, but Trusted Applications 160 may also be encrypted and signed by a Trusted Component Developer or 161 Device Administrator. The TEEP protocol not only uses CBOR but also 162 the respective security wrapper, namely COSE [RFC8152]. Furthermore, 163 for software updates the SUIT manifest format 164 [I-D.ietf-suit-manifest] is used, and for attestation the Entity 165 Attestation Token (EAT) [I-D.ietf-rats-eat] format is supported 166 although other attestation formats are also permitted. 168 This specification defines five messages: QueryRequest, 169 QueryResponse, Update, Success, and Error. 171 A TAM queries a device's current state with a QueryRequest message. 172 A TEEP Agent will, after authenticating and authorizing the request, 173 report attestation information, list all Trusted Components, and 174 provide information about supported algorithms and extensions in a 175 QueryResponse message. An error message is returned if the request 176 could not be processed. A TAM will process the QueryResponse message 177 and determine whether to initiate subsequent message exchanges to 178 install, update, or delete Trusted Applications. 180 +------------+ +-------------+ 181 | TAM | |TEEP Agent | 182 +------------+ +-------------+ 184 QueryRequest -------> 186 QueryResponse 188 <------- or 190 Error 192 With the Update message a TAM can instruct a TEEP Agent to install 193 and/or delete one or more Trusted Components. The TEEP Agent will 194 process the message, determine whether the TAM is authorized and 195 whether the Trusted Component has been signed by an authorized 196 Trusted Component Signer. A Success message is returned when the 197 operation has been completed successfully, or an Error message 198 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. TEEP messages sent by 233 TAMs (QueryRequest and Update) can include a "token". The first 234 usage of a token generated by a TAM MUST be randomly created. 235 Subsequent token values MUST be different for each subsequent 236 message created by a TAM. 238 2. Create a COSE Header containing the desired set of Header 239 Parameters. The COSE Header MUST be valid per the [RFC8152] 240 specification. 242 3. Create a COSE_Sign1 object using the TEEP message as the 243 COSE_Sign1 Payload; all steps specified in [RFC8152] for creating 244 a COSE_Sign1 object MUST be followed. 246 4. Prepend the COSE object with the TEEP CBOR tag to indicate that 247 the CBOR-encoded message is indeed a TEEP message. 249 4.1.2. Validating a TEEP Message 251 When TEEP message is received (see the ProcessTeepMessage conceptual 252 API defined in [I-D.ietf-teep-architecture] section 6.2.1), the 253 following validation steps are performed. If any of the listed steps 254 fail, then the TEEP message MUST be rejected. 256 1. Verify that the received message is a valid CBOR object. 258 2. Remove the TEEP message CBOR tag and verify that one of the COSE 259 CBOR tags follows it. 261 3. Verify that the message contains a COSE_Sign1 structure. 263 4. Verify that the resulting COSE Header includes only parameters 264 and values whose syntax and semantics are both understood and 265 supported or that are specified as being ignored when not 266 understood. 268 5. Follow the steps specified in Section 4 of [RFC8152] ("Signing 269 Objects") for validating a COSE_Sign1 object. The COSE_Sign1 270 payload is the content of the TEEP message. 272 6. Verify that the TEEP message is a valid CBOR map and verify the 273 fields of the TEEP message according to this specification. 275 4.2. QueryRequest Message 277 A QueryRequest message is used by the TAM to learn information from 278 the TEEP Agent, such as the features supported by the TEEP Agent, 279 including ciphersuites, and protocol versions. Additionally, the TAM 280 can selectively request data items from the TEEP Agent via the 281 request parameter. Currently, the following features are supported: 283 o Request for attestation information, 285 o Listing supported extensions, 287 o Querying installed Trusted Components, and 289 o Listing supported SUIT commands. 291 Like other TEEP messages, the QueryRequest message is signed, and the 292 relevant CDDL snippet is shown below. The complete CDDL structure is 293 shown in Appendix C. 295 query-request = [ 296 type: TEEP-TYPE-query-request, 297 options: { 298 ? token => bstr .size (8..64), 299 ? supported-cipher-suites => [ + suite ], 300 ? supported-freshness-mechanisms => [ + freshness-mechanism ], 301 ? challenge => bstr .size (8..512), 302 ? versions => [ + version ], 303 ? ocsp-data => bstr, 304 * $$query-request-extensions 305 * $$teep-option-extensions 306 }, 307 data-item-requested: data-item-requested 308 ] 310 The message has the following fields: 312 type 313 The value of (1) corresponds to a QueryRequest message sent from 314 the TAM to the TEEP Agent. 316 token 317 The value in the token parameter is used to match responses to 318 requests. This is particularly useful when a TAM issues multiple 319 concurrent requests to a TEEP Agent. The token MUST be present if 320 and only if the attestation bit is clear in the data-item- 321 requested value. The size of the token is at least 8 bytes (64 322 bits) and maximum of 64 bytes, which is the same as in an EAT 323 Nonce Claim (see [I-D.ietf-rats-eat] Section 3.3). 325 data-item-requested 326 The data-item-requested parameter indicates what information the 327 TAM requests from the TEEP Agent in the form of a bitmap. Each 328 value in the bitmap corresponds to an IANA registered information 329 element. This specification defines the following initial set of 330 information elements: 332 attestation (1) With this value the TAM requests the TEEP Agent 333 to return attestation evidence (e.g., an EAT) in the response. 335 trusted-components (2) With this value the TAM queries the TEEP 336 Agent for all installed Trusted Components. 338 extensions (4) With this value the TAM queries the TEEP Agent for 339 supported capabilities and extensions, which allows a TAM to 340 discover the capabilities of a TEEP Agent implementation. 342 suit-commands (8) With this value the TAM queries the TEEP Agent 343 for supported commands offered by the SUIT manifest 344 implementation. 346 Further values may be added in the future via IANA registration. 348 supported-cipher-suites 349 The supported-cipher-suites parameter lists the ciphersuite(s) 350 supported by the TAM. If this parameter is not present, it is to 351 be treated the same as if it contained both ciphersuites defined 352 in this document. Details about the ciphersuite encoding can be 353 found in Section 7. 355 supported-freshness-mechanisms 356 The supported-freshness-mechanisms parameter lists the freshness 357 mechanism(s) supported by the TAM. Details about the encoding can 358 be found in Section 8. If this parameter is absent, it means only 359 the nonce mechanism is supported. 361 challenge 362 The challenge field is an optional parameter used for ensuring the 363 freshness of the attestation evidence returned with a 364 QueryResponse message. It MUST be absent if the attestation bit 365 is clear (since the token is used instead in that case). When a 366 challenge is provided in the QueryRequest and an EAT is returned 367 with the QueryResponse message then the challenge contained in 368 this request MUST be copied into the nonce claim found in the EAT. 369 If any format other than EAT is used, it is up to that format to 370 define the use of the challenge field. 372 versions 373 The versions parameter enumerates the TEEP protocol version(s) 374 supported by the TAM. A value of 0 refers to the current version 375 of the TEEP protocol. If this field is not present, it is to be 376 treated the same as if it contained only version 0. 378 ocsp-data 379 The ocsp-data parameter contains a list of OCSP stapling data 380 respectively for the TAM certificate and each of the CA 381 certificates up to, but not including, the trust anchor. The TAM 382 provides OCSP data so that the TEEP Agent can validate the status 383 of the TAM certificate chain without making its own external OCSP 384 service call. OCSP data MUST be conveyed as a DER-encoded OCSP 385 response (using the ASN.1 type OCSPResponse defined in [RFC6960]). 387 The use of OCSP is OPTIONAL to implement for both the TAM and the 388 TEEP Agent. A TAM can query the TEEP Agent for the support of 389 this functionality via the capability discovery exchange, as 390 described above. 392 4.3. QueryResponse Message 394 The QueryResponse message is the successful response by the TEEP 395 Agent after receiving a QueryRequest message. 397 Like other TEEP messages, the QueryResponse message is signed, and 398 the relevant CDDL snippet is shown below. The complete CDDL 399 structure is shown in Appendix C. 401 query-response = [ 402 type: TEEP-TYPE-query-response, 403 options: { 404 ? token => bstr .size (8..64), 405 ? selected-cipher-suite => suite, 406 ? selected-version => version, 407 ? evidence-format => text, 408 ? evidence => bstr, 409 ? tc-list => [ + tc-info ], 410 ? requested-tc-list => [ + requested-tc-info ], 411 ? unneeded-tc-list => [ + SUIT_Component_Identifier ], 412 ? ext-list => [ + ext-info ], 413 * $$query-response-extensions, 414 * $$teep-option-extensions 415 } 416 ] 418 tc-info = { 419 component-id => SUIT_Component_Identifier, 420 ? tc-manifest-sequence-number => .within uint .size 8 421 } 423 requested-tc-info = { 424 component-id => SUIT_Component_Identifier, 425 ? tc-manifest-sequence-number => .within uint .size 8 426 ? have-binary => bool 427 } 429 The QueryResponse message has the following fields: 431 type 432 The value of (2) corresponds to a QueryResponse message sent from 433 the TEEP Agent to the TAM. 435 token 436 The value in the token parameter is used to match responses to 437 requests. The value MUST correspond to the value received with 438 the QueryRequest message if one was present, and MUST be absent if 439 no token was present in the QueryRequest. 441 selected-cipher-suite 442 The selected-cipher-suite parameter indicates the selected 443 ciphersuite. Details about the ciphersuite encoding can be found 444 in Section 7. 446 selected-version 447 The selected-version parameter indicates the TEEP protocol version 448 selected by the TEEP Agent. The absense of this parameter 449 indicates the same as if it was present with a value of 0. 451 evidence-format 452 The evidence-format parameter indicates the IANA Media Type of the 453 attestation evidence contained in the evidence parameter. It MUST 454 be present if the evidence parameter is present and the format is 455 not an EAT. 457 evidence 458 The evidence parameter contains the attestation evidence. This 459 parameter MUST be present if the QueryResponse is sent in response 460 to a QueryRequest with the attestation bit set. If the evidence- 461 format parameter is absent, the attestation evidence contained in 462 this parameter MUST be an Entity Attestation Token following the 463 encoding defined in [I-D.ietf-rats-eat]. See Section 4.3.1 for 464 further discussion. 466 tc-list 467 The tc-list parameter enumerates the Trusted Components installed 468 on the device in the form of tc-info objects. This parameter MUST 469 be present if the QueryResponse is sent in response to a 470 QueryRequest with the trusted-components bit set. 472 requested-tc-list 473 The requested-tc-list parameter enumerates the Trusted Components 474 that are not currently installed in the TEE, but which are 475 requested to be installed, for example by an installer of an 476 Untrusted Application that has a TA as a dependency, or by a 477 Trusted Application that has another Trusted Component as a 478 dependency. Requested Trusted Components are expressed in the 479 form of requested-tc-info objects. A TEEP Agent can get this 480 information from the UnrequestTA conceptual API defined in 481 [I-D.ietf-teep-architecture] section 6.2.1. 483 unneeded-tc-list 484 The unneeded-tc-list parameter enumerates the Trusted Components 485 that are currently installed in the TEE, but which are no longer 486 needed by any other application. The TAM can use this information 487 in determining whether a Trusted Component can be deleted. Each 488 unneeded Trusted Component is identified by its SUIT Component 489 Identifier. A TEEP Agent can get this information from the 490 UnrequestTA conceptual API defined in [I-D.ietf-teep-architecture] 491 section 6.2.1. 493 ext-list 494 The ext-list parameter lists the supported extensions. This 495 document does not define any extensions. 497 The tc-info object has the following fields: 499 component-id 500 A SUIT Component Identifier. 502 tc-manifest-sequence-number 503 The suit-manifest-sequence-number value from the SUIT manifest for 504 the Trusted Component, if a SUIT manifest was used. 506 The requested-tc-info message has the following fields: 508 component-id 509 A SUIT Component Identifier. 511 tc-manifest-sequence-number 512 The minimum suit-manifest-sequence-number value from a SUIT 513 manifest for the Trusted Component. If not present, indicates 514 that any sequence number will do. 516 have-binary 517 If present with a value of true, indicates that the TEEP agent 518 already has the Trusted Component binary and only needs an Update 519 message with a SUIT manifest that authorizes installing it. If 520 have-binary is true, the tc-manifest-sequence-number field MUST be 521 present. 523 4.3.1. Evidence 525 Section 7.1 of [I-D.ietf-teep-architecture] lists information that 526 may be required in the evidence depend on the circumstance. When an 527 Entity Attestation Token is used, the following claims can be used to 528 meet those requirements: 530 +------------+---------------------+--------------------------------+ 531 | Requiremen | Claim | Reference | 532 | t | | | 533 +------------+---------------------+--------------------------------+ 534 | Device | device-identifier | [I-D.birkholz-rats-suit-claims | 535 | unique | | ] section 3.1.3 | 536 | identifier | | | 537 | Vendor of | vendor-identifier | [I-D.birkholz-rats-suit-claims | 538 | the device | | ] section 3.1.1 | 539 | Class of | class-identifier | [I-D.birkholz-rats-suit-claims | 540 | the device | | ] section 3.1.2 | 541 | TEE | chip-version-scheme | [I-D.ietf-rats-eat] section | 542 | hardware | | 3.7 | 543 | type | | | 544 | TEE | chip-version-scheme | [I-D.ietf-rats-eat] section | 545 | hardware | | 3.7 | 546 | version | | | 547 | TEE | component- | [I-D.birkholz-rats-suit-claims | 548 | firmware | identifier | ] section 3.1.4 | 549 | type | | | 550 | TEE | version | [I-D.birkholz-rats-suit-claims | 551 | firmware | | ] section 3.1.8 | 552 | version | | | 553 | Freshness | nonce | [I-D.ietf-rats-eat] section | 554 | proof | | 3.3 | 555 +------------+---------------------+--------------------------------+ 557 4.4. Update Message 559 The Update message is used by the TAM to install and/or delete one or 560 more Trusted Components via the TEEP Agent. 562 Like other TEEP messages, the Update message is signed, and the 563 relevant CDDL snippet is shown below. The complete CDDL structure is 564 shown in Appendix C. 566 update = [ 567 type: TEEP-TYPE-update, 568 options: { 569 ? token => bstr .size (8..64), 570 ? manifest-list => [ + bstr .cbor SUIT_Envelope ], 571 * $$update-extensions, 572 * $$teep-option-extensions 573 } 574 ] 576 The Update message has the following fields: 578 type 579 The value of (3) corresponds to an Update message sent from the 580 TAM to the TEEP Agent. In case of successful processing, a 581 Success message is returned by the TEEP Agent. In case of an 582 error, an Error message is returned. Note that the Update message 583 is used for initial Trusted Component installation as well as for 584 updates and deletes. 586 token 587 The value in the token field is used to match responses to 588 requests. 590 manifest-list 591 The manifest-list field is used to convey one or multiple SUIT 592 manifests to install. A manifest is a bundle of metadata about a 593 Trusted Component, such as where to find the code, the devices to 594 which it applies, and cryptographic information protecting the 595 manifest. The manifest may also convey personalization data. 596 Trusted Component binaries and personalization data can be signed 597 and encrypted by the same Trusted Component Signer. Other 598 combinations are, however, possible as well. For example, it is 599 also possible for the TAM to sign and encrypt the personalization 600 data and to let the Trusted Component Developer sign and/or 601 encrypt the Trusted Component binary. 603 Note that an Update message carrying one or more SUIT manifests will 604 inherently involve multiple signatures, one by the TAM in the TEEP 605 message and one from a Trusted Component signer inside each manifest. 606 This is intentional as they are for different purposes. 608 The TAM is what authorizes apps to be installed, updated, and deleted 609 on a given TEE and so the TEEP signature is checked by the TEEP Agent 610 at protocol message processing time. (This same TEEP security 611 wrapper is also used on messages like QueryRequest so that Agents 612 only send potentially sensitive data such as evidence to trusted 613 TAMs.) 615 The Trusted Component signer on the other hand is what authorizes the 616 Trusted Component to actually run, so the manifest signature could be 617 checked at install time or load (or run) time or both, and this 618 checking is done by the TEE independent of whether TEEP is used or 619 some other update mechanism. See section 5 of 620 [I-D.ietf-teep-architecture] for further discussion. 622 4.5. Success Message 624 The Success message is used by the TEEP Agent to return a success in 625 response to an Update message. 627 Like other TEEP messages, the Success message is signed, and the 628 relevant CDDL snippet is shown below. The complete CDDL structure is 629 shown in Appendix C. 631 teep-success = [ 632 type: TEEP-TYPE-teep-success, 633 options: { 634 ? token => bstr .size (8..64), 635 ? msg => text .size (1..128), 636 ? suit-reports => [ + suit-report ], 637 * $$teep-success-extensions, 638 * $$teep-option-extensions 639 } 640 ] 642 The Success message has the following fields: 644 type 645 The value of (5) corresponds to corresponds to a Success message 646 sent from the TEEP Agent to the TAM. 648 token 649 The value in the token parameter is used to match responses to 650 requests. It MUST match the value of the token parameter in the 651 Update message the Success is in response to, if one was present. 652 If none was present, the token MUST be absent in the Success 653 message. 655 msg 656 The msg parameter contains optional diagnostics information 657 encoded in UTF-8 [RFC3629] using Net-Unicode form [RFC5198] with 658 max 128 bytes returned by the TEEP Agent. 660 suit-reports 661 If present, the suit-reports parameter contains a set of SUIT 662 Reports as defined in Section 4 of [I-D.moran-suit-report]. If 663 the suit-report-nonce field is present in the SUIT Report, is 664 value MUST match the value of the token parameter in the Update 665 message the Success message is in response to. 667 4.6. Error Message 669 The Error message is used by the TEEP Agent to return an error in 670 response to an Update message. 672 Like other TEEP messages, the Error message is signed, and the 673 relevant CDDL snippet is shown below. The complete CDDL structure is 674 shown in Appendix C. 676 teep-error = [ 677 type: TEEP-TYPE-teep-error, 678 options: { 679 ? token => bstr .size (8..64), 680 ? err-msg => text .size (1..128), 681 ? supported-cipher-suites => [ + suite ], 682 ? supported-freshness-mechanisms => [ + freshness-mechanism ], 683 ? versions => [ + version ], 684 ? suit-reports => [ + suit-report ], 685 * $$teep-error-extensions, 686 * $$teep-option-extensions 687 }, 688 err-code: uint (0..23) 689 ] 691 The Error message has the following fields: 693 type 694 The value of (6) corresponds to an Error message sent from the 695 TEEP Agent to the TAM. 697 token 698 The value in the token parameter is used to match responses to 699 requests. It MUST match the value of the token parameter in the 700 Update message the Success is in response to, if one was present. 701 If none was present, the token MUST be absent in the Error 702 message. 704 err-msg 705 The err-msg parameter is human-readable diagnostic text that MUST 706 be encoded using UTF-8 [RFC3629] using Net-Unicode form [RFC5198] 707 with max 128 bytes. 709 supported-cipher-suites 710 The supported-cipher-suites parameter lists the ciphersuite(s) 711 supported by the TEEP Agent. Details about the ciphersuite 712 encoding can be found in Section 7. This field is optional but 713 MUST be returned with the ERR_UNSUPPORTED_CRYPTO_ALG error 714 message. 716 supported-freshness-mechanisms 717 The supported-freshness-mechanisms parameter lists the freshness 718 mechanism(s) supported by the TEEP Agent. Details about the 719 encoding can be found in Section 8. If this parameter is absent, 720 it means only the nonce mechanism is supported. 722 versions 723 The versions parameter enumerates the TEEP protocol version(s) 724 supported by the TEEP Agent. This otherwise optional parameter 725 MUST be returned with the ERR_UNSUPPORTED_MSG_VERSION error 726 message. 728 suit-reports 729 If present, the suit-reports parameter contains a set of SUIT 730 Reports as defined in Section 4 of [I-D.moran-suit-report]. If 731 the suit-report-nonce field is present in the SUIT Report, is 732 value MUST match the value of the token parameter in the Update 733 message the Error message is in response to. 735 err-code 736 The err-code parameter contains one of the error codes listed 737 below). Only selected values are applicable to each message. 739 This specification defines the following initial error messages: 741 ERR_PERMANENT_ERROR (1) 742 The TEEP request contained incorrect fields or fields that are 743 inconsistent with other fields. For diagnosis purposes it is 744 RECOMMMENDED to identify the failure reason in the error message. 745 A TAM receiving this error might refuse to communicate further 746 with the TEEP Agent for some period of time until it has reason to 747 believe it is worth trying again, but it should take care not to 748 give up on communication when there is no attestation evidence 749 indicating that the error is genuine. In contrast, 750 ERR_TEMPORARY_ERROR is an indication that a more agressive retry 751 is warranted. 753 ERR_UNSUPPORTED_EXTENSION (2) 754 The TEEP Agent does not support an extension included in the 755 request message. For diagnosis purposes it is RECOMMMENDED to 756 identify the unsupported extension in the error message. A TAM 757 receiving this error might retry the request without using 758 extensions. 760 ERR_UNSUPPORTED_MSG_VERSION (4) 761 The TEEP Agent does not support the TEEP protocol version 762 indicated in the request message. A TAM receiving this error 763 might retry the request using a different TEEP protocol version. 765 ERR_UNSUPPORTED_CRYPTO_ALG (5) 766 The TEEP Agent does not support the cryptographic algorithm 767 indicated in the request message. A TAM receiving this error 768 might retry the request using a different cryptographic algorithm. 770 ERR_BAD_CERTIFICATE (6) 771 Processing of a certificate failed. For diagnosis purposes it is 772 RECOMMMENDED to include information about the failing certificate 773 in the error message. For example, the certificate was of an 774 unsupported type, or the certificate was revoked by its signer. A 775 TAM receiving this error might attempt to use an alternate 776 certificate. 778 ERR_CERTIFICATE_EXPIRED (9) 779 A certificate has expired or is not currently valid. A TAM 780 receiving this error might attempt to renew its certificate before 781 using it again. 783 ERR_TEMPORARY_ERROR (10) 784 A miscellaneous temporary error, such as a memory allocation 785 failure, occurred while processing the request message. A TAM 786 receiving this error might retry the same request at a later point 787 in time. 789 ERR_MANIFEST_PROCESSING_FAILED (17) 790 The TEEP Agent encountered one or more manifest processing 791 failures. If the suit-reports parameter is present, it contains 792 the failure details. A TAM receiving this error might still 793 attempt to install or update other components that do not depend 794 on the failed manifest. 796 New error codes should be added sparingly, not for every 797 implementation error. That is the intent of the err-msg field, which 798 can be used to provide details meaningful to humans. New error codes 799 should only be added if the TAM is expected to do something 800 behaviorally different upon receipt of the error message, rather than 801 just logging the event. Hence, each error code is responsible for 802 saying what the behavioral difference is expected to be. 804 5. Mapping of TEEP Message Parameters to CBOR Labels 806 In COSE, arrays and maps use strings, negative integers, and unsigned 807 integers as their keys. Integers are used for compactness of 808 encoding. Since the word "key" is mainly used in its other meaning, 809 as a cryptographic key, this specification uses the term "label" for 810 this usage as a map key. 812 This specification uses the following mapping: 814 +--------------------------------+-------+ 815 | Name | Label | 816 +--------------------------------+-------+ 817 | supported-cipher-suites | 1 | 818 | challenge | 2 | 819 | version | 3 | 820 | ocsp-data | 4 | 821 | selected-cipher-suite | 5 | 822 | selected-version | 6 | 823 | evidence | 7 | 824 | tc-list | 8 | 825 | ext-list | 9 | 826 | manifest-list | 10 | 827 | msg | 11 | 828 | err-msg | 12 | 829 | evidence-format | 13 | 830 | requested-tc-list | 14 | 831 | unneeded-tc-list | 15 | 832 | component-id | 16 | 833 | tc-manifest-sequence-number | 17 | 834 | have-binary | 18 | 835 | suit-reports | 19 | 836 | token | 20 | 837 | supported-freshness-mechanisms | 21 | 838 +--------------------------------+-------+ 840 6. Behavior Specification 842 Behavior is specified in terms of the conceptual APIs defined in 843 section 6.2.1 of [I-D.ietf-teep-architecture]. 845 6.1. TAM Behavior 847 When the ProcessConnect API is invoked, the TAM sends a QueryRequest 848 message. 850 When the ProcessTeepMessage API is invoked, the TAM first does 851 validation as specified in Section 4.1.2, and drops the message if it 852 is not valid. Otherwise, it proceeds as follows. 854 If the message includes a token, it can be used to match the response 855 to a request previously sent by the TAM. The TAM MUST expire the 856 token value after receiving the first response from the device that 857 has a valid signature and ignore any subsequent messages that have 858 the same token value. The token value MUST NOT be used for other 859 purposes, such as a TAM to identify the devices and/or a device to 860 identify TAMs or Trusted Components. 862 If a QueryResponse message is received that contains evidence, the 863 evidence is passed to an attestation Verifier (see 864 [I-D.ietf-rats-architecture]) to determine whether the Agent is in a 865 trustworthy state. Based on the results of attestation, and the 866 lists of installed, requested, and unneeded Trusted Components 867 reported in the QueryResponse, the TAM determines, in any 868 implementation specific manner, which Trusted Components need to be 869 installed, updated, or deleted, if any. If any Trusted Components 870 need to be installed, updated, or deleted, the TAM sends an Update 871 message containing SUIT Manifests with command sequences to do the 872 relevant installs, updates, or deletes. It is important to note that 873 the TEEP Agent's Update Procedure requires resolving and installing 874 any dependencies indicated in the manifest, which may take some time, 875 and the resulting Success or Error message is generated only after 876 completing the Update Procedure. Hence, depending on the freshness 877 mechanism in use, the TAM may need to store data (e.g., a nonce) for 878 some time. 880 If a Success or Error message is received containing one or more SUIT 881 Reports, the TAM also validates that the nonce in any SUIT Report 882 matches the token sent in the Update message, and drops the message 883 if it does not match. Otherwise, the TAM handles the update in any 884 implementation specific way, such as updating any locally cached 885 information about the state of the TEEP Agent, or logging the 886 results. 888 If any other Error message is received, the TAM can handle it in any 889 implementation specific way, but Section 4.6 provides recommendations 890 for such handling. 892 6.2. TEEP Agent Behavior 894 When the RequestTA API is invoked, the TEEP Agent first checks 895 whether the requested TA is already installed. If it is already 896 installed, the TEEP Agent passes no data back to the caller. 897 Otherwise, if the TEEP Agent chooses to initiate the process of 898 requesting the indicated TA, it determines (in any implementation 899 specific way) the TAM URI based on any TAM URI provided by the 900 RequestTA caller and any local configuration, and passes back the TAM 901 URI to connect to. 903 When the RequestPolicyCheck API is invoked, the TEEP Agent decides 904 whether to initiate communication with any trusted TAMs (e.g., it 905 might choose to do so for a given TAM unless it detects that it has 906 already communicated with that TAM recently). If so, it passes back 907 a TAM URI to connect to. If the TEEP Agent has multiple TAMs it 908 needs to connect with, it just passes back one, with the expectation 909 that RequestPolicyCheck API will be invoked to retrieve each one 910 successively until there are no more and it can pass back no data at 911 that time. Thus, once a TAM URI is returned, the TEEP Agent can 912 remember that it has already initiated communication with that TAM. 914 When the ProcessError API is invoked, the TEEP Agent can handle it in 915 any implementation specific way, such as logging the error or using 916 the information in future choices of TAM URI. 918 When the ProcessTeepMessage API is invoked, the Agent first does 919 validation as specified in Section 4.1.2, and drops the message if it 920 is not valid. Otherwise, processing continues as follows based on 921 the type of message. 923 When a QueryRequest message is received, the Agent responds with a 924 QueryResponse message if all fields were understood, or an Error 925 message if any error was encountered. 927 When an Update message is received, the Agent attempts to update the 928 Trusted Components specified in the SUIT manifests by following the 929 Update Procedure specified in [I-D.ietf-suit-manifest], and responds 930 with a Success message if all SUIT manifests were successfully 931 installed, or an Error message if any error was encountered. It is 932 important to note that the Update Procedure requires resolving and 933 installing any dependencies indicated in the manifest, which may take 934 some time, and the Success or Error message is generated only after 935 completing the Update Procedure. 937 7. Ciphersuites 939 A ciphersuite consists of an AEAD algorithm, a MAC algorithm, and a 940 signature algorithm. Each ciphersuite is identified with an integer 941 value, which corresponds to an IANA registered ciphersuite (see 942 Section 10.2. This document specifies two ciphersuites. 944 +-------+------------------------------------------------+ 945 | Value | Ciphersuite | 946 +-------+------------------------------------------------+ 947 | 1 | AES-CCM-16-64-128, HMAC 256/256, X25519, EdDSA | 948 | 2 | AES-CCM-16-64-128, HMAC 256/256, P-256, ES256 | 949 +-------+------------------------------------------------+ 951 A TAM MUST support both ciphersuites. A TEEP Agent MUST support at 952 least one of the two but can choose which one. For example, a TEEP 953 Agent might choose ciphersuite 2 if it has hardware support for it. 955 Any ciphersuites without confidentiality protection can only be added 956 if the associated specification includes a discussion of security 957 considerations and applicability, since manifests may carry sensitive 958 information. For example, Section 6 of [I-D.ietf-teep-architecture] 959 permits implementations that terminate transport security inside the 960 TEE and if the transport security provides confidentiality then 961 additional encryption might not be needed in the manifest for some 962 use cases. For most use cases, however, manifest confidentiality 963 will be needed to protect sensitive fields from the TAM as discussed 964 in Section 9.8 of [I-D.ietf-teep-architecture]. 966 8. Freshness Mechanisms 968 A freshness mechanism determines how a TAM can tell whether evidence 969 provided in a Query Response is fresh. There are multiple ways this 970 can be done as discussed in Section 10 of 971 [I-D.ietf-rats-architecture]. 973 Each freshness mechanism is identified with an integer value, which 974 corresponds to an IANA registered freshness mechanism (see 975 Section 10.3. This document defines the following freshness 976 mechanisms: 978 +-------+---------------------+ 979 | Value | Freshness mechanism | 980 +-------+---------------------+ 981 | 1 | Nonce | 982 | 2 | Timestamp | 983 | 3 | Epoch ID | 984 +-------+---------------------+ 986 In the Nonce mechanism, the evidence MUST include a nonce provided in 987 the QueryRequest challenge. In other mechanisms, a timestamp or 988 epoch ID determined via mechanisms outside the TEEP protocol is used, 989 and the challenge is only needed in the QueryRequest message if a 990 challenge is needed in generating evidence for reasons other than 991 freshness. 993 9. Security Considerations 995 This section summarizes the security considerations discussed in this 996 specification: 998 Cryptographic Algorithms 999 TEEP protocol messages exchanged between the TAM and the TEEP 1000 Agent are protected using COSE. This specification relies on the 1001 cryptographic algorithms provided by COSE. Public key based 1002 authentication is used by the TEEP Agent to authenticate the TAM 1003 and vice versa. 1005 Attestation 1006 A TAM can rely on the attestation evidence provided by the TEEP 1007 Agent. To sign the attestation evidence, it is necessary for the 1008 device to possess a public key (usually in the form of a 1009 certificate [RFC5280]) along with the corresponding private key. 1010 Depending on the properties of the attestation mechanism, it is 1011 possible to uniquely identify a device based on information in the 1012 attestation evidence or in the certificate used to sign the 1013 attestation evidence. This uniqueness may raise privacy concerns. 1014 To lower the privacy implications the TEEP Agent MUST present its 1015 attestation evidence only to an authenticated and authorized TAM 1016 and when using EATS, it SHOULD use encryption as discussed in 1017 [I-D.ietf-rats-eat], since confidentiality is not provided by the 1018 TEEP protocol itself and the transport protocol under the TEEP 1019 protocol might be implemented outside of any TEE. If any 1020 mechanism other than EATs is used, it is up to that mechanism to 1021 specify how privacy is provided. 1023 Trusted Component Binaries 1024 Each Trusted Component binary is signed by a Trusted Component 1025 Signer. It is the responsibility of the TAM to relay only 1026 verified Trusted Components from authorized Trusted Component 1027 Signers. Delivery of a Trusted Component to the TEEP Agent is 1028 then the responsibility of the TAM, using the security mechanisms 1029 provided by the TEEP protocol. To protect the Trusted Component 1030 binary, the SUIT manifest format is used and it offers a variety 1031 of security features, including digitial signatures and symmetric 1032 encryption. 1034 Personalization Data 1035 A Trusted Component Signer or TAM can supply personalization data 1036 along with a Trusted Component. This data is also protected by a 1037 SUIT manifest. Personalization data signed and encrypted by a 1038 Trusted Component Signer other than the TAM is opaque to the TAM. 1040 TEEP Broker 1041 As discussed in section 6 of [I-D.ietf-teep-architecture], the 1042 TEEP protocol typically relies on a TEEP Broker to relay messages 1043 between the TAM and the TEEP Agent. When the TEEP Broker is 1044 compromised it can drop messages, delay the delivery of messages, 1045 and replay messages but it cannot modify those messages. (A 1046 replay would be, however, detected by the TEEP Agent.) A 1047 compromised TEEP Broker could reorder messages in an attempt to 1048 install an old version of a Trusted Component. Information in the 1049 manifest ensures that TEEP Agents are protected against such 1050 downgrade attacks based on features offered by the manifest 1051 itself. 1053 Trusted Component Signer Compromise 1054 The QueryRequest message from a TAM to the TEEP Agent can include 1055 OCSP stapling data for the TAM's certificate and for intermediate 1056 CA certificates up to, but not including, the trust anchor so that 1057 the TEEP Agent can verify the certificate's revocation status. A 1058 certificate revocation status check on a Trusted Component Signer 1059 certificate is OPTIONAL by a TEEP Agent. A TAM is responsible for 1060 vetting a Trusted Component and before distributing them to TEEP 1061 Agents, so TEEP Agents can instead simply trust that a Trusted 1062 Component Signer certificate's status was done by the TAM. 1064 CA Compromise 1065 The CA issuing certificates to a TAM or a Trusted Component Signer 1066 might get compromised. A compromised intermediate CA certificate 1067 can be detected by a TEEP Agent by using OCSP information, 1068 assuming the revocation information is available. Additionally, 1069 it is RECOMMENDED to provide a way to update the trust anchor 1070 store used by the TEE, for example using a firmware update 1071 mechanism. If the CA issuing certificates to devices gets 1072 compromised then these devices might be rejected by a TAM, if 1073 revocation is available to the TAM. 1075 Compromised TAM 1076 The TEEP Agent SHOULD use OCSP information to verify the validity 1077 of the TAM's certificate (as well as the validity of intermediate 1078 CA certificates). The integrity and the accuracy of the clock 1079 within the TEE determines the ability to determine an expired or 1080 revoked certificate. OCSP stapling data includes signature 1081 generation time, allowing certificate validity dates to be 1082 compared to the current time. 1084 Compromised Time Source 1085 As discussed above, certificate validity checks rely on comparing 1086 validity dates to the current time, which relies on having a 1087 trusted source of time, such as [RFC8915]. A compromised time 1088 source could thus be used to subvert such validity checks. 1090 10. IANA Considerations 1092 10.1. Media Type Registration 1094 IANA is requested to assign a media type for application/teep+cbor. 1096 Type name: application 1098 Subtype name: teep+cbor 1100 Required parameters: none 1101 Optional parameters: none 1103 Encoding considerations: Same as encoding considerations of 1104 application/cbor. 1106 Security considerations: See Security Considerations Section of this 1107 document. 1109 Interoperability considerations: Same as interoperability 1110 considerations of application/cbor as specified in [RFC7049]. 1112 Published specification: This document. 1114 Applications that use this media type: TEEP protocol implementations 1116 Fragment identifier considerations: N/A 1118 Additional information: 1120 Deprecated alias names for this type: N/A 1122 Magic number(s): N/A 1124 File extension(s): N/A 1126 Macintosh file type code(s): N/A 1128 Person to contact for further information: teep@ietf.org 1130 Intended usage: COMMON 1132 Restrictions on usage: none 1134 Author: See the "Authors' Addresses" section of this document 1136 Change controller: IETF 1138 10.2. Ciphersuite Registry 1140 IANA is also requested to create a new registry for ciphersuites, as 1141 defined in Section 7. 1143 10.3. Freshness Mechanism Registry 1145 IANA is also requested to create a new registry for freshness 1146 mechanisms, as defined in Section 8. 1148 10.4. CBOR Tag Registry 1150 IANA is requested to register a CBOR tag in the "CBOR Tags" registry 1151 for use with TEEP messages. 1153 The registry contents is: 1155 o CBOR Tag: TBD1 1157 o Data Item: TEEP Message 1159 o Semantics: TEEP Message, as defined in draft-ietf-teep-protocol 1160 (TODO: replace with RFC once published) 1162 o Reference: draft-ietf-teep-protocol (TODO: replace with RFC once 1163 published) 1165 o Point of Contact: TEEP working group (teep@ietf.org) 1167 11. References 1169 11.1. Normative References 1171 [I-D.ietf-rats-architecture] 1172 Birkholz, H., Thaler, D., Richardson, M., Smith, N., and 1173 W. Pan, "Remote Attestation Procedures Architecture", 1174 draft-ietf-rats-architecture-12 (work in progress), April 1175 2021. 1177 [I-D.ietf-rats-eat] 1178 Mandyam, G., Lundblade, L., Ballesteros, M., and J. 1179 O'Donoghue, "The Entity Attestation Token (EAT)", draft- 1180 ietf-rats-eat-10 (work in progress), June 2021. 1182 [I-D.ietf-suit-manifest] 1183 Moran, B., Tschofenig, H., Birkholz, H., and K. Zandberg, 1184 "A Concise Binary Object Representation (CBOR)-based 1185 Serialization Format for the Software Updates for Internet 1186 of Things (SUIT) Manifest", draft-ietf-suit-manifest-14 1187 (work in progress), July 2021. 1189 [I-D.moran-suit-report] 1190 Moran, B., "Secure Reporting of Update Status", draft- 1191 moran-suit-report-01 (work in progress), February 2021. 1193 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1194 Requirement Levels", BCP 14, RFC 2119, 1195 DOI 10.17487/RFC2119, March 1997, 1196 . 1198 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1199 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 1200 2003, . 1202 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 1203 Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, 1204 . 1206 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1207 Housley, R., and W. Polk, "Internet X.509 Public Key 1208 Infrastructure Certificate and Certificate Revocation List 1209 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1210 . 1212 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 1213 Galperin, S., and C. Adams, "X.509 Internet Public Key 1214 Infrastructure Online Certificate Status Protocol - OCSP", 1215 RFC 6960, DOI 10.17487/RFC6960, June 2013, 1216 . 1218 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1219 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1220 October 2013, . 1222 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1223 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1224 . 1226 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1227 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1228 May 2017, . 1230 11.2. Informative References 1232 [I-D.birkholz-rats-suit-claims] 1233 Birkholz, H. and B. Moran, "Trustworthiness Vectors for 1234 the Software Updates of Internet of Things (SUIT) Workflow 1235 Model", draft-birkholz-rats-suit-claims-02 (work in 1236 progress), July 2021. 1238 [I-D.ietf-teep-architecture] 1239 Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, 1240 "Trusted Execution Environment Provisioning (TEEP) 1241 Architecture", draft-ietf-teep-architecture-15 (work in 1242 progress), July 2021. 1244 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1245 Writing an IANA Considerations Section in RFCs", BCP 26, 1246 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1247 . 1249 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 1250 Definition Language (CDDL): A Notational Convention to 1251 Express Concise Binary Object Representation (CBOR) and 1252 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 1253 June 2019, . 1255 [RFC8915] Franke, D., Sibold, D., Teichel, K., Dansarie, M., and R. 1256 Sundblad, "Network Time Security for the Network Time 1257 Protocol", RFC 8915, DOI 10.17487/RFC8915, September 2020, 1258 . 1260 A. Contributors 1262 We would like to thank Brian Witten (Symantec), Tyler Kim (Solacia), 1263 Nick Cook (Arm), and Minho Yoo (IoTrust) for their contributions to 1264 the Open Trust Protocol (OTrP), which influenced the design of this 1265 specification. 1267 B. Acknowledgements 1269 We would like to thank Eve Schooler for the suggestion of the 1270 protocol name. 1272 We would like to thank Kohei Isobe (TRASIO/SECOM), Kuniyasu Suzaki 1273 (TRASIO/AIST), Tsukasa Oi (TRASIO), and Yuichi Takita (SECOM) for 1274 their valuable implementation feedback. 1276 We would also like to thank Carsten Bormann and Henk Birkholz for 1277 their help with the CDDL. 1279 C. Complete CDDL 1281 Valid TEEP messages MUST adhere to the following CDDL data 1282 definitions, except that "SUIT_Envelope" and 1283 "SUIT_Component_Identifier" are specified in 1284 [I-D.ietf-suit-manifest]. 1286 teep-message = $teep-message-type .within teep-message-framework 1288 SUIT_Envelope = any 1290 teep-message-framework = [ 1291 type: uint (0..23) / $teep-type-extension, 1292 options: { * teep-option }, 1293 * uint; further integers, e.g., for data-item-requested 1294 ] 1296 teep-option = (uint => any) 1298 ; messages defined below: 1299 $teep-message-type /= query-request 1300 $teep-message-type /= query-response 1301 $teep-message-type /= update 1302 $teep-message-type /= teep-success 1303 $teep-message-type /= teep-error 1305 ; message type numbers, uint (0..23) 1306 TEEP-TYPE-query-request = 1 1307 TEEP-TYPE-query-response = 2 1308 TEEP-TYPE-update = 3 1309 TEEP-TYPE-teep-success = 5 1310 TEEP-TYPE-teep-error = 6 1312 version = .within uint .size 4 1313 ext-info = .within uint .size 4 1315 ; data items as bitmaps 1316 data-item-requested = $data-item-requested .within uint .size 8 1317 attestation = 1 1318 $data-item-requested /= attestation 1319 trusted-components = 2 1320 $data-item-requested /= trusted-components 1321 extensions = 4 1322 $data-item-requested /= extensions 1323 suit-commands = 8 1324 $data-item-requested /= suit-commands 1326 query-request = [ 1327 type: TEEP-TYPE-query-request, 1328 options: { 1329 ? token => bstr .size (8..64), 1330 ? supported-cipher-suites => [ + suite ], 1331 ? supported-freshness-mechanisms => [ + freshness-mechanism ], 1332 ? challenge => bstr .size (8..512), 1333 ? versions => [ + version ], 1334 ? ocsp-data => bstr, 1335 * $$query-request-extensions 1336 * $$teep-option-extensions 1337 }, 1338 data-item-requested: data-item-requested 1339 ] 1341 ; ciphersuites 1342 suite = $TEEP-suite .within uint .size 4 1344 TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 1 1345 TEEP-AES-CCM-16-64-128-HMAC256--256-P-256-ES256 = 2 1347 $TEEP-suite /= TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA 1348 $TEEP-suite /= TEEP-AES-CCM-16-64-128-HMAC256--256-P-256-ES256 1350 ; freshness-mechanisms 1352 freshness-mechanism = $TEEP-freshness-mechanism .within uint .size 4 1354 FRESHNESS_NONCE = 0 1355 FRESHNESS_TIMESTAMP = 1 1356 FRESHNESS_EPOCH_ID = 2 1358 $TEEP-freshness-mechanism /= FRESHNESS_NONCE 1359 $TEEP-freshness-mechanism /= FRESHNESS_TIMESTAMP 1360 $TEEP-freshness-mechanism /= FRESHNESS_EPOCH_ID 1362 query-response = [ 1363 type: TEEP-TYPE-query-response, 1364 options: { 1365 ? token => bstr .size (8..64), 1366 ? selected-cipher-suite => suite, 1367 ? selected-version => version, 1368 ? evidence-format => text, 1369 ? evidence => bstr, 1370 ? tc-list => [ + tc-info ], 1371 ? requested-tc-list => [ + requested-tc-info ], 1372 ? unneeded-tc-list => [ + SUIT_Component_Identifier ], 1373 ? ext-list => [ + ext-info ], 1374 * $$query-response-extensions, 1375 * $$teep-option-extensions 1376 } 1377 ] 1379 tc-info = { 1380 component-id => SUIT_Component_Identifier, 1381 ? tc-manifest-sequence-number => .within uint .size 8 1383 } 1385 requested-tc-info = { 1386 component-id => SUIT_Component_Identifier, 1387 ? tc-manifest-sequence-number => .within uint .size 8 1388 ? have-binary => bool 1389 } 1391 update = [ 1392 type: TEEP-TYPE-update, 1393 options: { 1394 ? token => bstr .size (8..64), 1395 ? manifest-list => [ + bstr .cbor SUIT_Envelope ], 1396 * $$update-extensions, 1397 * $$teep-option-extensions 1398 } 1399 ] 1401 teep-success = [ 1402 type: TEEP-TYPE-teep-success, 1403 options: { 1404 ? token => bstr .size (8..64), 1405 ? msg => text .size (1..128), 1406 ? suit-reports => [ + suit-report ], 1407 * $$teep-success-extensions, 1408 * $$teep-option-extensions 1409 } 1410 ] 1412 teep-error = [ 1413 type: TEEP-TYPE-teep-error, 1414 options: { 1415 ? token => bstr .size (8..64), 1416 ? err-msg => text .size (1..128), 1417 ? supported-cipher-suites => [ + suite ], 1418 ? supported-freshness-mechanisms => [ + freshness-mechanism ], 1419 ? versions => [ + version ], 1420 ? suit-reports => [ + suit-report ], 1421 * $$teep-error-extensions, 1422 * $$teep-option-extensions 1423 }, 1424 err-code: uint (0..23) 1425 ] 1427 ; The err-code parameter, uint (0..23) 1428 ERR_PERMANENT_ERROR = 1 1429 ERR_UNSUPPORTED_EXTENSION = 2 1430 ERR_UNSUPPORTED_MSG_VERSION = 4 1431 ERR_UNSUPPORTED_CRYPTO_ALG = 5 1432 ERR_BAD_CERTIFICATE = 6 1433 ERR_CERTIFICATE_EXPIRED = 9 1434 ERR_TEMPORARY_ERROR = 10 1435 ERR_MANIFEST_PROCESSING_FAILED = 17 1437 ; labels of mapkey for teep message parameters, uint (0..23) 1438 supported-cipher-suites = 1 1439 challenge = 2 1440 versions = 3 1441 ocsp-data = 4 1442 selected-cipher-suite = 5 1443 selected-version = 6 1444 evidence = 7 1445 tc-list = 8 1446 ext-list = 9 1447 manifest-list = 10 1448 msg = 11 1449 err-msg = 12 1450 evidence-format = 13 1451 requested-tc-list = 14 1452 unneeded-tc-list = 15 1453 component-id = 16 1454 tc-manifest-sequence-number = 17 1455 have-binary = 18 1456 suit-reports = 19 1457 token = 20 1459 D. Examples of Diagnostic Notation and Binary Representation 1461 D.1. Some assumptions in examples 1463 o OCSP stapling data = h'010203' 1465 o TEEP Device will have two TCs with the following SUIT Component 1466 Identifiers: 1468 * [ 0x000102030405060708090a0b0c0d0e0f ] 1470 * [ 0x100102030405060708090a0b0c0d0e0f ] 1472 o SUIT manifest-list is set empty only for example purposes 1474 D.2. QueryRequest Message 1475 D.2.1. CBOR Diagnostic Notation 1477 / query-request = / 1478 [ 1479 1, / type : TEEP-TYPE-query-request = 1 (uint (0..23)) / 1480 / options : / 1481 { 1482 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 1483 / token = 20 (mapkey) : 1484 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 1485 generated by TAM / 1486 1 : [ 1 ], / supported-cipher-suites = 1 (mapkey) : 1487 TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 1488 [ 1 ] (array of .within uint .size 4) / 1489 3 : [ 0 ], / version = 3 (mapkey) : 1490 [ 0 ] (array of .within uint .size 4) / 1491 4 : h'010203' / ocsp-data = 4 (mapkey) : 0x010203 (bstr) / 1492 }, 1493 3 / data-item-requested : 1494 attestation | trusted-components = 3 (.within uint .size 8) / 1495 ] 1497 D.2.2. CBOR Binary Representation 1499 83 # array(3) 1500 01 # unsigned(1) uint (0..23) 1501 A4 # map(4) 1502 14 # unsigned(20) uint (0..23) 1503 4F # bytes(16) (8..64) 1504 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 1505 01 # unsigned(1) uint (0..23) 1506 81 # array(1) 1507 01 # unsigned(1) within uint .size 4 1508 03 # unsigned(3) uint (0..23) 1509 81 # array(1) 1510 00 # unsigned(0) within uint .size 4 1511 04 # unsigned(4) uint (0..23) 1512 43 # bytes(3) 1513 010203 # "\x01\x02\x03" 1514 03 # unsigned(3) .within uint .size 8 1516 D.3. Entity Attestation Token 1518 This is shown below in CBOR diagnostic form. Only the payload signed 1519 by COSE is shown. 1521 D.3.1. CBOR Diagnostic Notation 1523 / eat-claim-set = / 1524 { 1525 / issuer / 1: "joe", 1526 / timestamp (iat) / 6: 1(1526542894) 1527 / nonce / 10: h'948f8860d13a463e8e', 1528 / secure-boot / 15: true, 1529 / debug-status / 16: 3, / disabled-permanently / 1530 / security-level / : 3, / secure-restricted / 1531 / device-identifier / : h'e99600dd921649798b013e9752dcf0c5', 1532 / vendor-identifier / : h'2b03879b33434a7ca682b8af84c19fd4', 1533 / class-identifier / : h'9714a5796bd245a3a4ab4f977cb8487f', 1534 / chip-version-scheme / : "MyTEE v1.0", 1535 / component-identifier / : h'60822887d35e43d5b603d18bcaa3f08d', 1536 / version / : "v0.1" 1537 } 1539 D.4. QueryResponse Message 1541 D.4.1. CBOR Diagnostic Notation 1542 / query-response = / 1543 [ 1544 2, / type : TEEP-TYPE-query-response = 2 (uint (0..23)) / 1545 / options : / 1546 { 1547 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 1548 / token = 20 (mapkey) : 1549 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 1550 given from TAM's QueryRequest message / 1551 5 : 1, / selected-cipher-suite = 5 (mapkey) : 1552 TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 1553 1 (.within uint .size 4) / 1554 6 : 0, / selected-version = 6 (mapkey) : 1555 0 (.within uint .size 4) / 1556 7 : ... / evidence = 7 (mapkey) : 1557 Entity Attestation Token / 1558 8 : [ / tc-list = 8 (mapkey) : (array of tc-info) / 1559 { 1560 16 : [ 0x000102030405060708090a0b0c0d0e0f ] / component-id = 1561 16 (mapkey) : [ h'000102030405060708090a0b0c0d0e0f' ] 1562 (SUIT_Component_Identifier = [* bstr]) / 1563 }, 1564 { 1565 16 : [ 0x100102030405060708090a0b0c0d0e0f ] / component-id = 1566 16 (mapkey) : [ h'100102030405060708090a0b0c0d0e0f' ] 1567 (SUIT_Component_Identifier = [* bstr]) / 1568 } 1569 ] 1570 } 1571 ] 1573 D.4.2. CBOR Binary Representation 1574 82 # array(2) 1575 02 # unsigned(2) uint (0..23) 1576 A5 # map(5) 1577 14 # unsigned(20) uint (0..23) 1578 4F # bytes(16) (8..64) 1579 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 1580 05 # unsigned(5) uint (0..23) 1581 01 # unsigned(1) .within uint .size 4 1582 06 # unsigned(6) uint (0..23) 1583 00 # unsigned(0) .within uint .size 4 1584 07 # unsigned(7) uint (0..23) 1585 ... # Entity Attestation Token 1586 08 # unsigned(8) uint (0..23) 1587 82 # array(2) 1588 81 # array(1) 1589 4F # bytes(16) 1590 000102030405060708090A0B0C0D0E0F 1591 81 # array(1) 1592 4F # bytes(16) 1593 100102030405060708090A0B0C0D0E0F 1595 D.5. Update Message 1597 D.5.1. CBOR Diagnostic Notation 1599 / update = / 1600 [ 1601 3, / type : TEEP-TYPE-update = 3 (uint (0..23)) / 1602 / options : / 1603 { 1604 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 1605 / token = 20 (mapkey) : 1606 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 1607 generated by TAM / 1608 10 : [ ] / manifest-list = 10 (mapkey) : 1609 [ ] (array of bstr wrapped SUIT_Envelope(any)) / 1610 / empty, example purpose only / 1611 } 1612 ] 1614 D.5.2. CBOR Binary Representation 1615 82 # array(2) 1616 03 # unsigned(3) uint (0..23) 1617 A3 # map(3) 1618 14 # unsigned(20) uint (0..23) 1619 4F # bytes(16) (8..64) 1620 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 1621 0A # unsigned(10) uint (0..23) 1622 80 # array(0) 1624 D.6. Success Message 1626 D.6.1. CBOR Diagnostic Notation 1628 / teep-success = / 1629 [ 1630 5, / type : TEEP-TYPE-teep-success = 5 (uint (0..23)) / 1631 / options : / 1632 { 1633 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 1634 / token = 20 (mapkey) : 1635 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 1636 given from TAM's Update message / 1637 } 1638 ] 1640 D.6.2. CBOR Binary Representation 1642 82 # array(2) 1643 05 # unsigned(5) uint (0..23) 1644 A1 # map(1) 1645 14 # unsigned(20) uint (0..23) 1646 4F # bytes(16) (8..64) 1647 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 1649 D.7. Error Message 1651 D.7.1. CBOR Diagnostic Notation 1652 / teep-error = / 1653 [ 1654 6, / type : TEEP-TYPE-teep-error = 6 (uint (0..23)) / 1655 / options : / 1656 { 1657 20 : 0xa0a1a2a3a4a5a6a7a8a9aaabacadaeaf, 1658 / token = 20 (mapkey) : 1659 h'a0a1a2a3a4a5a6a7a8a9aaabacadaeaf' (bstr .size (8..64)), 1660 given from TAM's Update message / 1661 12 : "disk-full" / err-msg = 12 (mapkey) : 1662 "disk-full" (text .size (1..128)) / 1663 }, 1664 17, / err-code : ERR_MANIFEST_PROCESSING_FAILED = 17 (uint (0..23)) / 1665 ] 1667 D.7.2. CBOR binary Representation 1669 83 # array(3) 1670 06 # unsigned(6) uint (0..23) 1671 A2 # map(2) 1672 14 # unsigned(20) uint (0..23) 1673 4F # bytes(16) (8..64) 1674 A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 1675 0C # unsigned(12) uint (0..23) 1676 69 # text(9) (1..128) 1677 6469736B2D66756C6C # "disk-full" 1678 11 # unsigned(17) uint (0..23) 1680 Authors' Addresses 1682 Hannes Tschofenig 1683 Arm Ltd. 1684 Absam, Tirol 6067 1685 Austria 1687 Email: hannes.tschofenig@arm.com 1689 Mingliang Pei 1690 Broadcom 1691 350 Ellis St 1692 Mountain View, CA 94043 1693 USA 1695 Email: mingliang.pei@broadcom.com 1696 David Wheeler 1697 Amazon 1698 US 1700 Email: davewhee@amazon.com 1702 Dave Thaler 1703 Microsoft 1704 US 1706 Email: dthaler@microsoft.com 1708 Akira Tsukamoto 1709 AIST 1710 JP 1712 Email: akira.tsukamoto@aist.go.jp