HTTP Transport for Trusted Execution Environment Provisioning: Agent-to- TAM Communication
draft-ietf-teep-otrp-over-http-03
The information below is for an old version of the document.
Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Active".
|
|
---|---|---|---|
Author | Dave Thaler | ||
Last updated | 2019-11-04 (Latest revision 2019-10-22) | ||
Replaces | draft-thaler-teep-otrp-over-http | ||
RFC stream | Internet Engineering Task Force (IETF) | ||
Formats | |||
Reviews |
GENART Last Call review
(of
-13)
by Russ Housley
Almost ready
ARTART Last Call review
(of
-13)
by Carsten Bormann
Ready w/nits
|
||
Additional resources | Mailing list discussion | ||
Stream | WG state | WG Document | |
Associated WG milestone |
|
||
Document shepherd | (None) | ||
IESG | IESG state | I-D Exists | |
Consensus boilerplate | Unknown | ||
Telechat date | (None) | ||
Responsible AD | (None) | ||
Send notices to | (None) |
draft-ietf-teep-otrp-over-http-03
TEEP WG D. Thaler Internet-Draft Microsoft Intended status: Informational November 04, 2019 Expires: May 7, 2020 HTTP Transport for Trusted Execution Environment Provisioning: Agent-to- TAM Communication draft-ietf-teep-otrp-over-http-03 Abstract The Trusted Execution Environment Provisioning (TEEP) Protocol is used to manage code and configuration data in a Trusted Execution Environment (TEE). This document specifies the HTTP transport for TEEP communication where a Trusted Application Manager (TAM) service is used to manage TEEs in devices that can initiate communication to the TAM. An implementation of this document can (if desired) run outside of any TEE, but interacts with a TEEP implementation that runs inside a TEE. Status of This Memo 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 http://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 May 7, 2020. Copyright Notice Copyright (c) 2019 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 (http://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 Thaler Expires May 7, 2020 [Page 1] Internet-Draft TEEP HTTP Transport November 2019 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. Internet-Draft JMAP Sieve February 2021 Request (and response) to create and activate a script using the uploaded blob: { "using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:sieve" ], "methodCalls": [ ["SieveScript/set", { "accountId": "ken", "create": { "A": { "name": null, "blobId": "Gabcc83e44a6e19991c4568d0b94e1767c83dd123" }, "onSuccessActivateScript": "#A" }, "0"] ] } { "methodResponses": [ [ "SieveScript/set", { "oldState": "1603741717.50737918-4096", "newState": "1603741751.227268529-4096", "created": { "A": { "id": "dd1b164f-8cdc-448c-9f54-60210b5f14ae", "name": "ken-20201210T171432-0", "blobId": "Sdd1b164f-8cdc-448c-9f54-60210b5f14ae", "isActive": true } }, "updated": null, "destroyed": null, "notCreated": null, "notUpdated": null, "notDestroyed": null, "accountId": "ken" }, "0" ] ] } Request (and response) to update script content using the JMAP Blob management extension [I-D.gondwana-jmap-blob]: Murchison Expires August 7, 2021 [Page 9] Internet-Draft JMAP Sieve February 2021 { "using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:sieve", "urn:ietf:params:jmap:blob" ], "methodCalls": [ ["Blob/set", { "accountId": "ken", "create": { "B": { "data:asText": "redirect \"ken@example.com\"\r\n;", "type": "application/sieve" } }, "1"], ["SieveScript/set", { "accountId": "ken", "update": { "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { "blobId": &Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. TEEP Broker Models . . . . . . . . . . . . . . . . . . . . . 4 3.1. Use of Abstract APIs . . . . . . . . . . . . . . . . . . 5 4. Use of HTTP as a Transport . . . . . . . . . . . . . . . . . 6 5. TEEP/HTTP Client Behavior . . . . . . . . . . . . . . . . . . 7 5.1. Receiving a request to install a new Trusted Application 7 5.1.1. Session Creation . . . . . . . . . . . . . . . . . . 7 5.2. Getting a message buffer back from a TEEP implementation 8 5.3. Receiving an HTTP response . . . . . . . . . . . . . . . 8 5.4. Handling checks for policy changes . . . . . . . . . . . 9 5.5. Error handling . . . . . . . . . . . . . . . . . . . . . 9 6. TEEP/HTTP Server Behavior . . . . . . . . . . . . . . . . . . 9 6.1. Receiving an HTTP POST request . . . . . . . . . . . . . 10 6.2. Getting an empty buffer back from the TEEP implementation 10 6.3. Getting a message buffer from the TEEP implementation . . 10 6.4. Error handling . . . . . . . . . . . . . . . . . . . . . 10 7. Sample message flow . . . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 10.1. Normative References . . . . . . . . . . . . . . . . . . 13 10.2. Informative References . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 1. Introduction Trusted Execution Environments (TEEs), including environments based on Intel SGX, ARM TrustZone, Secure Elements, and others, enforce that only authorized code can execute within the TEE, and any memory used by such code is protected against tampering or disclosure outside the TEE. The Trusted Execution Environment Provisioning (TEEP) protocol is designed to provision authorized code and configuration into TEEs. To be secure against malware, a TEEP implementation (referred to as a TEEP "Agent" on the client side, and a "Trusted Application Manager (TAM)" on the server side) must themselves run inside a TEE. However, the transport for TEEP, along with the underlying TCP/IP stack, does not necessarily run inside a TEE. This split allows the set of highly trusted code to be kept as small as possible, including Thaler Expires May 7, 2020 [Page 2] Internet-Draft TEEP HTTP Transport November 2019 allowing code (e.g., TCP/IP) that only sees encrypted messages, to be kept out of the TEE. The TEEP specification [I-D.tschofenig-teep-protocol] (and its predecessors [I-D.ietf-teep-opentrustprotocol] and [GP-OTrP]) describes the behavior of TEEP Agents and TAMs, but does not specify the details of the transport. The purpose of this document is to provide such details. That is, a TEEP-over-HTTP (TEEP/HTTP) implementation delivers messages up to a TEEP implementation, and accepts messages from the TEEP implementation to be sent over a network. The TEEP-over-HTTP implementation can be implemented either outside a TEE (i.e., in a TEEP "Broker") or inside a TEE. There are two topological scenarios in which TEEP could be deployed: 1. TAMs are reachable on the Internet, and Agents are on networks that might be behind a firewall, so that communication must be initiated by an Agent. Thus, the Agent has an HTTP Client and the TAM has an HTTP Server. 2. Agents are reachable on the Internet, and TAMs are on networks that might be behind a firewall, so that communication must be initiated by a TAM. Thus, the Agent has an HTTP Server and the TAM has an HTTP Client. The remainder of this document focuses primarily on the first scenario as depicted in Figure 1, but some sections (Section 4 and Section 8) may apply to the second scenario as well. A fuller discussion of the second scenario may be handled by a separate document. +------------------+ TEEP +------------------+ | TEEP Agent | <----------------------> | TAM | +------------------+ +------------------+ | | +------------------+ TEEP-over-HTTP +------------------+ | TEEP/HTTP Client | <----------------------> | TEEP/HTTP Server | +------------------+ +------------------+ | | +------------------+ HTTP +------------------+ | HTTP Client | <----------------------> | HTTP Server | +------------------+ +------------------+ Figure 1: Agent-to-TAM Communication Thaler Expires May 7, 2020 [Page 3] Internet-Draft TEEP HTTP Transport November 2019 2. Terminology 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 document also uses various terms defined in [I-D.ietf-teep-architecture], including Trusted Execution Environment (TEE), Trusted Application (TA), Trusted Application Manager (TAM), TEEP Agent, and TEEP Broker, and Rich Execution Environment (REE). 3. TEEP Broker Models Section 6 of the TEEP architecture [I-D.ietf-teep-architecture] defines a TEEP "Broker" as being a component on the device, but outside the TEE, that facilitates communication with a TAM. As depicted in Figure 2, there are multiple ways in which this can be implemented, with more or fewer layers being inside the TEE. For example, in model A, the model with the smallest TEE footprint, only the TEEP implementation is inside the TEE, whereas the TEEP/HTTP implementation is in the TEEP Broker outside the TEE. Thaler Expires May 7, 2020 [Page 4] Internet-Draft TEEP HTTP Transport November 2019 Model: A B C ... TEE TEE TEE +----------------+ | | | | TEEP | Agent | | | Agent | implementation | | | | +----------------+ v | | | | | +----------------+ ^ | | | TEEP/HTTP | Broker | | | | implementation | | | | +----------------+ | v | | | | +----------------+ | ^ | | HTTP | | | | | implementation | | | | +----------------+ | | v | | | +----------------+ | | ^ | TCP or QUIC | | | | Broker | implementation | | | | +----------------+ | | | REE REE REE Figure 2: TEEP Broker Models In other models, additional layers are moved into the TEE, increasing the TEE footprint, with the Broker either containing or calling the topmost protocol layer outside of the TEE. An implementation is free to choose any of these models, although model A is the one we will use in our examples. Passing information from an REE component to a TEE component is typically spoken of as being passed "in" to the TEE, and informaton passed in the opposite direction is spoken of as being passed "out". In the protocol layering sense, information is typically spoken of as being passed "up" or "down" the stack. Since the layer at which information is passed in/out may vary by implementation, we will generally use "up" and "down" in this document. 3.1. Use of Abstract APIs This document refers to various APIs between a TEEP implementation and a TEEP/HTTP implementation in the abstract, meaning the literal syntax and programming language are not specified, so that various concrete APIs can be designed (outside of the IETF) that are compliant. Thaler Expires May 7, 2020 [Page 5] Internet-Draft TEEP HTTP Transport November 2019 Some TEE architectures (e.g., SGX) may support API calls both into and out of a TEE. In other TEE architectures, there may be no calls out from a TEE, but merely data returned from calls into a TEE. This document attempts to be agnostic as to the concrete API architecture for Broker/Agent communication. Since in model A, the Broker/Agent communication is done at the layer between the TEEP and TEEP/HTTP implementations, and there may be some architectures that do not support calls out of the TEE (which would be downcalls from TEEP in model A), we will refer to passing information up to the TEEP implementation as API calls, but will simply refer to "passing data" back down from a TEEP implementation. A concrete API might pass data back via an API downcall or via data returned from an API upcall. This document will also refer to passing "no" data back out of a TEEP implementation. In a concrete API, this might be implemented by not making any downcall, or by returning 0 bytes from an upcall, for example. 4. Use of HTTP as a Transport This document uses HTTP [I-D.ietf-httpbis-semantics] as a transport. When not called out explicitly in this document, all implementation recommendations in [I-D.ietf-httpbis-bcp56bis] apply to use of HTTP by TEEP. Redirects MAY be automatically followed, and no additional request headers beyond those specified by HTTP need be modified or removed upon a following such a redirect. Content is not intended to be treated as active by browsers and so HTTP responses with content SHOULD have the following headers as explained in Section 4.12 of [I-D.ietf-httpbis-bcp56bis] (replacing the content type with the relevant TEEP content type per the TEEP specification): Content-Type: <content type> Cache-Control: no-store X-Content-Type-Options: nosniff Content-Security-Policy: default-src 'none' Referrer-Policy: no-referrer Only the POST method is specified for TAM resources exposed over HTTP. A URI of such a resource is referred to as a "TAM URI". A TAM URI can be any HTTP(S) URI. The URI to use is configured in a TEEP Agent via an out-of-band mechanism, as discussed in the next section. When HTTPS is used, TLS certificates MUST be checked according to [RFC2818]. Thaler Expires May 7, 2020 [Page 6] Internet-Draft TEEP HTTP Transport November 2019 5. TEEP/HTTP Client Behavior 5.1. Receiving a request to install a new Trusted Application In some environments, an application installer can determine (e.g., from an app manifest) that the application being installed or updated has a dependency on a given Trusted Application (TA) being available in a given type of TEE. In such a case, it will notify a TEEP Broker, where the notification will contain the following: - A unique identifier of the TA - Optionally, any metadata to provide to the TEEP implementation. This might include a TAM URI provided in the application manifest, for example. - Optionally, any requirements that may affect the choice of TEE, if multiple are available to the TEEP Broker. When a TEEP Broker receives such a notification, it first identifies in an implementation-dependent way which TEE (if any) is most appropriate based on the constraints expressed. If there is only one TEE, the choice is obvious. Otherwise, the choice might be based on factors such as capabilities of available TEE(s) compared with TEE requirements in the notification. Once the TEEP Broker picks a TEE, it passes the notification to the TEEP/HTTP Client for that TEE. The TEEP/HTTP Client then informs the TEEP implementation in that TEE by invoking an appropriate "RequestTA" API that identifies the TA needed and any other associated metadata. The TEEP/HTTP Client need not know whether the TEE already has such a TA installed or whether it is up to date. The TEEP implementation will either (a) pass no data back, (b) pass back a TAM URI to connect to, or (c) pass back a message buffer and TAM URI to send it to. The TAM URI passed back may or may not be the same as the TAM URI, if any, provided by the TEEP/HTTP Client, depending on the TEEP implementation's configuration. If they differ, the TEEP/HTTP Client MUST use the TAM URI passed back. 5.1.1. Session Creation If no data is passed back, the TEEP/HTTP Client simply informs its caller (e.g., the application installer) of success. If the TEEP implementation passes back a TAM URI with no message buffer, the TEEP/HTTP Client attempts to create session state, then sends an HTTP(S) POST to the TAM URI with an Accept header and an Thaler Expires May 7, 2020 [Page 7] Internet-Draft TEEP HTTP Transport November 2019 empty body. The HTTP request is then associated with the TEEP/HTTP Client's session state. If the TEEP implementation instead passes back a TAM URI with a message buffer, the TEEP/HTTP Client attempts to create session state and handles the message buffer as specified in Section 5.2. Session state consists of: - Any context (e.g., a handle) that identifies the API session with the TEEP implementation. - Any context that identifies an HTTP request, if one is outstanding. Initially, none exists. 5.2. Getting a message buffer back from a TEEP implementation When a TEEP implementation passes a message buffer (and TAM URI) to a TEEP/HTTP Client, the TEEP/HTTP Client MUST do the following, using the TEEP/HTTP Client"#B" } } }, "2"] ] } { "methodResponses": [ [ "Blob/set", { "oldState": null, "newState": "1603741700.309607123-0128", "created": { "B": { "id": "G969c83e44a6e10871c4568d0b94e1767c83ddeae", "blobId": "G969c83e44a6e10871c4568d0b94e1767c83ddeae", "type": "application/sieve", "size": 29 } }, "updated": null, "destroyed": null, "notCreated": null, "notUpdated": null, "notDestroyed": null, "accountId": "ken" }, "1" ], [ "SieveScript/set", Murchison Expires August 7, 2021 [Page 10] Internet-Draft JMAP Sieve February 2021 { "oldState": "1603741751.227268529-4096", "newState": "1603742603.309607868-4096", "created": null, "updated": { "dd1b164f-8cdc-448c-9f54-60210b5f14ae": null }, "destroyed": null, "notCreated": null, "notUpdated": null, "notDestroyed": null, "accountId": "ken" }, "2" ] ] } Murchison Expires August 7, 2021 [Page 11] Internet-Draft JMAP Sieve February 2021 Request (and response) to update script name and deactivate: { "using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:sieve" ], "methodCalls": [ ["SieveScript/set", { "accountId": "ken", "update": { "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { "name": "myscript" } }, "onSuccessActivateScript": null }, "3"] ] } { "methodResponses": [ [ "SieveScript/set", { "oldState": "1603742603.309607868-4096", "newState": "1603742967.852315428-4096", "created": null, "updated": { "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { "isActive": false } }, "destroyed": null, "notCreated": null, "notUpdated": null, "notDestroyed": null, "accountId": "ken" }, "3" ] ] } Murchison Expires August 7, 2021 [Page 12] Internet-Draft JMAP Sieve February 2021 Request (and response) to activate a script: { "using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:sieve" ], "methodCalls": [ ["SieveScript/set", { "accountId": "ken", "onSuccessActivateScript": "dd1b164f-8cdc-448c-9f54-60210b5f14ae" }, "4"] ] } { "methodResponses": [ [ "SieveScript/set", { "oldState": "1603742967.852315428-4096", "newState": "1603744460.316617118-4096", "created": null, "updated": { "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { "isActive": true } }, "destroyed": null, "notCreated": null, "notUpdated": null, "notDestroyed": null, "accountId": "ken" }, "4" ] ] } Requests (and responses) to deactivate and destroy the active script: { "using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:sieve" ], "methodCalls": [ ["SieveScript/set", { "accountId": "ken", "onSuccessActivateScript": null }, "5"], ["SieveScript/set", { Murchison Expires August 7, 2021 [Page 13] Internet-Draft JMAP Sieve February 2021 "accountId": "ken", "destroy": [ "dd1b164f-8cdc-448c-9f54-60210b5f14ae" ] }, "6"] ] } { "methodResponses": [ [ "SieveScript/set", { "oldState": "1603744460.316617118-4096", "newState": "1603744637.575375572-4096", "created": null, "updated": null, "updated": { "dd1b164f-8cdc-448c-9f54-60210b5f14ae": { "isActive": false } }, "destroyed": null, "notCreated": null, "notUpdated": null, "notDestroyed": null, "accountId": "ken" }, "5" ], [ "SieveScript/set", { "oldState": "1603744637.575375572-4096", "newState": "1603744637.854390875-4096", "created": null, "updated": null, "destroyed": [ "dd1b164f-8cdc-448c-9f54-60210b5f14ae" ], "notCreated": null, "notUpdated": null, "notDestroyed": null, "accountId": "ken" }, "6" ] ] } Murchison Expires August 7, 2021 [Page 14] Internet-Draft JMAP Sieve February 2021 2.3. SieveScript/query This is a standard "/query" method as described in [RFC8620], Section 5.5. A _FilterCondition_ object has the following properties, either of which may be omitted: o *name*: "String" The SieveScript "name" property contains the given string. o *isActive*: "Boolean" The "isActive" property of the SieveScript must be identical to the value given to match the condition. The following SieveScript properties MUST be supported for sorting: o *name* o *isActive* 2.4. SieveScript/validate This method is used by the client to verify Sieve script validity without storing the script on the server, providing similar functionality to the CHECKSCRIPT command in [RFC5804]. The method takes the following arguments: o *accountId*: "Id" The id of the account to use. o *blobId*: "Id" The id of the blob containing the raw octets of the script to validate, subject to the same requirements in Section 2. Murchison Expires August 7, 2021 [Page 15] Internet-Draft JMAP Sieve February 2021 The response has the following arguments: o *accountId*: "Id" The id of the account used for this call. o *error*: "SetError|null" A "invalidScript" SetError object if the script content is invalid (see Section 2.2), or "null" if the script content is valid. As with the SieveScript/set (Section 2.2) method, script content must first be uploaded as a blob using either the standard upload mechanism (see [RFC8620] Section 6.1) or the JMAP Blob management extension (see [I-D.gondwana-jmap-blob] Section 3.1). 2.5. SieveScript/test This method is used by the client to ask the Sieve interpreter to evaluate a Sieve script against a set of emails and report the actions that would be performed for each. When calling this method the "using" property of the Request object MUST contain the capabilities "urn:ietf:params:jmap:sieve" and "urn:ietf:params:jmap:mail". The latter is required due to the use of blob ids which may reference Email objects and the use of the Envelope object, as described below. The *SieveScript/test* method takes the following arguments: o *accountId*: "Id" The id of the account to use. o *scriptBlobId*: "String" The id of the blob containing the raw octets of the script to validate, subject to the same requirements in Section 2. o *emailBlobIds*: "Id[]" Murchison Expires August 7, 2021 [Page 16] Internet-Draft JMAP Sieve February 2021 The ids representing the raw octets of the [RFC5322] messages to test against. o *envelope*: "Envelope|null" Information that the Sieve interpreter should assume was present in the SMTP transaction that delivered the message when evaluating "envelope" tests. If "null", all "envelope" tests MUST evaluate to false. See Section 7 of [RFC8621] for the contents of the Envelope object. o *lastVacationResponse*: "UTCDate|null" The UTC date-time at which the Sieve interpreter should assume that it last auto-replied to the sender of the message, or "null" if the Sieve interpreter should assume that it has not auto- replied to the sender. The response has the following arguments: o *accountId*: "Id" The id of the account used for this call. o *completed*: "Id[Action[]]|null" A map of the blob id to a set of _Action_ types for each message successfully processed by the script, or "null" if none. The _Action_ data type is a tuple, represented as a JSON array containing three elements: 1. A "String" *name* of the Sieve action (e.g., "keep"). 2. A "String[*]" object containing any named (tagged) arguments for the action. The name MUST be the tag for the argument as given in the specification of the action (e.g., ":flags"). Murchison Expires August 7, 2021 [Page 17] Internet-Draft JMAP Sieve February 2021 This may be an empty object if the action does not have any tagged arguments, or none were specified in the Sieve script (e.g., discard [RFC5228] or ereject [RFC5429] action). 3. An "*[]" array containing any positional arguments for the action in the order as given in the specification of the action. This may be an empty array if the action does not have any positional arguments (e.g., discard [RFC5228] or keep [RFC5228] action). o *notCompleted*: "Id[SetError]|null" A map of the blob id to a SetError object for each message that was not successfully processed by the script, or "null#x27;s session state associated with its API call to the TEEP implementation. The TEEP/HTTP Client sends an HTTP POST request to the TAM URI with Accept and Content-Type headers with the TEEP media type in use, and a body containing the TEEP message buffer provided by the TEEP implementation. The HTTP request is then associated with the TEEP/ HTTP Client's session state. 5.3. Receiving an HTTP response When an HTTP response is received in response to a request associated with a given session state, the TEEP/HTTP Client MUST do the following. If the HTTP response body is empty, the TEEP/HTTP Client's task is complete, and it can delete its session state, and its task is done. If instead the HTTP response body is not empty, the TEEP/HTTP Client passes (e.g., using "ProcessOTrPMessage" API as mentioned in Section 6.2 of [I-D.ietf-teep-opentrustprotocol] if OTrP rather than TEEP is used for provisioning) the response body up to the TEEP implementation associated with the session. The TEEP implementation will then either pass no data back, or pass back a message buffer. If no data is passed back, the TEEP/HTTP Client's task is complete, and it can delete its session state, and inform its caller (e.g., the application installer) of success. Thaler Expires May 7, 2020 [Page 8] Internet-Draft TEEP HTTP Transport November 2019 If instead the TEEP implementation passes back a message buffer, the TEEP/HTTP Client handles the message buffer as specified in Section 5.2. 5.4. Handling checks for policy changes An implementation MUST provide a way to periodically check for TEEP policy changes. This can be done in any implementation-specific manner, such as: A) The TEEP/HTTP Client might call up to the TEEP implementation at an interval previously specified by the TEEP implementation. This approach requires that the TEEP/HTTP Client be capable of running a periodic timer. B) The TEEP/HTTP Client might be informed when an existing TA is invoked, and call up to the TEEP implementation if more time has passed than was previously specified by the TEEP implementation. This approach allows the device to go to sleep for a potentially long period of time. C) The TEEP/HTTP Client might be informed when any attestation attempt determines that the device is out of compliance, and call up to the TEEP implementation to remediate. The TEEP/HTTP Client informs the TEEP implementation by invoking an appropriate "RequestPolicyCheck" API. The TEEP implementation will either (a) pass no data back, (b) pass back a TAM URI to connect to, or (c) pass back a message buffer and TAM URI to send it to. Processing then continues as specified in Section 5.1.1. 5.5. Error handling If any local error occurs where the TEEP/HTTP Client cannot get a message buffer (empty or not) back from the TEEP implementation, the TEEP/HTTP Client deletes its session state, and informs its caller (e.g., the application installer) of a failure. If any HTTP request results in an HTTP error response or a lower layer error (e.g., network unreachable), the TEEP/HTTP Client calls the TEEP implementation's "ProcessError" API, and then deletes its session state and informs its caller of a failure. 6. TEEP/HTTP Server Behavior Thaler Expires May 7, 2020 [Page 9] Internet-Draft TEEP HTTP Transport November 2019 6.1. Receiving an HTTP POST request When an HTTP POST request is received with an empty body, the TEEP/ HTTP Server invokes the TAM's "ProcessConnect" API. The TAM will then pass back a (possibly empty) message buffer. When an HTTP POST request is received with a non-empty body, the TEEP/HTTP Server passes the request body to the TAM (e.g., using the "ProcessOTrPMessage" API mentioned in [I-D.ietf-teep-opentrustprotocol] if OTrP rather than TEEP is used for provisioning). The TAM will then pass back a (possibly empty) message buffer. 6.2. Getting an empty buffer back from the TEEP implementation If the TEEP implementation passes back an empty buffer, the TEEP/HTTP Server sends a successful (2xx) response with no body. 6.3. Getting a message buffer from the TEEP implementation If the TEEP implementation passes back a non-empty buffer, the TEEP/ HTTP Server generates a successful (2xx) response with a Content-Type header with the appropriate media type in use, and with the message buffer as the body. 6.4. Error handling If any error occurs where the TEEP/HTTP Server cannot get a message buffer (empty or not) back from the TEEP implementation, the TEEP/ HTTP Server generates an appropriate HTTP error response. 7. Sample message flow The following shows a sample TEEP message flow that uses application/ teep+json as the Content-Type. 1. An application installer determines (e.g., from an app manifest) that the application has a dependency on TA "X", and passes this notification to the TEEP Broker. The TEEP Broker picks a TEE (e.g., the only one available) based on this notification, and passes the information to the TEEP/HTTP Cient for that TEE. 2. The TEEP/HTTP Client calls the TEEP implementation's "RequestTA" API, passing TA Needed = X. 3. The TEEP implementation finds that no such TA is already installed, but that it can be obtained from a given TAM. The TEEP Agent passes the TAM URI (e.g., "https://example.com/tam") " if none. A "serverFail" SetError (see Section 3.6.2 of [RFC8620]) MUST be used to indicate a Sieve interpreter run-time error. The following additional errors may be returned instead of the "SieveScript/test" response: o "invalidScript": The script content is invalid (see Section 2.2). o "notFound": The script referenced by the id could not be found. o "rateLimit": The number of recent test method calls has reached a server-defined limit. o "requestTooLarge": The total number of emailBlobIds exceeds the maximum number the server is willing to process in a single test method call. o "serverFail": The script failed preparation to be executed for some other reason. The JSON data type to use for each argument value is a direct mapping from its Sieve data type, per the following table: Murchison Expires August 7, 2021 [Page 18] Internet-Draft JMAP Sieve February 2021 +-------------------+----------------+ | Sieve Type | JSON Type | +-------------------+----------------+ | Number | Number | | String | String | | String List | String[] | | tag with no value | Boolean (true) | +-------------------+----------------+ Recommendations for constructing the list of arguments are as follows: o Optional arguments in which the value is supplied by the Sieve interpreter SHOULD be included (e.g., ":from" and ":subject" arguments to the "vacation" [RFC5230] action). o Optional arguments in which the value is implicitly supplied by a Sieve variable SHOULD be included (e.g., "keep" or "fileinto" actions without an explicit ":flags" argument, but "imap4flags" [RFC5232] have been set on the internal variable). o Optional arguments in which the value is the specfied default MAY be omitted. o Tagged arguments that are only used to determine whether the action will be executed and have no impact on the result of the action MAY be omitted (e.g., ":days" and ":addresses" arguments to the vacation action). 2.5.1. Example Assume that the following script has been created and has blob id "S123". require [ "imapflags", "editheader", "vacation", "fcc" ]; setflag "$SieveFiltered"; addheader :last "X-Sieve-Filtered" "yes"; vacation :days 3 :fcc "INBOX.Sent" :flags "\\Answered" text: Gone fishing. . ; Murchison Expires August 7, 2021 [Page 19] Internet-Draft JMAP Sieve February 2021 Assume that the following email has been uploaded and assigned blob id "B456". From: "Some Example Sender" <example@example.net> To: ken@example.com Subject: test email Date: Wed, 23 Sep 2020 12:11:11 -0500 Content-Type: text/plain; charset="UTF-8" MIME-Version: 1.0 This is a test email. The following request executes the script against the email and provides envelope information for use by the "vacation" action. { "using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:sieve", "urn:ietf:params:jmap:mail" ], "methodCalls": [ [ "SieveScript/test", { "accountId": "ken", "scriptBlobId": "S123", "emailBlobIds": [ "B456" ], "envelope": { "mailFrom": { "email": "example@example.net", "parameters": null }, "rcptTo": [ { "email": "ken@example.com", "parameters": null } ] }, "lastVacationResponse": null }, "R1" ] ] } Murchison Expires August 7, 2021 [Page 20] Internet-Draft JMAP Sieve February 2021 The following response lists the actions that would be performed by the script. { "methodResponses": [ [ "SieveScript/test", { "completed": { "B456": [ [ "addheader", { ":last": true }, [ "X-Sieve-Filtered", "yes" ] ], [ "vacation", { ":fcc": "INBOX.Sent", ":flags": [ "\\answered" ], ":subject": "Auto: test email", ":from": "ken@example.com" }, [ "Gone fishing." ] ], [ "keep", { ":flags": [ "$SieveFiltered" ] }, [ ] ] ] }, "notCompleted": null, "accountId": "ken", }, "R1" ] ] } Murchison Expires August 7, 2021 [Page 21] Internet-Draft JMAP Sieve February 2021 3. Compatibility with JMAP Vacation Response Section 8 of [RFC8621] defines a VacationResponse object to represent an autoresponder to incoming email messages. Servers that implement the VacationResponse as a Sieve script that resides amongst other user scripts are subject to the following requirements: o MUST allow the VacationResponse Sieve script to be fetched by the SieveScript/get (Section 2.1) method. o MUST allow the VacationResponse Sieve script to be [de]activated via the "onSuccessActivateScript" argument to the SieveScript/set (Section 2.2) method. o MUST NOT allow the VacationResponse Sieve script to be destroyed or have its content updated by the SieveScript/set (Section 2.2) method. Any such request MUST be rejected with a "forbidden" SetError. A "description" property MAY be present with an explanation that the script can only be modified by a VacationResponse/set method. 4. Security Considerations All security considerations of JMAP [RFC8620] and Sieve [RFC5228] apply to this specification. 5. IANA Considerations 5.1. JMAP Capability Registration for "sieve" IANA will register the "sieve" JMAP Capability as follows: Capability Name: "urn:ietf:params:jmap:sieve" Specification document: this document Intended use: common Change Controller: IETF Security and privacy considerations: this document, Section 4 5.2. JMAP Error Codes Registry The following sub-sections register two new error codes in the JMAP Error Codes registry, as defined in [RFC8620]. Murchison Expires August 7, 2021 [Page 22] Internet-Draft JMAP Sieve February 2021 5.2.1. invalidScript JMAP Error Code: invalidScript Intended use: common Change controller: IETF Reference: This document, Section 2.2 Description: The SieveScript violates the Sieve grammar [RFC5228] and/or one or more extensions mentioned in the script's "require" statement(s) are not supported by the Sieve interpreter. 5.2.2. scriptIsActive JMAP Error Code: scriptIsActive Intended use: common Change controller: IETF Reference: This document, Section 2.2 Description: The client tried to destroy the active SieveScript. 6. Acknowledgments The concepts in this document are based largely on those in [RFC5804]. The author would like to thank the authors of that document for providing both inspiration and some borrowed text for this document. The author would also like to thank the following individuals for contributing their ideas and support for writing this specification: Bron Gondwana, Neil Jenkins, Alexey Melnikov, and Ricardo Signes. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>. Murchison Expires August 7, 2021 [Page 23] Internet-Draft JMAP Sieve February 2021 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003, <https://www.rfc-editor.org/info/rfc3629>. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/info/rfc3986>. [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, <https://www.rfc-editor.org/info/rfc5198>. [RFC5228] Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email Filtering Language", RFC 5228, DOI 10.17487/RFC5228, January 2008, <https://www.rfc-editor.org/info/rfc5228>. [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008, <https://www.rfc-editor.org/info/rfc5322>. [RFC5435] Melnikov, A., Ed., Leiba, B., Ed., Segmuller, W., and T. Martin, "Sieve Email Filtering: Extension for Notifications", RFC 5435, DOI 10.17487/RFC5435, January 2009, <https://www.rfc-editor.org/info/rfc5435>. [RFC6134] Melnikov, A. and B. Leiba, "Sieve Extension: Externally Stored Lists", RFC 6134, DOI 10.17487/RFC6134, July 2011, <https://www.rfc-editor.org/info/rfc6134>. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>. [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, <https://www.rfc-editor.org/info/rfc8620>. [RFC8621] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621, August 2019, <https://www.rfc-editor.org/info/rfc8621>. 7.2. Informative References [I-D.gondwana-jmap-blob] Gondwana, B., "JMAP Blob management extension", draft- gondwana-jmap-blob-01 (work in progress), November 2020. Murchison Expires August 7, 2021 [Page 24] Internet-Draft JMAP Sieve February 2021 [RFC5230] Showalter, T. and N. Freed, Ed., "Sieve Email Filtering: Vacation Extension", RFC 5230, DOI 10.17487/RFC5230, January 2008, <https://www.rfc-editor.org/info/rfc5230>. [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags Extension", RFC 5232, DOI 10.17487/RFC5232, January 2008, <https://www.rfc-editor.org/info/rfc5232>. [RFC5429] Stone, A., Ed., "Sieve Email Filtering: Reject and Extended Reject Extensions", RFC 5429, DOI 10.17487/RFC5429, March 2009, <https://www.rfc-editor.org/info/rfc5429>. [RFC5463] Freed, N., "Sieve Email Filtering: Ihave Extension", RFC 5463, DOI 10.17487/RFC5463, March 2009, <https://www.rfc-editor.org/info/rfc5463>. [RFC5804] Melnikov, A., Ed. and T. Martin, "A Protocol for Remotely Managing Sieve Scripts", RFC 5804, DOI 10.17487/RFC5804, July 2010, <https://www.rfc-editor.org/info/rfc5804>. Appendix A. Change History (To be removed by RFC Editor before publication) Changes since ietf-03: o SieveScript/test: Moved positional arguments into their own array (because the specfications don't use a consistent method for defining the action syntax or naming of positional arguments). Changes since ietf-02: o Removed open issues. o Reverted back to using only blob ids for script content. o Added "rateLimit" and "requestTooLarge" to the list of possible error codes for /set method. o Added Compatibility with JMAP Vacation Response section. o Added RFC5228 to Security Considerations. o Miscellaneous editorial changes. Changes since ietf-01: o Removed normative references to ManageSieve (RFC 5804). Murchison Expires August 7, 2021 [Page 25] Internet-Draft JMAP Sieve February 2021 o Added the 'maxSizeScriptNameThaler Expires May 7, 2020 [Page 10] Internet-Draft TEEP HTTP Transport November 2019 to the TEEP/HTTP Client. (If the TEEP implementation already had a cached TAM certificate that it trusts, it could skip to step 9 instead and generate a QueryResponse.) 4. The TEEP/HTTP Client sends an HTTP POST request to the TAM URI: POST /tam HTTP/1.1 Host: example.com Accept: application/teep+json Content-Length: 0 User-Agent: Foo/1.0 5. On the TAM side, the TEEP/HTTP Server receives the HTTP POST request, and calls the TEEP implementation's "ProcessConnect" API. 6. The TEEP implementation generates a TEEP message (where typically QueryRequest is the first message) and passes it to the TEEP/HTTP Server. 7. The TEEP/HTTP Server sends an HTTP successful response with the TEEP message in the body: HTTP/1.1 200 OK Content-Type: application/teep+json Content-Length: [length of TEEP message here] Server: Bar/2.2 Cache-Control: no-store X-Content-Type-Options: nosniff Content-Security-Policy: default-src 'none' Referrer-Policy: no-referrer [TEEP message here] 8. Back on the TEEP Agent side, the TEEP/HTTP Client gets the HTTP response, extracts the TEEP message and pass it up to the TEEP implementation. 9. The TEEP implementation processes the TEEP message, and generates a TEEP response (e.g., QueryResponse) which it passes back to the TEEP/HTTP Client. Thaler Expires May 7, 2020 [Page 11] Internet-Draft TEEP HTTP Transport November 2019 10. The TEEP/HTTP Client gets the TEEP message buffer and sends an HTTP POST request to the TAM URI, with the TEEP message in the body: POST /tam HTTP/1.1 Host: example.com Accept: application/teep+json Content-Type: application/teep+json Content-Length: [length of TEEP message here] User-Agent: Foo/1.0 [TEEP message here] 11. The TEEP/HTTP Server receives the HTTP POST request, and passes the payload up to the TAM implementation. 12. Steps 6-11 are then repeated until the TEEP implementation passes no data back to the TEEP/HTTP Server in step 6. 13. The TEEP/HTTP Server sends an HTTP successful response with no body: HTTP/1.1 204 No Content Server: Bar/2.2 14. The TEEP/HTTP Client deletes its session state. 8. Security Considerations Although TEEP is protected end-to-end inside of HTTP, there is still value in using HTTPS for transport, since HTTPS can provide additional protections as discussed in Section 6 of [I-D.ietf-httpbis-bcp56bis]. As such, TEEP/HTTP implementations MUST support HTTPS. The choice of HTTP vs HTTPS at runtime is up to policy, where an administrator configures the TAM URI to be used, but it is expected that real deployments will always use HTTPS TAM URIs. 9. IANA Considerations This document has no actions for IANA. Thaler Expires May 7, 2020 [Page 12] Internet-Draft TEEP HTTP Transport November 2019 10. References 10.1. Normative References [I-D.ietf-httpbis-semantics] Fielding, R., Nottingham, M., and J. Reschke, "HTTP Semantics", draft-ietf-httpbis-semantics-05 (work in progress), July 2019. [I-D.ietf-teep-opentrustprotocol] Pei, M., Atyeo, A., Cook, N., Yoo, M., and H. Tschofenig, "The Open Trust Protocol (OTrP)", draft-ietf-teep- opentrustprotocol-03 (work in progress), May 2019. [I-D.tschofenig-teep-protocol] Pei, M., Tschofenig, H., and D. Wheeler, "Trusted Execution Environment Provisioning (TEEP) Protocol", draft-tschofenig-teep-protocol-00 (work in progress), November 2019. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc- editor.org/info/rfc2119>. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/RFC2818, May 2000, <https://www.rfc- editor.org/info/rfc2818>. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>. 10.2. Informative References [GP-OTrP] Global Platform, "TEE Management Framework: Open Trust Protocol (OTrP) Profile Version 1.0", Global Platform GPD_SPE_123, May 2019, <https://globalplatform.org/specs-library/tee-management- framework-open-trust-protocol/>. [I-D.ietf-httpbis-bcp56bis] Nottingham, M., "Building Protocols with HTTP", draft- ietf-httpbis-bcp56bis-09 (work in progress), November 2019. Thaler Expires May 7, 2020 [Page 13] Internet-Draft TEEP HTTP Transport November 2019 [I-D.ietf-teep-architecture] Pei, M., Tschofenig, H., Wheeler, D., Atyeo, A., and D. Liu, "Trusted Execution Environment Provisioning (TEEP) Architecture", draft-ietf-teep-architecture-03 (work in progress), July 2019. Author's Address Dave Thaler Microsoft EMail: dthaler@microsoft.com Thaler Expires May 7, 2020 [Page 14]