-
Notifications
You must be signed in to change notification settings - Fork 2
/
draft-eriksson-http-resource-map.xml
executable file
·572 lines (512 loc) · 21.5 KB
/
draft-eriksson-http-resource-map.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
<?xml version="1.0" encoding="iso-8859-1"?>
<?rfc toc="yes" ?>
<?rfc compact="yes" ?>
<?rfc sortrefs="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc-ext allow-markup-in-artwork="yes" ?>
<?rfc-ext html-pretty-print="prettyprint https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"?>
<!DOCTYPE rfc [
<!ENTITY mdash "—">
]>
<rfc xmlns:x="http://purl.org/net/xml2rfc/ext" ipr="trust200902" category="info" docName="draft-eriksson-http-resource-map-latest">
<front>
<title>
Resource Maps
</title>
<author fullname="Goran AP Eriksson" initials="G. A. P." surname="Eriksson">
<organization>Ericsson</organization>
<address>
<postal>
<street>Farogatan 6</street>
<code>16480</code>
<city>Stockholm</city>
<country>Sweden</country>
</postal>
<email>goran.ap.eriksson@ericsson.com</email>
</address>
</author>
<author fullname="Christer Holmberg" initials="C." surname="Holmberg">
<organization>Ericsson</organization>
<address>
<email>christer.holmberg@ericsson.com</email>
</address>
</author>
<author fullname="Zaheduzzaman Sarker" initials="Z." surname="Sarker">
<organization>Ericsson</organization>
<address>
<email>zaheduzzaman.sarker@ericsson.com</email>
</address>
</author>
<author initials="J. F." surname="Reschke" fullname="Julian F. Reschke">
<organization abbrev="greenbytes">greenbytes GmbH</organization>
<address>
<postal>
<street>Hafenweg 16</street>
<city>Muenster</city><region>NW</region><code>48155</code>
<country>Germany</country>
</postal>
<email>julian.reschke@greenbytes.de</email>
<uri>http://greenbytes.de/tech/webdav/</uri>
</address>
</author>
<date year="2017" />
<area>Applications and Real-Time</area>
<abstract>
<t> When the 'out-of-band' content coding ('OOB') is used for delivering a number of resources from a primary server via a secondary server, the additional round trips for OOB responses and load on the primary server can be a significant nuisance.</t>
<t> In such situations, it is useful for the primary server to be able to provide the client with OOB response information for several resources in one go anticipating future client requests.
</t>
<t> This document describes a format for providing the client with the information, called a resource map, and how the resource map could be delivered to a client.
</t>
</abstract>
<note title="Editorial Note (To be removed by RFC Editor before publication)">
<t>
Distribution of this document is unlimited. Although this is not a work
item of the HTTPbis Working Group, comments should be sent to the
Hypertext Transfer Protocol (HTTP) mailing list at <eref target="mailto:ietf-http-wg@w3.org">ietf-http-wg@w3.org</eref>,
which may be joined by sending a message with subject
"subscribe" to <eref target="mailto:ietf-http-wg-request@w3.org?subject=subscribe">ietf-http-wg-request@w3.org</eref>.
</t>
<t>
Discussions of the HTTPbis Working Group are archived at
<eref target="http://lists.w3.org/Archives/Public/ietf-http-wg/"/>.
</t>
<t>
XML versions, latest edits, and issue tracking for this document
are available from <eref target="https://github.com/EricssonResearch/Blind-Cache-Drafts"/>.
</t>
<t>
The changes in this draft are summarized in <xref target="changes.since.00"/>.
</t>
</note>
</front>
<middle>
<section title="Introduction">
<t>
The mechanisms outlined in "An Architecture for Secure Content Delegation using HTTP" <xref target="SCD"/> and "Caching Secure HTTP Content using Blind Caches" <xref target="BC"/> use the 'out-of-band' content coding ('OOB') mechanism <xref target="OOBENC"/> to delegate the delivery of requested resource from a primary server to one or several secondary servers.
</t>
<t>
A primary server might decide to delegate the delivery of response payload for a set of resources, for instance individual video segments, or a set of images or parts of a large file.
</t>
<t>
In one approach the client sends individual requests for each of the resources to the primary server which provides the OOB content coding response information for the requested resources as meta data in each and every request to the primary server. This approach adds a minimum of one extra RTT (round trip time) for each request before the client can send the request to the desired secondary server.
</t>
<t>
In another approach the primary server anticipates a client's requests, for instance leveraging object dependency graph information, to provide the client with OOB content coding information for the subsequent requests in advance of requests.
</t>
<t>
This document describes a format for providing the client with the information for multipe OOB responses, called a resource map, and how the information is delivered to a client.
</t>
<!-- <section title="Abbreviations">
<t>
TBD
</t>
</section>-->
<section title="Notational Conventions" anchor="notational.conventions">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref target="RFC2119"/>.
</t>
</section>
</section>
<section title="Basic procedure for providing a Resource Map">
<t>A primary server creates a resource map containing information about how a set of resources on the origin it serves maps to a set of resource locations on one or multiple secondary servers.
</t>
<t>
<xref target="OOBENC"/> describes the basic procedure for providing the client with the OOB response meta data for an individual request, as examplified below:
</t>
<t>
Client request of a resource:
</t>
<figure><artwork type="message/http; msgtype="request"" x:indent-with=" ">
GET /test HTTP/1.1
Host: www.example.com
Accept-Encoding: gzip, out-of-band
</artwork></figure>
<t>
Response from primary server:
</t>
<figure><artwork type="message/http; msgtype="response"" x:indent-with=" ">
HTTP/1.1 200 OK
Date: Thu, 14 May 2015 18:52:00 GMT
Content-Type: text/plain
Cache-Control: max-age=10, public
Content-Encoding: out-of-band
Content-Length: <x:length-of target="exbody"/>
Vary: Accept-Encoding
<x:span anchor="exbody" x:lang="">{
"sr": [
{ "r" :
"http://example.net/bae27c36-fa6a-11e4-ae5d-00059a3c7a00"},
{ "r" :
"/c/bae27c36-fa6a-11e4-ae5d-00059a3c7a00"}
]
}
</x:span></artwork></figure>
<t>
A primary server can provide a Resource Map location in any response to a request for any resource using a Link header field <xref target="RFC5988"/> — this can
be an OOB response like the one above, but doesn't need to.
</t>
<figure><artwork type="example">
Link: </map>; rel="http://purl.org/linkrel/resource-map"
</artwork></figure>
<t>
Note that in this example, "/map" is a relative reference identifying the
resource map (relative to the request URI), and "http://purl.org/linkrel/resource-map" is the identifier for the link
relation "resource map".
</t>
<t>
A primary server can speculatively anticipate a client requesting a Resource Map and MAY use HTTP/2 <xref target="RFC7540"/> to push the response with the Resource Map to the client to decrease the extra delay a request for resource map otherwise would incur.
</t>
<t>
The basic operation for providing the client with a Resource Map is as follows:
</t>
<ol>
<li>Client requests resource from primary. Request includes Accept-Encoding header field including "out-of-band".</li>
<li>Primary server response includes Link header field identifying the resource map.</li>
<li>Client retrieves the resource map.</li>
<li>Resource Map becomes stale and will be retrieved again.</li>
</ol>
</section>
<section title="Updating the Resource Map">
<section title="Primary server need to update Resource Map">
<t>
Depending on the nature of the application and the resources, the primary server's need to provide the client with updates of the resource map information vary. In some cases there is no or little need for updates, in others there may be reasons for more frequent updates.
</t>
<t>
For instance, delegation information for static resources such as banners, images and script libraries for analytics might not change. In such a situation, the primary server does not need to stay in touch with the client to provide it with updates.
</t>
<t>
In another use case, the primary server provides the client with updates, for instance changing the secondary servers to be used by a mobile client.
</t>
<t>
Basically there are four approaches for a primary server to provide a client with updates to a resource map:
</t>
<ul>
<li>Piggyback signal about update on response to request from client</li>
<li>Client subscribes to Web Push updates</li>
<li>Client receives continuous updates</li>
<li>Resource Map validity time-out</li>
</ul>
</section>
<section title="Piggyback">
<t>
A primary server MAY add an Link header field to any response to a client. A client receiving a response with a Link header MUST retrieve the Resource Map web resource and process it.
</t>
</section>
<section title="Using Web Push">
<t>
A primary server MAY add an indication in the Resource Map to the client to use a notification service to receive updates to a Resource Map. When present a client SHOULD register for notifications.
</t>
<t>
A client receiving a Resource Map update notification MUST retrieve the Resource Map using the location information in the notification.
</t>
</section>
<section title="Continuous Updates">
<t>
In some situations, it is desirable to provide the client with a stream of Resource Map updates. Depending on the client type, either a secure bi-directional transport protocol is used, such as WebSocket, or the client is instructed to poll for changes.
</t>
<t>
A primary server MAY add an indication to the client to either poll or use a stream oriented protocol for receiving intermittent, frequent updates.
</t>
</section>
<section title="Resource Map Timer">
<t>
The freshness of a Resource Map can be given by the 'ma' timer. When expired, the OOB delegation is not valid and the client MUST request an update from the primary server
(this duplicates HTTP cache information, but might become important when the resource map is transmitted over a protocol other than HTTP).
</t>
</section>
<section title="Resource Map compression">
<section title="gzip">
<t>
A resource map might be large. For this reason a client can use compression content codings such as 'gzip' to decrease the size.
</t>
</section>
<section title="Formulas">
<t>
When using the resource map, the primary server could use a template or formula to optimize the size of the resource map information. For example, using URI templates <xref target="RFC6570"/>, and an agreed upon HMAC of the path postfix, it would be possible to specify a mapping for many URIs at once.
</t>
<t>
<figure><artwork type="example">
originURI =
"https://{origin}/images/{postfix}
mappedURI =
"https://cch.example.com/{origin}/images/{hmac-of-postfix}
</artwork></figure>
</t>
<t>
...would indicate a mapping for any https URI on "origin" below a root path of
"/images/", where the mapped URI would be constructed by concatenating
"https://cch.example.com/", the origin's host name, "/images/", and a base64- or hex-encoded opaque part, computed based on the remainder of the origin URI's path.
</t>
</section>
</section>
</section>
<section title="The Resource Map format">
<section title="Definitions">
<t>
A resource map will use and extend attributes outlined in <xref target="OOBENC"/> as well as additional extension attributes to be defined later.
</t>
<t>
The format of the resource map uses JavaScript Object Notation (JSON, <xref target="RFC7159"/>) describing a set of objects:
</t>
<ul>
<li>Objects for describing handling of updates of a resource map.</li>
<li>Objects for describing secondary servers and which resources that are mapped.</li>
<li>Objects for describing the resources on the secondary servers.</li>
</ul>
<figure>
<artwork type="example"><![CDATA[
{
"resource-map-updates" : {
//Information about resource map updates.
},
"secondary-servers" : {
//Information about secondary servers.
},
"resources" : [
//Information about resources on secondary servers.
]
}
]]></artwork></figure>
</section>
<section title="Updates for Resource Map">
<t>
<cref>Details to be done. Example below illustrates how this could be used.</cref>
</t>
<figure>
<artwork type="example"><![CDATA[
{
"resource-map-updates" : {
"max-age" : [ ],
"web push" : {
"notification service" : [ ] // URL
... // Other Web Push details
},
"online" : {
"poll" : {
"intervall" : [ ] //Poll
}
"connect" : [ ] // TODO: Relation to URL in Link <map>?
},
}
]]></artwork></figure>
</section>
<section title="Secondary Servers and Mapping of Resources">
<t>
<cref>Details to be done.</cref>
</t>
<!-- <figure><artwork type="example">
{
"secondary-servers" : {
...
},
"resources": [ ],
}
</artwork></figure>-->
</section>
</section>
<section title="Security Considerations">
<t>
All the considerations of <xref target="OOBENC"/> and <xref target="SCD"/> apply.
</t>
<t>
A resource map can be used to cause the client to request malicious content or perform DoS attacks on a victim secondary server. Clients MUST verify the identity of server providing the Resource Map.
</t>
<t>
In the case the resource map is delivered as a separate Web resource, the client MUST verify that the server providing the resource map belong to the same authority as the primary server.
</t>
<t>
The secondary server SHOULD take actions to detect and manage request loops caused by erroneous request from a client.
</t>
<t>
<cref>TODO: Using tokens for access control to secondary.</cref>
<cref>Issue: A resource map attribute that is applicable for a set of resources may open up for mixed attacker-controlled data and secrets.</cref>
</t>
</section>
<section title="IANA Considerations">
<t>
<cref anchor="media-type">
We will need a format definition of the media type and register
it; for now let's use "application/http-resource-map+json".
</cref>
</t>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor="RFC2119">
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials="S." surname="Bradner" fullname="Scott Bradner"/>
<date month="March" year="1997"/>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
</reference>
<reference anchor='RFC5988'>
<front>
<title>Web Linking</title>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'/>
<date year='2010' month='October' />
</front>
<seriesInfo name='RFC' value='5988'/>
</reference>
<reference anchor='RFC7159'>
<front>
<title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
<author initials='T.' surname='Bray' fullname='T. Bray'/>
<date year='2014' month='March' />
</front>
<seriesInfo name='RFC' value='7159' />
</reference>
<reference anchor='OOBENC'>
<front>
<title>'Out-Of-Band' Content Coding for HTTP</title>
<author initials='J' surname='Reschke' fullname='Julian F. Reschke'/>
<author initials='S' surname='Loreto' fullname='Salvatore Loreto'/>
<date month='March' year='2017'/>
</front>
<seriesInfo name="Internet-Draft" value="draft-reschke-http-oob-encoding-11"/>
</reference>
</references>
<references title="Informative References">
<reference anchor='RFC6570' target='http://www.rfc-editor.org/info/rfc6570'>
<front>
<title>URI Template</title>
<author initials='J.' surname='Gregorio' fullname='J. Gregorio'/>
<author initials='R.' surname='Fielding' fullname='R. Fielding'/>
<author initials='M.' surname='Hadley' fullname='M. Hadley'/>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'/>
<author initials='D.' surname='Orchard' fullname='D. Orchard'/>
<date year='2012' month='March' />
</front>
<seriesInfo name='RFC' value='6570'/>
</reference>
<reference anchor="RFC7540">
<front>
<title>Hypertext Transfer Protocol version 2</title>
<author initials="M." surname="Belshe" fullname="Mike Belshe"/>
<author initials="R." surname="Peon" fullname="Roberto Peon"/>
<author initials="M." surname="Thomson" fullname="Martin Thomson" role="editor"/>
<date month="May" year="2015"/>
</front>
<seriesInfo name="RFC" value="7540"/>
</reference>
<reference anchor="BC">
<front>
<title>Caching Secure HTTP Content using Blind Caches</title>
<author initials="M." surname="Thomson" fullname="Martin Thomson"/>
<author initials="G." surname="Eriksson" fullname="Goran Eriksson"/>
<author initials="C." surname="Holmberg" fullname="Christer Holmberg"/>
<date month="October" year="2016"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-thomson-http-bc-01"/>
</reference>
<reference anchor="SCD">
<front>
<title>
An Architecture for Secure Content Delegation using HTTP
</title>
<author initials="M." surname="Thomson" fullname="Martin Thomson"/>
<author initials="G." surname="Eriksson" fullname="Goran Eriksson"/>
<author initials="C." surname="Holmberg" fullname="Christer Holmberg"/>
<date month="October" year="2016"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-thomson-http-scd-02"/>
</reference>
</references>
<!--
<section title="Call Flows">
<section title="Client initiated cache priming">
</section>
</section>-->
<section title="Multiple Secondary Servers">
<t>
A primary server can provide multiple secondary servers for retrieving a resource or set of resources.
</t>
<t>
A Resource Map for the case when resources on "https://origin.example.com:8080" are mapped to two different secondary servers:
</t>
<figure><artwork type="example" x:lang="">
{
"secondary-servers": {
"server1": {
"name": "blind cache 1",
"address": "bc.example.com",
"protocol": "https",
"port": 8083,
"description": "Some text for debugging"
},
"server2": {
"name": "blind cache 2",
"address": "bc2.example.com",
"protocol": "https",
"port": 8082
}
},
"resources": [
{
"resource-origin": "/ex_jsl.js",
"mapped-path":
"/origin.example.com%3A8080/j39jl3jaac/29jfnf0f",
"attributes": {
"Content-Type": "application/javascript",
"Content-Encoding": "aesgcm",
"MI": ".....",
"Crypto-Key": "....."
},
"mapped": [
{
"server": "server1",
"attributes": {
"Max-Age": 1800
}
},
{
"server": "server2",
"attributes": {
"Max-Age": 1800
}
}
]
},
{
"resource-origin": "/another_resource.txt",
"mapped-path":
"/origin.example.com%3A8080/i39jfu2/1njknbs3",
"attributes": {
"Content-Type": "text/plain",
"Content-Encoding": "aesgcm",
"MI": ".....",
"Crypto-Key": "....."
},
"mapped": [
{
"server": "server2",
"attributes": {
"Max-Age": 1800
}
}
]
}
]
}</artwork></figure>
<t>
<cref>in the above example, why does resource-origin include scheme/host/port?</cref>
</t>
</section>
<section title="Change Log (To be removed before publication as RFC">
<section title="Since draft-eriksson-http-resource-map-00" anchor="changes.since.00">
<t>
Adjust link relation name.
</t>
<t>
Update references.
</t>
</section>
</section>
</back>
</rfc>