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