2004/id/draft-cohen-http-305-306-responses-00.txt



HTTP Working Group                                            Josh Cohen
Internet-Draft                             Netscape Communications Corp.
                                                         5 December 1996

                  HTTP/1.1 305 and 306 Response Codes

                    <draft-cohen-http-305-306-responses-00.txt>

Status of this Memo

   This document is an Internet-Draft.  Internet-Drafts are working
   documents of the Internet Engineering Task Force (IETF), its areas,
   and its working groups.  Note that other groups may also distribute
   working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet- Drafts as reference
   material or to cite them other than as ``work in progress.''

   To learn the current status of any Internet-Draft, please check the
   ``1id-abstracts.txt'' listing contained in the Internet- Drafts
   Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
   munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
   ftp.isi.edu (US West Coast).

Abstract

   The HTTP/1.1 RFC specifies a response code '305 Use Proxy' which is
   intended to cause a client to retry the request using a specified
   proxy server.  This functionality is important, but underspecified in
   the current spec.  The spec does not specify for how long or which
   URLs the redirect applies to, or how proxies can deal with or
   generate similar responses.  This draft proposes a specification for
   both the 305 response and a new response, "306 Switch Proxy".


J. Cohen          HTTP/1.1 305 and 306 Response Codes           [Page 1]


INTERNET-DRAFT                                           5 December 1996


Summary

 1.0 Response Codes

  1.1 305 Use Proxy
  1.2 306 Switch Proxy
  1.3 506 Redirection Failed

 2.0 Headers

  2.1 Set-proxy:
  2.2 Location:

 3.0 Methods

  3.1 OPTIONS

 4.0 Operational Constraints

 5.0 Notes


1.0 Response Codes

 1.1 305 Use Proxy

   The 305 is generated by an origin server to indicate that the client,
   or proxy, should use a proxy to access the requested resource.

   The request SHOULD be accompanied by a 'Set-proxy' response header
   indicating what proxy is to be used. The client will parse the 'Set-
   proxy' header as defined below to decide how long, for what URLs it
   should use the specified proxy.

   If the 305 response is not accompanied by a 'Set-proxy' header, it
   MUST be accompanied by a 'Location' header.  The 'Location' header
   will specify a URL to the proxy.

   If both headers are present in the response, the client SHOULD use
   the 'Set-proxy' header only.

 1.2 306 Switch Proxy

   The 306 response is generated by a proxy server to indicate that the
   client or proxy should use the information in the accompanying 'Set-
   proxy' header to choose a proxy for subsequent requests.

   The 306 response code MUST be accompanied by the 'Set-proxy' response


J. Cohen          HTTP/1.1 305 and 306 Response Codes           [Page 2]


INTERNET-DRAFT                                           5 December 1996


   header.  The client or proxy will parse the 'Set-proxy' header to
   determine which proxy to use, how long to use it, and for which URLs
   to use it.

 1.3 506 Redirection Failed

   The 506 response is returned when a redirection fails or is refused
   by a proxy or client.  If the redirection response included a body,
   then it SHOULD be included in the 506 response.

2.0 Headers

 2.1 'Set-proxy' Response Header

           The 'Set-proxy' header is defined as:

           Set-proxy: "Set-proxy" ":" 1(
                   action #(parameters)
                   )

           parameters = #( ( "scope" "=" scopePattern ) |
                   ( proxyURI "=" URI ) |
                   lifetime )

           lifetime = ( "seconds"  "=" integer )
                   | ( "hits"      "=" integer )

           action =  ( "DIRECT"
                   | "IPL"
                   | "SET" )
                   ) ";"

           scopePattern = "*" | "-" | URIpattern

   An example header:
       Set-proxy: SET ; proxyURI = "http://proxy.me.com:8080/",
           scope="http://", seconds=5

 action

   The first item, "action" specifies the type or mode of the change.
   Possible modes are:


   DIRECT
    Attempt to connect directly, with no proxy


J. Cohen          HTTP/1.1 305 and 306 Response Codes           [Page 3]


