One document matched: draft-hartke-core-coap-http-00.xml
<?xml version="1.0" encoding="us-ascii"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2616 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY I-D.ietf-core-coap SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-core-coap-04.xml">
<!ENTITY I-D.ietf-core-block SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-core-block-01.xml">
<!ENTITY I-D.ietf-core-observe SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-core-observe-01.xml">
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<?rfc strict="yes"?>
<?rfc toc="yes"?>
<?rfc tocdepth="3"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="info" docName="draft-hartke-core-coap-http-00" ipr="trust200902">
<front>
<title>Accessing HTTP resources over CoAP</title>
<author initials="K" surname="Hartke" fullname="Klaus Hartke">
<organization>Universitaet Bremen TZI</organization>
<address>
<postal>
<street>Postfach 330440</street>
<city>Bremen</city>
<code>D-28359</code>
<country>Germany</country>
</postal>
<phone>+49-421-218-63905</phone>
<facsimile>+49-421-218-7000</facsimile>
<email>hartke@tzi.org</email>
</address>
</author>
<date year="2011"/>
<area>Applications</area>
<workgroup>CoRE Working Group</workgroup>
<abstract>
<t>The CoAP/HTTP proxying mechanism defined in this document enables
Constrained Application Protocol (CoAP) clients to access a Hypertext
Transfer Protocol (HTTP) resource by delegating the task of retrieving
resource representations and manipulating resources to a CoAP
intermediary.</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>The Constrained Application Protocol (CoAP) <xref
target="I-D.ietf-core-coap"/> allows clients to specify an arbitrary,
absolute Uniform Resource Identifier (URI) <xref target="RFC3986"/> in
requests to CoAP proxies. This document defines what it means to perform
a CoAP request on a Hypertext Transfer Protocol (HTTP) URI <xref
target="RFC2616"/>.</t>
<t>The resulting CoAP/HTTP proxying mechanism enables CoAP clients to
access HTTP resources over CoAP by delegating the task of retrieving
resource representations and manipulating resources to a CoAP
intermediary. This relieves the client from the burden of implementing
any HTTP functionality itself.</t>
<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 anchor="proxying" title="CoAP/HTTP Proxying">
<t>If a request contains a Proxy-URI Option with an 'http' or 'https'
URI <xref target="RFC2616"/>, then the receiving CoAP end-point (called
"the proxy" henceforth) is requested to perform the operation specified
by the request method on the indicated HTTP resource and return the
result to the client.</t>
<t>This section specifies for any CoAP request the CoAP response that the
proxy should return to the client. How the proxy actually satisfies the
request is an implementation detail, although the typical case is
expected to be the proxy translating and forwarding the request to an
HTTP origin server (see <xref target="implementation"/>).</t>
<t>Since HTTP and CoAP share the basic set of request methods, performing
a CoAP request on an HTTP resource is not so different from performing it
on a CoAP resource. The meanings of the individual CoAP methods when
performed on HTTP resources are explained below.</t>
<t>If the proxy is unable or unwilling to service a request with an HTTP
URI, a 5.05 (Proxying Not Supported) response MUST be returned to the
client. If the proxy services the request by interacting with a third
party (such as the HTTP origin server) and is unable to obtain a result
within a reasonable timeframe, a 5.04 (Gateway Timeout) response MUST be
returned; if a result can be obtained but is not understood, a 5.02 (Bad
Gateway) response MUST be returned.</t>
<!--
<t>If the target HTTP resource does not exist and the request method is
not DELETE, a 4.04 (Not Found) response MUST be returned. If the resource
does not support the request method, a 4.05 (Method Not Allowed) response
MUST be returned. If the result of the performed operation is not
success, an appropriate error response MUST be returned. Otherwise, a
response with a code matching the outcome of the performed operation MUST
be returned.</t>
-->
<section anchor="get" title="GET">
<t>The GET method requests the proxy to return a representation of
the HTTP resource identified by the request URI.</t>
<t>Upon success, a 2.00 (OK) response SHOULD be returned. The payload
of the response MUST be a representation of the target HTTP resource,
and the Content-Type Option be set accordingly. The response MUST
indicate a Max-Age value that is no greater than the remaining time
the representation can be considered fresh. If the HTTP entity has an
entity tag, the proxy SHOULD include an ETag Option in the response
and process ETag Options in requests as described below.</t>
<t>A client can influence the processing of a GET request by including
the following options:
<list style="hanging">
<t hangText="Lifetime:">The request MAY include a Lifetime Option
<xref target="I-D.ietf-core-observe"/>. This requests the proxy to
notify the client of any changes to the state of the target HTTP
resource. If the proxy is unable to detect changes to the resource or
is unwilling to establish an observation relationship, the proxy
MUST silently ignore the option. Otherwise, the proxy establishes
an observation relationship as described in <xref
target="I-D.ietf-core-observe"/> and, whenever the state of the HTTP
resource changes, sends a 2.00 (OK) notification response to the
client.</t>
<t hangText="ETag:">The request MAY include one or more ETag Options,
identifying responses that the client has stored. This requests
the proxy to send a 2.03 (Valid) response whenever it would send a
2.00 (OK) response with an entity tag in the requested set otherwise.
(See also <xref target="max-age-etag"/>.)</t>
<t hangText="Block:">The request MAY include a Block Option <xref
target="I-D.ietf-core-block"/>, specifying the block the client is
interested in. This requests the proxy to send only the requested
block in a 2.00 (OK) response instead of the whole representation.
(See also <xref target="block-wise"/>.)</t>
<!--
<t hangText="Accept:">The request MAY include one or more Accept
Options, specifying the list of acceptable response content-types.
This requests the proxy to send a 4.06 (Not Acceptable) response
instead of a 2.00 (OK) response with a content-type not included in
the requested list.</t>
-->
</list>
</t>
</section>
<section anchor="put" title="PUT">
<t>The PUT method requests the proxy to update or create the HTTP
resource identified by the request URI with the enclosed
representation.</t>
<t>If a new resource is created at the request URI, a 2.01 (Created)
response MUST be returned to the client. If an existing resource is
modified, a 2.04 (Changed) response MUST be returned to indicate
successful completion of the request.</t>
<t>A client can influence the processing of a PUT request by including
the following options:
<list style="hanging">
<t hangText="Block:">The request MAY include a Block Option,
indicating a block-wise transfer as described in <xref
target="I-D.ietf-core-block"/>. (See also <xref
target="block-wise"/>.)</t>
</list>
</t>
</section>
<section anchor="delete" title="DELETE">
<t>The DELETE method requests the proxy to delete the HTTP resource
identified by the request URI at the HTTP origin server.</t>
<t>A 2.02 (Deleted) response MUST be returned to client upon success
or if the resource does not exist at the time of the request.</t>
<t>No further options are defined to enable the client to influence
the processing of a DELETE request.</t>
</section>
<section anchor="post" title="POST">
<t>The POST method requests the proxy to have the representation
enclosed in the request be processed by the HTTP origin server. The
actual function performed by the POST method is determined by the
origin server and dependent on the resource identified by the request
URI.</t>
<t>If the action performed by the POST method does not result in a
resource that can be identified by a URI, a 2.04 (Changed) response
MUST be returned to the client. If a resource has been created on
the origin server, a 2.01 (Created) response MUST be returned.</t>
<t>A client can influence the processing of a PUT request by including
the following options:
<list style="hanging">
<!--
<t hangText="Accept:">(TODO.)</t>
-->
<t hangText="Block:">The request MAY include a Block Option,
indicating a block-wise transfer as described in <xref
target="I-D.ietf-core-block"/>. (See also <xref
target="block-wise"/>.)</t>
</list>
</t>
</section>
</section>
<section anchor="implementation" title="Implementation Considerations">
<t>
The CoAP/HTTP proxying requirements described in <xref
target="proxying"/> deliberately make no restrictions on how a
proxy implementation actually satisfies a request to produce
the expected response. Obviously, these requirements would
not be very useful if they could not be implemented. Also,
some of the proxies will run on nodes that exhibit some
constraints and may use networks that also are
constrained.</t>
<t>
In general, an implementation will translate and forward CoAP
requests to the HTTP origin server and translate back HTTP
responses to CoAP responses, typically employing a
certain amount of caching to make this translation more
efficient. This non-normative section gives some hints for
implementing the translation.</t>
<section anchor="payloads-media-types" title="Payloads and Media Types">
<t>CoAP supports only a subset of media types. A proxy should convert
payloads and approximate content-types as closely as possible. For
example, if a HTTP server returns a resource representation in
"text/plain; charset=iso-8859-1" format, the proxy should convert the
payload to "text/plain; charset=utf-8" format. If conversion is not
possible, the proxy can specify a media type of
"application/octet-stream".</t>
</section>
<section anchor="max-age-etag" title="Max-Age and ETag Options">
<t>The proxy can determine the Max-Age Option for responses to GET
requests by calculating the freshness lifetime (see Section 13.2.4
of <xref target="RFC2616"/>) of the HTTP resource representation
retrieved. The Max-Age Option for responses to POST, PUT or DELETE
requests should always be set to 0.</t>
<t>The proxy can assign entity tags to responses it sends to a client.
These can be generated locally, if the proxy employs a cache, or be
derived from the ETag header field in a response from the HTTP origin
server, in which case the proxy can optimize future requests to the
HTTP by using Conditional Requests. Note that CoAP does not support
weak entity tags.</t>
</section>
<section anchor="block-wise" title="Block-wise Transfers">
<t>The proxy can optimize the processing of many requests. For example,
when a GET request includes a Block Option, the proxy can use HTTP
Range Requests to retrieve only the requested block(s) of the HTTP
resource from the origin server instead of retrieving the whole
resource.</t>
<t><xref target="proxying"/> makes no restrictions on whether the proxy
attempts to re-assemble all block-wise PUT requests into a single HTTP
PUT request or attempts to push each request forward by making use of
the HTTP Content-Range header field (which is not widely implemented
for PUT outside WebDAV). In either case, the handling chosen MUST be
reflected in the More bit sent back in the CoAP response as specified
in <xref target="I-D.ietf-core-block"/>.</t>
<t>For POST, similar considerations as with PUT apply, except that HTTP
Content-Range is even less widely implemented with HTTP POST.</t>
</section>
<section anchor="one-and-three" title="HTTP Status Codes 1xx and 3xx">
<t>CoAP does not have provisional responses (HTTP Status Codes 1xx) or
responses indicating that further action needs to be taken (HTTP Status
Codes 3xx). When a proxy receives such a response from the HTTP server,
the response should cause the proxy to complete the request, for
example, by following redirects. If the proxy is unable or unwilling
to do so, it can return a 5.02 (Bad Gateway) error.</t>
</section>
<!--
<section anchor="cookies" title="Cookies">
<t>(TODO.)</t>
</section>
-->
<section anchor="example" title="Example">
<t>The example in <xref target="fig-example-1"/> shows a possible
implementation of a basic CoAP GET request with an HTTP URI as the
value of a Proxy-URI Option. The proxy retrieves a representation of
the target resource from the HTTP origin server. It converts the
payload to UTF-8 charset, calculates the Max-Age Option from the
Expires header field, and derives an entity-tag from the ETag header
field.</t>
<figure anchor="fig-example-1" title="A basic GET request">
<artwork><![CDATA[
CoAP CoAP/HTTP HTTP
Client Proxy Server
| | |
| | |
+----->| | Header: GET (T=CON, Code=1, MID=0x1633)
| GET | | Token: 0x5a
| | | Proxy-URI: http://www.example.com/foo/bar
| | |
| | |
| +----->| GET /foo/bar HTTP/1.1
| | GET | Host: www.example.com
| | |
| | |
|<- - -+ | Header: (T=ACK, Code=0, MID=0x1633)
| | |
| | |
| |<-----+ HTTP/1.1 200 OK
| | 200 | Date: Tue, 01 Mar 2011 15:00:00 GMT
| | | Content-Type: text/plain; charset=iso-8859-1
| | | Content-Length: 11
| | | Expires: Tue, 01 Mar 2011 16:00:00 GMT
| | | ETag: "xyzzy"
| | | Connection: close
| | |
| | | Hello World
| | |
| | |
|<-----+ | Header: 2.00 OK (T=CON, Code=64, MID=0xAAF0)
| 2.00 | | Token: 0x5a
| | | C'-Type: text/plain; charset=utf-8
| | | Max-Age: 3600
| | | ETag: 0x78797A7A79
| | | Payload: "Hello World"
| | |
| | |
+- - ->| | Header: (T=ACK, Code=0, MID=0xAAF0)
| | |
| | |
]]></artwork>
</figure>
<t>The example in <xref target="fig-example-2"/> builds on the previous
example and shows a possible implementation of a GET request that
includes a previously returned ETag Option. The proxy makes a
Conditional Request to the HTTP origin server by including an
If-None-Match header field in the HTTP GET request. The CoAP response
indicates that the response stored by the client is fresh. It includes
a Max-Age Option calculated from the HTTP response's Expires header
field.</t>
<figure anchor="fig-example-2" title="A GET request with an ETag Option">
<artwork><![CDATA[
CoAP CoAP/HTTP HTTP
Client Proxy Server
| | |
| | |
+----->| | Header: GET (T=CON, Code=1, MID=0x1CB0)
| GET | | Token: 0x7b
| | | Proxy-URI: http://www.example.com/foo/bar
| | | ETag: 0x78797A7A79
| | |
| | |
| +----->| GET /foo/bar HTTP/1.1
| | GET | Host: www.example.com
| | | If-None-Match: "xyzzy"
| | |
| | |
|<- - -+ | Header: (T=ACK, Code=0, MID=0x1CB0)
| | |
| | |
| |<-----+ HTTP/1.1 304 Not Modified
| | 304 | Date: Tue, 01 Mar 2011 17:00:00 GMT
| | | Expires: Tue, 01 Mar 2011 18:00:00 GMT
| | | ETag: "xyzzy"
| | | Connection: close
| | |
| | |
|<-----+ | Header: 2.03 Valid (T=CON, Code=67, MID=0xAAFF)
| 2.03 | | Token: 0x7b
| | | Max-Age: 3600
| | | ETag: 0x78797A7A79
| | |
| | |
+- - ->| | Header: (T=ACK, Code=0, MID=0xAAFF)
| | |
| | |
]]></artwork>
</figure>
</section>
</section>
<section anchor="security" title="Security Considerations">
<t>When CoAP NoSec mode is used, a CoAP to HTTP proxy provides a way for
a UDP sender to initiate an HTTP transfer, possibly using a fake source
address, making the original request untraceable in general. (I.e. the
usual minimal protection afforded to HTTP proxies by the TCP three-way
handshake does not apply.) CoAP/HTTP proxies MUST be used in a way that
they don't attract attackers that want to exploit this, e.g., by
requiring communication security and/or by running them in a protected
network.</t>
<t>The security considerations of section 15.7 of RFC 2616 apply
and MUST be heeded. (TODO: Add further text about the perils of
proxies, e.g., cache poisoning.)</t>
</section>
<section anchor="iana-considerations" title="IANA Considerations">
<t>This document does not require IANA action.</t>
</section>
<section anchor="acknowledgements" title="Acknowledgements">
<t>Some text for <xref target="implementation"/> and <xref
target="security"/> was contributed by Carsten Bormann.</t>
</section>
</middle>
<back>
<references title="Normative References">
&RFC2119;
&RFC2616;
&RFC3986;
&I-D.ietf-core-coap;
&I-D.ietf-core-block;
&I-D.ietf-core-observe;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 09:23:50 |