idnits 2.17.1 draft-ietf-teep-otrp-over-http-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 08, 2019) is 1754 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-05 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) == Outdated reference: A later version (-15) exists of draft-ietf-httpbis-bcp56bis-08 == Outdated reference: A later version (-19) exists of draft-ietf-teep-architecture-02 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TEEP WG D. Thaler 3 Internet-Draft Microsoft 4 Intended status: Informational July 08, 2019 5 Expires: January 9, 2020 7 HTTP Transport for the Open Trust Protocol (OTrP) 8 draft-ietf-teep-otrp-over-http-01 10 Abstract 12 This document specifies the HTTP transport for the Open Trust 13 Protocol (OTrP), which is used to manage code and configuration data 14 in a Trusted Execution Environment (TEE). An implementation of this 15 document can run outside of any TEE, but interacts with an OTrP 16 implementation that runs inside a TEE. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on January 9, 2020. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3. Use of Abstract APIs . . . . . . . . . . . . . . . . . . . . 3 55 4. Use of HTTP as a Transport . . . . . . . . . . . . . . . . . 3 56 5. TEEP Broker Behavior . . . . . . . . . . . . . . . . . . . . 4 57 5.1. Receiving a request to install a new Trusted Application 4 58 5.1.1. Session Creation . . . . . . . . . . . . . . . . . . 5 59 5.2. Getting a message buffer back from an TEEP Agent . . . . 5 60 5.3. Receiving an HTTP response . . . . . . . . . . . . . . . 6 61 5.4. Handling checks for policy changes . . . . . . . . . . . 6 62 5.5. Error handling . . . . . . . . . . . . . . . . . . . . . 7 63 6. TAM Broker Behavior . . . . . . . . . . . . . . . . . . . . . 7 64 6.1. Receiving an HTTP POST request . . . . . . . . . . . . . 7 65 6.2. Getting an empty buffer back from the TAM . . . . . . . . 7 66 6.3. Getting a message buffer from the TAM . . . . . . . . . . 7 67 6.4. Error handling . . . . . . . . . . . . . . . . . . . . . 7 68 7. Sample message flow . . . . . . . . . . . . . . . . . . . . . 7 69 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 70 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 71 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 72 10.1. Normative References . . . . . . . . . . . . . . . . . . 10 73 10.2. Informative References . . . . . . . . . . . . . . . . . 10 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 76 1. Introduction 78 Trusted Execution Environments (TEEs), including Intel SGX, ARM 79 TrustZone, Secure Elements, and others, enforce that only authorized 80 code can execute within the TEE, and any memory used by such code is 81 protected against tampering or disclosure outside the TEE. The Open 82 Trust Protocol (OTrP) is designed to provision authorized code and 83 configuration into TEEs. 85 To be secure against malware, an OTrP implementation (referred to as 86 an OTrP "Agent" on the client side, and a "Trusted Application 87 Manager (TAM)" on the server side) must themselves run inside a TEE. 88 However, the transport for OTrP, along with typical networking 89 stacks, need not run inside a TEE. This split allows the set of 90 highly trusted code to be kept as small as possible, including 91 allowing code (e.g., TCP/IP) that only sees encrypted messages to be 92 kept out of the TEE. 94 The OTrP specification [I-D.ietf-teep-opentrustprotocol] describes 95 the behavior of TEEP Agents and TAMs, but does not specify the 96 details of the transport, an implementation of which is referred to 97 as a "Broker". The purpose of this document is to provide such 98 details. That is, the HTTP transport for OTrP is implemented in a 99 Broker (typically outside a TEE) that delivers messages up to an OTrP 100 implementation, and accepts messages from the OTrP implementation to 101 be sent over a network. 103 2. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in BCP 108 14 [RFC2119] [RFC8174] when, and only when, they appear in all 109 capitals, as shown here. 111 This document also uses various terms defined in 112 [I-D.ietf-teep-architecture], including Trusted Execution Environment 113 (TEE), Trusted Application (TA), Trusted Application Manager (TAM), 114 TEEP Agent, and TEEP Broker. 116 3. Use of Abstract APIs 118 This document refers to various APIs between a Broker and an OTrP 119 implementation in the abstract, meaning the literal syntax and 120 programming language are not specified, so that various concrete APIs 121 can be designed (outside of the IETF) that are compliant. 123 It is common in some TEE architectures (e.g., SGX) to refer to calls 124 into a Trusted Application (TA) as "ECALLs" (or enclave-calls), and 125 calls out from a Trusted Application (TA) as "OCALLs" (or out-calls). 127 In other TEE architectures, there may be no OCALLs, but merely data 128 returned from calls into a TA. This document attempts to be agnostic 129 as to the concrete API architecture. As such, abstract APIs used in 130 this document will refer to calls into a TA as API calls, and will 131 simply refer to "passing data" back out of the TA. A concrete API 132 might pass data back via an OCALL or via data returned from an API 133 call. 135 This document will also refer to passing "no" data back out of a TA. 136 In an OCALL-based architecture, this might be implemented by not 137 making any such call. In a return-based architecture, this might be 138 implemented by returning 0 bytes. 140 4. Use of HTTP as a Transport 142 This document uses HTTP [I-D.ietf-httpbis-semantics] as a transport. 143 When not called out explicitly in this document, all implementation 144 recommendations in [I-D.ietf-httpbis-bcp56bis] apply to use of HTTP 145 by OTrP. 147 Redirects MAY be automatically followed, and no additional request 148 headers beyond those specified by HTTP need be modified or removed 149 upon a following such a redirect. 151 Content is not intended to be treated as active by browsers and so 152 HTTP responses with content SHOULD have the following headers as 153 explained in Section 4.12 of [I-D.ietf-httpbis-bcp56bis] (replacing 154 the content type with the relevant OTrP content type per the OTrP 155 specification): 157 Content-Type: 158 Cache-Control: no-store 159 X-Content-Type-Options: nosniff 160 Content-Security-Policy: default-src 'none' 161 Referrer-Policy: no-referrer 163 Only the POST method is specified for TAM resources exposed over 164 HTTP. A URI of such a resource is referred to as a "TAM URI". A TAM 165 URI can be any HTTP(S) URI. The URI to use is configured in an TEEP 166 Agent via an out-of-band mechanism, as discussed in the next section. 168 When HTTPS is used, TLS certificates MUST be checked according to 169 [RFC2818]. 171 5. TEEP Broker Behavior 173 5.1. Receiving a request to install a new Trusted Application 175 When the TEEP Broker receives a notification (e.g., from an 176 application installer) that an application has a dependency on a 177 given Trusted Application (TA) being available in a given type of 178 TEE, the notification will contain the following: 180 - A unique identifier of the TA 182 - Optionally, any metadata to pass to the TEEP Agent. This might 183 include a TAM URI provided in the application manifest, for 184 example. 186 - Optionally, any requirements that may affect the choice of TEE, if 187 multiple are available to the TEEP Broker. 189 When such a notification is received, the TEEP Broker first 190 identifies in an implementation-dependent way which TEE (if any) is 191 most appropriate based on the constraints expressed. If there is 192 only one TEE, the choice is obvious. Otherwise, the choice might be 193 based on factors such as capabilities of available TEE(s) compared 194 with TEE requirements in the notification. 196 The TEEP Broker then informs the TEEP Agent in that TEE by invoking 197 an appropriate "RequestTA" API that identifies the TA needed and any 198 other associated metadata. The TEEP Broker need not know whether the 199 TEE already has such a TA installed or whether it is up to date. 201 The TEEP Agent will either (a) pass no data back, (b) pass back a TAM 202 URI to connect to, or (c) pass back a message buffer and TAM URI to 203 send it to. The TAM URI passed back may or may not be the same as 204 the TAM URI, if any, provided by the broker, depending on the TEEP 205 Agent's configuration. If they differ, the TEEP Broker MUST use the 206 TAM URI passed back. 208 5.1.1. Session Creation 210 If no data is passed back, the TEEP Broker simply informs its client 211 (e.g., the application installer) of success. 213 If the TEEP Agent passes back a TAM URI with no message buffer, the 214 TEEP Broker attempts to create session state, then sends an HTTP(S) 215 POST to the TAM URI with an Accept header and an empty body. The 216 HTTP request is then associated with the TEEP Broker's session state. 218 If the TEEP Agent instead passes back a TAM URI with a message 219 buffer, the TEEP Broker attempts to create session state and handles 220 the message buffer as specified in Section 5.2. 222 Session state consists of: 224 - Any context (e.g., a handle) that identifies the API session with 225 the TEEP Agent. 227 - Any context that identifies an HTTP request, if one is 228 outstanding. Initially, none exists. 230 5.2. Getting a message buffer back from an TEEP Agent 232 When a message buffer (and TAM URI) is passed to a TEEP Broker from 233 an TEEP Agent, the TEEP Broker MUST do the following, using the TEEP 234 Broker's session state associated with its API call to the TEEP 235 Agent. 237 The TEEP Broker sends an HTTP POST request to the TAM URI with Accept 238 and Content-Type headers with the OTrP media type in use, and a body 239 containing the OTrP message buffer provided by the TEEP Agent. The 240 HTTP request is then associated with the TEEP Broker's session state. 242 5.3. Receiving an HTTP response 244 When an HTTP response is received in response to a request associated 245 with a given session state, the TEEP Broker MUST do the following. 247 If the HTTP response body is empty, the TEEP Broker's task is 248 complete, and it can delete its session state, and its task is done. 250 If instead the HTTP response body is not empty, the TEEP Broker calls 251 a "ProcessOTrPMessage" API (Section 6.2 of 252 [I-D.ietf-teep-opentrustprotocol]) to pass the response body to the 253 TEEP Agent associated with the session. The TEEP Agent will then 254 pass no data back, or pass pack a message buffer. 256 If no data is passed back, the TEEP Broker's task is complete, and it 257 can delete its session state, and inform its client (e.g., the 258 application installer) of success. 260 If instead the TEEP Agent passes back a message buffer, the TEEP 261 Broker handles the message buffer as specified in Section 5.2. 263 5.4. Handling checks for policy changes 265 An implementation MUST provide a way to periodically check for OTrP 266 policy changes. This can be done in any implementation-specific 267 manner, such as: 269 A) The TEEP Broker might call into the TEEP Agent at an interval 270 previously specified by the TEEP Agent. This approach requires that 271 the TEEP Broker be capable of running a periodic timer. 273 B) The TEEP Broker might be informed when an existing TA is invoked, 274 and call into the TEEP Agent if more time has passed than was 275 previously specified by the TEEP Agent. This approach allows the 276 device to go to sleep for a potentially long period of time. 278 C) The TEEP Broker might be informed when any attestation attempt 279 determines that the device is out of compliance, and call into the 280 TEEP Agent to remediate. 282 The TEEP Broker informs the TEEP Agent by invoking an appropriate 283 "RequestPolicyCheck" API. The TEEP Agent will either (a) pass no 284 data back, (b) pass back a TAM URI to connect to, or (c) pass back a 285 message buffer and TAM URI to send it to. Processing then continues 286 as specified in Section 5.1.1. 288 5.5. Error handling 290 If any local error occurs where the TEEP Broker cannot get a message 291 buffer (empty or not) back from the TEEP Agent, the TEEP Broker 292 deletes its session state, and informs its client (e.g., the 293 application installer) of a failure. 295 If any HTTP request results in an HTTP error response or a lower 296 layer error (e.g., network unreachable), the TEEP Broker calls the 297 TEEP Agent's "ProcessError" API, and then deletes its session state 298 and informs its client of a failure. 300 6. TAM Broker Behavior 302 6.1. Receiving an HTTP POST request 304 When an HTTP POST request is received with an empty body, the TAM 305 Broker invokes the TAM's "ProcessConnect" API. The TAM will then 306 pass back a (possibly empty) message buffer. 308 When an HTTP POST request is received with a non-empty body, the TAM 309 Broker calls the TAM's "ProcessOTrPMessage" API to pass it the 310 request body. The TAM will then pass back a (possibly empty) message 311 buffer. 313 6.2. Getting an empty buffer back from the TAM 315 If the TAM passes back an empty buffer, the TAM Broker sends a 316 successful (2xx) response with no body. 318 6.3. Getting a message buffer from the TAM 320 If the TAM passes back a non-empty buffer, the TAM Broker generates a 321 successful (2xx) response with a Content-Type header with the OTrP 322 media type in use, and with the message buffer as the body. 324 6.4. Error handling 326 If any error occurs where the TAM Broker cannot get a message buffer 327 (empty or not) back from the TAM, the TAM Broker generates an 328 appropriate HTTP error response. 330 7. Sample message flow 332 The following shows a sample OTrP message flow that uses application/ 333 otrp+json as the Content-Type. 335 1. An application installer determines (e.g., from an app manifest) 336 that the application has a dependency on TA "X", and passes this 337 notification to the TEEP Broker. The TEEP Broker picks an TEEP 338 Agent (e.g., the only one available) based on this notification. 340 2. The TEEP Broker calls the TEEP Agent's "RequestTA" API, passing 341 TA Needed = X. 343 3. The TEEP Agent finds that no such TA is already installed, but 344 that it can be obtained from a given TAM. The TEEP Agent passes 345 the TAM URI (e.g., "https://example.com/tam") to the TEEP 346 Broker. (If the TEEP Agent already had a cached TAM certificate 347 that it trusts, it could skip to step 9 instead and generate a 348 GetDeviceStateResponse.) 350 4. The TEEP Broker sends an HTTP POST request to the TAM URI: 352 POST /tam HTTP/1.1 353 Host: example.com 354 Accept: application/otrp+json 355 Content-Length: 0 356 User-Agent: Foo/1.0 358 5. The TAM Broker receives the HTTP POST request, and calls the 359 TAM's "ProcessConnect" API. 361 6. The TAM generates an OTrP message (typically 362 GetDeviceStateRequest is the first message) and passes it to the 363 TAM Broker. 365 7. The TAM Broker sends an HTTP successful response with the OTrP 366 message in the body: 368 HTTP/1.1 200 OK 369 Content-Type: application/otrp+json 370 Content-Length: [length of OTrP message here] 371 Server: Bar/2.2 372 Cache-Control: no-store 373 X-Content-Type-Options: nosniff 374 Content-Security-Policy: default-src 'none' 375 Referrer-Policy: no-referrer 377 [OTrP message here] 379 8. The TEEP Broker gets the HTTP response, extracts the OTrP 380 message and calls the TEEP Agent's "ProcessOTrPMessage" API to 381 pass it the message. 383 9. The TEEP Agent processes the OTrP message, and generates an OTrP 384 response (e.g., GetDeviceStateResponse) which it passes back to 385 the TEEP Broker. 387 10. The TEEP Broker gets the OTrP message buffer and sends an HTTP 388 POST request to the TAM URI, with the OTrP message in the body: 390 POST /tam HTTP/1.1 391 Host: example.com 392 Accept: application/otrp+json 393 Content-Type: application/otrp+json 394 Content-Length: [length of OTrP message here] 395 User-Agent: Foo/1.0 397 [OTrP message here] 399 11. The TAM Broker receives the HTTP POST request, and calls the 400 TAM's "ProcessOTrPMessage" API. 402 12. Steps 6-11 are then repeated until the TAM passes no data back 403 to the TAM Broker in step 6. 405 13. The TAM Broker sends an HTTP successful response with no body: 407 HTTP/1.1 204 No Content 408 Server: Bar/2.2 410 14. The TEEP Broker deletes its session state. 412 8. Security Considerations 414 Although OTrP is protected end-to-end inside of HTTP, there is still 415 value in using HTTPS for transport, since HTTPS can provide 416 additional protections as discussed in Section 6 of 417 [I-D.ietf-httpbis-bcp56bis]. As such, Broker implementations MUST 418 support HTTPS. The choice of HTTP vs HTTPS at runtime is up to 419 policy, where an administrator configures the TAM URI to be used, but 420 it is expected that real deployments will always use HTTPS TAM URIs. 422 9. IANA Considerations 424 This document has no actions for IANA. 426 10. References 428 10.1. Normative References 430 [I-D.ietf-httpbis-semantics] 431 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 432 Semantics", draft-ietf-httpbis-semantics-05 (work in 433 progress), July 2019. 435 [I-D.ietf-teep-opentrustprotocol] 436 Pei, M., Atyeo, A., Cook, N., Yoo, M., and H. Tschofenig, 437 "The Open Trust Protocol (OTrP)", draft-ietf-teep- 438 opentrustprotocol-03 (work in progress), May 2019. 440 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 441 Requirement Levels", BCP 14, RFC 2119, 442 DOI 10.17487/RFC2119, March 1997, . 445 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 446 DOI 10.17487/RFC2818, May 2000, . 449 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 450 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 451 May 2017, . 453 10.2. Informative References 455 [I-D.ietf-httpbis-bcp56bis] 456 Nottingham, M., "Building Protocols with HTTP", draft- 457 ietf-httpbis-bcp56bis-08 (work in progress), November 458 2018. 460 [I-D.ietf-teep-architecture] 461 Pei, M., Tschofenig, H., Wheeler, D., Atyeo, A., and D. 462 Liu, "Trusted Execution Environment Provisioning (TEEP) 463 Architecture", draft-ietf-teep-architecture-02 (work in 464 progress), March 2019. 466 Author's Address 468 Dave Thaler 469 Microsoft 471 EMail: dthaler@microsoft.com