idnits 2.17.1 draft-reschke-http-oob-encoding-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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 7, 2015) is 3124 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) == Outdated reference: A later version (-02) exists of draft-thomson-http-encryption-01 -- Obsolete informational reference (is this intentional?): RFC 7232 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Reschke 3 Internet-Draft greenbytes 4 Intended status: Standards Track S. Loreto 5 Expires: April 9, 2016 Ericsson 6 October 7, 2015 8 'Out-Of-Band' Content Coding for HTTP 9 draft-reschke-http-oob-encoding-01 11 Abstract 13 This document describes an Hypertext Transfer Protocol (HTTP) content 14 coding that can be used to describe the location of a secondary 15 resource that contains the payload. 17 Editorial Note (To be removed by RFC Editor before publication) 19 Distribution of this document is unlimited. Although this is not a 20 work item of the HTTPbis Working Group, comments should be sent to 21 the Hypertext Transfer Protocol (HTTP) mailing list at 22 ietf-http-wg@w3.org [1], which may be joined by sending a message 23 with subject "subscribe" to ietf-http-wg-request@w3.org [2]. 25 Discussions of the HTTPbis Working Group are archived at 26 . 28 XML versions, latest edits, and issue tracking for this document are 29 available from and 30 . 32 The changes in this draft are summarized in Appendix C.1. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at http://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on April 9, 2016. 50 Copyright Notice 52 Copyright (c) 2015 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 69 3. 'Out-Of-Band' Content Coding . . . . . . . . . . . . . . . . . 3 70 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 71 3.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 72 3.3. Problem Reporting . . . . . . . . . . . . . . . . . . . . 5 73 3.3.1. Server Not Reachable . . . . . . . . . . . . . . . . . 6 74 3.3.2. Resource Not Found . . . . . . . . . . . . . . . . . . 6 75 3.3.3. Payload Unusable . . . . . . . . . . . . . . . . . . . 6 76 3.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 77 3.4.1. Basic Example . . . . . . . . . . . . . . . . . . . . 6 78 3.4.2. Example involving an encrypted resource . . . . . . . 8 79 3.4.3. Example For Problem Reporting . . . . . . . . . . . . 9 80 4. Feature Discovery . . . . . . . . . . . . . . . . . . . . . . 10 81 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 82 5.1. Content Modifications . . . . . . . . . . . . . . . . . . 10 83 5.2. Use in Requests . . . . . . . . . . . . . . . . . . . . . 10 84 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 85 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 86 7.1. Normative References . . . . . . . . . . . . . . . . . . . 10 87 7.2. Informative References . . . . . . . . . . . . . . . . . . 11 88 Appendix A. Alternatives, or: why not a new Status Code? . . . . 12 89 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 12 90 B.1. Range Requests . . . . . . . . . . . . . . . . . . . . . . 12 91 B.2. Accessing the Secondary Resource Too Early . . . . . . . . 12 92 Appendix C. Change Log (to be removed by RFC Editor before 93 publication) . . . . . . . . . . . . . . . . . . . . 13 94 C.1. Changes since draft-reschke-http-oob-encoding-00 . . . . . 13 95 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 13 97 1. Introduction 99 This document describes an Hypertext Transfer Protocol (HTTP) content 100 coding (Section 3.1.2.1 of [RFC7231]) that can be used to describe 101 the location of a secondary resource that contains the payload. 103 The primary use case for this content coding is to enable origin 104 servers to delegate the delivery of content to a secondary server 105 that might be "closer" to the client (with respect to network 106 topology) and/or able to cache content, leveraging content 107 encryption, as described in [ENCRYPTENC]. 109 2. Notational Conventions 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in [RFC2119]. 115 This document reuses terminology used in the base HTTP 116 specifications, namely Section 2 of [RFC7230] and Section 3 of 117 [RFC7231]. 119 3. 'Out-Of-Band' Content Coding 121 3.1. Overview 123 The 'Out-Of-Band' content coding is used to direct the recipient to 124 retrieve the actual message representation (Section 3 of [RFC7231]) 125 from a secondary resource, such as a public cache: 127 1. Client performs GET request 129 2. Received response specifies the 'out-of-band' content coding; the 130 payload of the response contains additional meta data, plus the 131 location of the secondary resource 133 3. Client performs GET request on secondary resource (usually again 134 via HTTP(s)) 136 4. Secondary server provides wrapped HTTP message 138 5. Client unwraps that representation (obtaining a full HTTP 139 message) 141 6. Client combines above representation with additional 142 representation metadata obtained from the primary resource 144 Client Secondary Server Origin Server 146 sends GET request with Accept-Encoding: out-of-band 147 (1) |---------------------------------------------------------\ 148 status 200 and Content-Coding: out-of-band | 149 (2) <---------------------------------------------------------/ 151 GET to secondary server 152 (3) |---------------------------\ 153 wrapped HTTP message | 154 (4) <---------------------------/ 156 (5, 6) 157 Client and combines HTTP message received in (4) 158 with metadata received in (2). 160 3.2. Definitions 162 The name of the content coding is "out-of-band". 164 The payload format uses JavaScript Object Notation (JSON, [RFC7159]), 165 describing an array of objects describing secondary resources, each 166 containing some of the members below: 168 'URI' A REQUIRED string containing the URI reference (Section 4.1 of 169 [RFC3986]) of the secondary resource. 171 'metadata' An OPTIONAL object containing additional members, 172 representing header field values to be recombined with the 173 metadata from the secondary resource and which can not appear as 174 header fields in the response message itself (header fields that 175 occur multiple times need to be combined into a single field value 176 as per Section 3.2.2 of [RFC7230]; header field names are lower- 177 cased). 179 The payload format uses a JSON array so that the origin server can 180 specify multiple secondary resources. When a client receives a 181 response containing multiple entries, it is free to choose which of 182 these to use. 184 The representation of the secondary resource needs to use a media 185 type capable of representing a full HTTP message. For now the only 186 supported type is "application/http" (Section 8.3.2 of [RFC7230]). 188 The client then obtains the original message by: 190 1. Unwrapping the encapsulated HTTP message by removing any transfer 191 and content codings. 193 The latter might require additional metadata that could be 194 present in the "metadata" object, such as the "Encryption-Key" 195 header field described in Section 4 of [ENCRYPTENC]. 197 2. Replacing/setting any response header fields from the primary 198 response except for framing-related information such as Content- 199 Length, Transfer-Encoding and Content-Encoding. 201 3. Replacing/setting any header fields with those present as members 202 in the "metadata" object. [[anchor3: Do we have a use case for 203 this?]] 205 If the client is unable to retrieve the secondary resource's 206 representation (host can't be reached, non 2xx response status code, 207 payload failing integrity check, etc.), it can choose an alternate 208 secondary resource (if specified), or simply retry the request to the 209 origin server without including "out-of-band" in the Accept-Encoding 210 request header field. In the latter case, it can be useful to inform 211 the origin server about what problems were encountered when trying to 212 access the secondary resource; see Section 3.3 for details. 214 Note that although this mechanism causes the inclusion of external 215 content, it will not affect the application-level security properties 216 of the reconstructed message, such as its web origin ([RFC6454]). 218 The cacheability of the response for the secondary resource does not 219 affect the cacheability of the reconstructed response message, which 220 is the same as for the origin server's response. 222 Note that because the server's response depends on the request's 223 Accept-Encoding header field, the response usually will need to be 224 declared to vary on that. See Section 7.1.4 of [RFC7231] and Section 225 2.3 of [RFC7232] for details. 227 3.3. Problem Reporting 229 When the client fails to obtain the secondary resource, it can be 230 useful to inform the origin server about the condition. This can be 231 accomplished by adding a "Link" header field ([RFC5988]) to a 232 subsequent request to the origin server, detailing the URI of the 233 secondary resource and the failure reason. 235 The following link extension relations are defined: 237 3.3.1. Server Not Reachable 239 Used in case the server was not reachable. 241 Link relation: 243 http://purl.org/NET/linkrel/not-reachable 245 3.3.2. Resource Not Found 247 Used in case the server responded, but the object could not be 248 obtained. 250 Link relation: 252 http://purl.org/NET/linkrel/resource-not-found 254 3.3.3. Payload Unusable 256 Used in case the the payload could be obtained, but wasn't usable 257 (for instance, because integrity checks failed). 259 Link relation: 261 http://purl.org/NET/linkrel/payload-unusable 263 3.4. Examples 265 3.4.1. Basic Example 267 Client request of primary resource: 269 GET /test HTTP/1.1 270 Host: www.example.com 271 Accept-Encoding: gzip, out-of-band 273 Response: 275 HTTP/1.1 200 OK 276 Date: Thu, 14 May 2015 18:52:00 GMT 277 Content-Type: text/plain 278 Cache-Control: max-age=10, public 279 Content-Encoding: out-of-band 280 Content-Length: 76 281 Vary: Accept-Encoding 283 [{ 284 "URI": "http://example.net/bae27c36-fa6a-11e4-ae5d-00059a3c7a00" 285 }] 287 (note that the Content-Type header field describes the media type of 288 the secondary's resource representation) 290 Client request for secondary resource: 292 GET /bae27c36-fa6a-11e4-ae5d-00059a3c7a00 HTTP/1.1 293 Host: example.net 295 Response: 297 HTTP/1.1 200 OK 298 Date: Thu, 14 May 2015 18:52:10 GMT 299 Content-Type: application/http 300 Cache-Control: private 301 Content-Length: 115 303 HTTP/1.1 200 OK 304 Date: Thu, 14 May 2015 17:00:00 GMT 305 Content-Length: 15 306 Content-Language: en 308 Hello, world. 310 Final message after recombining header fields: 312 HTTP/1.1 200 OK 313 Date: Thu, 14 May 2015 18:52:00 GMT 314 Content-Length: 15 315 Cache-Control: max-age=10, public 316 Content-Type: text/plain 317 Content-Language: en 319 Hello, world. 321 In this example, Cache-Control, Content-Length, and Date have been 322 set/overwritten with data from the primary resource's representation. 324 3.4.2. Example involving an encrypted resource 326 Given the example HTTP message from Section 5.4 of [ENCRYPTENC], a 327 primary resource could use the "out-of-band" encoding to specify just 328 the location of the secondary resource plus the contents of the 329 "Encryption-Key" header field needed to decrypt the payload: 331 Response: 333 HTTP/1.1 200 OK 334 Date: Thu, 14 May 2015 18:52:00 GMT 335 Content-Encoding: out-of-band 336 Content-Type: text/plain 337 Content-Length: 192 338 Vary: Accept-Encoding 340 [{ 341 "URI": "http://example.net/bae27c36-fa6a-11e4-ae5d-00059a3c7a00" 342 "metadata": { 343 "encryption-key": "keyid=\"a1\"; 344 key=\"9Z57YCb3dK95dSsdFJbkag\"" 345 } 346 }] 348 (note that the Content-Type header field describes the media type of 349 the secondary's resource representation) 350 Response for secondary resource: 352 HTTP/1.1 200 OK 353 Date: Thu, 14 May 2015 18:52:10 GMT 354 Content-Type: application/http 355 Content-Length: ... 356 Cache-Control: private 358 HTTP/1.1 200 OK 359 Content-Length: 31 360 Content-Encoding: aesgcm128 361 Encryption: keyid="a1"; salt="ibZx1RNz537h1XNkRcPpjA" 363 zK3kpG__Z8whjIkG6RYgPz11oUkTKcxPy9WP-VPMfuc 364 (payload body shown in base64 here) 366 Final message after recombining header fields: 368 HTTP/1.1 200 OK 369 Date: Thu, 14 May 2015 18:52:00 GMT 370 Content-Length: 15 371 Content-Type: text/plain 373 I am the walrus 375 3.4.3. Example For Problem Reporting 377 Client requests primary resource as in Section 3.4.1, but the attempt 378 to access the secondary resource fails. 380 Response: 382 HTTP/1.1 404 Not Found 383 Date: Thu, 08 September 2015 16:49:00 GMT 384 Content-Type: text/plain 385 Content-Length: 20 387 Resource Not Found 389 Client retries with the origin server and includes Link header field 390 reporting the problem: 392 GET /test HTTP/1.1 393 Host: www.example.com 394 Accept-Encoding: gzip, out-of-band 395 Link: ; 396 rel="http://purl.org/NET/linkrel/resource-not-found" 398 4. Feature Discovery 400 New content codings can be deployed easily, as the client can use the 401 "Accept-Encoding" header field (Section 5.3.4 of [RFC7231]) to signal 402 which content codings are supported. 404 5. Security Considerations 406 5.1. Content Modifications 408 This specification does not define means to verify that the payload 409 obtained from the secondary resource really is what the origin server 410 expects it to be. Content signatures can address this concern (see 411 [CONTENTSIG]). 413 5.2. Use in Requests 415 In general, content codings can be used in both requests and 416 responses. This particular content coding has been designed for 417 responses. When supported in requests, it creates a new attack 418 vector where the receiving server can be tricked into including 419 content that the client might not have access to otherwise (such as 420 HTTP resources behind a firewall). 422 6. IANA Considerations 424 The IANA "HTTP Content Coding Registry", located at 425 , needs to be 426 updated with the registration below: 428 Name: out-of-band 430 Description: Payload needs to be retrieved from a secondary resource 432 Reference: Section 3 of this document 434 7. References 436 7.1. Normative References 438 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 439 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 440 RFC2119, March 1997, 441 . 443 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, 444 "Uniform Resource Identifier (URI): Generic Syntax", 445 STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, 446 . 448 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/ 449 RFC5988, October 2010, 450 . 452 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 453 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, 454 March 2014, . 456 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 457 Transfer Protocol (HTTP/1.1): Message Syntax and 458 Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, 459 . 461 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 462 Transfer Protocol (HTTP/1.1): Semantics and Content", 463 RFC 7231, DOI 10.17487/RFC7231, June 2014, 464 . 466 7.2. Informative References 468 [CONTENTSIG] Thomson, M., "Content-Signature Header Field for HTTP", 469 draft-thomson-http-content-signature-00 (work in 470 progress), July 2015. 472 [ENCRYPTENC] Thomson, M., "Encrypted Content-Encoding for HTTP", 473 draft-thomson-http-encryption-01 (work in progress), 474 July 2015. 476 [RFC2017] Freed, N. and K. Moore, "Definition of the URL MIME 477 External-Body Access-Type", RFC 2017, DOI 10.17487/ 478 RFC2017, October 1996, 479 . 481 [RFC4483] Burger, E., "A Mechanism for Content Indirection in 482 Session Initiation Protocol (SIP) Messages", RFC 4483, 483 DOI 10.17487/RFC4483, May 2006, 484 . 486 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 487 DOI 10.17487/RFC6454, December 2011, 488 . 490 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 491 Transfer Protocol (HTTP/1.1): Conditional Requests", 492 RFC 7232, DOI 10.17487/RFC7232, June 2014, 493 . 495 URIs 497 [1] 499 [2] 501 Appendix A. Alternatives, or: why not a new Status Code? 503 A plausible alternative approach would be to implement this 504 functionality one level up, using a new redirect status code (Section 505 6.4 of [RFC7231]). However, this would have several drawbacks: 507 o Servers will need to know whether a client understands the new 508 status code; thus some additional signal to opt into this protocol 509 would always be needed. 511 o In redirect messages, representation metadata (Section 3.1 of 512 [RFC7231]), namely "Content-Type", applies to the response 513 message, not the redirected-to resource. 515 o The origin-preserving nature of using a content coding woudld be 516 lost. 518 Another alternative would be to implement the indirection on the 519 level of the media type using something similar to the type "message/ 520 external-body", defined in [RFC2017] and refined for use in the 521 Session Initiation Protocol (SIP) in [RFC4483]. This approach though 522 would share most of the drawbacks of the status code approach 523 mentioned above. 525 Appendix B. Open Issues 527 B.1. Range Requests 529 We probably need to handle Range Requests. How would this work? 530 Passing down the Range request header field to the secondary 531 resource? 533 What about codes other than 200 and 206? 535 B.2. Accessing the Secondary Resource Too Early 537 One use-case for this protocol is to enable a system of "blind 538 caches", which would serve the secondary resources. These caches 539 might only be populated on demand, thus it could happen that whatever 540 mechanism is used to populate the cache hasn't finished when the 541 client hits it (maybe due to race conditions, or because the cache is 542 behind a middlebox which doesn't allow the origin server to push 543 content to it). 545 In this particular case, it can be useful if the client was able to 546 "piggyback" the URI of the primary resource, giving the secondary 547 server a means by which it could obtain the payload itself. This 548 information could be provided in yet another Link header field: 550 GET bae27c36-fa6a-11e4-ae5d-00059a3c7a00 HTTP/1.1 551 Host: example.net 552 Link: ; 553 rel="http://purl.org/NET/linkrel/primary-resource" 555 (continuing the example from Section 3.4.1) 557 What's unclear is whether it's ok for the client to reveal the URI if 558 the primary resource, and under which conditions it's ok for the 559 secondary server to access it. All it needs is the potentially 560 encrypted payload, so maybe yet another URI on the origin server is 561 needed. 563 Appendix C. Change Log (to be removed by RFC Editor before publication) 565 C.1. Changes since draft-reschke-http-oob-encoding-00 567 Mention media type approach. 569 Explain that clients can always fall back not to use oob when the 570 secondary resource isn't available. 572 Add Vary response header field to examples and mention that it'll 573 usually be needed 574 (). 576 Experimentally add problem reporting using piggy-backed Link header 577 fields (). 579 Appendix D. Acknowledgements 581 Thanks to Christer Holmberg, Daniel Lindstrom, Goran Eriksson, John 582 Mattsson, Kevin Smith, Mark Nottingham, Martin Thomson, and Roland 583 Zink for feedback on this document. 585 Authors' Addresses 587 Julian F. Reschke 588 greenbytes GmbH 589 Hafenweg 16 590 Muenster, NW 48155 591 Germany 593 EMail: julian.reschke@greenbytes.de 594 URI: http://greenbytes.de/tech/webdav/ 596 Salvatore Loreto 597 Ericsson 598 Hirsalantie 11 599 Jorvas 02420 600 Finland 602 EMail: salvatore.loreto@ericsson.com