INTERNET-DRAFT                                           5 December 1996


   IPL
    Initial Program Load, the client or proxy should attempt to revert
    back to its default or initial proxy setting.  This is meant to
    instruct a client to re-fetch its proxy configuration, or PAC file.
    When set, the accompanying scope field MUST be "*" A client receiv-
    ing this response SHOULD prompt the user for confirmation.


    If accompanied by a 'proxyURI' parameter, a proxy or client MAY use
    the value as a URL containing a configuration to retrieve.  If a
    client  does so, it MUST prompt the user for confirmation.


   SET
    Set to parameter "proxyURI".  The client should use the URL speci-
    fied for "proxyURI" as the proxy.  If the SET mode is specified, the
    parameter, "proxyURI", MUST be present.

 Scope

    Scope refers to a URI prefix pattern that specifies which URIs are
    subject to this header setting.  URIs should be matched against the
    scope with this rule :

     The scope "*" means all requests
     The scope "-" means this EXACT URL ONLY

    Otherwise, the URL is compared with the scope after it is:


   *   truncated to the length of the scope


   *   domain names are set in reverse order.

     For example:

       scope = "http://com.foo.www/services/"

       URL "http://www.foo.com/services/express/2day.html"
       transformed: "http://com.foo.www/services/express/" (MATCH)

     Another example:

       scope = "http://com.ups/"      URL "http://www.ups.com/"  (MATCH)
       URL "http://www.fedex.com/" (FAIL)


J. Cohen          HTTP/1.1 305 and 306 Response Codes           [Page 4]


INTERNET-DRAFT                                           5 December 1996


     The lifetime parameter specifies how long the specified proxy
     should be used.  If lifetime is specified as "seconds" then the
     proxy setting remains in effect for 'integer' seconds.  If lifetime
     is specified in 'hits' then the proxy setting remains in effect for
     'integer' transactions.

 2.2 Location Header


     In the original HTTP/1.1 spec, the 'Location' header was used to
     indicate the proxy setting.  Its use is DEPRECATED by the 'Set-
     proxy' header in the context of a 305 response. All new implementa-
     tions MUST send the Set-proxy header.  Implementations MAY send the
     'Location' header so as to allow backward compatibility.


     If the 'Location' header is specified, it should contain a URI of
     the proxy.  If the Set-proxy header is not specified, the client
     should use this proxy for just one request, and only for the origi-
     nally requested exact URL.

 3.0 Methods


     A client or proxy receiving a 305 or 306, should use the OPTIONS
     method to determine if the server or proxy it is talking to actu-
     ally is an HTTP/1.1 server supporting 305 and 306 responses.


J. Cohen          HTTP/1.1 305 and 306 Response Codes           [Page 5]


INTERNET-DRAFT                                           5 December 1996


4.0 Operational Constraints


   * Both the 305 and 306 response codes are HOP by HOP.  A proxy server
     MUST not forward a 305 or 306 respose code (unless it generated the
     306).


   * A webserver MUST NOT send a 306 response under any circumstances


   * A proxy server MUST NOT generate a 305 response.


   * A client or proxy SHOULD NOT accept a 306 from a proxy that it
     learned of via a 305 response code.


   * A client or proxy MAY maintain state and allow a lifetime to extend
     beyond a session or restart.


   * A 'Set-proxy: IPL' SHOULD override any previous 'Set-proxy' header.


   * A 305 or 306 response MAY contain a body containing an explanation
     of the redirect for clients which do not understand the redirect


   * In the absence of any parameter, the following defaults should be
     used:

       lifetime = this transaction only
       scope = this exact URL only


   * When receiving a 305 response, the client or proxy will enforce the
     following rule with respect to the scope.

     The scope specified must be more restrictive than the transformed
     URL in question.

     Example: (in order of restrictiveness)

       http://com.ups.www/services/express/1day.html ( most restrictive)
             http://com.ups.www/ (all requests for only www.ups.com )
             http://com.ups ( all requests for ups.com )
             http://  ( for all http requests )


J. Cohen          HTTP/1.1 305 and 306 Response Codes           [Page 6]


