idnits 2.17.1 draft-ietf-httpbis-client-hints-03.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 (December 2, 2016) is 2702 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 December 2, 2016 5 Expires: June 5, 2017 7 HTTP Client Hints 8 draft-ietf-httpbis-client-hints-03 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 June 5, 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 . . . . . . . . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . . . . . . . 13 96 A.3. Since -02 . . . . . . . . . . . . . . . . . . . . . . . . 13 97 A.4. Since -03 . . . . . . . . . . . . . . . . . . . . . . . . 13 99 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 101 1. Introduction 103 There are thousands of different devices accessing the web, each with 104 different device capabilities and preference information. These 105 device capabilities include hardware and software characteristics, as 106 well as dynamic user and client preferences. 108 One way to infer some of these capabilities is through User-Agent 109 (UA; Section 5.5.3 of [RFC7231]) detection against an established 110 database of client signatures. However, this technique requires 111 acquiring such a database, integrating it into the serving path, and 112 keeping it up to date. However, even once this infrastructure is 113 deployed, UA sniffing has numerous limitations: 115 o UA detection cannot reliably identify all static variables 116 o UA detection cannot infer any dynamic client preferences 117 o UA detection requires an external device database 118 o UA detection is not cache friendly 120 A popular alternative strategy is to use HTTP cookies ([RFC6265]) to 121 communicate some information about the client. However, this 122 approach is also not cache friendly, bound by same origin policy, and 123 imposes additional client-side latency by requiring JavaScript 124 execution to create and manage HTTP cookies. 126 This document defines a set of new request header fields that allow 127 the client to perform proactive content negotiation (Section 3.4.1 of 128 [RFC7231]) by indicating a list of device and agent specific 129 preferences, through a mechanism similar to the Accept header field 130 which is used to indicate preferred response formats. 132 Client Hints does not supersede or replace the User-Agent header 133 field. Existing device detection mechanisms can continue to use both 134 mechanisms if necessary. By advertising its capabilities within a 135 request header field, Client Hints allows for cache friendly and 136 proactive content negotiation. 138 1.1. Notational Conventions 140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 141 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 142 document are to be interpreted as described in [RFC2119]. 144 This document uses the Augmented Backus-Naur Form (ABNF) notation of 145 [RFC5234] with the list rule extension defined in [RFC7230], 146 Appendix B. It includes by reference the DIGIT rule from [RFC5234] 147 and the OWS and field-name rules from [RFC7230]. 149 2. Client Hint Request Header Fields 151 A Client Hint request header field is a HTTP header field that is 152 used by HTTP clients to indicate configuration data that can be used 153 by the server to select an appropriate response. Each one conveys a 154 list of client preferences that the server can use to adapt and 155 optimize the response. 157 2.1. Sending Client Hints 159 Clients control which Client Hint headers and their respective header 160 fields are communicated, based on their default settings, user 161 configuration and/or preferences. The user can be given the choice 162 to enable, disable, or override specific hints. 164 The client and server, or an intermediate proxy, can use an opt-in 165 mechanism to negotiate which fields should be reported to allow for 166 efficient content adaption. 168 2.2. Server Processing of Client Hints 170 Servers respond with an optimized response based on one or more 171 received hints from the client. When doing so, and if the resource 172 is cacheable, the server MUST also emit a Vary response header field 173 (Section 7.1.4 of [RFC7231]), and optionally Key 174 ([I-D.ietf-httpbis-key]), to indicate which hints can affect the 175 selected response and whether the selected response is appropriate 176 for a later request. 178 Further, depending on the used hint, the server can emit additional 179 response header fields to confirm the property of the response, such 180 that the client can adjust its processing. For example, this 181 specification defines "Content-DPR" response header field that needs 182 to be returned by the server when the "DPR" hint is used to select 183 the response. 185 2.2.1. Advertising Support for Client Hints 187 Servers can advertise support for Client Hints using the Accept-CH 188 header field or an equivalent HTML meta element with http-equiv 189 attribute ([W3C.REC-html5-20141028]). 191 Accept-CH = #field-name 193 For example: 195 Accept-CH: DPR, Width, Viewport-Width, Downlink 197 When a client receives Accept-CH, or if it is capable of processing 198 the HTML response and finds an equivalent HTML meta element, it can 199 treat it as a signal that the server is interested in receiving the 200 Client-Hint header fields that match the advertised field-values; 201 subsequent requests initiated to the same server and, optionally any 202 subresource requests initiated as a result of processing the response 203 from the server that includes the Accept-CH opt-in, can include the 204 Client-Hint header fields that match the advertised field-values. 206 For example, based on Accept-CH example above, a user agent could 207 append DPR, Width, Viewport-Width, and Downlink header fields to all 208 subresource requests initiated by the page constructed from the 209 response. Alternatively, a client can treat advertised support as a 210 persistent origin preference and append same header fields on all 211 future requests initiated to and by the resources associated with 212 that origin. 214 2.2.2. Interaction with Caches 216 When selecting an optimized response based on one or more Client 217 Hints, and if the resource is cacheable, the server needs to emit a 218 Vary response header field ([RFC7234]) to indicate which hints can 219 affect the selected response and whether the selected response is 220 appropriate for a later request. 222 Vary: DPR 224 Above example indicates that the cache key needs to include the DPR 225 header field. 227 Vary: DPR, Width, Downlink 229 Above example indicates that the cache key needs to include the DPR, 230 Width, and Downlink header fields. 232 Client Hints MAY be combined with Key ([I-D.ietf-httpbis-key]) to 233 enable fine-grained control of the cache key for improved cache 234 efficiency. For example, the server can return the following set of 235 instructions: 237 Key: DPR;partition=1.5:2.5:4.0 239 Above example indicates that the cache key needs to include the value 240 of the DPR header field with three segments: less than 1.5, 1.5 to 241 less than 2.5, and 4.0 or greater. 243 Key: Width;div=320 245 Above example indicates that the cache key needs to include the value 246 of the Width header field and be partitioned into groups of 320: 247 0-320, 320-640, and so on. 249 Key: Downlink;partition=0.5:1.0:3.0:5.0:10 251 Above example indicates that the cache key needs to include the 252 (Mbps) value of the Downlink header field with six segments: less 253 than 0.5, 0.5 to less than 1.0, 1.0 to less than 3.0, 3.0 to less 254 than 5.0, 5.0 to less than 10; 10 or higher. 256 3. The DPR Client Hint 258 The "DPR" request header field is a number that indicates the 259 client's current Device Pixel Ratio (DPR), which is the ratio of 260 physical pixels over CSS px (Section 5.2 of 261 [W3C.CR-css-values-3-20160929]) of the layout viewport (Section 9.1.1 262 of [CSS2]) on the device. 264 DPR = 1*DIGIT [ "." 1*DIGIT ] 266 If DPR occurs in a message more than once, the last value overrides 267 all previous occurrences. 269 3.1. Confirming Selected DPR 271 The "Content-DPR" response header field is a number that indicates 272 the ratio between physical pixels over CSS px of the selected image 273 response. 275 Content-DPR = 1*DIGIT [ "." 1*DIGIT ] 277 DPR ratio affects the calculation of intrinsic size of image 278 resources on the client - i.e. typically, the client automatically 279 scales the natural size of the image by the DPR ratio to derive its 280 display dimensions. As a result, the server MUST explicitly indicate 281 the DPR of the selected image response whenever the DPR hint is used, 282 and the client MUST use the DPR value returned by the server to 283 perform its calculations. In case the server returned Content-DPR 284 value contradicts previous client-side DPR indication, the server 285 returned value MUST take precedence. 287 Note that DPR confirmation is only required for image responses, and 288 the server does not need to confirm the resource width as this value 289 can be derived from the resource itself once it is decoded by the 290 client. 292 If Content-DPR occurs in a message more than once, the last value 293 overrides all previous occurrences. 295 4. The Width Client Hint 297 The "Width" request header field is a number that indicates the 298 desired resource width in physical px (i.e. intrinsic size of an 299 image). The provided physical px value is a number rounded to the 300 smallest following integer (i.e. ceiling value). 302 Width = 1*DIGIT 304 If the desired resource width is not known at the time of the request 305 or the resource does not have a display width, the Width header field 306 can be omitted. If Width occurs in a message more than once, the 307 last value overrides all previous occurrences. 309 5. The Viewport-Width Client Hint 311 The "Viewport-Width" request header field is a number that indicates 312 the layout viewport width in CSS px. The provided CSS px value is a 313 number rounded to the smallest following integer (i.e. ceiling 314 value). 316 Viewport-Width = 1*DIGIT 318 If Viewport-Width occurs in a message more than once, the last value 319 overrides all previous occurrences. 321 6. The Downlink Client Hint 323 The "Downlink" request header field is a number that indicates the 324 client's maximum downlink speed in megabits per second (Mbps), as 325 defined by the "downlinkMax" attribute in the W3C Network Information 326 API ([NETINFO]). 328 Downlink = 1*DIGIT [ "." 1*DIGIT ] 330 If Downlink occurs in a message more than once, the minimum value 331 should be used to override other occurrences. 333 7. The Save-Data Client Hint 335 The "Save-Data" request header field consists of one or more tokens 336 that indicate client's preference for reduced data usage, due to high 337 transfer costs, slow connection speeds, or other reasons. 339 Save-Data = sd-token *( OWS ";" OWS [sd-token] ) 340 sd-token = token 342 This document defines the "on" sd-token value, which is used as a 343 signal indicating explicit user opt-in into a reduced data usage mode 344 on the client, and when communicated to origins allows them to 345 deliver alternate content honoring such preference - e.g. smaller 346 image and video resources, alternate markup, and so on. New token 347 and extension token values can only be defined by revisions of this 348 specification. 350 8. Examples 352 For example, given the following request header fields: 354 DPR: 2.0 355 Width: 320 356 Viewport-Width: 320 358 The server knows that the device pixel ratio is 2.0, that the 359 intended display width of the requested resource is 160 CSS px (320 360 physical pixels at 2x resolution), and that the viewport width is 320 361 CSS px. 363 If the server uses above hints to perform resource selection for an 364 image asset, it must confirm its selection via the Content-DPR 365 response header to allow the client to calculate the appropriate 366 intrinsic size of the image response. The server does not need to 367 confirm resource width, only the ratio between physical pixels and 368 CSS px of the selected image resource: 370 Content-DPR: 1.0 372 The Content-DPR response header field indicates to the client that 373 the server has selected resource with DPR ratio of 1.0. The client 374 can use this information to perform additional processing on the 375 resource - for example, calculate the appropriate intrinsic size of 376 the image resource such that it is displayed at the correct 377 resolution. 379 Alternatively, the server could select an alternate resource based on 380 the maximum downlink speed advertised in the request header fields: 382 Downlink: 0.384 384 The server knows that the client's maximum downlink speed is 385 0.384Mbps (GPRS EDGE), and it can use this information to select an 386 optimized resource - for example, an alternate image asset, 387 stylesheet, HTML document, media stream, and so on. 389 9. Security Considerations 391 Client Hints defined in this specification do not expose new 392 information about the user's environment beyond what is already 393 available to, and can be communicated by, the application at runtime 394 via JavaScript and CSS. For example, the application can obtain 395 viewport width, image display width, and device pixel ratio via 396 JavaScript, or through the use of CSS media queries and unique 397 resource URLs even if JavaScript is disabled. However, implementors 398 should consider the privacy implications of various methods to enable 399 delivery of Client Hints - see "Sending Client Hints" section. 401 For example, sending Client Hints on all requests can make 402 information about the user's environment available to origins that 403 otherwise did not have access to this data, which may or may not be 404 the desired outcome - e.g. this may enable an image optimization 405 service to deliver a tailored asset, and it may reveal same 406 information about the user to other origins that may not have had 407 access to it before. Similarly, sending highly granular data, such 408 as image and viewport width may help identify users across multiple 409 requests. Restricting such field values to an enumerated range, 410 where the user agent advertises a threshold value that is close but 411 is not an exact representation of the current value, might reduce 412 such fingerprinting risks. 414 The implementers can provide mechanisms and policies to control how 415 and when such hints are advertised: require origin opt-in and 416 restrict delivery to same origin subrequests; limit delivery to 417 requests that already carry indentifying information (e.g. cookies); 418 modify delivery policy when in an "incognito" or a similar privacy 419 mode; enable user configuration and opt in, and so on. 421 10. IANA Considerations 423 This document defines the "Accept-CH", "DPR", "Width", and "Downlink" 424 HTTP request fields, "Content-DPR" HTTP response field, and registers 425 them in the Permanent Message Header Fields registry. 427 10.1. Accept-CH 429 o Header field name: Accept-CH 430 o Applicable protocol: HTTP 431 o Status: standard 432 o Author/Change controller: IETF 433 o Specification document(s): Section 2.2.1 of this document 434 o Related information: for Client Hints 436 10.2. Content-DPR 438 o Header field name: Content-DPR 439 o Applicable protocol: HTTP 440 o Status: standard 441 o Author/Change controller: IETF 442 o Specification document(s): Section 3.1 of this document 443 o Related information: for Client Hints 445 10.3. Downlink 447 o Header field name: Downlink 448 o Applicable protocol: HTTP 449 o Status: standard 450 o Author/Change controller: IETF 451 o Specification document(s): Section 6 of this document 452 o Related information: for Client Hints 454 10.4. DPR 456 o Header field name: DPR 457 o Applicable protocol: HTTP 458 o Status: standard 459 o Author/Change controller: IETF 460 o Specification document(s): Section 3 of this document 461 o Related information: for Client Hints 463 10.5. Save-Data 465 o Header field name: Save-Data 466 o Applicable protocol: HTTP 467 o Status: standard 468 o Author/Change controller: IETF 469 o Specification document(s): Section 7 of this document 470 o Related information: for Client Hints 472 10.6. Viewport-Width 474 o Header field name: Viewport-Width 475 o Applicable protocol: HTTP 476 o Status: standard 477 o Author/Change controller: IETF 478 o Specification document(s): Section 5 of this document 479 o Related information: for Client Hints 481 10.7. Width 483 o Header field name: Width 484 o Applicable protocol: HTTP 485 o Status: standard 486 o Author/Change controller: IETF 487 o Specification document(s): Section 4 of this document 488 o Related information: for Client Hints 490 11. References 492 11.1. Normative References 494 [CSS2] Bos, B., Celic, T., Hickson, I., and H. Lie, "Cascading 495 Style Sheets Level 2 Revision 1 (CSS 2.1) Specification", 496 W3C Recommendation REC-CSS2-20110607, June 2011, 497 . 499 [NETINFO] Caceres, M., Moreno, F., and I. Grigorik, "Network 500 Information API", n.d., . 502 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 503 Requirement Levels", BCP 14, RFC 2119, 504 DOI 10.17487/RFC2119, March 1997, 505 . 507 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 508 Specifications: ABNF", STD 68, RFC 5234, 509 DOI 10.17487/RFC5234, January 2008, 510 . 512 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 513 Protocol (HTTP/1.1): Message Syntax and Routing", 514 RFC 7230, DOI 10.17487/RFC7230, June 2014, 515 . 517 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 518 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 519 DOI 10.17487/RFC7231, June 2014, 520 . 522 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 523 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 524 RFC 7234, DOI 10.17487/RFC7234, June 2014, 525 . 527 [W3C.CR-css-values-3-20160929] 528 Atkins, T. and E. Etemad, "CSS Values and Units Module 529 Level 3", World Wide Web Consortium CR CR-css-values- 530 3-20160929, September 2016, . 533 [W3C.REC-html5-20141028] 534 Hickson, I., Berjon, R., Faulkner, S., Leithead, T., 535 Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5", 536 World Wide Web Consortium Recommendation REC- 537 html5-20141028, October 2014, 538 . 540 11.2. Informative References 542 [I-D.ietf-httpbis-key] 543 Fielding, R. and M. Nottingham, "The Key HTTP Response 544 Header Field", draft-ietf-httpbis-key-01 (work in 545 progress), March 2016. 547 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 548 DOI 10.17487/RFC6265, April 2011, 549 . 551 Appendix A. Changes 553 A.1. Since -00 555 o Issue 168 (make Save-Data extensible) updated ABNF. 556 o Issue 163 (CH review feedback) editorial feedback from httpwg 557 list. 558 o Issue 153 (NetInfo API citation) added normative reference. 560 A.2. Since -01 562 o Issue 200: Moved Key reference to informative. 563 o Issue 215: Extended passive fingerprinting and mitigation 564 considerations. 565 o Changed document status to experimental. 567 A.3. Since -02 569 o Issue 239: Updated reference to CR-css-values-3 570 o Issue 240: Updated reference for Network Information API 571 o Issue 241: Consistency in IANA considerations 572 o Issue 250: Clarified Accept-CH 574 A.4. Since -03 576 None yet. 578 Author's Address 580 Ilya Grigorik 581 Google 583 Email: ilya@igvita.com 584 URI: https://www.igvita.com/