--- 1/draft-ietf-teep-protocol-07.txt 2022-03-07 16:13:30.474999365 -0800 +++ 2/draft-ietf-teep-protocol-08.txt 2022-03-07 16:13:30.607002696 -0800 @@ -1,25 +1,25 @@ TEEP H. Tschofenig Internet-Draft Arm Ltd. Intended status: Standards Track M. Pei -Expires: 28 April 2022 Broadcom +Expires: 8 September 2022 Broadcom D. Wheeler Amazon D. Thaler Microsoft A. Tsukamoto AIST - 25 October 2021 + 7 March 2022 Trusted Execution Environment Provisioning (TEEP) Protocol - draft-ietf-teep-protocol-07 + draft-ietf-teep-protocol-08 Abstract This document specifies a protocol that installs, updates, and deletes Trusted Components in a device with a Trusted Execution Environment (TEE). This specification defines an interoperable protocol for managing the lifecycle of Trusted Components. Status of This Memo @@ -29,91 +29,118 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on 28 April 2022. + This Internet-Draft will expire on 8 September 2022. Copyright Notice - Copyright (c) 2021 IETF Trust and the persons identified as the + Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components - extracted from this document must include Simplified BSD License text - as described in Section 4.e of the Trust Legal Provisions and are - provided without warranty as described in the Simplified BSD License. + extracted from this document must include Revised BSD License text as + described in Section 4.e of the Trust Legal Provisions and are + provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Message Overview . . . . . . . . . . . . . . . . . . . . . . 4 - 4. Detailed Messages Specification . . . . . . . . . . . . . . . 5 - 4.1. Creating and Validating TEEP Messages . . . . . . . . . . 5 - 4.1.1. Creating a TEEP message . . . . . . . . . . . . . . . 5 + 4. Detailed Messages Specification . . . . . . . . . . . . . . . 6 + 4.1. Creating and Validating TEEP Messages . . . . . . . . . . 6 + 4.1.1. Creating a TEEP message . . . . . . . . . . . . . . . 6 4.1.2. Validating a TEEP Message . . . . . . . . . . . . . . 6 - 4.2. QueryRequest Message . . . . . . . . . . . . . . . . . . 6 + 4.2. QueryRequest Message . . . . . . . . . . . . . . . . . . 7 4.3. QueryResponse Message . . . . . . . . . . . . . . . . . . 9 - 4.3.1. Evidence . . . . . . . . . . . . . . . . . . . . . . 11 - 4.4. Update Message . . . . . . . . . . . . . . . . . . . . . 12 - 4.5. Success Message . . . . . . . . . . . . . . . . . . . . . 14 - 4.6. Error Message . . . . . . . . . . . . . . . . . . . . . . 15 - 5. Mapping of TEEP Message Parameters to CBOR Labels . . . . . . 18 - 6. Behavior Specification . . . . . . . . . . . . . . . . . . . 20 - 6.1. TAM Behavior . . . . . . . . . . . . . . . . . . . . . . 20 - 6.2. TEEP Agent Behavior . . . . . . . . . . . . . . . . . . . 21 - 7. Ciphersuites . . . . . . . . . . . . . . . . . . . . . . . . 22 - 8. Freshness Mechanisms . . . . . . . . . . . . . . . . . . . . 22 - 9. Security Considerations . . . . . . . . . . . . . . . . . . . 23 - 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 - 10.1. Media Type Registration . . . . . . . . . . . . . . . . 25 - 10.2. Ciphersuite Registry . . . . . . . . . . . . . . . . . . 26 - 10.3. Freshness Mechanism Registry . . . . . . . . . . . . . . 27 - 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 - 11.1. Normative References . . . . . . . . . . . . . . . . . . 27 - 11.2. Informative References . . . . . . . . . . . . . . . . . 29 - A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 29 - B. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30 - C. Complete CDDL . . . . . . . . . . . . . . . . . . . . . . . . 30 - D. Examples of Diagnostic Notation and Binary Representation . . 34 - D.1. QueryRequest Message . . . . . . . . . . . . . . . . . . 34 - D.1.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 34 - D.1.2. CBOR Binary Representation . . . . . . . . . . . . . 34 - D.2. Entity Attestation Token . . . . . . . . . . . . . . . . 35 - D.2.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 35 - D.3. QueryResponse Message . . . . . . . . . . . . . . . . . . 35 - D.3.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 35 - D.3.2. CBOR Binary Representation . . . . . . . . . . . . . 36 - D.4. Update Message . . . . . . . . . . . . . . . . . . . . . 37 - D.4.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 37 - D.4.2. CBOR Binary Representation . . . . . . . . . . . . . 37 - D.5. Success Message . . . . . . . . . . . . . . . . . . . . . 38 - D.5.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 38 - D.5.2. CBOR Binary Representation . . . . . . . . . . . . . 38 - D.6. Error Message . . . . . . . . . . . . . . . . . . . . . . 38 - D.6.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 38 - D.6.2. CBOR binary Representation . . . . . . . . . . . . . 39 - E. Examples of SUIT Manifests . . . . . . . . . . . . . . . . . 39 - E.1. Install a Trusted Component . . . . . . . . . . . . . . . 39 - E.2. Delete a Trusted Component . . . . . . . . . . . . . . . 43 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 + 4.3.1. Evidence and Attestation Results . . . . . . . . . . 12 + 4.4. Update Message . . . . . . . . . . . . . . . . . . . . . 13 + 4.4.1. Example 1: Having one SUIT Manifest pointing to a URI + of a Trusted Component Binary . . . . . . . . . . . . 15 + 4.4.2. Example 2: Having a SUIT Manifest include the Trusted + Component Binary . . . . . . . . . . . . . . . . . . 17 + 4.4.3. Example 3: Supplying Personalization Data for the + Trusted Component Binary . . . . . . . . . . . . . . 18 + 4.4.4. Example 4: Unlinking Trusted Component . . . . . . . 20 + 4.5. Success Message . . . . . . . . . . . . . . . . . . . . . 21 + 4.6. Error Message . . . . . . . . . . . . . . . . . . . . . . 22 + 5. EAT Profile . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 6. Mapping of TEEP Message Parameters to CBOR Labels . . . . . . 27 + 7. Behavior Specification . . . . . . . . . . . . . . . . . . . 29 + 7.1. TAM Behavior . . . . . . . . . . . . . . . . . . . . . . 29 + 7.2. TEEP Agent Behavior . . . . . . . . . . . . . . . . . . . 30 + 8. Ciphersuites . . . . . . . . . . . . . . . . . . . . . . . . 31 + 9. Freshness Mechanisms . . . . . . . . . . . . . . . . . . . . 32 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 33 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 + 11.1. Media Type Registration . . . . . . . . . . . . . . . . 35 + 11.2. Freshness Mechanism Registry . . . . . . . . . . . . . . 36 + 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 + 12.1. Normative References . . . . . . . . . . . . . . . . . . 36 + 12.2. Informative References . . . . . . . . . . . . . . . . . 38 + A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 39 + B. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39 + C. Complete CDDL . . . . . . . . . . . . . . . . . . . . . . . . 39 + D. Examples of Diagnostic Notation and Binary Representation . . 43 + D.1. QueryRequest Message . . . . . . . . . . . . . . . . . . 43 + D.1.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 43 + D.1.2. CBOR Binary Representation . . . . . . . . . . . . . 44 + D.2. Entity Attestation Token . . . . . . . . . . . . . . . . 44 + D.2.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 44 + D.3. QueryResponse Message . . . . . . . . . . . . . . . . . . 45 + D.3.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 45 + D.3.2. CBOR Binary Representation . . . . . . . . . . . . . 46 + D.4. Update Message . . . . . . . . . . . . . . . . . . . . . 47 + D.4.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 47 + D.4.2. CBOR Binary Representation . . . . . . . . . . . . . 47 + D.5. Success Message . . . . . . . . . . . . . . . . . . . . . 48 + D.5.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 48 + D.5.2. CBOR Binary Representation . . . . . . . . . . . . . 48 + D.6. Error Message . . . . . . . . . . . . . . . . . . . . . . 48 + D.6.1. CBOR Diagnostic Notation . . . . . . . . . . . . . . 48 + D.6.2. CBOR binary Representation . . . . . . . . . . . . . 49 + E. Examples of SUIT Manifests . . . . . . . . . . . . . . . . . 49 + Example 1: SUIT Manifest pointing to URI of the Trusted Component + Binary . . . . . . . . . . . . . . . . . . . . . . . . . 50 + CBOR Diagnostic Notation of SUIT Manifest . . . . . . . . . . 50 + CBOR Binary Representation . . . . . . . . . . . . . . . . . 51 + CBOR Binary in Hex . . . . . . . . . . . . . . . . . . . . . 52 + Example 2: SUIT Manifest including the Trusted Component + Binary . . . . . . . . . . . . . . . . . . . . . . . . . 53 + CBOR Diagnostic Notation of SUIT Manifest . . . . . . . . . . 53 + CBOR Binary Representation . . . . . . . . . . . . . . . . . 54 + CBOR Binary in Hex . . . . . . . . . . . . . . . . . . . . . 56 + Example 3: Supplying Personalization Data for Trusted Component + Binary . . . . . . . . . . . . . . . . . . . . . . . . . 56 + CBOR Diagnostic Notation of SUIT Manifest . . . . . . . . . . 56 + CBOR Binary Represenation . . . . . . . . . . . . . . . . . . 58 + CBOR Binary in Hex . . . . . . . . . . . . . . . . . . . . . 60 + E.4. Example 4: Unlink a Trusted Component . . . . . . . . . . 60 + CBOR Diagnostic Notation of SUIT Manifest . . . . . . . . . . 60 + CBOR Binary Representation . . . . . . . . . . . . . . . . . 61 + CBOR Binary in Hex . . . . . . . . . . . . . . . . . . . . . 63 + F. Examples of SUIT Reports . . . . . . . . . . . . . . . . . . 63 + F.1. Example 1: Success . . . . . . . . . . . . . . . . . . . 63 + F.2. Example 2: Faiure . . . . . . . . . . . . . . . . . . . . 64 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 65 1. Introduction The Trusted Execution Environment (TEE) concept has been designed to separate a regular operating system, also referred as a Rich Execution Environment (REE), from security-sensitive applications. In a TEE ecosystem, device vendors may use different operating systems in the REE and may use different types of TEEs. When Trusted Component Developers or Device Administrators use Trusted Application Managers (TAMs) to install, update, and delete Trusted Applications @@ -224,24 +251,26 @@ } 4.1. Creating and Validating TEEP Messages 4.1.1. Creating a TEEP message To create a TEEP message, the following steps are performed. 1. Create a TEEP message according to the description below and populate it with the respective content. TEEP messages sent by - TAMs (QueryRequest and Update) can include a "token". The first - usage of a token generated by a TAM MUST be randomly created. - Subsequent token values MUST be different for each subsequent - message created by a TAM. + TAMs (QueryRequest and Update) can include a "token". The TAM + can decide, in any implementation-specific way, whether to + include a token in a message. The first usage of a token + generated by a TAM MUST be randomly created. Subsequent token + values MUST be different for each subsequent message created by a + TAM. 2. Create a COSE Header containing the desired set of Header Parameters. The COSE Header MUST be valid per the [RFC8152] specification. 3. Create a COSE_Sign1 object using the TEEP message as the COSE_Sign1 Payload; all steps specified in [RFC8152] for creating a COSE_Sign1 object MUST be followed. 4.1.2. Validating a TEEP Message @@ -264,21 +293,21 @@ Objects") for validating a COSE_Sign1 object. The COSE_Sign1 payload is the content of the TEEP message. 5. Verify that the TEEP message is a valid CBOR map and verify the fields of the TEEP message according to this specification. 4.2. QueryRequest Message A QueryRequest message is used by the TAM to learn information from the TEEP Agent, such as the features supported by the TEEP Agent, - including ciphersuites, and protocol versions. Additionally, the TAM + including ciphersuites and protocol versions. Additionally, the TAM can selectively request data items from the TEEP Agent via the request parameter. Currently, the following features are supported: * Request for attestation information, * Listing supported extensions, * Querying installed Trusted Components, and * Listing supported SUIT commands. @@ -339,55 +368,57 @@ trusted-components (2) With this value the TAM queries the TEEP Agent for all installed Trusted Components. extensions (4) With this value the TAM queries the TEEP Agent for supported capabilities and extensions, which allows a TAM to discover the capabilities of a TEEP Agent implementation. Further values may be added in the future via IANA registration. supported-cipher-suites - The supported-cipher-suites parameter lists the ciphersuite(s) + The supported-cipher-suites parameter lists the ciphersuites supported by the TAM. If this parameter is not present, it is to - be treated the same as if it contained both ciphersuites defined - in this document. Details about the ciphersuite encoding can be - found in Section 7. + be treated the same as if it contained all ciphersuites defined in + this document that are listed as "MUST". Details about the + ciphersuite encoding can be found in Section 8. supported-freshness-mechanisms The supported-freshness-mechanisms parameter lists the freshness mechanism(s) supported by the TAM. Details about the encoding can - be found in Section 8. If this parameter is absent, it means only + be found in Section 9. If this parameter is absent, it means only the nonce mechanism is supported. challenge The challenge field is an optional parameter used for ensuring the freshness of the attestation evidence returned with a QueryResponse message. It MUST be absent if the attestation bit is clear (since the token is used instead in that case). When a challenge is provided in the QueryRequest and an EAT is returned with a QueryResponse message then the challenge contained in this request MUST be used to generate the EAT, such as by copying the - challengt into the nonce claim found in the EAT if using the Nonce - freshness mechanism. For more details see Section 8. If any + challenge into the nonce claim found in the EAT if using the Nonce + freshness mechanism. For more details see Section 9. If any format other than EAT is used, it is up to that format to define the use of the challenge field. versions The versions parameter enumerates the TEEP protocol version(s) supported by the TAM. A value of 0 refers to the current version of the TEEP protocol. If this field is not present, it is to be treated the same as if it contained only version 0. 4.3. QueryResponse Message The QueryResponse message is the successful response by the TEEP - Agent after receiving a QueryRequest message. + Agent after receiving a QueryRequest message. As discussed in + Section 7.2, it can also be sent unsolicited if the contents of the + QueryRequest are already known and do not vary per message. Like other TEEP messages, the QueryResponse message is signed, and the relevant CDDL snippet is shown below. The complete CDDL structure is shown in Appendix C. query-response = [ type: TEEP-TYPE-query-response, options: { ? token => bstr .size (8..64), ? selected-cipher-suite => suite, @@ -422,21 +453,21 @@ token The value in the token parameter is used to match responses to requests. The value MUST correspond to the value received with the QueryRequest message if one was present, and MUST be absent if no token was present in the QueryRequest. selected-cipher-suite The selected-cipher-suite parameter indicates the selected ciphersuite. Details about the ciphersuite encoding can be found - in Section 7. + in Section 8. selected-version The selected-version parameter indicates the TEEP protocol version selected by the TEEP Agent. The absense of this parameter indicates the same as if it was present with a value of 0. evidence-format The evidence-format parameter indicates the IANA Media Type of the attestation evidence contained in the evidence parameter. It MUST be present if the evidence parameter is present and the format is @@ -458,21 +489,21 @@ QueryRequest with the trusted-components bit set. requested-tc-list The requested-tc-list parameter enumerates the Trusted Components that are not currently installed in the TEE, but which are requested to be installed, for example by an installer of an Untrusted Application that has a TA as a dependency, or by a Trusted Application that has another Trusted Component as a dependency. Requested Trusted Components are expressed in the form of requested-tc-info objects. A TEEP Agent can get this - information from the UnrequestTA conceptual API defined in + information from the RequestTA conceptual API defined in [I-D.ietf-teep-architecture] section 6.2.1. unneeded-tc-list The unneeded-tc-list parameter enumerates the Trusted Components that are currently installed in the TEE, but which are no longer needed by any other application. The TAM can use this information in determining whether a Trusted Component can be deleted. Each unneeded Trusted Component is identified by its SUIT Component Identifier. A TEEP Agent can get this information from the UnrequestTA conceptual API defined in [I-D.ietf-teep-architecture] @@ -503,59 +534,67 @@ manifest for the Trusted Component. If not present, indicates that any sequence number will do. have-binary If present with a value of true, indicates that the TEEP agent already has the Trusted Component binary and only needs an Update message with a SUIT manifest that authorizes installing it. If have-binary is true, the tc-manifest-sequence-number field MUST be present. -4.3.1. Evidence +4.3.1. Evidence and Attestation Results - Section 7.1 of [I-D.ietf-teep-architecture] lists information that - may be required in the evidence depend on the circumstance. When an - Entity Attestation Token is used, the following claims can be used to - meet those requirements: + Section 7 of [I-D.ietf-teep-architecture] lists information that may + appear in evidence depending on the circumstance. However, the + evidence is opaque to the TEEP protocol and there are no formal + requirements on the contents of evidence. - +===========+=====================+=================================+ + TAMs however consume Attestation Results and do need enough + information therein to make decisions on how to remediate a TEE that + is out of compliance, or update a TEE that is requesting an + authorized change. To do so, the information in Section 7 of + [I-D.ietf-teep-architecture] is often required depending on the + policy. When an Entity Attestation Token is used, the following + claims can be used to meet those requirements: + + +=============+==================+=================================+ |Requirement|Claim | Reference | - +===========+=====================+=================================+ - |Device |device-identifier | [I-D.birkholz-rats-suit-claims] | - |unique | | section 3.1.3 | + +=============+==================+=================================+ + | Device | ueid | [I-D.ietf-rats-eat] section 3.4 | + | unique | | | |identifier | | | - +-----------+---------------------+---------------------------------+ - |Vendor of |vendor-identifier | [I-D.birkholz-rats-suit-claims] | - |the device | | section 3.1.1 | - +-----------+---------------------+---------------------------------+ + +-------------+------------------+---------------------------------+ + | Vendor of | oemid | [I-D.ietf-rats-eat] section 3.6 | + | the device | | | + +-------------+------------------+---------------------------------+ |Class of |class-identifier | [I-D.birkholz-rats-suit-claims] | |the device | | section 3.1.2 | - +-----------+---------------------+---------------------------------+ + +-------------+------------------+---------------------------------+ |TEE |chip-version | [I-D.ietf-rats-eat] section 3.7 | |hardware | | | |type | | | - +-----------+---------------------+---------------------------------+ + +-------------+------------------+---------------------------------+ |TEE |chip-version | [I-D.ietf-rats-eat] section 3.7 | |hardware | | | |version | | | - +-----------+---------------------+---------------------------------+ - |TEE |component-identifier | [I-D.birkholz-rats-suit-claims] | - |firmware | | section 3.1.4 | + +-------------+------------------+---------------------------------+ + | TEE | sw-name | [I-D.ietf-rats-eat] section 3.9 | + | firmware | | | |type | | | - +-----------+---------------------+---------------------------------+ - |TEE |version | [I-D.birkholz-rats-suit-claims] | - |firmware | | section 3.1.8 | + +-------------+------------------+---------------------------------+ + | TEE | sw-version | [I-D.ietf-rats-eat] section | + | firmware | | 3.10 | |version | | | - +-----------+---------------------+---------------------------------+ + +-------------+------------------+---------------------------------+ |Freshness |nonce | [I-D.ietf-rats-eat] section 3.3 | |proof | | | - +-----------+---------------------+---------------------------------+ + +-------------+------------------+---------------------------------+ Table 1 4.4. Update Message The Update message is used by the TAM to install and/or delete one or more Trusted Components via the TEEP Agent. Like other TEEP messages, the Update message is signed, and the relevant CDDL snippet is shown below. The complete CDDL structure is @@ -593,36 +632,304 @@ manifest. The manifest may also convey personalization data. Trusted Component binaries and personalization data can be signed and encrypted by the same Trusted Component Signer. Other combinations are, however, possible as well. For example, it is also possible for the TAM to sign and encrypt the personalization data and to let the Trusted Component Developer sign and/or encrypt the Trusted Component binary. Note that an Update message carrying one or more SUIT manifests will inherently involve multiple signatures, one by the TAM in the TEEP - message and one from a Trusted Component signer inside each manifest. + message and one from a Trusted Component Signer inside each manifest. This is intentional as they are for different purposes. The TAM is what authorizes apps to be installed, updated, and deleted on a given TEE and so the TEEP signature is checked by the TEEP Agent at protocol message processing time. (This same TEEP security wrapper is also used on messages like QueryRequest so that Agents only send potentially sensitive data such as evidence to trusted TAMs.) The Trusted Component signer on the other hand is what authorizes the Trusted Component to actually run, so the manifest signature could be checked at install time or load (or run) time or both, and this checking is done by the TEE independent of whether TEEP is used or some other update mechanism. See section 5 of [I-D.ietf-teep-architecture] for further discussion. + The Update Message has a SUIT_Envelope containing SUIT manifests. + Following are some examples of using SUIT manifests in the Update + Message. + +4.4.1. Example 1: Having one SUIT Manifest pointing to a URI of a + Trusted Component Binary + + In this example, a SUIT Manifest has a URI pointing to a Trusted + Component Binary. + + A Trusted Component Developer creates a new Trusted Component Binary + and hosts it at a Trusted Component Developer's URI. Then the + Trusted Component Developer generates an associated SUIT manifest + with the filename "tc-uuid.suit" that contains the URI. The filename + "tc-uuid.suit" is used in Example 3 later. + + The TAM receives the latest SUIT manifest from the Trusted Component + Developer, and the URI it contains will not be changeable by the TAM + since the SUIT manifest is signed by the Trusted Component Developer. + + Pros: + + * The Trusted Component Developer can ensure that the intact Trusted + Component Binary is downloaded by devices + + * The TAM does not have to send large Update messages containing the + Trusted Component Binary + + Cons: + + * The Trusted Component Developer must host the Trusted Component + Binary server + + * The device must fetch the Trusted Component Binary in another + connection after receiving an Update message + +------------+ +-------------+ + | TAM | | TEEP Agent | + +------------+ +-------------+ + + Update ----> + + +=================== teep-protocol(TAM) ==================+ + | TEEP_Message([ | + | TEEP-TYPE-update, | + | options: { | + | manifest-list: [ | + | += suit-manifest "tc-uuid.suit" (TC Developer) =+ | + | | SUIT_Envelope({ | | + | | manifest: { | | + | | install: { | | + | | set-parameter: { | | + | | uri: "https://example.org/tc-uuid.ta" | | + | | }, | | + | | fetch | | + | | } | | + | | } | | + | | }) | | + | +===============================================+ | + | ] | + | } | + | ]) | + +=========================================================+ + + and then, + + +-------------+ +--------------+ + | TEEP Agent | | TC Developer | + +-------------+ +--------------+ + + <---- + + fetch "https://example.org/tc-uuid.ta" + + +======= tc-uuid.ta =======+ + | 48 65 6C 6C 6F 2C 20 ... | + +==========================+ + + Figure 1: URI of the Trusted Component Binary + + For the full SUIT Manifest example binary, see Appendix "Example 1: + SUIT Manifest pointing to URI of the Trusted Component Binary". + +4.4.2. Example 2: Having a SUIT Manifest include the Trusted Component + Binary + + In this example, the SUIT manifest contains the entire Trusted + Component Binary using the integrated-payload (see + [I-D.ietf-suit-manifest] Section 7.6). + + A Trusted Component Developer delegates to the TAM the task of + delivering the Trusted Component Binary in the SUIT manifest. The + Trusted Component Developer creates a SUIT manifest and embeds the + Trusted Component Binary, which is referenced in the URI parameter + with identifier "#tc". The Trusted Component Developer provides the + SUIT manifest to the TAM. + + The TAM serves the SUIT manifest containing the Trusted Component + Binary to the device in an Update message. + + Pros: + + * The device can obtain the Trusted Component Binary and its SUIT + manifest together in one Update message + + * The Trusted Component Developer does not have to host a server to + deliver the Trusted Component Binary directly to devices + + Cons: + + * The TAM must host the Trusted Component Binary itself, rather than + delegating such storage to the Trusted Component Developer + + * The TAM must deliver Trusted Component Binaries in Update + messages, which result in increased Update message size + +------------+ +-------------+ + | TAM | | TEEP Agent | + +------------+ +-------------+ + + Update ----> + + +=========== teep-protocol(TAM) ============+ + | TEEP_Message([ | + | TEEP-TYPE-update, | + | options: { | + | manifest-list: [ | + | +== suit-manifest(TC Developer) ==+ | + | | SUIT_Envelope({ | | + | | "#tc": h'48 65 6C 6C ...', | | + | | manifest: { | | + | | install: { | | + | | set-parameter: { | | + | | uri: "#tc" | | + | | }, | | + | | fetch | | + | | } | | + | | } | | + | | }) | | + | +=================================+ | + | ] | + | } | + | ]) | + +===========================================+ + + Figure 2: Integrated Payload with Trusted Component Binary + + For the full SUIT Manifest example binary, see Appendix "Example 2: + SUIT Manifest including the Trusted Component Binary". + +4.4.3. Example 3: Supplying Personalization Data for the Trusted + Component Binary + + In this example, Personalization Data is associated with the Trusted + Component Binary "tc-uuid.suit" from Example 1. + + The Trusted Component Developer places Personalization Data in a file + named "config.json" and hosts it on an HTTPS server. The Trusted + Component Developer then creates a SUIT manifest with the URI, + specifying which Trusted Component Binary it correlates to in the + parameter 'dependency-resolution', and signs the SUIT manifest. + + The TAM delivers the SUIT manifest of the Personalization Data which + depends on the Trusted Component Binary from Example 1. + + +------------+ +-------------+ + | TAM | | TEEP Agent | + +------------+ +-------------+ + + Update ----> + + +================= teep-protocol(TAM) ======================+ + | TEEP_Message([ | + | TEEP-TYPE-update, | + | options: { | + | manifest-list: [ | + | +======== suit-manifest(TC Developer) ============+ | + | | SUIT_Envelope({ | | + | | manifest: { | | + | | common: { | | + | | dependencies: [ | | + | | {{digest-of-tc.suit}} | | + | | ] | | + | | } | | + | | dependency-resolution: { | | + | | set-parameter: { | | + | | uri: "https://example.org/tc-uuid.suit" | | + | | } | | + | | fetch | | + | | } | | + | | install: { | | + | | set-parameter: { | | + | | uri: "https://example.org/config.json" | | + | | }, | | + | | fetch | | + | | set-dependency-index | | + | | process-dependency | | + | | } | | + | | } | | + | | }) | | + | +=================================================+ | + | ] | + | } | + | ]) | + +===========================================================+ + + and then, + + +-------------+ +--------------+ + | TEEP Agent | | TC Developer | + +-------------+ +--------------+ + + <---- + + fetch "https://example.org/config.json" + + +=======config.json========+ + | 7B 22 75 73 65 72 22 ... | + +==========================+ + + Figure 3: Personalization Data + + For the full SUIT Manifest example binary, see Appendix "Example 3: + Supplying Personalization Data for Trusted Component Binary". + +4.4.4. Example 4: Unlinking Trusted Component + + This subsection shows an example deleting the Trusted Component + Binary in the TEEP Device. + + A Trusted Component Developer can also generate SUIT Manifest which + unlinks the installed Trusted Component. The TAM deliver it when the + TAM want to uninstall the component. + + The directive-unlink (see [I-D.moran-suit-trust-domains] Section- + 6.5.4) is located in the manifest to delete the Trusted Component. + Note that in case other Trusted Components depend on it, i.e. the + reference count is not zero, the TEEP Device SHOULD NOT delete it + immediately. + + +------------+ +-------------+ + | TAM | | TEEP Agent | + +------------+ +-------------+ + + Update ----> + + +=========== teep-protocol(TAM) ============+ + | TEEP_Message([ | + | TEEP-TYPE-update, | + | options: { | + | manifest-list: [ | + | +== suit-manifest(TC Developer) ==+ | + | | SUIT_Envelope({ | | + | | manifest: { | | + | | install: [ | | + | | unlink | | + | | ] | | + | | } | | + | | }) | | + | +=================================+ | + | ] | + | } | + | ]) | + +===========================================+ + + Figure 4: Unlink Trusted Component example (summary) + + For the full SUIT Manifest example binary, see Appendix E. SUIT + Example 4 (Appendix "E.4. Example 4: Unlink a Trusted Component") + 4.5. Success Message The Success message is used by the TEEP Agent to return a success in response to an Update message. Like other TEEP messages, the Success message is signed, and the relevant CDDL snippet is shown below. The complete CDDL structure is shown in Appendix C. teep-success = [ @@ -649,24 +956,25 @@ If none was present, the token MUST be absent in the Success message. msg The msg parameter contains optional diagnostics information encoded in UTF-8 [RFC3629] using Net-Unicode form [RFC5198] with max 128 bytes returned by the TEEP Agent. suit-reports If present, the suit-reports parameter contains a set of SUIT - Reports as defined in Section 4 of [I-D.moran-suit-report]. If - the suit-report-nonce field is present in the SUIT Report, is - value MUST match the value of the token parameter in the Update - message the Success message is in response to. + Reports as defined in Section 4 of [I-D.moran-suit-report]. If a + token parameter was present in the Update message the Success + message is in response to, the suit-report-nonce field MUST be + present in the SUIT Report with a value matching the token + parameter in the Update message. 4.6. Error Message The Error message is used by the TEEP Agent to return an error in response to an Update message. Like other TEEP messages, the Error message is signed, and the relevant CDDL snippet is shown below. The complete CDDL structure is shown in Appendix C. @@ -699,42 +1007,43 @@ message. err-msg The err-msg parameter is human-readable diagnostic text that MUST be encoded using UTF-8 [RFC3629] using Net-Unicode form [RFC5198] with max 128 bytes. supported-cipher-suites The supported-cipher-suites parameter lists the ciphersuite(s) supported by the TEEP Agent. Details about the ciphersuite - encoding can be found in Section 7. This otherwise optional + encoding can be found in Section 8. This otherwise optional parameter MUST be returned if err-code is ERR_UNSUPPORTED_CIPHER_SUITES. supported-freshness-mechanisms The supported-freshness-mechanisms parameter lists the freshness mechanism(s) supported by the TEEP Agent. Details about the - encoding can be found in Section 8. This otherwise optional + encoding can be found in Section 9. This otherwise optional parameter MUST be returned if err-code is ERR_UNSUPPORTED_FRESHNESS_MECHANISMS. versions The versions parameter enumerates the TEEP protocol version(s) supported by the TEEP Agent. This otherwise optional parameter MUST be returned if err-code is ERR_UNSUPPORTED_MSG_VERSION. suit-reports If present, the suit-reports parameter contains a set of SUIT - Reports as defined in Section 4 of [I-D.moran-suit-report]. If - the suit-report-nonce field is present in the SUIT Report, is - value MUST match the value of the token parameter in the Update - message the Error message is in response to. + Reports as defined in Section 4 of [I-D.moran-suit-report]. If a + token parameter was present in the Update message the Error + message is in response to, the suit-report-nonce field MUST be + present in the SUIT Report with a value matching the token + parameter in the Update message. err-code The err-code parameter contains one of the error codes listed below). Only selected values are applicable to each message. This specification defines the following initial error messages: ERR_PERMANENT_ERROR (1) The TEEP request contained incorrect fields or fields that are inconsistent with other fields. For diagnosis purposes it is @@ -798,21 +1107,86 @@ on the failed manifest. New error codes should be added sparingly, not for every implementation error. That is the intent of the err-msg field, which can be used to provide details meaningful to humans. New error codes should only be added if the TAM is expected to do something behaviorally different upon receipt of the error message, rather than just logging the event. Hence, each error code is responsible for saying what the behavioral difference is expected to be. -5. Mapping of TEEP Message Parameters to CBOR Labels +5. EAT Profile + + The TEEP protocol operates between a TEEP Agent and a TAM. While the + TEEP protocol does not require use of EAT, use of EAT is encouraged + and Section 4.3 explicitly defines a way to carry an Entity + Attestation Token evidence in a QueryResponse. + + As discussed in Section 4.3.1, the content of attestation evidence is + opaque to the TEEP architecture, but the content of Attestation + Results is not, where Attestation Results flow between a Verifier and + a TAM (as the Relying Party). Although Attestation Results required + by a TAM are separable from the TEEP protocol per se, this section is + included as part of the requirements for building a compliant TAM + that uses EATs for Attestation Results. + + Section 7 of [I-D.ietf-rats-eat] defines the requirement for Entity + Attestation Token profiles. This section defines an EAT profile for + use with TEEP. + + * profile-label: The profile-label for this specification is the URI + + https://datatracker.ietf.org/doc/html/draft-ietf-teep-protocol-08 + (https://datatracker.ietf.org/doc/html/draft-ietf-teep-protocol-08). + (RFC-editor: upon RFC publication, replace string with + "https://www.rfc-editor.org/info/rfcXXXX" where XXXX is the RFC + number of this document.) + + * Use of JSON, CBOR, or both: CBOR only. + + * CBOR Map and Array Encoding: Only definite length arrays and maps. + + * CBOR String Encoding: Only definite-length strings are allowed. + + * CBOR Preferred Serialization: Encoders must use preferred + serialization, and decoders need not accept non-preferred + serialization. + + * COSE/JOSE Protection: See Section 8. + + * Detached EAT Bundle Support: DEB use is permitted. + + * Verification Key Identification: COSE Key ID (kid) is used, where + the key ID is the hash of a public key (where the public key may + be used as a raw public key, or in a certificate). + + * Endorsement Identification: Optional, but semantics are the same + as in Verification Key Identification. + + * Freshness: See Section 9. + + * Required Claims: None. + + * Prohibited Claims: None. + + * Additional Claims: Optional claims are those listed in + Section 4.3.1. + + * Refined Claim Definition: None. + + * CBOR Tags: CBOT Tags are not used. + + * Manifests and Software Evidence Claims: The sw-name claim for a + Trusted Component holds the URI of the SUIT manifest for that + component. + +6. Mapping of TEEP Message Parameters to CBOR Labels In COSE, arrays and maps use strings, negative integers, and unsigned integers as their keys. Integers are used for compactness of encoding. Since the word "key" is mainly used in its other meaning, as a cryptographic key, this specification uses the term "label" for this usage as a map key. This specification uses the following mapping: +================================+=======+ @@ -854,26 +1228,26 @@ +--------------------------------+-------+ | suit-reports | 19 | +--------------------------------+-------+ | token | 20 | +--------------------------------+-------+ | supported-freshness-mechanisms | 21 | +--------------------------------+-------+ Table 2 -6. Behavior Specification +7. Behavior Specification Behavior is specified in terms of the conceptual APIs defined in section 6.2.1 of [I-D.ietf-teep-architecture]. -6.1. TAM Behavior +7.1. TAM Behavior When the ProcessConnect API is invoked, the TAM sends a QueryRequest message. When the ProcessTeepMessage API is invoked, the TAM first does validation as specified in Section 4.1.2, and drops the message if it is not valid. Otherwise, it proceeds as follows. If the message includes a token, it can be used to match the response to a request previously sent by the TAM. The TAM MUST expire the @@ -906,30 +1280,40 @@ matches the token sent in the Update message, and drops the message if it does not match. Otherwise, the TAM handles the update in any implementation specific way, such as updating any locally cached information about the state of the TEEP Agent, or logging the results. If any other Error message is received, the TAM can handle it in any implementation specific way, but Section 4.6 provides recommendations for such handling. -6.2. TEEP Agent Behavior +7.2. TEEP Agent Behavior When the RequestTA API is invoked, the TEEP Agent first checks whether the requested TA is already installed. If it is already installed, the TEEP Agent passes no data back to the caller. Otherwise, if the TEEP Agent chooses to initiate the process of requesting the indicated TA, it determines (in any implementation specific way) the TAM URI based on any TAM URI provided by the RequestTA caller and any local configuration, and passes back the TAM - URI to connect to. + URI to connect to. It MAY also pass back a QueryResponse message if + all of the following conditions are true: + + * The last QueryRequest message received from that TAM contained no + token or challenge, + + * The ProcessError API was not invoked for that TAM since the last + QueryResponse message was received from it, and + + * The public key or certificate of the TAM is cached and not + expired. When the RequestPolicyCheck API is invoked, the TEEP Agent decides whether to initiate communication with any trusted TAMs (e.g., it might choose to do so for a given TAM unless it detects that it has already communicated with that TAM recently). If so, it passes back a TAM URI to connect to. If the TEEP Agent has multiple TAMs it needs to connect with, it just passes back one, with the expectation that RequestPolicyCheck API will be invoked to retrieve each one successively until there are no more and it can pass back no data at that time. Thus, once a TAM URI is returned, the TEEP Agent can @@ -951,93 +1335,116 @@ When an Update message is received, the Agent attempts to update the Trusted Components specified in the SUIT manifests by following the Update Procedure specified in [I-D.ietf-suit-manifest], and responds with a Success message if all SUIT manifests were successfully installed, or an Error message if any error was encountered. It is important to note that the Update Procedure requires resolving and installing any dependencies indicated in the manifest, which may take some time, and the Success or Error message is generated only after completing the Update Procedure. -7. Ciphersuites +8. Ciphersuites - A ciphersuite consists of an AEAD algorithm, a MAC algorithm, and a - signature algorithm. Each ciphersuite is identified with an integer - value, which corresponds to an IANA registered ciphersuite (see - Section 10.2. This document specifies two ciphersuites. + The TEEP protocol uses COSE for protection of TEEP messages. After a + QueryResponse is received, the selected cryptographic algorithm is + used in subsequent TEEP messages (Install, Success, and Error). To + negotiate cryptographic mechanisms and algorithms, the TEEP protocol + defines the following ciphersuite structure. - +=======+================================================+ - | Value | Ciphersuite | - +=======+================================================+ - | 1 | AES-CCM-16-64-128, HMAC 256/256, X25519, EdDSA | - +-------+------------------------------------------------+ - | 2 | AES-CCM-16-64-128, HMAC 256/256, P-256, ES256 | - +-------+------------------------------------------------+ + ciphersuite = [ + teep-cose-sign-algs / nil, + teep-cose-encrypt-algs / nil , + teep-cose-mac-algs / nil + ] - Table 3 + The ciphersuite structure is used to present the combination of + mechanisms and cryptographic algorithms. Each suite value + corresponds with a COSE-type defined in Section 2 of [RFC8152]. - A TAM MUST support both ciphersuites. A TEEP Agent MUST support at - least one of the two but can choose which one. For example, a TEEP - Agent might choose ciphersuite 2 if it has hardware support for it. + supported-cipher-suites = [ + suite ] + + Cryptographic algorithm values are defined in the COSE Algorithms + registry [COSE.Algorithm]. A TAM MUST support both of the following + ciphersuites. A TEEP Agent MUST support at least one of the two but + can choose which one. For example, a TEEP Agent might choose a given + ciphersuite if it has hardware support for it. + + teep-cose-sign-algs /= cose-alg-es256, + teep-cose-sign-algs /= cose-alg-eddsa + + A TAM or TEEP Agent MUST also support the following algorithms: + + teep-cose-encrypt-algs /= cose-alg-accm-16-64-128 + + teep-cose-mac-algs /= cose-alg-hmac-256 + + A TAM or TEEP Agent MAY also support one or more of the following + algorithms: + + teep-cose-sign-algs /= cose-alg-ps256, + teep-cose-sign-algs /= cose-alg-ps384, + teep-cose-sign-algs /= cose-alg-ps512, + teep-cose-sign-algs /= cose-alg-rsa-oaep-256, + teep-cose-sign-algs /= cose-alg-rsa-oaep-512 Any ciphersuites without confidentiality protection can only be added if the associated specification includes a discussion of security considerations and applicability, since manifests may carry sensitive information. For example, Section 6 of [I-D.ietf-teep-architecture] permits implementations that terminate transport security inside the TEE and if the transport security provides confidentiality then additional encryption might not be needed in the manifest for some use cases. For most use cases, however, manifest confidentiality will be needed to protect sensitive fields from the TAM as discussed in Section 9.8 of [I-D.ietf-teep-architecture]. -8. Freshness Mechanisms +9. Freshness Mechanisms A freshness mechanism determines how a TAM can tell whether evidence provided in a Query Response is fresh. There are multiple ways this can be done as discussed in Section 10 of [I-D.ietf-rats-architecture]. Each freshness mechanism is identified with an integer value, which corresponds to an IANA registered freshness mechanism (see - Section 10.3. This document defines the following freshness + Section 11.2. This document defines the following freshness mechanisms: +=======+=====================+ | Value | Freshness mechanism | +=======+=====================+ | 1 | Nonce | +-------+---------------------+ | 2 | Timestamp | +-------+---------------------+ | 3 | Epoch ID | +-------+---------------------+ - Table 4 + Table 3 In the Nonce mechanism, the evidence MUST include a nonce provided in the QueryRequest challenge. In other mechanisms, a timestamp or epoch ID determined via mechanisms outside the TEEP protocol is used, and the challenge is only needed in the QueryRequest message if a challenge is needed in generating evidence for reasons other than freshness. If a TAM supports multiple freshness mechanisms that require different challenge formats, the QueryRequest message can currently only send one such challenge. This situation is expected to be rare, but should it occur, the TAM can choose to prioritize one of them and exclude the other from the supported-freshness-mechanisms in the QueryRequest, and resend the QueryRequest with the other mechanism if an ERR_UNSUPPORTED_FRESHNESS_MECHANISMS Error is received that indicates the TEEP Agent supports the other mechanism. -9. Security Considerations +10. Security Considerations This section summarizes the security considerations discussed in this specification: Cryptographic Algorithms TEEP protocol messages exchanged between the TAM and the TEEP Agent are protected using COSE. This specification relies on the cryptographic algorithms provided by COSE. Public key based authentication is used by the TEEP Agent to authenticate the TAM and vice versa. @@ -1112,23 +1519,23 @@ The integrity and the accuracy of the clock within the TEE determines the ability to determine an expired TAM certificate, if certificates are used. Compromised Time Source As discussed above, certificate validity checks rely on comparing validity dates to the current time, which relies on having a trusted source of time, such as [RFC8915]. A compromised time source could thus be used to subvert such validity checks. -10. IANA Considerations +11. IANA Considerations -10.1. Media Type Registration +11.1. Media Type Registration IANA is requested to assign a media type for application/teep+cbor. Type name: application Subtype name: teep+cbor Required parameters: none Optional parameters: none @@ -1159,110 +1566,94 @@ Person to contact for further information: teep@ietf.org Intended usage: COMMON Restrictions on usage: none Author: See the "Authors' Addresses" section of this document Change controller: IETF -10.2. Ciphersuite Registry - - IANA is also requested to create a new registry for ciphersuites. - - Name of registry: TEEP Ciphersuites - - Policy: Specification Required - - Additional requirements: The specification must document relevant - security considerations. - - Initial values: - - +=======+=========================+===============+ - | Value | Ciphersuite | Specification | - +=======+=========================+===============+ - | 1 | AES-CCM-16-64-128, HMAC | RFC TBD | - | | 256/256, X25519, EdDSA | Section 7 | - +-------+-------------------------+---------------+ - | 2 | AES-CCM-16-64-128, HMAC | RFC TBD | - | | 256/256, P-256, ES256 | Section 7 | - +-------+-------------------------+---------------+ - - Table 5 - - [RFC Editor: please replace TBD above with the number assigned to - this document] - -10.3. Freshness Mechanism Registry +11.2. Freshness Mechanism Registry IANA is also requested to create a new registry for freshness mechanisms. Name of registry: TEEP Freshness Mechanisms - Policy: Specification Required + Policy: Specification Required [RFC8126] Additional requirements: The specification must document relevant security considerations. Initial values: +=======+=====================+===================+ | Value | Freshness mechanism | Specification | +=======+=====================+===================+ - | 1 | Nonce | RFC TBD Section 8 | + | 1 | Nonce | RFC TBD Section 9 | +-------+---------------------+-------------------+ - | 2 | Timestamp | RFC TBD Section 8 | + | 2 | Timestamp | RFC TBD Section 9 | +-------+---------------------+-------------------+ - | 3 | Epoch ID | RFC TBD Section 8 | + | 3 | Epoch ID | RFC TBD Section 9 | +-------+---------------------+-------------------+ - Table 6 + Table 4 - [RFC Editor: please replace TBD above with the number assigned to - this document] + (RFC Editor: please replace TBD above with the number assigned to + this document.) -11. References +12. References -11.1. Normative References +12.1. Normative References + + [COSE.Algorithm] + IANA, "COSE Algorithms", n.d., + . [I-D.ietf-rats-architecture] Birkholz, H., Thaler, D., Richardson, M., Smith, N., and W. Pan, "Remote Attestation Procedures Architecture", Work in Progress, Internet-Draft, draft-ietf-rats-architecture- - 12, 23 April 2021, . + 15, 8 February 2022, . [I-D.ietf-rats-eat] Lundblade, L., Mandyam, G., and J. O'Donoghue, "The Entity Attestation Token (EAT)", Work in Progress, Internet- - Draft, draft-ietf-rats-eat-11, 24 October 2021, + Draft, draft-ietf-rats-eat-12, 24 February 2022, . + 12.txt>. [I-D.ietf-suit-manifest] Moran, B., Tschofenig, H., Birkholz, H., and K. Zandberg, "A Concise Binary Object Representation (CBOR)-based Serialization Format for the Software Updates for Internet of Things (SUIT) Manifest", Work in Progress, Internet- - Draft, draft-ietf-suit-manifest-14, 12 July 2021, + Draft, draft-ietf-suit-manifest-16, 25 October 2021, . + 16.txt>. [I-D.moran-suit-report] Moran, B., "Secure Reporting of Update Status", Work in Progress, Internet-Draft, draft-moran-suit-report-01, 22 February 2021, . + [I-D.moran-suit-trust-domains] + Moran, B., "SUIT Manifest Extensions for Multiple Trust + Domains", Work in Progress, Internet-Draft, draft-moran- + suit-trust-domains-00, 25 October 2021, + . + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003, . [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network @@ -1280,37 +1671,37 @@ October 2013, . [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", RFC 8152, DOI 10.17487/RFC8152, July 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . -11.2. Informative References +12.2. Informative References [I-D.birkholz-rats-suit-claims] Birkholz, H. and B. Moran, "Trustworthiness Vectors for the Software Updates of Internet of Things (SUIT) Workflow Model", Work in Progress, Internet-Draft, draft-birkholz- - rats-suit-claims-02, 12 July 2021, + rats-suit-claims-03, 12 January 2022, . + claims-03.txt>. [I-D.ietf-teep-architecture] Pei, M., Tschofenig, H., Thaler, D., and D. Wheeler, "Trusted Execution Environment Provisioning (TEEP) Architecture", Work in Progress, Internet-Draft, draft- - ietf-teep-architecture-15, 12 July 2021, + ietf-teep-architecture-16, 28 February 2022, . + architecture-16.txt>. [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, @@ -1326,33 +1717,32 @@ We would like to thank Brian Witten (Symantec), Tyler Kim (Solacia), Nick Cook (Arm), and Minho Yoo (IoTrust) for their contributions to the Open Trust Protocol (OTrP), which influenced the design of this specification. B. Acknowledgements We would like to thank Eve Schooler for the suggestion of the protocol name. - We would like to thank Kohei Isobe (TRASIO/SECOM), Kuniyasu Suzaki - (TRASIO/AIST), Tsukasa Oi (TRASIO), and Yuichi Takita (SECOM) for - their valuable implementation feedback. + We would like to thank Kohei Isobe (TRASIO/SECOM), Ken Takayama + (SECOM) Kuniyasu Suzaki (TRASIO/AIST), Tsukasa Oi (TRASIO), and + Yuichi Takita (SECOM) for their valuable implementation feedback. We would also like to thank Carsten Bormann and Henk Birkholz for their help with the CDDL. C. Complete CDDL Valid TEEP messages MUST adhere to the following CDDL data - definitions, except that "SUIT_Envelope" and - "SUIT_Component_Identifier" are specified in - [I-D.ietf-suit-manifest]. + definitions, except that SUIT_Envelope and SUIT_Component_Identifier + are specified in [I-D.ietf-suit-manifest]. teep-message = $teep-message-type .within teep-message-framework SUIT_Envelope = any teep-message-framework = [ type: uint (0..23) / $teep-type-extension, options: { * teep-option }, * uint; further integers, e.g., for data-item-requested ] @@ -1392,27 +1782,47 @@ ? supported-freshness-mechanisms => [ + freshness-mechanism ], ? challenge => bstr .size (8..512), ? versions => [ + version ], * $$query-request-extensions * $$teep-option-extensions }, data-item-requested: data-item-requested ] ; ciphersuites - suite = $TEEP-suite .within uint .size 4 + suite = [ + teep-cose-sign-algs / nil, + teep-cose-encrypt-algs / nil, + teep-cose-mac-algs / nil + ] - TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 1 - TEEP-AES-CCM-16-64-128-HMAC256--256-P-256-ES256 = 2 + teep-cose-sign-algs /= cose-alg-es256, + teep-cose-sign-algs /= cose-alg-eddsa + teep-cose-sign-algs /= cose-alg-ps256, + teep-cose-sign-algs /= cose-alg-ps384, + teep-cose-sign-algs /= cose-alg-ps512, + teep-cose-sign-algs /= cose-alg-rsa-oaep-256, + teep-cose-sign-algs /= cose-alg-rsa-oaep-512 + teep-cose-encrypt-algs /= cose-alg-accm-16-64-128 - $TEEP-suite /= TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA - $TEEP-suite /= TEEP-AES-CCM-16-64-128-HMAC256--256-P-256-ES256 + teep-cose-mac-algs /= cose-alg-hmac-256 + + ; algorithm identifiers defined in the IANA COSE Algorithms Registry + cose-alg-es256 = -7 + cose-alg-eddsa = -8 + cose-alg-ps256 = -37 + cose-alg-ps384 = -38 + cose-alg-ps512 = -39 + cose-alg-rsa-oaep-256 = -41 + cose-alg-rsa-oaep-512 = -42 + cose-alg-accm-16-64-128 = 10 + cose-alg-hmac-256 = 5 ; freshness-mechanisms freshness-mechanism = $TEEP-freshness-mechanism .within uint .size 4 FRESHNESS_NONCE = 0 FRESHNESS_TIMESTAMP = 1 FRESHNESS_EPOCH_ID = 2 $TEEP-freshness-mechanism /= FRESHNESS_NONCE @@ -1513,21 +1922,21 @@ tc-manifest-sequence-number = 17 have-binary = 18 suit-reports = 19 token = 20 supported-freshness-mechanisms = 21 D. Examples of Diagnostic Notation and Binary Representation This section includes some examples with the following assumptions: - * TEEP Device will have two TCs with the following SUIT Component + * The device will have two TCs with the following SUIT Component Identifiers: - [ 0x000102030405060708090a0b0c0d0e0f ] - [ 0x100102030405060708090a0b0c0d0e0f ] * SUIT manifest-list is set empty only for example purposes (see Appendix E for actual manifest examples) D.1. QueryRequest Message @@ -1730,307 +2138,764 @@ 14 # unsigned(20) uint (0..23) 4F # bytes(16) (8..64) A0A1A2A3A4A5A6A7A8A9AAABACADAEAF 0C # unsigned(12) uint (0..23) 69 # text(9) (1..128) 6469736B2D66756C6C # "disk-full" 11 # unsigned(17) uint (0..23) E. Examples of SUIT Manifests - This section shows some examples of SUIT manifests for a case where - the TEE will use a Trusted Application (TA) for OP-TEE on Arm - TrustZone, storing the TA in Replay Protected Memory Block (RPMB) - secure storage in a file named "edd94cd8-9d9c-4cc8-9216- - b3ad5a2d5b8a.ta". + This section shows some examples of SUIT manifests described in + Section 4.4. - The TA developer places personalization data for the device on an - HTTPS server and puts the URI in the TA manifest. The - personalization data will also be stored in RPMB secure storage in a - file named "config.json". + The examples are signed using the following ECDSA secp256r1 key with + SHA256 as the digest function. -E.1. Install a Trusted Component + COSE_Sign1 Cryptographic Key: - This sample manifest installs a Trusted Component that depends on - personalization data resolved separately. + -----BEGIN PRIVATE KEY----- + MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgApZYjZCUGLM50VBC + CjYStX+09jGmnyJPrpDLTz/hiXOhRANCAASEloEarguqq9JhVxie7NomvqqL8Rtv + P+bitWWchdvArTsfKktsCYExwKNtrNHXi9OB3N+wnAUtszmR23M4tKiW + -----END PRIVATE KEY----- - TA Manifest: + The corresponding public key can be used to verify these examples: - 107({ - / authentication-wrapper / 2:<<[ - digest: <<[ - / algorithm-id / -16 / "sha256" /, - / digest-bytes / h'd6c1fc7200483092e2db59d4907f9b15' - h'05cb3af2795cf78f7ae3d88166fdf743' + -----BEGIN PUBLIC KEY----- + MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhJaBGq4LqqvSYVcYnuzaJr6qi/Eb + bz/m4rVlnIXbwK07HypLbAmBMcCjbazR14vTgdzfsJwFLbM5kdtzOLSolg== + -----END PUBLIC KEY----- + +Example 1: SUIT Manifest pointing to URI of the Trusted Component Binary + +CBOR Diagnostic Notation of SUIT Manifest + +/ SUIT_Envelope_Tagged / 107( { + / suit-authentication-wrapper / 2: << [ + << [ + / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, + / suit-digest-bytes: / h'DB601ADE73092B58532CA03FBB663DE49532435336F1558B49BB622726A2FEDD' ]>>, - signature: <<18([ - / protected / <<{ - / alg / 1:-7 / "ES256" /, + << / COSE_Sign1_Tagged / 18( [ + / protected: / << { + / algorithm-id / 1: -7 / ES256 / }>>, - / unprotected / {}, - / payload / F6 / nil /, - / signature / h'd11a2dd9610fb62a707335f584079225' - h'709f96e8117e7eeed98a2f207d05c8ec' - h'fba1755208f6abea977b8a6efe3bc2ca' - h'3215e1193be201467d052b42db6b7287' + / unprotected: / {}, + / payload: / null, + / signature: / h'5B2D535A2B6D5E3C585C1074F414DA9E10BD285C99A33916DADE3ED38812504817AC48B62B8E984EC622785BD1C411888BE531B1B594507816B201F6F28579A4' ])>> ]>>, - / manifest / 3:<<{ - / manifest-version / 1:1, - / manifest-sequence-number / 2:3, - / common / 3:<<{ - / components / 2:[ - ["OP-TEE","RPMB","edd94cd8-9d9c-4cc8-9216- b3ad5a2d5b8a","ta"] + / suit-manifest / 3: << { + / suit-manifest-version / 1: 1, + / suit-manifest-sequence-number / 2: 3, + / suit-common / 3: << { + / suit-components / 2: [ + [ + h'544545502D446576696365', / "TEEP-Device" / + h'5365637572654653', / "SecureFS" / + h'8D82573A926D4754935332DC29997F74', / tc-uuid / + h'7461' / "ta" / + ] ], - / common-sequence / 4:<<[ - / directive-override-parameters / 20,{ - / vendor-id / 1:h'c0ddd5f15243566087db4f5b0aa26c2f', - / class-id / 2:h'db42f7093d8c55baa8c5265fc5820f4e', - / image-digest / 3:<<[ - / algorithm-id / -16 / "sha256" /, - / digest-bytes / h'00112233445566778899aabbccddeeff' - h'0123456789abcdeffedcba9876543210' + / suit-common-sequence / 4: << [ + / suit-directive-override-parameters / 20, { + / suit-parameter-vendor-identifier / 1: h'C0DDD5F15243566087DB4F5B0AA26C2F', + / suit-parameter-class-identifier / 2: h'DB42F7093D8C55BAA8C5265FC5820F4E', + / suit-parameter-image-digest / 3: << [ + / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, + / suit-digest-bytes: / h'8CF71AC86AF31BE184EC7A05A411A8C3A14FD9B77A30D046397481469468ECE8' ]>>, - / image-size / 14:76778, + / suit-parameter-image-size / 14: 20 }, - / condition-vendor-identifier / 1,15, - / condition-class-identifier / 2,15 - ]>>, + / suit-condition-vendor-identifier / 1, 15, + / suit-condition-class-identifier / 2, 15 + + ] >> }>>, - / install / 9:<<[ - / directive-set-parameters / 19,{ - / uri / 21: - 'https://teep.example/edd94cd8-9d9c-4cc8-9216-b3ad5a2d5b8a.ta', + / suit-install / 9: << [ + / suit-directive-override-parameters / 20, { + / suit-parameter-uri / 21: "https://example.org/8d82573a-926d-4754-9353-32dc29997f74.ta" } , - / directive-fetch / 21,2, - / condition-image-match / 3,15 + / suit-directive-fetch / 21, 15, + / suit-condition-image-match / 3, 15 + ] >> + } >> +} ) +CBOR Binary Representation + +D8 6B # tag(107) / SUIT_Envelope_Tagged / + A2 # map(2) + 02 # unsigned(2) / suit-authentication-wrapper / + 58 73 # bytes(115) + 82 # array(2) + 58 24 # bytes(36) + 82 # array(2) + 2F # negative(15) / -16 = suit-cose-alg-sha256 / + 58 20 # bytes(32) + DB601ADE73092B58532CA03FBB663DE49532435336F1558B49BB622726A2FEDD + 58 4A # bytes(74) + D2 # tag(18) / COSE_Sign1_Tagged / + 84 # array(4) + 43 # bytes(3) + A1 # map(1) + 01 # unsigned(1) / algorithm-id / + 26 # negative(6) / -7 = ES256 / + A0 # map(0) + F6 # primitive(22) / null / + 58 40 # bytes(64) + 5B2D535A2B6D5E3C585C1074F414DA9E10BD285C99A33916DADE3ED38812504817AC48B62B8E984EC622785BD1C411888BE531B1B594507816B201F6F28579A4 + 03 # unsigned(3) / suit-manifest: / + 58 D4 # bytes(212) + A4 # map(4) + 01 # unsigned(1) / suit-manifest-version: / + 01 # unsigned(1) + 02 # unsigned(2) / suit-manifest-sequence-number: / + 03 # unsigned(3) + 03 # unsigned(3) / suit-common: / + 58 84 # bytes(132) + A2 # map(2) + 02 # unsigned(2) / suit-components: / + 81 # array(1) + 84 # array(4) + 4B # bytes(11) + 544545502D446576696365 # "TEEP-Device" + 48 # bytes(8) + 5365637572654653 # "SecureFS" + 50 # bytes(16) + 8D82573A926D4754935332DC29997F74 # tc-uuid + 42 # bytes(2) + 7461 # "ta" + 04 # unsigned(4) / suit-common-sequence: / + 58 54 # bytes(84) + 86 # array(6) + 14 # unsigned(20) / suit-directive-override-parameters: / + A4 # map(4) + 01 # unsigned(1) / suit-parameter-vendor-identifier: / + 50 # bytes(16) + C0DDD5F15243566087DB4F5B0AA26C2F + 02 # unsigned(2) / suit-parameter-class-identifier: / + 50 # bytes(16) + DB42F7093D8C55BAA8C5265FC5820F4E + 03 # unsigned(3) / suit-parameter-image-digest: / + 58 24 # bytes(36) + 82 # array(2) + 2F # negative(15) / -16 = suit-cose-alg-sha256 / + 58 20 # bytes(32) + 8CF71AC86AF31BE184EC7A05A411A8C3A14FD9B77A30D046397481469468ECE8 + 0E # unsigned(14) / suit-parameter-image-size: / + 14 # unsigned(20) + 01 # unsigned(1) / suit-condition-vendor-identifier: / + 0F # unsigned(15) + 02 # unsigned(2) / suit-condition-class-identifier: / + 0F # unsigned(15) + 09 # unsigned(9) / suit-install: / + 58 45 # bytes(69) + 86 # array(6) + 14 # unsigned(20) / suit-directive-override-parameters: / + A1 # map(1) + 15 # unsigned(21) / suit-parameter-uri: / + 78 3B # text(59) + 68747470733A2F2F6578616D706C652E6F72672F38643832353733612D393236642D343735342D393335332D3332646332393939376637342E7461 # "https://example.org/8d82573a-926d-4754-9353-32dc29997f74.ta" + 15 # unsigned(21) / suit-directive-fetch: / + 0F # unsigned(15) + 03 # unsigned(3) / suit-condition-image-match: / + 0F # unsigned(15) + +CBOR Binary in Hex + D86BA2025873825824822F5820DB601ADE73092B58532CA03FBB663DE495 + 32435336F1558B49BB622726A2FEDD584AD28443A10126A0F658405B2D53 + 5A2B6D5E3C585C1074F414DA9E10BD285C99A33916DADE3ED38812504817 + AC48B62B8E984EC622785BD1C411888BE531B1B594507816B201F6F28579 + A40358D4A401010203035884A20281844B544545502D4465766963654853 + 65637572654653508D82573A926D4754935332DC29997F74427461045854 + 8614A40150C0DDD5F15243566087DB4F5B0AA26C2F0250DB42F7093D8C55 + BAA8C5265FC5820F4E035824822F58208CF71AC86AF31BE184EC7A05A411 + A8C3A14FD9B77A30D046397481469468ECE80E14010F020F0958458614A1 + 15783B68747470733A2F2F6578616D706C652E6F72672F38643832353733 + 612D393236642D343735342D393335332D3332646332393939376637342E + 7461150F030F + +Example 2: SUIT Manifest including the Trusted Component Binary + +CBOR Diagnostic Notation of SUIT Manifest + +/ SUIT_Envelope_Tagged / 107( { + / suit-authentication-wrapper / 2: << [ + << [ + / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, + / suit-digest-bytes: / h'14A98BE957DE38FAE37376EA491FD6CAD9BFBD3C90051C8F5B017D7A496C3B05' ]>>, - / validate / 10:<<[ - / condition-image-match / 3,15 - ]>>, - / run / 12:<<[ - / directive-run / 23,2 + << / COSE_Sign1_Tagged / 18( [ + / protected: / << { + / algorithm-id / 1: -7 / ES256 / + } >>, + / unprotected: / {}, + / payload: / null, + / signature: / h'4093B323953785981EB607C8BA61B21E5C4F85726A2AF48C1CB05BD4401B1B1565070728FDA38E6496D631E1D23F966CFF7805EDE721D48507D9192993DA8722' + ] ) >> ]>>, - / text / 13:<<{ + / suit-integrated-payload / "#tc": h'48656C6C6F2C2053656375726520576F726C6421', / "Hello, Secure World!" / + / suit-manifest / 3: << { + / suit-manifest-version / 1: 1, + / suit-manifest-sequence-number / 2: 3, + / suit-common / 3: << { + / suit-components / 2: [ [ - h'4f502d544545', - h'44f301', - h'edd94cd89d9c4cc89216b3ad5a2d5b8a', - h'7461' - ]:{ - / model-name / 2: 'OP-TEE on TF-A on TrustZone', - / vendor-domain / 3:'teep.example' - } - }>> + h'544545502D446576696365', / "TEEP-Device" / + h'5365637572654653', / "SecureFS" / + h'8D82573A926D4754935332DC29997F74', / tc-uuid / + h'7461' / "ta" / + ] + ], + / suit-common-sequence / 4: << [ + / suit-directive-override-parameters / 20, { + / suit-parameter-vendor-identifier / 1: h'C0DDD5F15243566087DB4F5B0AA26C2F', + / suit-parameter-class-identifier / 2: h'DB42F7093D8C55BAA8C5265FC5820F4E', + / suit-parameter-image-digest / 3: << [ + / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, + / suit-digest-bytes: / h'8CF71AC86AF31BE184EC7A05A411A8C3A14FD9B77A30D046397481469468ECE8' + ] >>, + / suit-parameter-image-size / 14: 20 + }, + / suit-condition-vendor-identifier / 1, 15, + / suit-condition-class-identifier / 2, 15 + ] >> + } >>, + / suit-install / 9: << [ + / suit-directive-override-parameters / 20, { + / suit-parameter-uri / 21: "#tc" + }, + / suit-directive-fetch / 21, 15, + / suit-condition-image-match / 3, 15 + ] >> }>> }) - Personalization Data Manifest: +CBOR Binary Representation - 107({ - 2:<<[ - digest: <<[ - / algorithm-id / -16 / "sha256" /, - / digest-bytes / h'a7fd6593eac32eb4be578278e6540c5c' - h'09cfd7d4d234973054833b2b93030609' - ]>> +D8 6B # tag(107) / SUIT_Envelope_Tagged / + A3 # map(3) + 02 # unsigned(2) / suit-authentication-wrapper / + 58 73 # bytes(115) + 82 # array(2) + 58 24 # bytes(36) + 82 # array(2) + 2F # negative(15) / -16 = suit-cose-alg-sha256 / + 58 20 # bytes(32) + 14A98BE957DE38FAE37376EA491FD6CAD9BFBD3C90051C8F5B017D7A496C3B05 + 58 4A # bytes(74) + D2 # tag(18) / COSE_Sign1_Tagged / + 84 # array(4) + 43 # bytes(3) + A1 # map(1) + 01 # unsigned(1) / algorithm-id / + 26 # negative(6) / -7 = ES256 / + A0 # map(0) + F6 # primitive(22) / null / + 58 40 # bytes(64) + 4093B323953785981EB607C8BA61B21E5C4F85726A2AF48C1CB05BD4401B1B1565070728FDA38E6496D631E1D23F966CFF7805EDE721D48507D9192993DA8722 + 63 # text(3) / suit-integrated-payload / + 237463 # "#tc" + 54 # bytes(20) + 48656C6C6F2C2053656375726520576F726C6421 # "Hello, Secure World!" + + 03 # unsigned(3) / suit-manifest: / + 58 9A # bytes(154) + A4 # map(4) + 01 # unsigned(1) / suit-manifest-version: / + 01 # unsigned(1) + 02 # unsigned(2) / suit-manifest-sequence-number: / + 03 # unsigned(3) + 03 # unsigned(3) / suit-common: / + 58 84 # bytes(132) + A2 # map(2) + 02 # unsigned(2) / suit-components: / + 81 # array(1) + 84 # array(4) + 4B # bytes(11) + 544545502D446576696365 # "TEEP-Device" + 48 # bytes(8) + 5365637572654653 # "SecureFS" + 50 # bytes(16) + 8D82573A926D4754935332DC29997F74 # tc-uuid + 42 # bytes(2) + 7461 # "ta" + 04 # unsigned(4) / suit-common-sequence: / + 58 54 # bytes(84) + 86 # array(6) + 14 # unsigned(20) / suit-directive-override-parameters: / + A4 # map(4) + 01 # unsigned(1) / suit-parameter-vendor-identifier: / + 50 # bytes(16) + C0DDD5F15243566087DB4F5B0AA26C2F + 02 # unsigned(2) / suit-parameter-class-identifier: / + 50 # bytes(16) + DB42F7093D8C55BAA8C5265FC5820F4E + 03 # unsigned(3) / suit-parameter-image-digest: / + 58 24 # bytes(36) + 82 # array(2) + 2F # negative(15) / -16 = suit-cose-alg-sha256 / + 58 20 # bytes(32) + 8CF71AC86AF31BE184EC7A05A411A8C3A14FD9B77A30D046397481469468ECE8 + 0E # unsigned(14) / suit-parameter-image-size: / + 14 # unsigned(20) + 01 # unsigned(1) / suit-condition-vendor-identifier: / + 0F # unsigned(15) + 02 # unsigned(2) / suit-condition-class-identifier: / + 0F # unsigned(15) + 09 # unsigned(9) / suit-install: / + 4C # bytes(12) + 86 # array(6) + 14 # unsigned(20) / suit-directive-override-parameters: / + A1 # map(1) + 15 # unsigned(21) / suit-parameter-uri: / + 63 # text(3) + 237463 # "#tc" + 15 # unsigned(21) / suit-directive-fetch: / + 0F # unsigned(15) + 03 # unsigned(3) / suit-condition-image-match: / + 0F # unsigned(15) + +CBOR Binary in Hex + + D86BA3025873825824822F582014A98BE957DE38FAE37376EA491FD6CAD9 + BFBD3C90051C8F5B017D7A496C3B05584AD28443A10126A0F658404093B3 + 23953785981EB607C8BA61B21E5C4F85726A2AF48C1CB05BD4401B1B1565 + 070728FDA38E6496D631E1D23F966CFF7805EDE721D48507D9192993DA87 + 22632374635448656C6C6F2C2053656375726520576F726C642103589AA4 + 01010203035884A20281844B544545502D44657669636548536563757265 + 4653508D82573A926D4754935332DC29997F744274610458548614A40150 + C0DDD5F15243566087DB4F5B0AA26C2F0250DB42F7093D8C55BAA8C5265F + C5820F4E035824822F58208CF71AC86AF31BE184EC7A05A411A8C3A14FD9 + B77A30D046397481469468ECE80E14010F020F094C8614A1156323746315 + 0F030F + +Example 3: Supplying Personalization Data for Trusted Component Binary + +CBOR Diagnostic Notation of SUIT Manifest + +/ SUIT_Envelope_Tagged / 107( { + / suit-authentication-wrapper / 2: << [ + << [ + / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, + / suit-digest-bytes: / h'CE596D785169B72712560B3A246AA98F814498EA3625EEBB72CED9AF273E7FFD' ]>>, - / manifest / 3:<<{ - / manifest-version / 1:1, - / manifest-sequence-number / 2:3, - / dependencies / 1:[ + << / COSE_Sign1_Tagged / 18( [ + / protected: / << { + / algorithm-id / 1: -7 / ES256 / + } >>, + / unprotected: / {}, + / payload: / null, + / signature: / h'E9083AA71D2BFCE48253037B9C3116A5EDF23BE0F4B4357A8A835F724660DA7482C64345B4C73DE95F05513BD09FC2E58BD2CC865CC851AD797513A9A951A3CA' + ] ) >> + ] >>, + / suit-manifest / 3: << { + / suit-manifest-version / 1: 1, + / suit-manifest-sequence-number / 2: 3, + / suit-common / 3: << { + / suit-dependencies / 1: [ { - / dependency-digest / 1:[ - / algorithm-id / -16 / "sha256" /, - / digest-bytes / h'd6c1fc7200483092e2db59d4907f9b15' - h'05cb3af2795cf78f7ae3d88166fdf743' + / suit-dependency-digest / 1: [ + / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, + / suit-digest-bytes: / h'F8690E5A86D010BF2B5348ABB99F2254DB7B608D0D626B98DB51AB3ECFC51907' ] } ], - / components / 2:[ - ["OP-TEE","RPMB","config.json"] + / suit-components / 2: [ + [ + h'544545502D446576696365', / "TEEP-Device" / + h'5365637572654653', / "SecureFS" / + h'636F6E6669672E6A736F6E' / "config.json" / + ] ], - / common-sequence / 4:<<[ - / directive-set-component-index / 12,0, - / directive-override-parameters / 20,{ - / vendor-id / 1:h'ec41787224345ae580003de697ff8d43' - / ec417872-2434-5ae5-8000-3de697ff8d43 /, - / class-id / 2:h'eb1701b48be85709aca0adf89f056a64' - / eb1701b4-8be8-5709-aca0-adf89f056a64 /, - / image-digest / 3:<<[ - / algorithm-id / -16 / "sha256" /, - / digest-bytes / h'aaabcccdeeef00012223444566678889' - h'abbbcdddefff01112333455567778999' - ]>> - }, - / condition-vendor-identifier / 1,15, - / condition-class-identifier / 2,15 + / suit-common-sequence / 4: << [ + / suit-directive-set-component-index / 12, 0, + / suit-directive-override-parameters / 20, { + / suit-parameter-vendor-identifier / 1: h'C0DDD5F15243566087DB4F5B0AA26C2F', + / suit-parameter-class-identifier / 2: h'DB42F7093D8C55BAA8C5265FC5820F4E', + / suit-parameter-image-digest / 3: << [ + / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, + / suit-digest-bytes: / h'AAABCCCDEEEF00012223444566678889ABBBCDDDEFFF01112333455567778999' ]>>, - / dependency-resolution / 7:<<[ - / directive-set-dependency-index / 13,0, - / directive-set-parameters / 19,{ - / uri / 21:'tam.teep.example/' - 'edd94cd8-9d9c-4cc8-' - '9216-b3ad5a2d5b8a.suit', + / suit-parameter-image-size / 14: 64 }, - / directive-fetch / 21,2, - / condition-image-match / 3,15 - ]>>, - / install / 9:<<[ - / directive-set-component-index / 12,0, - / directive-set-parameters / 19,{ - / uri / 21: - 'http://tam.teep.example/config.json', + / suit-condition-vendor-idnetifier / 1, 15, + / suit-condition-class-identifier / 2, 15 + ] >> + } >>, + / suit-dependency-resolution / 7: << [ + / suit-directive-set-dependency-index / 13, 0, + / suit-directive-override-parameters / 20, { + / suit-parameter-uri / 21: "https://example.org/8d82573a-926d-4754-9353-32dc29997f74.suit" }, - / directive-set-dependency-index / 13,0, - / directive-process-dependency / 18,0, - / directive-set-component-index / 12,0, - / directive-fetch / 21,2, - / condition-image-match / 3,15 - ]>>, - / validate / 10:<<[ - / directive-set-component-index / 12,0, - / condition-image-match / 3,15, - / directive-set-dependency-index / 13,0, - / directive-process-dependency / 18,0 - ]>>, - / run / 12:<<[ - / directive-set-dependency-index / 13,0, - / directive-process-dependency / 18,0 + / suit-directive-fetch / 21, 2, + / suit-condition-image-match / 3, 15 ]>>, - / text / 13:<<{ - [h'4f502d544545', h'44f301', - h'636f6e6669672e6a736f6e']:{ - / model-name / 2: 'Personalised OP-TEE on TF-A on TrustZone', - / vendor-domain / 3:'tam.teep.example', + / suit-install / 9: << [ + / suit-directive-set-dependency-index / 13, 0, + / suit-directive-process-dependency / 18, 0, + / suit-directive-set-component-index / 12, 0, + / suit-directive-override-parameters / 20, { + / suit-parameter-uri / 21: "https://example.org/config.json" }, - [ - h'4f502d544545', - h'44f301', - h'edd94cd89d9c4cc89216b3ad5a2d5b8a', - h'7461' - ]:{ - / model-name / 2:'OP-TEE on TF-A on TrustZone', - / vendor-domain / 3:'teep.example' - } - }>> + / suit-directive-fetch / 21, 2, + / suit-condition-image-match / 3, 15 + ] >>, + / suit-validate / 10: << [ + / suit-directive-set-component-index / 12, 0, + / suit-condition-image-match/ 3, 15 + ] >> }>> }) -E.2. Delete a Trusted Component +CBOR Binary Represenation - This sample manifest removes a Trusted Component and its dependency. +D8 6B # tag(107) / SUIT_Envelope_Tagged / + A2 # map(2) + 02 # unsigned(2) / suit-authentication-wrapper: / + 58 73 # bytes(115) + 82 # array(2) + 58 24 # bytes(36) + 82 # array(2) + 2F # negative(15) / -16 = suit-cose-alg-sha256 / + 58 20 # bytes(32) + CE596D785169B72712560B3A246AA98F814498EA3625EEBB72CED9AF273E7FFD + 58 4A # bytes(74) + D2 # tag(18) / COSE_Sign1_Tagged / + 84 # array(4) + 43 # bytes(3) + A1 # map(1) + 01 # unsigned(1) / algorithm-id / + 26 # negative(6) / -7 = ES256 / + A0 # map(0) + F6 # primitive(22) / null / + 58 40 # bytes(64) + E9083AA71D2BFCE48253037B9C3116A5EDF23BE0F4B4357A8A835F724660DA7482C64345B4C73DE95F05513BD09FC2E58BD2CC865CC851AD797513A9A951A3CA + 03 # unsigned(3) / suit-manifest: / + 59 0134 # bytes(308) + A6 # map(6) + 01 # unsigned(1) / suit-manifest-version: / + 01 # unsigned(1) + 02 # unsigned(2) / suit-manifest-sequence-number: / + 03 # unsigned(3) + 03 # unsigned(3) / suit-common: / + 58 A7 # bytes(167) + A3 # map(3) + 01 # unsigned(1) / suit-dependencies: / + 81 # array(1) + A1 # map(1) + 01 # unsigned(1) suit-dependency-digest: / + 82 # array(2) + 2F # negative(15) / -16 = suit-cose-alg-sha256 / + 58 20 # bytes(32) + F8690E5A86D010BF2B5348ABB99F2254DB7B608D0D626B98DB51AB3ECFC51907 + 02 # unsigned(2) / suit-components: / + 81 # array(1) + 83 # array(3) + 4B # bytes(11) + 544545502D446576696365 # "TEEP-Device" + 48 # bytes(8) + 5365637572654653 # "SecureFS" + 4B # bytes(11) + 636F6E6669672E6A736F6E # "config.json" + 04 # unsigned(4) / suit-common-sequence: / + 58 57 # bytes(87) + 88 # array(8) + 0C # unsigned(12) / suit-directive-set-component-index: / + 00 # unsigned(0) + 14 # unsigned(20) / suit-directive-override-parameters: / + A4 # map(4) + 01 # unsigned(1) / suit-parameter-vendor-identifier: / + 50 # bytes(16) + C0DDD5F15243566087DB4F5B0AA26C2F + 02 # unsigned(2) / suit-parameter-class-identifier: / + 50 # bytes(16) + DB42F7093D8C55BAA8C5265FC5820F4E + 03 # unsigned(3) / suit-parameter-image-digest: / + 58 24 # bytes(36) + 82 # array(2) + 2F # negative(15) / -16 = suit-cose-alg-sha256 / + 58 20 # bytes(32) + AAABCCCDEEEF00012223444566678889ABBBCDDDEFFF01112333455567778999 + 0E # unsigned(14) / suit-parameter-image-size: / + 18 40 # unsigned(64) + 01 # unsigned(1) / suit-condition-vendor-identifier: / + 0F # unsigned(15) + 02 # unsigned(2) / suit-condition-class-identifier: / + 0F # unsigned(15) + 07 # unsigned(7) / suit-dependency-resolution: / + 58 49 # bytes(73) + 88 # array(8) + 0D # unsigned(13) / suit-directive-set-dependency-index: / + 00 # unsigned(0) + 14 # unsigned(20) / suit-directive-override-parameters: / + A1 # map(1) + 15 # unsigned(21) / suit-parameter-uri: / + 78 3D # text(61) + 68747470733A2F2F6578616D706C652E6F72672F38643832353733612D393236642D343735342D393335332D3332646332393939376637342E73756974 # "https://example.org/8d82573a-926d-4754-9353-32dc29997f74.suit" + 15 # unsigned(21) / suit-directive-fetch: / + 02 # unsigned(2) + 03 # unsigned(3) / suit-condition-image-match: / + 0F # unsigned(15) + 09 # unsigned(9) / suit-install: / + 58 2F # bytes(47) + 8C # array(12) + 0D # unsigned(13) / suit-directive-set-dependency-index: / + 00 # unsigned(0) + 12 # unsigned(18) / suit-directive-process-dependency: / + 00 # unsigned(0) + 0C # unsigned(12) / suit-directive-set-component-index: / + 00 # unsigned(0) + 14 # unsigned(20) / suit-directive-override-parameters: / + A1 # map(1) + 15 # unsigned(21) / suit-parameter-uri: / + 78 1F # text(31) + 68747470733A2F2F6578616D706C652E6F72672F636F6E6669672E6A736F6E # "https://example.org/config.json" + 15 # unsigned(21) / suit-directive-fetch: / + 02 # unsigned(2) + 03 # unsigned(3) / suit-condition-image-match: / + 0F # unsigned(15) + 0A # unsigned(10) / suit-validate: / + 45 # bytes(5) + 84 # array(4) + 0C # unsigned(12) / suit-directive-set-component-index: / + 00 + 03 # unsigned(3) / suit-condition-image-match: / + 0F # unsigned(15) - 107({ - / authentication-wrapper / 2:<<[ - digest: <<[ - / algorithm-id / -16 / "sha256" /, - / digest-bytes / - h'a6c4590ac53043a98e8c4106e1e31b305516d7cf0a655eddfac6d45c810e036a' +CBOR Binary in Hex + + D86BA2025873825824822F5820CE596D785169B72712560B3A246AA98F81 + 4498EA3625EEBB72CED9AF273E7FFD584AD28443A10126A0F65840E9083A + A71D2BFCE48253037B9C3116A5EDF23BE0F4B4357A8A835F724660DA7482 + C64345B4C73DE95F05513BD09FC2E58BD2CC865CC851AD797513A9A951A3 + CA03590134A6010102030358A7A30181A101822F5820DB601ADE73092B58 + 532CA03FBB663DE49532435336F1558B49BB622726A2FEDD0281834B5445 + 45502D4465766963654853656375726546534B636F6E6669672E6A736F6E + 045857880C0014A40150C0DDD5F15243566087DB4F5B0AA26C2F0250DB42 + F7093D8C55BAA8C5265FC5820F4E035824822F5820AAABCCCDEEEF000122 + 23444566678889ABBBCDDDEFFF011123334555677789990E1840010F020F + 075849880D0014A115783D68747470733A2F2F6578616D706C652E6F7267 + 2F38643832353733612D393236642D343735342D393335332D3332646332 + 393939376637342E737569741502030F09582F8C0D0012000C0014A11578 + 1F68747470733A2F2F6578616D706C652E6F72672F636F6E6669672E6A73 + 6F6E1502030F0A45840C00030F + +E.4. Example 4: Unlink a Trusted Component + +CBOR Diagnostic Notation of SUIT Manifest +/ SUIT_Envelope_Tagged / 107( { + / suit-authentication-wrapper / 2: << [ + << [ + / suit-digest-algorithm-id: / -16 / suit-cose-alg-sha256 /, + / suit-digest-bytes: / h'632454F19A9440A5B83493628A7EF8704C8A0205A62C34E425BAA34C71341F42' ]>>, - signature: <<18([ + << / COSE_Sign1_Tagged / 18( [ / protected / <<{ - / alg / 1:-7 / "ES256" /, + / algorithm-id / 1: -7 / ES256 / }>>, - / unprotected / { - }, - / payload / F6 / nil /, - / signature / h'd11a2dd9610fb62a707335f58407922570 - 9f96e8117e7eeed98a2f207d05c8ecfba1755208f6abea977b8a6efe3bc2ca3215e119 - 3be201467d052b42db6b7287' + / unprotected: / {}, + / payload: / null, + / signature: / h'A32CDB7C1D089C27408CED3C79087220EB0D77F105BB5330912875F4D94AD108D7658C650463AEB7E1CCA5084F22B2F3993176E8B3529A3202ED735E4D39BBBF' ])>> - ] ]>>, - / manifest / 3:<<{ - / manifest-version / 1:1, - / manifest-sequence-number / 2:0, - / common / 3:<<{ - / components / 2:[ - [h'00'] + / suit-manifest / 3: << { + / suit-manifest-version / 1: 1, + / suit-manifest-sequence-number / 2: 18446744073709551615 / UINT64_MAX /, + / suit-common / 3: << { + / suit-components / 2: [ + [ + h'544545502D446576696365', / "TEEP-Device" / + h'5365637572654653', / "SecureFS" / + h'8D82573A926D4754935332DC29997F74', / tc-uuid / + h'7461' / "ta" / + ] ], - / common-sequence / 4:<<[ - / directive-override-parameters / 20,{ - / vendor-id / - 1:h'fa6b4a53d5ad5fdfbe9de663e4d41ffe' / fa6b4a53-d5ad-5fdf- - be9d-e663e4d41ffe /, - / class-id / - 2:h'1492af1425695e48bf429b2d51f2ab45' / - 1492af14-2569-5e48-bf42-9b2d51f2ab45 /, - / image-digest / 3:<<[ - / algorithm-id / -16 / "sha256" /, - / digest-bytes / - h'00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210' - ]>>, - / image-size / 14:34768, + / suit-common-sequence / 4: << [ + / suit-directive-override-parameters / 20, { + / suit-parameter-vendor-identifier / 1: h'C0DDD5F15243566087DB4F5B0AA26C2F', + / suit-parameter-class-identifier / 2: h'DB42F7093D8C55BAA8C5265FC5820F4E' } , - / condition-vendor-identifier / 1,15 , - / condition-class-identifier / 2,15 - ]>>, - }>>, - / validate / 10:<<[ - / condition-image-match / 3,15 - ]>>, - / run / 12:<<[ - / directive-run / 23,2 - ]>>, + / suit-condition-vendor-identifier / 1, 15, + / suit-condition-class-identifier / 2, 15 + ] >> }>>, + / suit-install / 9: << [ + / suit-directive-set-component-index: / 12, 0, + / suit-directive-unlink: / 33, 0 + ] >> + } >> }) - Total size of Envelope without COSE authentication object: 161 +CBOR Binary Representation +D8 6B # tag(107) / SUIT_Envelope_Tagged / + A2 # map(2) + 02 # unsigned(2) / suit-authentication-wrapper / + 58 73 # bytes(115) + 82 # array(2) + 58 24 # bytes(36) + 82 # array(2) + 2F # negative(15) / -16 = suit-cose-alg-sha256 / + 58 20 # bytes(32) + 632454F19A9440A5B83493628A7EF8704C8A0205A62C34E425BAA34C71341F42 + 58 4A # bytes(74) + D2 # tag(18) / COSE_Sign1_Tagged / + 84 # array(4) + 43 # bytes(3) + A1 # map(1) + 01 # unsigned(1) / algorithm-id / + 26 # negative(6) / -7 = ES256 / + A0 # map(0) + F6 # primitive(22) / null / + 58 40 # bytes(64) + A32CDB7C1D089C27408CED3C79087220EB0D77F105BB5330912875F4D94AD108D7658C650463AEB7E1CCA5084F22B2F3993176E8B3529A3202ED735E4D39BBBF + 03 # unsigned(3) / suit-manifest: / + 58 73 # bytes(115) + A4 # map(4) + 01 # unsigned(1) / suit-manifest-version: / + 01 # unsigned(1) + 02 # unsigned(2) / suit-manifest-sequence-number: / + 1B FFFFFFFFFFFFFFFF # unsigned(18446744073709551615) + 03 # unsigned(3) / suit-common: / + 58 5B # bytes(91) + A2 # map(2) + 02 # unsigned(2) / suit-components: / + 81 # array(1) + 84 # array(4) + 4B # bytes(11) + 544545502D446576696365 # "TEEP-Device" + 48 # bytes(8) + 5365637572654653 # "SecureFS" + 50 # bytes(16) + 8D82573A926D4754935332DC29997F74 # tc-uuid + 42 # bytes(2) + 7461 # "ta" + 04 # unsigned(4) / suit-common-sequence: / + 58 2B # bytes(84) + 86 # array(6) + 14 # unsigned(20) / suit-directive-override-parameters: / + A2 # map(2) + 01 # unsigned(1) / suit-parameter-vendor-identifier: / + 50 # bytes(16) + C0DDD5F15243566087DB4F5B0AA26C2F + 02 # unsigned(2) / suit-parameter-class-identifier: / + 50 # bytes(16) + DB42F7093D8C55BAA8C5265FC5820F4E + 01 # unsigned(1) / suit-condition-vendor-identifier: / + 0F # unsigned(15) + 02 # unsigned(2) / suit-condition-class-identifier: / + 0F # unsigned(15) + 09 # unsigned(9) / suit-install: / + 46 # bytes(6) + 84 # array(4) + 0C # unsigned(12) / suit-directive-set-component-index: / + 00 # unsigned(0) + 18 21 # unsigned(33) / suit-directive-unlink: / + 00 # unsigned(0) - Envelope: +CBOR Binary in Hex - d86ba2025827815824822f5820a6c4590ac53043a98e8c4106e1e31b3055 - 16d7cf0a655eddfac6d45c810e036a035871a50101020003585fa2028181 - 41000458568614a40150fa6b4a53d5ad5fdfbe9de663e4d41ffe02501492 - af1425695e48bf429b2d51f2ab45035824822f5820001122334455667788 - 99aabbccddeeff0123456789abcdeffedcba98765432100e1987d0010f02 - 0f0a4382030f0c43821702 + D86BA2025873825824822F5820632454F19A9440A5B83493628A7EF8704C + 8A0205A62C34E425BAA34C71341F42584AD28443A10126A0F65840A32CDB + 7C1D089C27408CED3C79087220EB0D77F105BB5330912875F4D94AD108D7 + 658C650463AEB7E1CCA5084F22B2F3993176E8B3529A3202ED735E4D39BB + BF035873A40101021BFFFFFFFFFFFFFFFF03585BA20281844B544545502D + 446576696365485365637572654653508D82573A926D4754935332DC2999 + 7F7442746104582B8614A20150C0DDD5F15243566087DB4F5B0AA26C2F02 + 50DB42F7093D8C55BAA8C5265FC5820F4E010F020F0946840C00182100 - Total size of Envelope with COSE authentication object: 237 +F. Examples of SUIT Reports - Envelope with COSE authentication object: + This section shows some examples of SUIT reports. - d86ba2025873825824822f5820a6c4590ac53043a98e8c4106e1e31b3055 - 16d7cf0a655eddfac6d45c810e036a584ad28443a10126a0f65840d11a2d - d9610fb62a707335f584079225709f96e8117e7eeed98a2f207d05c8ecfb - a1755208f6abea977b8a6efe3bc2ca3215e1193be201467d052b42db6b72 - 87035871a50101020003585fa202818141000458568614a40150fa6b4a53 - d5ad5fdfbe9de663e4d41ffe02501492af1425695e48bf429b2d51f2ab45 - 035824822f582000112233445566778899aabbccddeeff0123456789abcd - effedcba98765432100e1987d0010f020f0a4382030f0c43821702 +F.1. Example 1: Success + + SUIT Reports have no records if no conditions have failed. The URI + in this example is the reference URI provided in the SUIT manifest. + +{ + / suit-report-manifest-digest / 1:<<[ + / algorithm-id / -16 / "sha256" /, + / digest-bytes / h'a7fd6593eac32eb4be578278e6540c5c' + h'09cfd7d4d234973054833b2b93030609' + ]>>, + / suit-report-manifest-uri / 2: "tam.teep.example/personalisation.suit", + / suit-report-records / 4: [] +} +F.2. Example 2: Faiure + +{ + / suit-report-manifest-digest / 1:<<[ + / algorithm-id / -16 / "sha256" /, + / digest-bytes / h'a7fd6593eac32eb4be578278e6540c5c09cfd7d4d234973054833b2b93030609' + ]>>, + / suit-report-manifest-uri / 2: "tam.teep.example/personalisation.suit", + / suit-report-records / 4: [ + { + / suit-record-manifest-id / 1:[], + / suit-record-manifest-section / 2: 7 / dependency-resolution /, + / suit-record-section-offset / 3: 66, + / suit-record-dependency-index / 5: 0, + / suit-record-failure-reason / 6: 404 + } + ] +} + + where the dependency-resolution refers to: + + 107({ + authentication-wrapper, + / manifest / 3:<<{ + / manifest-version / 1:1, + / manifest-sequence-number / 2:3, + common, + dependency-resolution, + install, + validate, + run, + text + }>>, + }) + + and the suit-record-section-offset refers to: + + <<[ + / directive-set-dependency-index / 13,0 , + / directive-set-parameters / 19,{ + / uri / 21:'tam.teep.example/' + 'edd94cd8-9d9c-4cc8-9216-b3ad5a2d5b8a.suit', + } , + / directive-fetch / 21,2 , + / condition-image-match / 3,15 + ]>>, Authors' Addresses Hannes Tschofenig Arm Ltd. 6067 Absam Austria - Email: hannes.tschofenig@arm.com Mingliang Pei Broadcom 350 Ellis St Mountain View, CA 94043 United States of America - Email: mingliang.pei@broadcom.com David Wheeler Amazon United States of America - Email: davewhee@amazon.com Dave Thaler Microsoft United States of America - Email: dthaler@microsoft.com Akira Tsukamoto AIST Japan - Email: akira.tsukamoto@aist.go.jp