One document matched: draft-hartke-core-coap-http-00.txt
CoRE Working Group K. Hartke
Internet-Draft Universitaet Bremen TZI
Intended status: Informational March 7, 2011
Expires: September 8, 2011
Accessing HTTP resources over CoAP
draft-hartke-core-coap-http-00
Abstract
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.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on September 8, 2011.
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Hartke Expires September 8, 2011 [Page 1]
Internet-Draft Accessing HTTP resources over CoAP March 2011
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. CoAP/HTTP Proxying . . . . . . . . . . . . . . . . . . . . . . 3
2.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Implementation Considerations . . . . . . . . . . . . . . . . 5
3.1. Payloads and Media Types . . . . . . . . . . . . . . . . . 6
3.2. Max-Age and ETag Options . . . . . . . . . . . . . . . . . 6
3.3. Block-wise Transfers . . . . . . . . . . . . . . . . . . . 6
3.4. HTTP Status Codes 1xx and 3xx . . . . . . . . . . . . . . 7
3.5. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7
4. Security Considerations . . . . . . . . . . . . . . . . . . . 9
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10
7. Normative References . . . . . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10
Hartke Expires September 8, 2011 [Page 2]
Internet-Draft Accessing HTTP resources over CoAP March 2011
1. Introduction
The Constrained Application Protocol (CoAP) [I-D.ietf-core-coap]
allows clients to specify an arbitrary, absolute Uniform Resource
Identifier (URI) [RFC3986] in requests to CoAP proxies. This
document defines what it means to perform a CoAP request on a
Hypertext Transfer Protocol (HTTP) URI [RFC2616].
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.
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 [RFC2119].
2. CoAP/HTTP Proxying
If a request contains a Proxy-URI Option with an 'http' or 'https'
URI [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.
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 Section 3).
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.
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.
Hartke Expires September 8, 2011 [Page 3]
Internet-Draft Accessing HTTP resources over CoAP March 2011
2.1. GET
The GET method requests the proxy to return a representation of the
HTTP resource identified by the request URI.
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.
A client can influence the processing of a GET request by including
the following options:
Lifetime: The request MAY include a Lifetime Option
[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 [I-D.ietf-core-observe]
and, whenever the state of the HTTP resource changes, sends a 2.00
(OK) notification response to the client.
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 Section 3.2.)
Block: The request MAY include a Block Option [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 Section 3.3.)
2.2. PUT
The PUT method requests the proxy to update or create the HTTP
resource identified by the request URI with the enclosed
representation.
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.
Hartke Expires September 8, 2011 [Page 4]
Internet-Draft Accessing HTTP resources over CoAP March 2011
A client can influence the processing of a PUT request by including
the following options:
Block: The request MAY include a Block Option, indicating a block-
wise transfer as described in [I-D.ietf-core-block]. (See also
Section 3.3.)
2.3. DELETE
The DELETE method requests the proxy to delete the HTTP resource
identified by the request URI at the HTTP origin server.
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.
No further options are defined to enable the client to influence the
processing of a DELETE request.
2.4. POST
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.
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.
A client can influence the processing of a PUT request by including
the following options:
Block: The request MAY include a Block Option, indicating a block-
wise transfer as described in [I-D.ietf-core-block]. (See also
Section 3.3.)
3. Implementation Considerations
The CoAP/HTTP proxying requirements described in Section 2
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.
Hartke Expires September 8, 2011 [Page 5]
Internet-Draft Accessing HTTP resources over CoAP March 2011
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.
3.1. Payloads and Media Types
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".
3.2. Max-Age and ETag Options
The proxy can determine the Max-Age Option for responses to GET
requests by calculating the freshness lifetime (see Section 13.2.4 of
[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.
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.
3.3. Block-wise Transfers
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.
Section 2 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 [I-D.ietf-core-block].
For POST, similar considerations as with PUT apply, except that HTTP
Hartke Expires September 8, 2011 [Page 6]
Internet-Draft Accessing HTTP resources over CoAP March 2011
Content-Range is even less widely implemented with HTTP POST.
3.4. HTTP Status Codes 1xx and 3xx
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.
3.5. Example
The example in Figure 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.
Hartke Expires September 8, 2011 [Page 7]
Internet-Draft Accessing HTTP resources over CoAP March 2011
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)
| | |
| | |
Figure 1: A basic GET request
The example in Figure 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.
Hartke Expires September 8, 2011 [Page 8]
Internet-Draft Accessing HTTP resources over CoAP March 2011
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)
| | |
| | |
Figure 2: A GET request with an ETag Option
4. Security Considerations
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.
Hartke Expires September 8, 2011 [Page 9]
Internet-Draft Accessing HTTP resources over CoAP March 2011
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.)
5. IANA Considerations
This document does not require IANA action.
6. Acknowledgements
Some text for Section 3 and Section 4 was contributed by Carsten
Bormann.
7. Normative References
[I-D.ietf-core-block]
Shelby, Z. and C. Bormann, "Blockwise transfers in CoAP",
draft-ietf-core-block-01 (work in progress), January 2011.
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
"Constrained Application Protocol (CoAP)",
draft-ietf-core-coap-04 (work in progress), January 2011.
[I-D.ietf-core-observe]
Hartke, K. and Z. Shelby, "Observing Resources in CoAP",
draft-ietf-core-observe-01 (work in progress),
February 2011.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
Hartke Expires September 8, 2011 [Page 10]
Internet-Draft Accessing HTTP resources over CoAP March 2011
Author's Address
Klaus Hartke
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63905
Fax: +49-421-218-7000
Email: hartke@tzi.org
Hartke Expires September 8, 2011 [Page 11]
| PAFTECH AB 2003-2026 | 2026-04-23 04:18:32 |