--- 1/draft-ietf-teep-otrp-over-http-12.txt 2022-02-28 15:13:09.816375751 -0800 +++ 2/draft-ietf-teep-otrp-over-http-13.txt 2022-02-28 15:13:09.852376671 -0800 @@ -1,19 +1,19 @@ TEEP WG D. Thaler Internet-Draft Microsoft -Intended status: Standards Track 26 July 2021 -Expires: 27 January 2022 +Intended status: Standards Track 28 February 2022 +Expires: 1 September 2022 HTTP Transport for Trusted Execution Environment Provisioning: Agent Initiated Communication - draft-ietf-teep-otrp-over-http-12 + draft-ietf-teep-otrp-over-http-13 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 code and data in TEEs on 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 @@ -27,25 +27,25 @@ 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 27 January 2022. + This Internet-Draft will expire on 1 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. @@ -56,34 +56,35 @@ 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. TEEP Broker . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Use of Abstract APIs . . . . . . . . . . . . . . . . . . 4 4. Use of HTTP as a Transport . . . . . . . . . . . . . . . . . 5 5. TEEP/HTTP Client Behavior . . . . . . . . . . . . . . . . . . 6 5.1. Receiving a request to install a new Trusted Application . . . . . . . . . . . . . . . . . . . . . . . 6 5.1.1. Session Creation . . . . . . . . . . . . . . . . . . 7 5.2. Receiving a notification that a Trusted Application is no longer needed . . . . . . . . . . . . . . . . . . . . . . 7 - 5.3. Getting a message buffer back from a TEEP Agent . . . . . 8 + 5.3. Getting a TAM URI and message buffer back from a TEEP + Agent . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.4. Receiving an HTTP response . . . . . . . . . . . . . . . 8 5.5. Handling checks for policy changes . . . . . . . . . . . 9 5.6. Error handling . . . . . . . . . . . . . . . . . . . . . 9 - 6. TEEP/HTTP Server Behavior . . . . . . . . . . . . . . . . . . 9 + 6. TEEP/HTTP Server Behavior . . . . . . . . . . . . . . . . . . 10 6.1. Receiving an HTTP POST request . . . . . . . . . . . . . 10 6.2. Getting an empty buffer back from the TAM . . . . . . . . 10 6.3. Getting a message buffer from the TAM . . . . . . . . . . 10 6.4. Error handling . . . . . . . . . . . . . . . . . . . . . 10 7. Sample message flow . . . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 10.1. Normative References . . . . . . . . . . . . . . . . . . 12 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 13 10.2. Informative References . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 1. Introduction A Trusted Execution Environment (TEE) is an environment that enforces that any code within that environment cannot be tampered with, and that any data used by such code cannot be read or tampered with by any code outside that environment. The Trusted Execution Environment Provisioning (TEEP) protocol is designed to provision authorized code @@ -204,23 +205,23 @@ 4. Use of HTTP as a Transport This document uses HTTP [I-D.ietf-httpbis-semantics] as a transport. For the motivation behind the HTTP recommendations in this document, see the discussion of HTTP as a transport in [I-D.ietf-httpbis-bcp56bis]. Redirects MUST NOT be automatically followed. Cookies are not used. 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] (using the - relevant TEEP content type defined in [I-D.ietf-teep-protocol]): + HTTP responses with content SHOULD have the following header fields + as explained in Section 4.13 of [I-D.ietf-httpbis-bcp56bis] (using + the TEEP media type defined in [I-D.ietf-teep-protocol]): Content-Type: application/teep+cbor 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. @@ -231,23 +232,24 @@ protections as discussed in Sections 4.4.2 and 6 of [I-D.ietf-httpbis-bcp56bis]. However, there may be constrained nodes where code space is an issue. [RFC7925] provides TLS profiles that can be used in many constrained nodes, but in rare cases the most constrained nodes might need to use HTTP without a TLS stack, relying on the end-to-end security provided by the TEEP protocol. When HTTPS is used, clients MUST use the procedures detailed in - Section 6 of [RFC6125] to verify the authenticity of the server. See - [BCP195] for additional TLS recommendations and [RFC7925] for TLS - recommendations related to IoT devices. + Section 4.3.4 of [I-D.ietf-httpbis-semantics] to verify the + authenticity of the server. See [BCP195] for additional TLS + recommendations and [RFC7925] for TLS recommendations related to IoT + devices. 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 application 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: @@ -282,23 +284,24 @@ the TEEP Agent'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 Agent 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 with the TEEP media - type requested, and an empty body. The HTTP request is then - associated with the TEEP/HTTP Client's session state. + HTTP(S) POST to the TAM URI with an Accept header field with the TEEP + media type specified in [I-D.ietf-teep-protocol], and an empty body. + The HTTP request is then associated with the TEEP/HTTP Client's + session state. If the TEEP Agent 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.3. Session state consists of: * Any context (e.g., a handle) that identifies the API session with the TEEP Agent. @@ -310,83 +313,90 @@ In some environments, an application installer can determine (e.g., from an application manifest) that a given Trusted Application is no longer needed, such as if the application that previously depended on the TA is uninstalled or updated in a way that removes the dependency. 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 Agent. This might + include a TAM URI provided in the original 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 appropriate - based on the constraints expressed, as in Section 5.1. + in an implementation-dependent way which TEE (if any) is believed to + contain the TA that is no longer needed, similar to the process in + Section 5.1. 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 Agent in that TEE by invoking an appropriate "UnrequestTA" API that identifies the unneeded TA. The TEEP/HTTP Client need not know whether the TEE actually has the TA installed. The TEEP Agent 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 Agent's configuration. If they differ, the TEEP/HTTP Client MUST use the TAM URI passed back. Processing then continues as in Section 5.1.1. -5.3. Getting a message buffer back from a TEEP Agent +5.3. Getting a TAM URI and message buffer back from a TEEP Agent - When a TEEP Agent 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's session state associated with its API call to the - TEEP Agent. + When a TEEP Agent passes a TAM URI and optionally a message buffer to + a TEEP/HTTP Client, the TEEP/HTTP Client MUST do the following, using + the TEEP/HTTP Client's session state associated with its API call to + the TEEP Agent. 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 Agent. - The HTTP request is then associated with the TEEP/HTTP Client's - session state. + Accept and Content-Type header fields with the TEEP media type, and a + body containing the TEEP message buffer (if any) provided by the TEEP + Agent. The HTTP request is then associated with the TEEP/HTTP + Client's session state. 5.4. 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 "ProcessTeepMessage" API as mentioned in + passes (e.g., using the "ProcessTeepMessage" API as mentioned in Section 6.2.1 of [I-D.ietf-teep-architecture]) the response body up to the TEEP Agent associated with the session. The TEEP Agent 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. If instead the TEEP Agent passes back a message buffer, the TEEP/HTTP Client handles the message buffer as specified in Section 5.3. 5.5. Handling checks for policy changes An implementation MUST provide a way to periodically check for TAM policy changes, such as a Trusted Application needing to be deleted from a TEE because it is no longer permitted, or needing to be updated to a later version. This can be done in any implementation- - specific manner, such as: + specific manner, such as any of the following or a combination + thereof: A) The TEEP/HTTP Client might call up to the TEEP Agent at an interval previously specified by the TEEP Agent. 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 Agent if more time has passed than was previously specified by the TEEP Agent. This approach allows the device to go to sleep for a potentially long period of time. @@ -404,61 +414,64 @@ The TEEP Agent might need to talk to multiple TAMs, however, as shown in Figure 1 of [I-D.ietf-teep-architecture]. To accomplish this, the TEEP/HTTP Client keeps invoking the "RequestPolicyCheck" API until the TEEP Agent passes no data back, so that the TEEP Agent can return each TAM URI in response to a separate API call. 5.6. Error handling If any local error occurs where the TEEP/HTTP Client cannot get a message buffer (empty or not) back from the TEEP Agent, the TEEP/HTTP - Client deletes its session state, and informs its caller (e.g., the - application installer) of a failure. + Client deletes its session state, and informs its caller (if any, + 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 Agent's "ProcessError" API, and then deletes its session state and informs its caller of a failure. 6. TEEP/HTTP Server Behavior + 6.1. Receiving an HTTP POST request - If the TAM does not receive the appropriate Content-Type header - fields, the TAM SHOULD fail the request, returning a 415 Unsupported + If the TAM does not receive the appropriate Content-Type header field + value, the TAM SHOULD fail the request, returning a 415 Unsupported Media Type response. Similarly, if an appropriate Accept header field is not present, the TAM SHOULD fail the request with an appropriate error response. (This is for consistency with common implementation practice to allow the HTTP server to choose a default error response, since in some implementations the choice is done at the HTTP layer rather than the layer at which TEEP-over-HTTP would be implemented.) Otherwise, processing continues as follows. - 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 an empty body, this + indicates a request for a new TEEP session, and the TEEP/HTTP Server + invokes the TAM's "ProcessConnect" API. The TAM will then pass back + a 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 + When an HTTP POST request is received with a non-empty body, this + indicates a message on an existing TEEP session, and the TEEP/HTTP + Server passes the request body to the TAM (e.g., using the "ProcessTeepMessage" API mentioned in [I-D.ietf-teep-architecture]). The TAM will then pass back a (possibly empty) message buffer. 6.2. Getting an empty buffer back from the TAM If the TAM passes back an empty buffer, the TEEP/HTTP Server sends a successful (2xx) response with no body. It SHOULD be status 204 (No Content). 6.3. Getting a message buffer from the TAM If the TAM 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 + generates a successful (2xx) response with a Content-Type header + field with the TEEP media type, 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 TAM, the TEEP/HTTP Server generates an appropriate HTTP 5xx error response. 7. Sample message flow @@ -470,33 +483,33 @@ 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 Agent's "RequestTA" API, passing TA Needed = X. 3. The TEEP Agent 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") to the TEEP/HTTP - Client. + back the TAM URI (e.g., "https://example.com/tam") to the TEEP/ + HTTP Client. 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+cbor Content-Length: 0 User-Agent: Foo/1.0 where the TEEP/HTTP Client fills in an implementation-specific - value in the User-Agent header. + value in the User-Agent header field. 5. On the TAM side, the TEEP/HTTP Server receives the HTTP POST request, and calls the TAM's "ProcessConnect" API. 6. The TAM 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: @@ -504,21 +517,21 @@ Content-Type: application/teep+cbor Content-Length: [length of TEEP message here] Server: Bar/2.2 X-Content-Type-Options: nosniff Content-Security-Policy: default-src 'none' Referrer-Policy: no-referrer [TEEP message here] where the TEEP/HTTP Server fills in an implementation-specific - value in the Server header. + value in the Server header field. 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 Agent. 9. The TEEP Agent processes the TEEP message, and generates a TEEP response (e.g., QueryResponse) which it passes back to the TEEP/ HTTP Client. 10. The TEEP/HTTP Client gets the TEEP message buffer and sends an @@ -545,28 +558,29 @@ HTTP/1.1 204 No Content Server: Bar/2.2 14. The TEEP/HTTP Client deletes its session state. 8. Security Considerations Section 4 discussed security recommendations for HTTPS transport of TEEP messages. See Section 6 of [I-D.ietf-httpbis-bcp56bis] for - additional discussion of HTTP(S) security considerations. + additional discussion of HTTP(S) security considerations. See + section 9 of [I-D.ietf-teep-architecture] for security considerations + specific to the use of TEEP. 9. IANA Considerations This document has no actions for IANA. 10. References - 10.1. Normative References [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, . [I-D.ietf-httpbis-semantics] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP @@ -564,67 +578,60 @@ [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, . [I-D.ietf-httpbis-semantics] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP Semantics", Work in Progress, Internet-Draft, draft-ietf- - httpbis-semantics-17, 25 July 2021, + httpbis-semantics-19, 12 September 2021, . + semantics-19.txt>. [I-D.ietf-teep-protocol] Tschofenig, H., Pei, M., Wheeler, D., Thaler, D., and A. Tsukamoto, "Trusted Execution Environment Provisioning (TEEP) Protocol", Work in Progress, Internet-Draft, draft- - ietf-teep-protocol-06, 12 July 2021, + ietf-teep-protocol-07, 25 October 2021, . + 07.txt>. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . - [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and - Verification of Domain-Based Application Service Identity - within Internet Public Key Infrastructure Using X.509 - (PKIX) Certificates in the Context of Transport Layer - Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March - 2011, . - [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things", RFC 7925, DOI 10.17487/RFC7925, July 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 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, . [I-D.ietf-httpbis-bcp56bis] Nottingham, M., "Building Protocols with HTTP", Work in - Progress, Internet-Draft, draft-ietf-httpbis-bcp56bis-12, - 27 April 2021, . + Progress, Internet-Draft, draft-ietf-httpbis-bcp56bis-15, + 27 August 2021, . [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, . [I-D.ietf-teep-opentrustprotocol]