INTERNET-DRAFT                                           5 December 1996


       *  ( all requests )

     If the scope returned with a 305 response is less restrictive than
     the requested URL, the client MUST prompt the user for confirmation
     before accepting the new proxy setting.


   * Since HTTP/1.0 proxies may unknowingly forward a 305 or 306
     response code that was generated maliciously or in good faith, the
     client must attempt to ascertain if the proxy with which it is
     directly communicating is HTTP/1.1 and if it supports the 'Set-
     proxy' header.  To determine this, the client or proxy should use
     the OPTIONS method to make a request check for this feature.


Security Considerations

     Great care should be taken when implementing client side actions
     based on the 305 or 306.  Since older proxies may unknowingly for-
     ward either of these reponses, clients should be prepared to check
     the validity.


   * Please read the section 'Operational Constraints'


   * A client or proxy MUST NOT accept a 305 response from a proxy.


   * A client or proxy MUST NOT accept a 306 response from an origin
     server.


   * When receiving a 306 response from a proxy, the client MUST verify
     that the proxy supports the 306 response with a METHODS request.

5.0 Notes

     Further specification is needed to define exactly how to use
     METHODs, or another mechanism to determin if set-proxy is sup-
     ported.

Author's Address

     Josh Cohen
     Netscape Communications Corporation
     501 E. Middlefield Rd
     Mountain View, CA 94043


J. Cohen          HTTP/1.1 305 and 306 Response Codes           [Page 7]


INTERNET-DRAFT                                           5 December 1996


     Phone (415) 937-4157
     EMail: josh@netscape.com


J. Cohen          HTTP/1.1 305 and 306 Response Codes           [Page 8]


