| TEEP | H. Tschofenig |
| Internet-Draft | Arm Ltd. |
| Intended status: Standards Track | M. Pei |
| Expires: October 16, 2020 | Broadcom |
| D. Wheeler | |
| Intel | |
| D. Thaler | |
| Microsoft | |
| A. Tsukamoto | |
| AIST | |
| April 14, 2020 |
Trusted Execution Environment Provisioning (TEEP) Protocol
draft-ietf-teep-protocol-02
This document specifies a protocol that installs, updates, and deletes Trusted Applications (TAs) in a device with a Trusted Execution Environment (TEE). This specification defines an interoperable protocol for managing the lifecycle of TAs.
The protocol name is pronounced teepee. This conjures an image of a wedge-shaped protective covering for one’s belongings, which sort of matches the intent of this protocol.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
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 October 16, 2020.
Copyright (c) 2020 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.
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 an TEE ecosystem, device vendors may use different operating systems in the REE and may use different types of TEEs. When application providers or device administrators use Trusted Application Managers (TAMs) to install, update, and delete Trusted Applications (TAs) on a wide range of devices with potentially different TEEs then an interoperability need arises.
This document specifies the protocol for communicating between a TAM and a TEEP Agent, involving a TEEP Broker.
The Trusted Execution Environment Provisioning (TEEP) architecture document [I-D.ietf-teep-architecture] has set to provide a design guidance for such an interoperable protocol and introduces the necessary terminology. Note that the term Trusted Application may include more than code; it may also include configuration data and keys needed by the TA to operate correctly.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This specification re-uses the terminology defined in [I-D.ietf-teep-architecture].
The TEEP protocol consists of a couple of messages exchanged between a TAM and a TEEP Agent via a TEEP Broker. The messages are encoded in CBOR and designed to provide end-to-end security. TEEP protocol messages are signed by the endpoints, i.e., the TAM and the TEEP Agent, but trusted applications may as well be encrypted and signed by the service provider. The TEEP protocol not only re-use CBOR but also the respective security wrapper, namely COSE [RFC8152]. Furthermore, for attestation the Entity Attestation Token (EAT) [I-D.ietf-rats-eat] and for software updates the SUIT manifest format [I-D.ietf-suit-manifest] are re-used.
This specification defines six messages.
A TAM queries a device’s current state with a QueryRequest message. A TEEP Agent will, after authenticating and authorizing the request, report attestation information, list all TAs, and provide information about supported algorithms and extensions in a QueryResponse message. An error message is returned if the request could not be processed. A TAM will process the QueryResponse message and determine whether subsequent message exchanges to install, update, or delete trusted applications shall be initiated.
+------------+ +-------------+
| TAM | |TEEP Agent |
+------------+ +-------------+
QueryRequest ------->
QueryResponse
<------- or
Error
With the TrustedAppInstall message a TAM can instruct a TEEP Agent to install a TA. The TEEP Agent will process the message, determine whether the TAM is authorized and whether the TA has been signed by an authorized SP. In addition to the binary, the TAM may also provide personalization data. If the TrustedAppInstall message was processed successfully then a Success message is returned to the TAM, an Error message otherwise.
+------------+ +-------------+
| TAM | |TEEP Agent |
+------------+ +-------------+
TrustedAppInstall ---->
Success
<---- or
Error
With the TrustedAppDelete message a TAM can instruct a TEEP Agent to delete one or multiple TA(s). A Success message is returned when the operation has been completed successfully, and an Error message otherwise.
+------------+ +-------------+
| TAM | |TEEP Agent |
+------------+ +-------------+
TrustedAppDelete ---->
Success
<---- or
Error
TEEP messages are protected by the COSE_Sign1 structure. The TEEP protocol messages are described in CDDL format [RFC8610] below.
teep-message => (QueryRequest /
QueryResponse /
TrustedAppInstall /
TrustedAppDelete /
Error /
Success ),
}
To create a TEEP message, the following steps are performed.
When validating a TEEP message, the following steps are performed. If any of the listed steps fail, then the TEEP message MUST be rejected.
A QueryRequest message is used by the TAM to learn information from the TEEP Agent. The TAM can learn the features supported by the TEEP Agent, 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:
Like other TEEP messages, the QueryRequest message is signed, and the relevant CDDL snippet is shown below. The complete CDDL structure is shown in [CDDL].
query-request = [
type: TEEP-TYPE-query-request,
token: uint,
options: {
? supported-cipher-suites => suite,
? nonce => bstr .size (8..64),
? version => [ + version ],
? oscp-data => bstr,
* $$query-request-extensions
* $$teep-option-extensions
},
data-item-requested
]
The message has the following fields:
Further values may be added in the future via IANA registration.
The QueryResponse message is the successful response by the TEEP Agent after receiving a QueryRequest 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 [CDDL].
query-response = [
type: TEEP-TYPE-query-response,
token: uint,
options: {
? selected-cipher-suite => suite,
? selected-version => version,
? eat => bstr,
? ta-list => [ + bstr ],
? ext-list => [ + ext-info ],
* $$query-response-extensions,
* $$teep-option-extensions
}
]
The message has the following fields:
The TrustedAppInstall message is used by the TAM to install software (trusted apps) via the TEEP Agent.
Like other TEEP messages, the TrustedAppInstall message is signed, and the relevant CDDL snippet is shown below. The complete CDDL structure is shown in [CDDL].
trusted-app-install = [
type: TEEP-TYPE-trusted-app-install,
token: uint,
option: {
? manifest-list => [ + SUIT-envelope ],
* $$trusted-app-install-extensions,
* $$teep-option-extensions
}
]
The TrustedAppInstall message has the following fields:
The TrustedAppDelete message is used by the TAM to remove software (trust apps) from the device.
Like other TEEP messages, the TrustedAppDelete message is signed, and the relevant CDDL snippet is shown below. The complete CDDL structure is shown in [CDDL].
trusted-app-delete = [
type: TEEP-TYPE-trusted-app-delete,
token: uint,
option: {
? ta-list => [ + bstr ],
* $$trusted-app-delete-extensions,
* $$teep-option-extensions
}
]
The TrustedAppDelete message has the following fields:
The TEEP protocol defines two implicit success messages and this explicit Success message for the cases where the TEEP Agent cannot return another reply, such as for the TrustedAppInstall and the TrustedAppDelete messages.
Like other TEEP messages, the Success message is signed, and the relevant CDDL snippet is shown below. The complete CDDL structure is shown in [CDDL].
teep-success = [
type: TEEP-TYPE-teep-success,
token: uint,
option: {
? msg => text,
* $$teep-success-extensions,
* $$teep-option-extensions
}
]
The Success message has the following fields:
The Error message is used by the TEEP Agent to return an error.
Like other TEEP messages, the Error message is signed, and the relevant CDDL snippet is shown below. The complete CDDL structure is shown in [CDDL].
teep-error = [
type: TEEP-TYPE-teep-error,
token: uint,
err-code: uint,
options: {
? err-msg => text,
? cipher-suites => [ + suite ],
? versions => [ + version ],
* $$teep-error--extensions,
* $$teep-option-extensions
}
]
The Error message has the following fields:
This specification defines the following initial error messages:
Additional error code can be registered with IANA.
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:
| Name | Label |
|---|---|
| cipher-suites | 1 |
| nonce | 2 |
| version | 3 |
| ocsp-data | 4 |
| selected-cipher-suite | 5 |
| selected-version | 6 |
| eat | 7 |
| ta-list | 8 |
| ext-list | 9 |
| manifest-list | 10 |
| msg | 11 |
| err-msg | 12 |
A ciphersuite consists of an AEAD algorithm, a HMAC algorithm, and a signature algorithm. Each ciphersuite is identified with an integer value, which corresponds to an IANA registered ciphersuite. This document specifies two ciphersuites.
| 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 |
This section summarizes the security considerations discussed in this specification:
IANA is requested to assign a media type for application/teep+cbor.
IANA is also requested to create a new registry for the error codes defined in Section 4.
Registration requests are evaluated after a three-week review period on the teep-reg-review@ietf.org mailing list, on the advice of one or more Designated Experts [RFC8126]. However, to allow for the allocation of values prior to publication, the Designated Experts may approve registration once they are satisfied that such a specification will be published.
Registration requests sent to the mailing list for review should use an appropriate subject (e.g., “Request to register an error code: example”). Registration requests that are undetermined for a period longer than 21 days can be brought to the IESG’s attention (using the iesg@ietf.org mailing list) for resolution.
Criteria that should be applied by the Designated Experts includes determining whether the proposed registration duplicates existing functionality, whether it is likely to be of general applicability or whether it is useful only for a single extension, and whether the registration description is clear.
IANA must only accept registry updates from the Designated Experts and should direct all requests for registration to the review mailing list.
IANA is also requested to create a new registry for ciphersuites, as defined in Section 6.
IANA is requested to register a CBOR tag in the “CBOR Tags” registry for use with TEEP messages.
The registry contents is:
| [I-D.ietf-teep-architecture] | Pei, M., Tschofenig, H., Thaler, D. and D. Wheeler, "Trusted Execution Environment Provisioning (TEEP) Architecture", Internet-Draft draft-ietf-teep-architecture-08, April 2020. |
| [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, June 2019. |
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.
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 also like to thank Carsten Bormann and Henk Birkholz for their help with the CDDL.
teep-message = $teep-message-type .within teep-message-framework
SUIT-envelope = bstr ; placeholder
teep-message-framework = [
type: 0..23 / $teep-type-extension,
token: uint,
options: { * teep-option },
* int; further integers, e.g. for data-item-requested
]
teep-option = (uint => any)
; messages defined below:
$teep-message-type /= query-request
$teep-message-type /= query-response
$teep-message-type /= trusted-app-install
$teep-message-type /= trusted-app-delete
$teep-message-type /= teep-error
$teep-message-type /= teep-success
; message type numbers
TEEP-TYPE-query-request = 1
TEEP-TYPE-query-response = 2
TEEP-TYPE-trusted-app-install = 3
TEEP-TYPE-trusted-app-delete = 4
TEEP-TYPE-teep-error = 5
TEEP-TYPE-teep-success = 6
version = uint .size 4
ext-info = uint
; data items as bitmaps
data-item-requested = $data-item-requested .within uint .size 8
attestation = 1
$data-item-requested /= attestation
trusted-apps = 2
$data-item-requested /= trusted-apps
extensions = 4
$data-item-requested /= extensions
suit-commands = 8
$data-item-requested /= suit-commands
query-request = [
type: TEEP-TYPE-query-request,
token: uint,
options: {
? supported-cipher-suites => suite,
? nonce => bstr .size (8..64),
? version => [ + version ],
? oscp-data => bstr,
* $$query-request-extensions
* $$teep-option-extensions
},
data-item-requested
]
; ciphersuites as bitmaps
suite = $TEEP-suite .within uint .size 8
TEEP-AES-CCM-16-64-128-HMAC256--256-X25519-EdDSA = 1
TEEP-AES-CCM-16-64-128-HMAC256--256-P-256-ES256 = 2
$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
query-response = [
type: TEEP-TYPE-query-response,
token: uint,
options: {
? selected-cipher-suite => suite,
? selected-version => version,
? eat => bstr,
? ta-list => [ + bstr ],
? ext-list => [ + ext-info ],
* $$query-response-extensions,
* $$teep-option-extensions
}
]
trusted-app-install = [
type: TEEP-TYPE-trusted-app-install,
token: uint,
option: {
? manifest-list => [ + SUIT-envelope ],
* $$trusted-app-install-extensions,
* $$teep-option-extensions
}
]
trusted-app-delete = [
type: TEEP-TYPE-trusted-app-delete,
token: uint,
option: {
? ta-list => [ + bstr ],
* $$trusted-app-delete-extensions,
* $$teep-option-extensions
}
]
teep-success = [
type: TEEP-TYPE-teep-success,
token: uint,
option: {
? msg => text,
* $$teep-success-extensions,
* $$teep-option-extensions
}
]
teep-error = [
type: TEEP-TYPE-teep-error,
token: uint,
options: {
? err-msg => text,
? cipher-suites => [ + suite ],
? versions => [ + version ],
* $$teep-error--extensions,
* $$teep-option-extensions
}
err-code: uint,
]
cipher-suites = 1
nonce = 2
versions = 3
oscp-data = 4
selected-cipher-suite = 5
selected-version = 6
eat = 7
ta-list = 8
ext-list = 9
manifest-list = 10
msg = 11
err-msg = 12