idnits 2.17.1 draft-ietf-teep-otrp-over-http-00.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 (June 21, 2019) is 1764 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-04 ** 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 -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). 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 June 21, 2019 5 Expires: December 23, 2019 7 HTTP Transport for the Open Trust Protocol (OTrP) 8 draft-ietf-teep-otrp-over-http-00 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 December 23, 2019. 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. Client 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 OTrP 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. Server 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 . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 10.1. Normative References . . . . . . . . . . . . . . . . . . 11 73 10.2. Informative References . . . . . . . . . . . . . . . . . 11 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 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 OTrP 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 Agent, and 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]: 155 Content-Type: application/otrp+json 156 Cache-Control: no-store 157 X-Content-Type-Options: nosniff 158 Content-Security-Policy: default-src 'none' 159 Referrer-Policy: no-referrer 161 Only the POST method is specified for TAM resources exposed over 162 HTTP. A URI of such a resource is referred to as a "TAM URI". A TAM 163 URI can be any HTTP(S) URI. The URI to use is configured in an OTrP 164 Agent via an out-of-band mechanism, as discussed in the next section. 166 When HTTPS is used, TLS certificates MUST be checked according to 167 [RFC2818]. 169 5. Client Broker Behavior 171 5.1. Receiving a request to install a new Trusted Application 173 When the Broker receives a notification (e.g., from an application 174 installer) that an application has a dependency on a given Trusted 175 Application (TA) being available in a given type of TEE, the 176 notification will contain the following: 178 - A unique identifier of the TA 180 - Optionally, any metadata to pass to the OTrP Agent. This might 181 include a TAM URI provided in the application manifest, for 182 example. 184 - Optionally, any requirements that may affect the choice of TEE, if 185 multiple are available to the Broker. 187 When such a notification is received, the Broker first identifies in 188 an implementation-dependent way which TEE (if any) is most 189 appropriate based on the constraints expressed. If there is only one 190 TEE, the choice is obvious. Otherwise, the choice might be based on 191 factors such as capabilities of available TEE(s) compared with TEE 192 requirements in the notification. 194 The Broker then informs the OTrP Agent in that TEE by invoking an 195 appropriate "RequestTA" API that identifies the TA needed and any 196 other associated metadata. The Broker need not know whether the TEE 197 already has such a TA installed or whether it is up to date. 199 The OTrP Agent will either (a) pass no data back, (b) pass back a TAM 200 URI to connect to, or (c) pass back a message buffer and TAM URI to 201 send it to. The TAM URI passed back may or may not be the same as 202 the TAM URI, if any, provided by the broker, depending on the OTrP 203 Agent's configuration. If they differ, the Broker MUST use the TAM 204 URI passed back. 206 5.1.1. Session Creation 208 If no data is passed back, the Broker simply informs its client 209 (e.g., the application installer) of success. 211 If the OTrP Agent passes back a TAM URI with no message buffer, the 212 TEEP Broker attempts to create session state, then sends an HTTP(S) 213 POST to the TAM URI with an "Accept: application/otrp+json" header 214 and an empty body. The HTTP request is then associated with the 215 Broker's session state. 217 If the OTrP Agent instead passes back a TAM URI with a message 218 buffer, the TEEP Broker attempts to create session state and handles 219 the message buffer as specified in Section 5.2. 221 Session state consists of: 223 - Any context (e.g., a handle) that identifies the API session with 224 the OTrP Agent. 226 - Any context that identifies an HTTP request, if one is 227 outstanding. Initially, none exists. 229 5.2. Getting a message buffer back from an OTrP Agent 231 When a message buffer (and TAM URI) is passed to a Broker from an 232 OTrP Agent, the Broker MUST do the following, using the Broker's 233 session state associated with its API call to the OTrP Agent. 235 The Broker sends an HTTP POST request to the TAM URI with "Accept: 236 application/otrp+json" and "Content-Type: application/otrp+json" 237 headers, and a body containing the OTrP message buffer provided by 238 the OTrP Agent. The HTTP request is then associated with the 239 Broker's session state. 241 5.3. Receiving an HTTP response 243 When an HTTP response is received in response to a request associated 244 with a given session state, the Broker MUST do the following. 246 If the HTTP response body is empty, the Broker's task is complete, 247 and it can delete its session state, and its task is done. 249 If instead the HTTP response body is not empty, the Broker calls a 250 "ProcessOTrPMessage" API (Section 6.2 of 251 [I-D.ietf-teep-opentrustprotocol]) to pass the response body to the 252 OTrP Agent associated with the session. The OTrP Agent will then 253 pass no data back, or pass pack a message buffer. 255 If no data is passed back, the Broker's task is complete, and it can 256 delete its session state, and inform its client (e.g., the 257 application installer) of success. 259 If instead the OTrP Agent passes back a message buffer, the TEEP 260 Broker handles the message buffer as specified in Section 5.2. 262 5.4. Handling checks for policy changes 264 An implementation MUST provide a way to periodically check for OTrP 265 policy changes. This can be done in any implementation-specific 266 manner, such as: 268 A) The Broker might call into the OTrP Agent at an interval 269 previously specified by the OTrP Agent. This approach requires that 270 the Broker be capable of running a periodic timer. 272 B) The Broker might be informed when an existing TA is invoked, and 273 call into the OTrP Agent if more time has passed than was previously 274 specified by the OTrP Agent. This approach allows the device to go 275 to sleep for a potentially long period of time. 277 C) The Broker might be informed when any attestation attempt 278 determines that the device is out of compliance, and call into the 279 OTrP Agent to remediate. 281 The Broker informs the OTrP Agent by invoking an appropriate 282 "RequestPolicyCheck" API. The OTrP Agent will either (a) pass no 283 data back, (b) pass back a TAM URI to connect to, or (c) pass back a 284 message buffer and TAM URI to send it to. Processing then continues 285 as specified in Section 5.1.1. 287 5.5. Error handling 289 If any local error occurs where the Broker cannot get a message 290 buffer (empty or not) back from the OTrP Agent, the Broker deletes 291 its session state, and informs its client (e.g., the application 292 installer) of a failure. 294 If any HTTP request results in an HTTP error response or a lower 295 layer error (e.g., network unreachable), the Broker calls the OTrP 296 Agent's "ProcessError" API, and then deletes its session state and 297 informs its client of a failure. 299 6. Server Broker Behavior 301 6.1. Receiving an HTTP POST request 303 When an HTTP POST request is received with an empty body, the Broker 304 invokes the TAM's "ProcessConnect" API. The TAM will then pass back 305 a (possibly empty) message buffer. 307 When an HTTP POST request is received with a non-empty body, the 308 Broker calls the TAM's "ProcessOTrPMessage" API to pass it the 309 request body. The TAM will then pass back a (possibly empty) message 310 buffer. 312 6.2. Getting an empty buffer back from the TAM 314 If the TAM passes back an empty buffer, the Broker sends a successful 315 (2xx) response with no body. 317 6.3. Getting a message buffer from the TAM 319 If the TAM passes back a non-empty buffer, the Broker generates a 320 successful (2xx) response with a "Content-Type: application/ 321 otrp+json" header, and with the message buffer as the body. 323 6.4. Error handling 325 If any error occurs where the Broker cannot get a message buffer 326 (empty or not) back from the TAM, the Broker generates an appropriate 327 HTTP error response. 329 7. Sample message flow 331 1. An application installer determines (e.g., from an app manifest) 332 that the application has a dependency on TA "X", and passes this 333 notification to the Client Broker. The Client Broker picks an 334 OTrP Agent (e.g., the only one available) based on this 335 notification. 337 2. The Client Broker calls the OTrP Agent's "RequestTA" API, 338 passing TA Needed = X. 340 3. The OTrP Agent finds that no such TA is already installed, but 341 that it can be obtained from a given TAM. The OTrP Agent passes 342 the TAM URI (e.g., "https://example.com/tam") to the Client 343 Broker. (If the OTrP Agent already had a cached TAM certificate 344 that it trusts, it could skip to step 9 instead and generate a 345 GetDeviceStateResponse.) 347 4. The Client Broker sends an HTTP POST request to the TAM URI: 349 POST /tam HTTP/1.1 350 Host: example.com 351 Accept: application/otrp+json 352 Content-Length: 0 353 User-Agent: Foo/1.0 355 5. The Server Broker receives the HTTP POST request, and calls the 356 TAM's "ProcessConnect" API. 358 6. The TAM generates an OTrP message (typically 359 GetDeviceStateRequest is the first message) and passes it to the 360 Server Broker. 362 7. The Server Broker sends an HTTP successful response with the 363 OTrP message in the body: 365 HTTP/1.1 200 OK 366 Content-Type: application/otrp+json 367 Content-Length: [length of OTrP message here] 368 Server: Bar/2.2 369 Cache-Control: no-store 370 X-Content-Type-Options: nosniff 371 Content-Security-Policy: default-src 'none' 372 Referrer-Policy: no-referrer 374 [OTrP message here] 376 8. The Client Broker gets the HTTP response, extracts the OTrP 377 message and calls the OTrP Agent's "ProcessOTrPMessage" API to 378 pass it the message. 380 9. The OTrP Agent processes the OTrP message, and generates an OTrP 381 response (e.g., GetDeviceStateResponse) which it passes back to 382 the Client Broker. 384 10. The Client Broker gets the OTrP message buffer and sends an HTTP 385 POST request to the TAM URI, with the OTrP message in the body: 387 POST /tam HTTP/1.1 388 Host: example.com 389 Accept: application/otrp+json 390 Content-Type: application/otrp+json 391 Content-Length: [length of OTrP message here] 392 User-Agent: Foo/1.0 394 [OTrP message here] 396 11. The Server Broker receives the HTTP POST request, and calls the 397 TAM's "ProcessOTrPMessage" API. 399 12. Steps 6-11 are then repeated until the TAM passes no data back 400 to the Server Broker in step 6. 402 13. The Server Broker sends an HTTP successful response with no 403 body: 405 HTTP/1.1 204 No Content 406 Server: Bar/2.2 408 14. The Client Broker deletes its session state. 410 8. Security Considerations 412 Although OTrP is protected end-to-end inside of HTTP, there is still 413 value in using HTTPS for transport, since HTTPS can provide 414 additional protections as discussed in Section 6 of 415 [I-D.ietf-httpbis-bcp56bis]. As such, Broker implementations MUST 416 support HTTPS. The choice of HTTP vs HTTPS at runtime is up to 417 policy, where an administrator configures the TAM URI to be used, but 418 it is expected that real deployments will always use HTTPS TAM URIs. 420 9. IANA Considerations 422 [[NOTE: This section should probably be moved to the OTrP spec.]] 424 This section requests that IANA assign the "application/otrp+json" 425 media type. 427 Type name: application 429 Subtype name: otrp+json 431 Required parameters: none 433 Optional parameters: none 435 Encoding considerations: Same as encoding considerations of 436 application/json as specified in Section 11 of [RFC7159]. 438 Security considerations: See Section 12 of [RFC7159] and Section 8 of 439 this document. 441 Interoperability considerations: Same as interoperability 442 considerations of application/json as specified in [RFC7159]. 444 Published specification: [I-D.ietf-teep-opentrustprotocol] 446 Applications that use this media type: OTrP implementations. 448 Fragment identifier considerations: N/A 450 Additional information: 451 Deprecated alias names for this type: N/A 452 Magic number(s): N/A 453 File extension(s): N/A 454 Macintosh file type code(s): N/A 456 Person & email address to contact for further information: 457 teep@ietf.org 459 Intended usage: COMMON 461 Restrictions on usage: none 463 Author: See the "Authors' Addresses" section of this document. 465 Change controller: IETF 467 10. References 469 10.1. Normative References 471 [I-D.ietf-httpbis-semantics] 472 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 473 Semantics", draft-ietf-httpbis-semantics-04 (work in 474 progress), March 2019. 476 [I-D.ietf-teep-opentrustprotocol] 477 Pei, M., Atyeo, A., Cook, N., Yoo, M., and H. Tschofenig, 478 "The Open Trust Protocol (OTrP)", draft-ietf-teep- 479 opentrustprotocol-03 (work in progress), May 2019. 481 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 482 Requirement Levels", BCP 14, RFC 2119, 483 DOI 10.17487/RFC2119, March 1997, . 486 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 487 DOI 10.17487/RFC2818, May 2000, . 490 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 491 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 492 May 2017, . 494 10.2. Informative References 496 [I-D.ietf-httpbis-bcp56bis] 497 Nottingham, M., "Building Protocols with HTTP", draft- 498 ietf-httpbis-bcp56bis-08 (work in progress), November 499 2018. 501 [I-D.ietf-teep-architecture] 502 Pei, M., Tschofenig, H., Wheeler, D., Atyeo, A., and D. 503 Liu, "Trusted Execution Environment Provisioning (TEEP) 504 Architecture", draft-ietf-teep-architecture-02 (work in 505 progress), March 2019. 507 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 508 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 509 2014, . 511 Author's Address 513 David Thaler 514 Microsoft 516 EMail: dthaler@microsoft.com