1	wakaba	1.1
2
3
4
5
6
7			HTTP Working Group Josh Cohen
8			Internet-Draft Netscape Communications Corp.
9			5 December 1996
10
11			HTTP/1.1 305 and 306 Response Codes
12
13			<draft-cohen-http-305-306-responses-00.txt>
14
15			Status of this Memo
16
17			This document is an Internet-Draft. Internet-Drafts are working
18			documents of the Internet Engineering Task Force (IETF), its areas,
19			and its working groups. Note that other groups may also distribute
20			working documents as Internet-Drafts.
21
22			Internet-Drafts are draft documents valid for a maximum of six months
23			and may be updated, replaced, or obsoleted by other documents at any
24			time. It is inappropriate to use Internet- Drafts as reference
25			material or to cite them other than as ``work in progress.''
26
27			To learn the current status of any Internet-Draft, please check the
28			``1id-abstracts.txt'' listing contained in the Internet- Drafts
29			Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
30			munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
31			ftp.isi.edu (US West Coast).
32
33			Abstract
34
35			The HTTP/1.1 RFC specifies a response code '305 Use Proxy' which is
36			intended to cause a client to retry the request using a specified
37			proxy server. This functionality is important, but underspecified in
38			the current spec. The spec does not specify for how long or which
39			URLs the redirect applies to, or how proxies can deal with or
40			generate similar responses. This draft proposes a specification for
41			both the 305 response and a new response, "306 Switch Proxy".
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58			J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 1]
59
60
61
62
63
64			INTERNET-DRAFT 5 December 1996
65
66
67			Summary
68
69			1.0 Response Codes
70
71			1.1 305 Use Proxy
72			1.2 306 Switch Proxy
73			1.3 506 Redirection Failed
74
75			2.0 Headers
76
77			2.1 Set-proxy:
78			2.2 Location:
79
80			3.0 Methods
81
82			3.1 OPTIONS
83
84			4.0 Operational Constraints
85
86			5.0 Notes
87
88
89			1.0 Response Codes
90
91			1.1 305 Use Proxy
92
93			The 305 is generated by an origin server to indicate that the client,
94			or proxy, should use a proxy to access the requested resource.
95
96			The request SHOULD be accompanied by a 'Set-proxy' response header
97			indicating what proxy is to be used. The client will parse the 'Set-
98			proxy' header as defined below to decide how long, for what URLs it
99			should use the specified proxy.
100
101			If the 305 response is not accompanied by a 'Set-proxy' header, it
102			MUST be accompanied by a 'Location' header. The 'Location' header
103			will specify a URL to the proxy.
104
105			If both headers are present in the response, the client SHOULD use
106			the 'Set-proxy' header only.
107
108			1.2 306 Switch Proxy
109
110			The 306 response is generated by a proxy server to indicate that the
111			client or proxy should use the information in the accompanying 'Set-
112			proxy' header to choose a proxy for subsequent requests.
113
114			The 306 response code MUST be accompanied by the 'Set-proxy' response
115
116
117
118			J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 2]
119
120
121
122
123
124			INTERNET-DRAFT 5 December 1996
125
126
127			header. The client or proxy will parse the 'Set-proxy' header to
128			determine which proxy to use, how long to use it, and for which URLs
129			to use it.
130
131			1.3 506 Redirection Failed
132
133			The 506 response is returned when a redirection fails or is refused
134			by a proxy or client. If the redirection response included a body,
135			then it SHOULD be included in the 506 response.
136
137			2.0 Headers
138
139			2.1 'Set-proxy' Response Header
140
141			The 'Set-proxy' header is defined as:
142
143			Set-proxy: "Set-proxy" ":" 1(
144			action #(parameters)
145			)
146
147			parameters = #( ( "scope" "=" scopePattern ) \|
148			( proxyURI "=" URI ) \|
149			lifetime )
150
151			lifetime = ( "seconds" "=" integer )
152			\| ( "hits" "=" integer )
153
154			action = ( "DIRECT"
155			\| "IPL"
156			\| "SET" )
157			) ";"
158
159			scopePattern = "*" \| "-" \| URIpattern
160
161			An example header:
162			Set-proxy: SET ; proxyURI = "http://proxy.me.com:8080/",
163			scope="http://", seconds=5
164
165			action
166
167			The first item, "action" specifies the type or mode of the change.
168			Possible modes are:
169
170
171			DIRECT
172			Attempt to connect directly, with no proxy
173
174
175
176
177
178			J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 3]
179
180
181
182
183
184			INTERNET-DRAFT 5 December 1996
185
186
187			IPL
188			Initial Program Load, the client or proxy should attempt to revert
189			back to its default or initial proxy setting. This is meant to
190			instruct a client to re-fetch its proxy configuration, or PAC file.
191			When set, the accompanying scope field MUST be "*" A client receiv-
192			ing this response SHOULD prompt the user for confirmation.
193
194
195			If accompanied by a 'proxyURI' parameter, a proxy or client MAY use
196			the value as a URL containing a configuration to retrieve. If a
197			client does so, it MUST prompt the user for confirmation.
198
199
200			SET
201			Set to parameter "proxyURI". The client should use the URL speci-
202			fied for "proxyURI" as the proxy. If the SET mode is specified, the
203			parameter, "proxyURI", MUST be present.
204
205			Scope
206
207			Scope refers to a URI prefix pattern that specifies which URIs are
208			subject to this header setting. URIs should be matched against the
209			scope with this rule :
210
211			The scope "*" means all requests
212			The scope "-" means this EXACT URL ONLY
213
214			Otherwise, the URL is compared with the scope after it is:
215
216
217			* truncated to the length of the scope
218
219
220			* domain names are set in reverse order.
221
222			For example:
223
224			scope = "http://com.foo.www/services/"
225
226			URL "http://www.foo.com/services/express/2day.html"
227			transformed: "http://com.foo.www/services/express/" (MATCH)
228
229			Another example:
230
231			scope = "http://com.ups/" URL "http://www.ups.com/" (MATCH)
232			URL "http://www.fedex.com/" (FAIL)
233
234
235
236
237
238			J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 4]
239
240
241
242
243
244			INTERNET-DRAFT 5 December 1996
245
246
247			The lifetime parameter specifies how long the specified proxy
248			should be used. If lifetime is specified as "seconds" then the
249			proxy setting remains in effect for 'integer' seconds. If lifetime
250			is specified in 'hits' then the proxy setting remains in effect for
251			'integer' transactions.
252
253			2.2 Location Header
254
255
256			In the original HTTP/1.1 spec, the 'Location' header was used to
257			indicate the proxy setting. Its use is DEPRECATED by the 'Set-
258			proxy' header in the context of a 305 response. All new implementa-
259			tions MUST send the Set-proxy header. Implementations MAY send the
260			'Location' header so as to allow backward compatibility.
261
262
263			If the 'Location' header is specified, it should contain a URI of
264			the proxy. If the Set-proxy header is not specified, the client
265			should use this proxy for just one request, and only for the origi-
266			nally requested exact URL.
267
268			3.0 Methods
269
270
271			A client or proxy receiving a 305 or 306, should use the OPTIONS
272			method to determine if the server or proxy it is talking to actu-
273			ally is an HTTP/1.1 server supporting 305 and 306 responses.
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			J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 5]
299
300
301
302
303
304			INTERNET-DRAFT 5 December 1996
305
306
307			4.0 Operational Constraints
308
309
310			* Both the 305 and 306 response codes are HOP by HOP. A proxy server
311			MUST not forward a 305 or 306 respose code (unless it generated the
312			306).
313
314
315			* A webserver MUST NOT send a 306 response under any circumstances
316
317
318			* A proxy server MUST NOT generate a 305 response.
319
320
321			* A client or proxy SHOULD NOT accept a 306 from a proxy that it
322			learned of via a 305 response code.
323
324
325			* A client or proxy MAY maintain state and allow a lifetime to extend
326			beyond a session or restart.
327
328
329			* A 'Set-proxy: IPL' SHOULD override any previous 'Set-proxy' header.
330
331
332			* A 305 or 306 response MAY contain a body containing an explanation
333			of the redirect for clients which do not understand the redirect
334
335
336			* In the absence of any parameter, the following defaults should be
337			used:
338
339			lifetime = this transaction only
340			scope = this exact URL only
341
342
343			* When receiving a 305 response, the client or proxy will enforce the
344			following rule with respect to the scope.
345
346			The scope specified must be more restrictive than the transformed
347			URL in question.
348
349			Example: (in order of restrictiveness)
350
351			http://com.ups.www/services/express/1day.html ( most restrictive)
352			http://com.ups.www/ (all requests for only www.ups.com )
353			http://com.ups ( all requests for ups.com )
354			http:// ( for all http requests )
355
356
357
358			J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 6]
359
360
361
362
363
364			INTERNET-DRAFT 5 December 1996
365
366
367			* ( all requests )
368
369			If the scope returned with a 305 response is less restrictive than
370			the requested URL, the client MUST prompt the user for confirmation
371			before accepting the new proxy setting.
372
373
374			* Since HTTP/1.0 proxies may unknowingly forward a 305 or 306
375			response code that was generated maliciously or in good faith, the
376			client must attempt to ascertain if the proxy with which it is
377			directly communicating is HTTP/1.1 and if it supports the 'Set-
378			proxy' header. To determine this, the client or proxy should use
379			the OPTIONS method to make a request check for this feature.
380
381
382			Security Considerations
383
384			Great care should be taken when implementing client side actions
385			based on the 305 or 306. Since older proxies may unknowingly for-
386			ward either of these reponses, clients should be prepared to check
387			the validity.
388
389
390			* Please read the section 'Operational Constraints'
391
392
393			* A client or proxy MUST NOT accept a 305 response from a proxy.
394
395
396			* A client or proxy MUST NOT accept a 306 response from an origin
397			server.
398
399
400			* When receiving a 306 response from a proxy, the client MUST verify
401			that the proxy supports the 306 response with a METHODS request.
402
403			5.0 Notes
404
405			Further specification is needed to define exactly how to use
406			METHODs, or another mechanism to determin if set-proxy is sup-
407			ported.
408
409			Author's Address
410
411			Josh Cohen
412			Netscape Communications Corporation
413			501 E. Middlefield Rd
414			Mountain View, CA 94043
415
416
417
418			J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 7]
419
420
421
422
423
424			INTERNET-DRAFT 5 December 1996
425
426
427			Phone (415) 937-4157
428			EMail: josh@netscape.com
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			J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 8]
479
480