TEEP WG D. Thaler Internet-Draft Microsoft Intended status: InformationalJuly 08,October 22, 2019 Expires:January 9,April 24, 2020 HTTP Transport forthe Open Trust Protocol (OTrP) draft-ietf-teep-otrp-over-http-01Trusted Execution Environment Provisioning: Agent-to- TAM Communication draft-ietf-teep-otrp-over-http-02 AbstractThis document specifies the HTTP transport for theThe Open Trust Protocol(OTrP), which(OTrP) is used to manage code and configuration data in a Trusted Execution Environment (TEE). This document specifies the HTTP transport for OTrP 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 an OTrP 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 onJanuary 9,April 24, 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 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . .34 3. TEEP Broker Models . . . . . . . . . . . . . . . . . . . . . 4 3.1. Use of Abstract APIs . . . . . . . . . . . . . . . . . .. . 35 4. Use of HTTP as a Transport . . . . . . . . . . . . . . . . .36 5.TEEP BrokerOTrP/HTTP Client Behavior . . . . . . . . . . . . . . . . . .. . 47 5.1. Receiving a request to install a new Trusted Application47 5.1.1. Session Creation . . . . . . . . . . . . . . . . . .57 5.2. Getting a message buffer back from anTEEP Agent . . . . 5OTrP implementation 8 5.3. Receiving an HTTP response . . . . . . . . . . . . . . .68 5.4. Handling checks for policy changes . . . . . . . . . . .69 5.5. Error handling . . . . . . . . . . . . . . . . . . . . .79 6.TAM BrokerOTrP/HTTP Server Behavior . . . . . . . . . . . . . . . . . .. . . 710 6.1. Receiving an HTTP POST request . . . . . . . . . . . . .710 6.2. Getting an empty buffer back from theTAM . . . . . . . . 7OTrP implementation 10 6.3. Getting a message buffer from theTAM . . . . . . . .OTrP implementation . .710 6.4. Error handling . . . . . . . . . . . . . . . . . . . . .710 7. Sample message flow . . . . . . . . . . . . . . . . . . . . .710 8. Security Considerations . . . . . . . . . . . . . . . . . . .912 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . .1012 10. References . . . . . . . . . . . . . . . . . . . . . . . . .1013 10.1. Normative References . . . . . . . . . . . . . . . . . .1013 10.2. Informative References . . . . . . . . . . . . . . . . .1013 Author's Address . . . . . . . . . . . . . . . . . . . . . . . .1114 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 Open Trust Protocol (OTrP) is designed to provision authorized code and configuration into TEEs. To be secure against malware, an OTrP implementation (referred to asan OTrPa 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 OTrP, along withtypical networking stacks, needthe 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 allowing code (e.g., TCP/IP) that only sees encrypted messages to be kept out of the TEE. The OTrP specification[I-D.ietf-teep-opentrustprotocol]([I-D.ietf-teep-opentrustprotocol] or [I-D.tschofenig-teep-otrp-v2]) describes the behavior of TEEP Agents and TAMs, but does not specify the details of thetransport, an implementation of which is referred to as a "Broker".transport. The purpose of this document is to provide such details. That is,the HTTP transport foran OTrPis implemented in a Broker (typically outside a TEE) thatover HTTP (OTrP/HTTP) implementation delivers messages up to an OTrP implementation, and accepts messages from the OTrP implementation to be sent over a network.2. TerminologyThekey words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL"OTrP over HTTP implementation can be implemented either outside a TEE (i.e., inthis documenta TEEP "Broker") or inside a TEE. There areto be interpreted as describedtwo topological scenarios inBCP 14 [RFC2119] [RFC8174] when,which OTrP could be deployed: 1. TAMs are reachable on the Internet, andonly when, they appear in all capitals, as shown here. This document also uses various terms defined inAgents 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. +------------------+ OTrP +------------------+ | TEEP Agent | <----------------------> | TAM | +------------------+ +------------------+ | | +------------------+ OTrP over HTTP +------------------+ | OTrP/HTTP Client | <----------------------> | OTrP/HTTP Server | +------------------+ +------------------+ | | +------------------+ HTTP +------------------+ | HTTP Client | <----------------------> | HTTP Server | +------------------+ +------------------+ Figure 1: Agent-to-TAM Communication 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,andTEEPBroker.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 OTrP implementation is inside the TEE, whereas the OTrP/HTTP implementation is in the TEEP Broker outside the TEE. Model: A B C ... TEE TEE TEE +----------------+ | | | | OTrP | Agent | | | Agent | implementation | | | | +----------------+ v | | | | | +----------------+ ^ | | | OTrP/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 betweena Broker andan OTrP implementation and an OTrP/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.It is common in someSome TEE architectures (e.g., SGX)to refer tomay support API calls both intoa Trusted Application (TA) as "ECALLs" (or enclave-calls),andcallsoutfromof aTrusted Application (TA) as "OCALLs" (or out-calls).TEE. In other TEE architectures, there may be noOCALLs,calls out from a TEE, but merely data returned from calls into aTA.TEE. This document attempts to be agnostic as to the concrete APIarchitecture. As such, abstract APIs usedarchitecture for Broker/Agent communication. Since inthis documentmodel A, the Broker/Agent communication is done at the layer between the OTrP and OTrP/HTTP implementations, and there may be some architectures that do not support calls out of the TEE (which would be downcalls from OTrP in model A), we will refer tocalls into a TApassing information up to the OTrP implementation as API calls,andbut will simply refer to "passing data" backout of the TA.down from an OTrP implementation. A concrete API might pass data back via anOCALLAPI downcall or via data returned from an APIcall.upcall. This document will also refer to passing "no" data back out ofa TA. InanOCALL-based architecture,OTrP implementation. In a concrete API, this might be implemented by not making anysuch call. In a return-based architecture, this might be implementeddowncall, or by returning 0bytes.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 OTrP. 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 OTrP content type per the OTrP 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 inana 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]. 5.TEEP BrokerOTrP/HTTP Client Behavior 5.1. Receiving a request to install a new Trusted ApplicationWhen the TEEP Broker receives a notificationIn some environments, an application installer can determine (e.g., from anapplication installer)app manifest) thatanthe application being installed or updated has a dependency on a given Trusted Application (TA) being available in a given type ofTEE,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 topassprovide to theTEEP Agent.OTrP 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. Whensuchanotification is received, theTEEP 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.TheOnce the TEEP Broker picks a TEE, it passes the notification to the OTrP/HTTP Cient for that TEE. The OTrP/HTTP Client then informs theTEEP AgentOTrP implementation in that TEE by invoking an appropriate "RequestTA" API that identifies the TA needed and any other associated metadata. TheTEEP BrokerOTrP/HTTP Client need not know whether the TEE already has such a TA installed or whether it is up to date. TheTEEP AgentOTrP 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 thebroker,OTrP/HTTP Client, depending on theTEEP Agent'sOTrP implementation's configuration. If they differ, theTEEP BrokerOTrP/HTTP Client MUST use the TAM URI passed back. 5.1.1. Session Creation If no data is passed back, theTEEP BrokerOTrP/HTTP Client simply informs itsclientcaller (e.g., the application installer) of success. If theTEEP AgentOTrP implementation passes back a TAM URI with no message buffer, theTEEP BrokerOTrP/HTTP Client attempts to create session state, then sends an HTTP(S) POST to the TAM URI with an Accept header and an empty body. The HTTP request is then associated with theTEEP Broker'sOTrP/HTTP Client's session state. If theTEEP AgentOTrP implementation instead passes back a TAM URI with a message buffer, theTEEP BrokerOTrP/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 theTEEP Agent.OTrP implementation. - Any context that identifies an HTTP request, if one is outstanding. Initially, none exists. 5.2. Getting a message buffer back from anTEEP AgentOTrP implementation When an OTrP implementation passes a message buffer (and TAM URI)is passedtoa TEEP Broker fromanTEEP Agent,OTrP/HTTP Client, theTEEP BrokerOTrP/HTTP Client MUST do the following, using theTEEP Broker'sOTrP/HTTP Client's session state associated with its API call to theTEEP Agent.OTrP implementation. TheTEEP BrokerOTrP/HTTP Client sends an HTTP POST request to the TAM URI with Accept and Content-Type headers with the OTrP media type in use, and a body containing the OTrP message buffer provided by theTEEP Agent.OTrP implementation. The HTTP request is then associated with theTEEP Broker'sOTrP/ 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, theTEEP BrokerOTrP/HTTP Client MUST do the following. If the HTTP response body is empty, theTEEP Broker'sOTrP/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, theTEEP BrokerOTrP/HTTP Client calls a "ProcessOTrPMessage" API (Section 6.2 of [I-D.ietf-teep-opentrustprotocol]) to pass the response body up to theTEEP AgentOTrP implementation associated with the session. TheTEEP AgentOTrP implementation will then either pass no data back, or passpackback a message buffer. If no data is passed back, theTEEP Broker'sOTrP/HTTP Client's task is complete, and it can delete its session state, and inform itsclientcaller (e.g., the application installer) of success. If instead theTEEP AgentOTrP implementation passes back a message buffer, theTEEP BrokerOTrP/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 OTrP policy changes. This can be done in any implementation-specific manner, such as: A) TheTEEP BrokerOTrP/HTTP Client might callintoup to theTEEP AgentOTrP implementation at an interval previously specified by theTEEP Agent.OTrP implementation. This approach requires that theTEEP BrokerOTrP/HTTP Client be capable of running a periodic timer. B) TheTEEP BrokerOTrP/HTTP Client might be informed when an existing TA is invoked, and callintoup to theTEEP AgentOTrP implementation if more time has passed than was previously specified by theTEEP Agent.OTrP implementation. This approach allows the device to go to sleep for a potentially long period of time. C) TheTEEP BrokerOTrP/HTTP Client might be informed when any attestation attempt determines that the device is out of compliance, and callintoup to theTEEP AgentOTrP implementation to remediate. TheTEEP BrokerOTrP/HTTP Client informs theTEEP AgentOTrP implementation by invoking an appropriate "RequestPolicyCheck" API. TheTEEP AgentOTrP 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 theTEEP BrokerOTrP/HTTP Client cannot get a message buffer (empty or not) back from theTEEP Agent,OTrP implementation, theTEEP BrokerOTrP/HTTP Client deletes its session state, and informs itsclientcaller (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), theTEEP BrokerOTrP/HTTP Client calls theTEEP Agent'sOTrP implementation's "ProcessError" API, and then deletes its session state and informs itsclientcaller of a failure. 6.TAM BrokerOTrP/HTTP Server Behavior 6.1. Receiving an HTTP POST request When an HTTP POST request is received with an empty body, theTAM BrokerOTrP/ 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, theTAM BrokerOTrP/HTTP Server calls the TAM's "ProcessOTrPMessage" API to pass it the request body. The TAM will then pass back a (possibly empty) message buffer. 6.2. Getting an empty buffer back from theTAMOTrP implementation If theTAMOTrP implementation passes back an empty buffer, theTAM BrokerOTrP/HTTP Server sends a successful (2xx) response with no body. 6.3. Getting a message buffer from theTAMOTrP implementation If theTAMOTrP implementation passes back a non-empty buffer, theTAM BrokerOTrP/ HTTP Server generates a successful (2xx) response with a Content-Type header with the OTrP media type in use, and with the message buffer as the body. 6.4. Error handling If any error occurs where theTAM BrokerOTrP/HTTP Server cannot get a message buffer (empty or not) back from theTAM,OTrP implementation, theTAM BrokerOTrP/ HTTP Server generates an appropriate HTTP error response. 7. Sample message flow The following shows a sample OTrP message flow that uses application/ otrp+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 picksan TEEP Agenta TEE (e.g., the only one available) based on thisnotification.notification, and passes the information to the OTrP/HTTP Cient for that TEE. 2. TheTEEP BrokerOTrP/HTTP Client calls theTEEP Agent'sOTrP implementation's "RequestTA" API, passing TA Needed = X. 3. TheTEEP AgentOTrP 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") to theTEEP Broker.OTrP/HTTP Client. (If theTEEP AgentOTrP implementation already had a cached TAM certificate that it trusts, it could skip to step 9 instead and generate a GetDeviceStateResponse.) 4. TheTEEP BrokerOTrP/HTTP Client sends an HTTP POST request to the TAM URI: POST /tam HTTP/1.1 Host: example.com Accept: application/otrp+json Content-Length: 0 User-Agent: Foo/1.0 5.TheOn the TAMBrokerside, the OTrP/HTTP Server receives the HTTP POST request, and calls theTAM'sOTrP implementation's "ProcessConnect" API. 6. TheTAMOTrP implementation generates an OTrP message(typically(where typically GetDeviceStateRequest is the first message) and passes it to theTAM Broker.OTrP/HTTP Server. 7. TheTAM BrokerOTrP/HTTP Server sends an HTTP successful response with the OTrP message in the body: HTTP/1.1 200 OK Content-Type: application/otrp+json Content-Length: [length of OTrP 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 [OTrP message here] 8.TheBack on the TEEPBrokerAgent side, the OTrP/HTTP Client gets the HTTP response, extracts the OTrP message and calls theTEEP Agent'sOTrP implementation's "ProcessOTrPMessage" API to pass it the message. 9. TheTEEP AgentOTrP implementation processes the OTrP message, and generates an OTrP response (e.g., GetDeviceStateResponse) which it passes back to theTEEP Broker.OTrP/HTTP Client. 10. TheTEEP BrokerOTrP/HTTP Client gets the OTrP message buffer and sends an HTTP POST request to the TAM URI, with the OTrP message in the body: POST /tam HTTP/1.1 Host: example.com Accept: application/otrp+json Content-Type: application/otrp+json Content-Length: [length of OTrP message here] User-Agent: Foo/1.0 [OTrP message here] 11. TheTAM BrokerOTrP/HTTP Server receives the HTTP POST request, and calls theTAM'sOTrP implementation's "ProcessOTrPMessage" API. 12. Steps 6-11 are then repeated until theTAMOTrP implementation passes no data back to theTAM BrokerOTrP/HTTP Server in step 6. 13. TheTAM BrokerOTrP/HTTP Server sends an HTTP successful response with no body: HTTP/1.1 204 No Content Server: Bar/2.2 14. TheTEEP BrokerOTrP/HTTP Client deletes its session state. 8. Security Considerations Although OTrP 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,BrokerOTrP/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. 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-otrp-v2] Pei, M., Tschofenig, H., and D. Wheeler, "The Open Trust Protocol (OTrP) v2", draft-tschofenig-teep-otrp-v2-00 (work in progress), July 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 [I-D.ietf-httpbis-bcp56bis] Nottingham, M., "Building Protocols with HTTP", draft- ietf-httpbis-bcp56bis-08 (work in progress), November 2018. [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-02draft-ietf-teep-architecture-03 (work in progress),MarchJuly 2019. Author's Address Dave Thaler Microsoft EMail: dthaler@microsoft.com