idnits 2.17.1 draft-ietf-httpbis-client-hints-02.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 (October 4, 2016) is 2761 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group I. Grigorik 3 Internet-Draft Google 4 Intended status: Experimental October 4, 2016 5 Expires: April 7, 2017 7 HTTP Client Hints 8 draft-ietf-httpbis-client-hints-02 10 Abstract 12 An increasing diversity of Web-connected devices and software 13 capabilities has created a need to deliver optimized content for each 14 device. 16 This specification defines a set of HTTP request header fields, 17 colloquially known as Client Hints, to address this. They are 18 intended to be used as input to proactive content negotiation; just 19 as the Accept header field allows clients to indicate what formats 20 they prefer, Client Hints allow clients to indicate a list of device 21 and agent specific preferences. 23 Note to Readers 25 Discussion of this draft takes place on the HTTP working group 26 mailing list (ietf-http-wg@w3.org), which is archived at 27 https://lists.w3.org/Archives/Public/ietf-http-wg/ . 29 Working Group information can be found at http://httpwg.github.io/ ; 30 source code and issues list for this draft can be found at 31 https://github.com/httpwg/http-extensions/labels/client-hints . 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on April 7, 2017. 50 Copyright Notice 52 Copyright (c) 2016 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 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 69 2. Client Hint Request Header Fields . . . . . . . . . . . . . . 4 70 2.1. Sending Client Hints . . . . . . . . . . . . . . . . . . 4 71 2.2. Server Processing of Client Hints . . . . . . . . . . . . 4 72 2.2.1. Advertising Support for Client Hints . . . . . . . . 4 73 2.2.2. Interaction with Caches . . . . . . . . . . . . . . . 5 74 3. The DPR Client Hint . . . . . . . . . . . . . . . . . . . . . 6 75 3.1. Confirming Selected DPR . . . . . . . . . . . . . . . . . 6 76 4. The Width Client Hint . . . . . . . . . . . . . . . . . . . . 7 77 5. The Viewport-Width Client Hint . . . . . . . . . . . . . . . 7 78 6. The Downlink Client Hint . . . . . . . . . . . . . . . . . . 7 79 7. The Save-Data Client Hint . . . . . . . . . . . . . . . . . . 8 80 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 81 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9 82 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 83 10.1. Accept-CH . . . . . . . . . . . . . . . . . . . . . . . 10 84 10.2. Content-DPR . . . . . . . . . . . . . . . . . . . . . . 10 85 10.3. Downlink . . . . . . . . . . . . . . . . . . . . . . . . 10 86 10.4. DPR . . . . . . . . . . . . . . . . . . . . . . . . . . 10 87 10.5. Save-Data . . . . . . . . . . . . . . . . . . . . . . . 10 88 10.6. Viewport-Width . . . . . . . . . . . . . . . . . . . . . 11 89 10.7. Width . . . . . . . . . . . . . . . . . . . . . . . . . 11 90 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 91 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 92 11.2. Informative References . . . . . . . . . . . . . . . . . 12 93 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 12 94 A.1. Since -00 . . . . . . . . . . . . . . . . . . . . . . . . 12 95 A.2. Since -01 . . . . . . . . . . . . . . . . . . . . . . . . 12 96 A.3. Since -02 . . . . . . . . . . . . . . . . . . . . . . . . 13 97 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 99 1. Introduction 101 There are thousands of different devices accessing the web, each with 102 different device capabilities and preference information. These 103 device capabilities include hardware and software characteristics, as 104 well as dynamic user and client preferences. 106 One way to infer some of these capabilities is through User-Agent 107 (UA; Section 5.5.3 of [RFC7231]) detection against an established 108 database of client signatures. However, this technique requires 109 acquiring such a database, integrating it into the serving path, and 110 keeping it up to date. However, even once this infrastructure is 111 deployed, UA sniffing has numerous limitations: 113 o UA detection cannot reliably identify all static variables 114 o UA detection cannot infer any dynamic client preferences 115 o UA detection requires an external device database 116 o UA detection is not cache friendly 118 A popular alternative strategy is to use HTTP cookies ([RFC6265]) to 119 communicate some information about the client. However, this 120 approach is also not cache friendly, bound by same origin policy, and 121 imposes additional client-side latency by requiring JavaScript 122 execution to create and manage HTTP cookies. 124 This document defines a set of new request header fields that allow 125 the client to perform proactive content negotiation (Section 3.4.1 of 126 [RFC7231]) by indicating a list of device and agent specific 127 preferences, through a mechanism similar to the Accept header field 128 which is used to indicate preferred response formats. 130 Client Hints does not supersede or replace the User-Agent header 131 field. Existing device detection mechanisms can continue to use both 132 mechanisms if necessary. By advertising its capabilities within a 133 request header field, Client Hints allows for cache friendly and 134 proactive content negotiation. 136 1.1. Notational Conventions 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 140 document are to be interpreted as described in [RFC2119]. 142 This document uses the Augmented Backus-Naur Form (ABNF) notation of 143 [RFC5234] with the list rule extension defined in [RFC7230], 144 Appendix B. It includes by reference the DIGIT rule from [RFC5234] 145 and the OWS and field-name rules from [RFC7230]. 147 2. Client Hint Request Header Fields 149 A Client Hint request header field is a HTTP header field that is 150 used by HTTP clients to indicate configuration data that can be used 151 by the server to select an appropriate response. Each one conveys a 152 list of client preferences that the server can use to adapt and 153 optimize the response. 155 2.1. Sending Client Hints 157 Clients control which Client Hint headers and their respective header 158 fields are communicated, based on their default settings, user 159 configuration and/or preferences. The user can be given the choice 160 to enable, disable, or override specific hints. 162 The client and server, or an intermediate proxy, can use an opt-in 163 mechanism to negotiate which fields should be reported to allow for 164 efficient content adaption. 166 2.2. Server Processing of Client Hints 168 Servers respond with an optimized response based on one or more 169 received hints from the client. When doing so, and if the resource 170 is cacheable, the server MUST also emit a Vary response header field 171 (Section 7.1.4 of [RFC7231]), and optionally Key 172 ([I-D.ietf-httpbis-key]), to indicate which hints can affect the 173 selected response and whether the selected response is appropriate 174 for a later request. 176 Further, depending on the used hint, the server can emit additional 177 response header fields to confirm the property of the response, such 178 that the client can adjust its processing. For example, this 179 specification defines "Content-DPR" response header field that needs 180 to be returned by the server when the "DPR" hint is used to select 181 the response. 183 2.2.1. Advertising Support for Client Hints 185 Servers can advertise support for Client Hints using the Accept-CH 186 header field or an equivalent HTML meta element with http-equiv 187 attribute ([W3C.REC-html5-20141028]). 189 Accept-CH = #field-name 191 For example: 193 Accept-CH: DPR, Width, Viewport-Width, Downlink 195 When a client receives Accept-CH, or if it is capable of processing 196 the HTML response and finds an equivalent HTML meta element, it 197 SHOULD append the Client-Hint header fields that match the advertised 198 field-values to the header list of all subsequent requests. For 199 example, based on Accept-CH example above, a user agent could append 200 DPR, Width, Viewport-Width, and Downlink header fields to all 201 subresource requests initiated by the page constructed from the 202 response. Alternatively, a client can treat advertised support as a 203 persistent origin preference and append same header fields on all 204 future requests initiated to and by the resources associated with 205 that origin. 207 2.2.2. Interaction with Caches 209 When selecting an optimized response based on one or more Client 210 Hints, and if the resource is cacheable, the server needs to emit a 211 Vary response header field ([RFC7234]) to indicate which hints can 212 affect the selected response and whether the selected response is 213 appropriate for a later request. 215 Vary: DPR 217 Above example indicates that the cache key needs to include the DPR 218 header field. 220 Vary: DPR, Width, Downlink 222 Above example indicates that the cache key needs to include the DPR, 223 Width, and Downlink header fields. 225 Client Hints MAY be combined with Key ([I-D.ietf-httpbis-key]) to 226 enable fine-grained control of the cache key for improved cache 227 efficiency. For example, the server can return the following set of 228 instructions: 230 Key: DPR;partition=1.5:2.5:4.0 232 Above example indicates that the cache key needs to include the value 233 of the DPR header field with three segments: less than 1.5, 1.5 to 234 less than 2.5, and 4.0 or greater. 236 Key: Width;div=320 238 Above example indicates that the cache key needs to include the value 239 of the Width header field and be partitioned into groups of 320: 240 0-320, 320-640, and so on. 242 Key: Downlink;partition=0.5:1.0:3.0:5.0:10 244 Above example indicates that the cache key needs to include the 245 (Mbps) value of the Downlink header field with six segments: less 246 than 0.5, 0.5 to less than 1.0, 1.0 to less than 3.0, 3.0 to less 247 than 5.0, 5.0 to less than 10; 10 or higher. 249 3. The DPR Client Hint 251 The "DPR" request header field is a number that indicates the 252 client's current Device Pixel Ratio (DPR), which is the ratio of 253 physical pixels over CSS px (Section 5.2 of 254 [W3C.CR-css-values-3-20150611]) of the layout viewport (Section 9.1.1 255 of [CSS2]) on the device. 257 DPR = 1*DIGIT [ "." 1*DIGIT ] 259 If DPR occurs in a message more than once, the last value overrides 260 all previous occurrences. 262 3.1. Confirming Selected DPR 264 The "Content-DPR" response header field is a number that indicates 265 the ratio between physical pixels over CSS px of the selected image 266 response. 268 Content-DPR = 1*DIGIT [ "." 1*DIGIT ] 270 DPR ratio affects the calculation of intrinsic size of image 271 resources on the client - i.e. typically, the client automatically 272 scales the natural size of the image by the DPR ratio to derive its 273 display dimensions. As a result, the server MUST explicitly indicate 274 the DPR of the selected image response whenever the DPR hint is used, 275 and the client MUST use the DPR value returned by the server to 276 perform its calculations. In case the server returned Content-DPR 277 value contradicts previous client-side DPR indication, the server 278 returned value MUST take precedence. 280 Note that DPR confirmation is only required for image responses, and 281 the server does not need to confirm the resource width as this value 282 can be derived from the resource itself once it is decoded by the 283 client. 285 If Content-DPR occurs in a message more than once, the last value 286 overrides all previous occurrences. 288 4. The Width Client Hint 290 The "Width" request header field is a number that indicates the 291 desired resource width in physical px (i.e. intrinsic size of an 292 image). The provided physical px value is a number rounded to the 293 smallest following integer (i.e. ceiling value). 295 Width = 1*DIGIT 297 If the desired resource width is not known at the time of the request 298 or the resource does not have a display width, the Width header field 299 can be omitted. If Width occurs in a message more than once, the 300 last value overrides all previous occurrences. 302 5. The Viewport-Width Client Hint 304 The "Viewport-Width" request header field is a number that indicates 305 the layout viewport width in CSS px. The provided CSS px value is a 306 number rounded to the smallest following integer (i.e. ceiling 307 value). 309 Viewport-Width = 1*DIGIT 311 If Viewport-Width occurs in a message more than once, the last value 312 overrides all previous occurrences. 314 6. The Downlink Client Hint 316 The "Downlink" request header field is a number that indicates the 317 client's maximum downlink speed in megabits per second (Mbps), as 318 defined by the "downlinkMax" attribute in the W3C Network Information 319 API ([NETINFO]). 321 Downlink = 1*DIGIT [ "." 1*DIGIT ] 323 If Downlink occurs in a message more than once, the minimum value 324 should be used to override other occurrences. 326 7. The Save-Data Client Hint 328 The "Save-Data" request header field consists of one or more tokens 329 that indicate client's preference for reduced data usage, due to high 330 transfer costs, slow connection speeds, or other reasons. 332 Save-Data = sd-token *( OWS ";" OWS [sd-token] ) 333 sd-token = token 335 This document defines the "on" sd-token value, which is used as a 336 signal indicating explicit user opt-in into a reduced data usage mode 337 on the client, and when communicated to origins allows them to 338 deliver alternate content honoring such preference - e.g. smaller 339 image and video resources, alternate markup, and so on. New token 340 and extension token values can only be defined by revisions of this 341 specification. 343 8. Examples 345 For example, given the following request header fields: 347 DPR: 2.0 348 Width: 320 349 Viewport-Width: 320 351 The server knows that the device pixel ratio is 2.0, that the 352 intended display width of the requested resource is 160 CSS px (320 353 physical pixels at 2x resolution), and that the viewport width is 320 354 CSS px. 356 If the server uses above hints to perform resource selection for an 357 image asset, it must confirm its selection via the Content-DPR 358 response header to allow the client to calculate the appropriate 359 intrinsic size of the image response. The server does not need to 360 confirm resource width, only the ratio between physical pixels and 361 CSS px of the selected image resource: 363 Content-DPR: 1.0 365 The Content-DPR response header field indicates to the client that 366 the server has selected resource with DPR ratio of 1.0. The client 367 can use this information to perform additional processing on the 368 resource - for example, calculate the appropriate intrinsic size of 369 the image resource such that it is displayed at the correct 370 resolution. 372 Alternatively, the server could select an alternate resource based on 373 the maximum downlink speed advertised in the request header fields: 375 Downlink: 0.384 377 The server knows that the client's maximum downlink speed is 378 0.384Mbps (GPRS EDGE), and it can use this information to select an 379 optimized resource - for example, an alternate image asset, 380 stylesheet, HTML document, media stream, and so on. 382 9. Security Considerations 384 Client Hints defined in this specification do not expose new 385 information about the user's environment beyond what is already 386 available to, and can be communicated by, the application at runtime 387 via JavaScript and CSS. For example, the application can obtain 388 viewport width, image display width, and device pixel ratio via 389 JavaScript, or through the use of CSS media queries and unique 390 resource URLs even if JavaScript is disabled. However, implementors 391 should consider the privacy implications of various methods to enable 392 delivery of Client Hints - see "Sending Client Hints" section. 394 For example, sending Client Hints on all requests can make 395 information about the user's environment available to origins that 396 otherwise did not have access to this data, which may or may not be 397 the desired outcome - e.g. this may enable an image optimization 398 service to deliver a tailored asset, and it may reveal same 399 information about the user to other origins that may not have had 400 access to it before. Similarly, sending highly granular data, such 401 as image and viewport width may help identify users across multiple 402 requests. Restricting such field values to an enumerated range, 403 where the user agent advertises a threshold value that is close but 404 is not an exact representation of the current value, might reduce 405 such fingerprinting risks. 407 The implementers can provide mechanisms and policies to control how 408 and when such hints are advertised: require origin opt-in and 409 restrict delivery to same origin subrequests; limit delivery to 410 requests that already carry indentifying information (e.g. cookies); 411 modify delivery policy when in an "incognito" or a similar privacy 412 mode; enable user configuration and opt in, and so on. 414 10. IANA Considerations 416 This document defines the "Accept-CH", "DPR", "Width", and "Downlink" 417 HTTP request fields, "Content-DPR" HTTP response field, and registers 418 them in the Permanent Message Header Fields registry. 420 10.1. Accept-CH 422 o Header field name: Accept-CH 423 o Applicable protocol: HTTP 424 o Status: standard 425 o Author/Change controller: IETF 426 o Specification document(s): Section 2.2.1 427 o Related information: for Client Hints 429 10.2. Content-DPR 431 o Header field name: Content-DPR 432 o Applicable protocol: HTTP 433 o Status: standard 434 o Author/Change controller: IETF 435 o Specification document(s): Section 3.1 of this document 436 o Related information: for Client Hints 438 10.3. Downlink 440 o Header field name: Downlink 441 o Applicable protocol: HTTP 442 o Status: standard 443 o Author/Change controller: IETF 444 o Specification document(s): Section 6 of this document 445 o Related information: for Client Hints 447 10.4. DPR 449 o Header field name: DPR 450 o Applicable protocol: HTTP 451 o Status: standard 452 o Author/Change controller: IETF 453 o Specification document(s): Section 3 of this document 454 o Related information: for Client Hints 456 10.5. Save-Data 458 o Header field name: Save-Data 459 o Applicable protocol: HTTP 460 o Status: standard 461 o Author/Change controller: IETF 462 o Specification document(s): Section 7 of this document 463 o Related information: for Client Hints 465 10.6. Viewport-Width 467 o Header field name: Viewport-Width 468 o Applicable protocol: HTTP 469 o Status: standard 470 o Author/Change controller: IETF 471 o Specification document(s): Section 5 of this document 472 o Related information: for Client Hints 474 10.7. Width 476 o Header field name: Width 477 o Applicable protocol: HTTP 478 o Status: standard 479 o Author/Change controller: IETF 480 o Specification document(s): Section 4 of this document 481 o Related information: for Client Hints 483 11. References 485 11.1. Normative References 487 [CSS2] Bos, B., Celic, T., Hickson, I., and H. Lie, "Cascading 488 Style Sheets Level 2 Revision 1 (CSS 2.1) Specification", 489 W3C Recommendation REC-CSS2-20110607, June 2011, 490 . 492 [NETINFO] Caceres, M., Moreno, F., and I. Grigorik, "Network 493 Information API", December 2015, . 496 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 497 Requirement Levels", BCP 14, RFC 2119, 498 DOI 10.17487/RFC2119, March 1997, 499 . 501 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 502 Specifications: ABNF", STD 68, RFC 5234, 503 DOI 10.17487/RFC5234, January 2008, 504 . 506 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 507 Protocol (HTTP/1.1): Message Syntax and Routing", 508 RFC 7230, DOI 10.17487/RFC7230, June 2014, 509 . 511 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 512 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 513 DOI 10.17487/RFC7231, June 2014, 514 . 516 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 517 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 518 RFC 7234, DOI 10.17487/RFC7234, June 2014, 519 . 521 [W3C.CR-css-values-3-20150611] 522 Atkins, T. and E. Etemad, "CSS Values and Units Module 523 Level 3", World Wide Web Consortium CR CR-css-values- 524 3-20150611, June 2015, 525 . 527 [W3C.REC-html5-20141028] 528 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 529 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 530 World Wide Web Consortium Recommendation REC- 531 html5-20141028, October 2014, 532 . 534 11.2. Informative References 536 [I-D.ietf-httpbis-key] 537 Fielding, R. and M. Nottingham, "The Key HTTP Response 538 Header Field", draft-ietf-httpbis-key-01 (work in 539 progress), March 2016. 541 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 542 DOI 10.17487/RFC6265, April 2011, 543 . 545 Appendix A. Changes 547 A.1. Since -00 549 o Issue 168 (make Save-Data extensible) updated ABNF. 550 o Issue 163 (CH review feedback) editorial feedback from httpwg 551 list. 552 o Issue 153 (NetInfo API citation) added normative reference. 554 A.2. Since -01 556 o Issue 200: Moved Key reference to informative. 557 o Issue 215: Extended passive fingerprinting and mitigation 558 considerations. 560 o Changed document status to experimental. 562 A.3. Since -02 564 None yet. 566 Author's Address 568 Ilya Grigorik 569 Google 571 Email: ilya@igvita.com 572 URI: https://www.igvita.com/