Ignore:
Timestamp:
Jul 22, 2010, 10:43:26 PM (9 years ago)
Author:
fielding@…
Message:

Addresses #109: Clarify entity / representation / variant terminology

Replace more entity, entities, and entity-body, as appropriate.

Addresses #183: "requested resource" in content-encoding definition

Fixed.

Clarifies #178: Content-MD5 and partial responses

New terminology makes it easier to understand what is digested.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p3-payload.xml

    r867 r874  
    602602<section title="Canonicalization and Text Defaults" anchor="canonicalization.and.text.defaults">
    603603<t>
    604    Internet media types are registered with a canonical form. An
    605    entity-body transferred via HTTP messages &MUST; be represented in the
     604   Internet media types are registered with a canonical form. A
     605   representation transferred via HTTP messages &MUST; be in the
    606606   appropriate canonical form prior to its transmission except for
    607607   "text" types, as defined in the next paragraph.
     
    611611   the text line break. HTTP relaxes this requirement and allows the
    612612   transport of text media with plain CR or LF alone representing a line
    613    break when it is done consistently for an entire entity-body. HTTP
    614    applications &MUST; accept CRLF, bare CR, and bare LF as being
    615    representative of a line break in text media received via HTTP. In
    616    addition, if the text is represented in a character set that does not
     613   break when it is done consistently for an entire representation. HTTP
     614   applications &MUST; accept CRLF, bare CR, and bare LF as indicating
     615   a line break in text media received via HTTP. In
     616   addition, if the text is in a character encoding that does not
    617617   use octets 13 and 10 for CR and LF respectively, as is the case for
    618    some multi-byte character sets, HTTP allows the use of whatever octet
    619    sequences are defined by that character set to represent the
     618   some multi-byte character encodings, HTTP allows the use of whatever octet
     619   sequences are defined by that character encoding to represent the
    620620   equivalent of CR and LF for line breaks. This flexibility regarding
    621    line breaks applies only to text media in the entity-body; a bare CR
     621   line breaks applies only to text media in the payload body; a bare CR
    622622   or LF &MUST-NOT; be substituted for CRLF within any of the HTTP control
    623623   structures (such as header fields and multipart boundaries).
    624624</t>
    625625<t>
    626    If an entity-body is encoded with a content-coding, the underlying
     626   If a representation is encoded with a content-coding, the underlying
    627627   data &MUST; be in a form defined above prior to being encoded.
    628628</t>
    629629<t>
    630630   The "charset" parameter is used with some media types to define the
    631    character set (<xref target="character.sets"/>) of the data. When no explicit charset
     631   character encoding (<xref target="character.sets"/>) of the data. When no explicit charset
    632632   parameter is provided by the sender, media subtypes of the "text"
    633633   type are defined to have a default charset value of "ISO-8859-1" when
    634    received via HTTP. Data in character sets other than "ISO-8859-1" or
     634   received via HTTP. Data in character encodings other than "ISO-8859-1" or
    635635   its subsets &MUST; be labeled with an appropriate charset value. See
    636636   <xref target="missing.charset"/> for compatibility problems.
     
    641641<t>
    642642   MIME provides for a number of "multipart" types -- encapsulations of
    643    one or more entities within a single message-body. All multipart
     643   one or more representations within a single message-body. All multipart
    644644   types share a common syntax, as defined in <xref target="RFC2046" x:sec="5.1.1" x:fmt="of"/>,
    645645   and &MUST; include a boundary parameter as part of the media type
     
    705705</section>
    706706
    707 <section title="Entity" anchor="entity">
     707<section title="Representation" anchor="representation">
    708708<t>
    709709   Request and Response messages &MAY; transfer a representation if not otherwise
     
    721721  <x:anchor-alias value="extension-header"/>
    722722<t>
    723    Entity-header fields define metadata about the entity-body or,
    724    if no body is present, about the resource identified by the request.
     723   Entity-header fields define metadata about the representation data
     724   enclosed in the message-body or, if no message-body is present, about
     725   the representation that would have been transferred in a 200 response
     726   to a simultaneous GET request on the Effective Request URI.
    725727</t>
    726728<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="entity-header"/><iref primary="true" item="Grammar" subitem="extension-header"/>
     
    747749</section>
    748750
    749 <section title="Entity Body" anchor="entity.body">
    750   <x:anchor-alias value="entity-body"/>
    751 <t>
    752    The entity-body (if any) sent with an HTTP request or response is in
     751<section title="Payload Body" anchor="payload.body">
     752  <x:anchor-alias value="payload-body"/>
     753<t>
     754   The payload body (if any) sent with an HTTP request or response is in
    753755   a format and encoding defined by the entity-header fields.
    754756</t>
    755 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="entity-body"/>
    756   <x:ref>entity-body</x:ref>    = *<x:ref>OCTET</x:ref>
    757 </artwork></figure>
    758 <t>
    759    An entity-body is only present in a message when a message-body is
    760    present, as described in &message-body;. The entity-body is obtained
     757<t>
     758   A payload body is only present in a message when a message-body is
     759   present, as described in &message-body;. The payload body is obtained
    761760   from the message-body by decoding any Transfer-Encoding that might
    762761   have been applied to ensure safe and proper transfer of the message.
     
    765764<section title="Type" anchor="type">
    766765<t>
    767    When an entity-body is included with a message, the data type of that
     766   When a payload body is included with a message, the data type of that
    768767   body is determined via the header fields Content-Type and Content-Encoding.
    769768   These define a two-layer, ordered encoding model:
    770769</t>
    771770<figure><artwork type="example">
    772   entity-body := Content-Encoding( Content-Type( data ) )
     771  payload-body := Content-Encoding( Content-Type( data ) )
    773772</artwork></figure>
    774773<t>
    775774   Content-Type specifies the media type of the underlying data. Any HTTP/1.1
    776    message containing an entity-body &SHOULD; include a Content-Type header
     775   message containing a payload body &SHOULD; include a Content-Type header
    777776   field defining the media type of that body, unless that information is
    778777   unknown.
     
    791790</t>
    792791<t>
    793    Client that do so risk drawing incorrect conclusions, which may expose
     792   Clients that do so risk drawing incorrect conclusions, which may expose
    794793   additional security risks (e.g., "privilege escalation"). Implementers are
    795794   encouraged to provide a means of disabling such "content sniffing" when it
     
    799798   Content-Encoding may be used to indicate any additional content
    800799   codings applied to the data, usually for the purpose of data
    801    compression, that are a property of the requested resource.  There is
     800   compression, that are a property of the representation.  There is
    802801   no default encoding.
    803802</t>
     
    928927   initial response from the origin server. Selection is based on a list
    929928   of the available representations of the response included within the
    930    header fields or entity-body of the initial response, with each
     929   header fields or body of the initial response, with each
    931930   representation identified by its own URI. Selection from among the
    932931   representations may be performed automatically (if the user agent is
     
    13421341</t>
    13431342<t>
    1344    If the content-coding of an entity in a request message is not
     1343   If the content-coding of a representation in a request message is not
    13451344   acceptable to the origin server, the server &SHOULD; respond with a
    13461345   status code of 415 (Unsupported Media Type).
     
    13621361   The "Content-Language" entity-header field describes the natural
    13631362   language(s) of the intended audience for the representation. Note that this might
    1364    not be equivalent to all the languages used within the entity-body.
     1363   not be equivalent to all the languages used within the representation.
    13651364</t>
    13661365<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Language"/><iref primary="true" item="Grammar" subitem="Content-Language-v"/>
     
    15041503<t>
    15051504   The "Content-MD5" entity-header field, as defined in <xref target="RFC1864"/>, is
    1506    an MD5 digest of the entity-body that provides an end-to-end message
    1507    integrity check (MIC) of the entity-body. Note that a MIC is good for
    1508    detecting accidental modification of the entity-body in transit, but is not
     1505   an MD5 digest of the payload body that provides an end-to-end message
     1506   integrity check (MIC) of the payload body (the message-body after any
     1507   transfer-coding is decoded). Note that a MIC is good for
     1508   detecting accidental modification of the payload body in transit, but is not
    15091509   proof against malicious attacks.
    15101510</t>
     
    15151515<t>
    15161516   The Content-MD5 header field &MAY; be generated by an origin server or
    1517    client to function as an integrity check of the entity-body. Only
    1518    origin servers or clients &MAY; generate the Content-MD5 header field;
     1517   client to function as an integrity check of the payload body. Only
     1518   origin servers or user agents &MAY; generate the Content-MD5 header field;
    15191519   proxies and gateways &MUST-NOT; generate it, as this would defeat its
    1520    value as an end-to-end integrity check. Any recipient of the entity-body,
    1521    including gateways and proxies, &MAY; check that the digest value
    1522    in this header field matches that of the entity-body as received.
    1523 </t>
    1524 <t>
    1525    The MD5 digest is computed based on the content of the entity-body,
    1526    including any content-coding that has been applied, but not including
    1527    any transfer-encoding applied to the message-body. If the message is
    1528    received with a transfer-encoding, that encoding &MUST; be removed
    1529    prior to checking the Content-MD5 value against the received representation.
    1530 </t>
    1531 <t>
    1532    This has the result that the digest is computed on the octets of the
    1533    entity-body exactly as, and in the order that, they would be sent if
    1534    no transfer-encoding were being applied.
     1520   value as an end-to-end integrity check. Any recipient &MAY; check that
     1521   the digest value in this header field matches a corresponding digest
     1522   calculated on payload body as received.
     1523</t>
     1524<t>
     1525   The MD5 digest is computed based on the content of the payload body,
     1526   including any content-coding, but not including any transfer-coding
     1527   applied to the message-body because such transfer-codings might be
     1528   applied or removed anywhere along the request/response chain.
     1529   If the message is received with a transfer-coding, that encoding &MUST;
     1530   be decoded prior to checking the Content-MD5 value against the received
     1531   payload.
    15351532</t>
    15361533<t>
     
    15411538</t>
    15421539<t>
    1543    There are several consequences of this. The entity-body for composite
     1540   There are several consequences of this. The payload for composite
    15441541   types &MAY; contain many body-parts, each with its own MIME and HTTP
    15451542   headers (including Content-MD5, Content-Transfer-Encoding, and
     
    15811578<t>
    15821579   The "Content-Type" entity-header field indicates the media type of the
    1583    entity-body. In the case of responses to the HEAD method, the media type is
     1580   representation. In the case of responses to the HEAD method, the media type is
    15841581   that which would have been sent had the request been a GET.
    15851582</t>
     
    15951592</artwork></figure>
    15961593<t>
    1597    Further discussion of methods for identifying the media type of an
    1598    entity is provided in <xref target="type"/>.
     1594   Further discussion of methods for identifying the media type of a
     1595   representation is provided in <xref target="type"/>.
    15991596</t>
    16001597</section>
     
    25342531</references>
    25352532
    2536 <section title="Differences Between HTTP Entities and RFC 2045 Entities" anchor="differences.between.http.entities.and.rfc.2045.entities">
     2533<section title="Differences between HTTP and MIME" anchor="differences.between.http.and.mime">
    25372534<t>
    25382535   HTTP/1.1 uses many of the constructs defined for Internet Mail (<xref target="RFC5322"/>) and the Multipurpose Internet Mail Extensions (MIME <xref target="RFC2045"/>) to
    2539    allow entities to be transmitted in an open variety of
     2536   allow a message-body to be transmitted in an open variety of
    25402537   representations and with extensible mechanisms. However, RFC 2045
    25412538   discusses mail, and HTTP has a few features that are different from
    2542    those described in RFC 2045. These differences were carefully chosen
     2539   those described in MIME. These differences were carefully chosen
    25432540   to optimize performance over binary connections, to allow greater
    25442541   freedom in the use of new media types, to make date comparisons
     
    25472544</t>
    25482545<t>
    2549    This appendix describes specific areas where HTTP differs from RFC
    2550    2045. Proxies and gateways to strict MIME environments &SHOULD; be
     2546   This appendix describes specific areas where HTTP differs from MIME.
     2547   Proxies and gateways to strict MIME environments &SHOULD; be
    25512548   aware of these differences and provide the appropriate conversions
    25522549   where necessary. Proxies and gateways from MIME environments to HTTP
     
    25822579<section title="Conversion to Canonical Form" anchor="conversion.to.canonical.form">
    25832580<t>
    2584    <xref target="RFC2045"/> requires that an Internet mail entity be converted to
     2581   MIME requires that an Internet mail body-part be converted to
    25852582   canonical form prior to being transferred, as described in <xref target="RFC2049" x:fmt="of" x:sec="4"/>.
    25862583   <xref target="canonicalization.and.text.defaults"/> of this document describes the forms
     
    26232620<section title="Introduction of Content-Encoding" anchor="introduction.of.content-encoding">
    26242621<t>
    2625    RFC 2045 does not include any concept equivalent to HTTP/1.1's
     2622   MIME does not include any concept equivalent to HTTP/1.1's
    26262623   Content-Encoding header field. Since this acts as a modifier on the
    26272624   media type, proxies and gateways from HTTP to MIME-compliant
    26282625   protocols &MUST; either change the value of the Content-Type header
    2629    field or decode the entity-body before forwarding the message. (Some
     2626   field or decode the representation before forwarding the message. (Some
    26302627   experimental applications of Content-Type for Internet mail have used
    26312628   a media-type parameter of ";conversions=&lt;content-coding&gt;" to perform
    26322629   a function equivalent to Content-Encoding. However, this parameter is
    2633    not part of RFC 2045).
     2630   not part of the MIME standards).
    26342631</t>
    26352632</section>
     
    26372634<section title="No Content-Transfer-Encoding" anchor="no.content-transfer-encoding">
    26382635<t>
    2639    HTTP does not use the Content-Transfer-Encoding field of RFC
    2640    2045. Proxies and gateways from MIME-compliant protocols to HTTP &MUST;
     2636   HTTP does not use the Content-Transfer-Encoding field of MIME.
     2637   Proxies and gateways from MIME-compliant protocols to HTTP &MUST;
    26412638   remove any Content-Transfer-Encoding
    26422639   prior to delivering the response message to an HTTP client.
     
    28462843<x:ref>disposition-type</x:ref> = "attachment" / disp-extension-token
    28472844
    2848 <x:ref>entity-body</x:ref> = *OCTET
    28492845<x:ref>entity-header</x:ref> = Content-Encoding / Content-Language / Content-Length
    28502846 / Content-Location / Content-MD5 / Content-Range / Content-Type /
     
    28862882; MIME-Version defined but not used
    28872883; content-disposition defined but not used
    2888 ; entity-body defined but not used
    28892884; entity-header defined but not used
    28902885</artwork></figure></section>
Note: See TracChangeset for help on using the changeset viewer.