One document matched: draft-castellani-core-http-mapping-04.xml
<?xml version="1.0" encoding="us-ascii"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2046.xml">
<!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 RFC3040 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3040.xml">
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC4732 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4732.xml">
<!ENTITY RFC5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
<!ENTITY RFC6202 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6202.xml">
<!ENTITY RFC4287 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4287.xml">
<!ENTITY I-D.ietf-core-coap SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-core-coap-07.xml">
<!ENTITY I-D.ietf-core-observe SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-core-observe-02.xml">
<!ENTITY I-D.ietf-core-block SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-core-block-04.xml">
<!ENTITY I-D.ietf-core-groupcomm SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-core-groupcomm-00.xml">
<!ENTITY I-D.eggert-core-congestion-control SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-eggert-core-congestion-control-01.xml">
<!ENTITY I-D.bormann-core-simple-server-discovery SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-bormann-core-simple-server-discovery-00.xml">
<!ENTITY I-D.vanderstok-core-bc SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-vanderstok-core-bc-04.xml">
<!ENTITY I-D.ietf-httpbis-p1-messaging SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p1-messaging-18.xml">
<!ENTITY I-D.ietf-httpbis-p2-semantics SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p2-semantics-18.xml">
<!ENTITY I-D.thomson-hybi-http-timeout SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-thomson-hybi-http-timeout-00.xml">
<!ENTITY I-D.shelby-core-resource-directory SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-shelby-core-resource-directory-01.xml">
<!ENTITY I-D.snell-http-prefer SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-snell-http-prefer-12.xml">
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<?rfc strict="no"?>
<?rfc toc="yes"?>
<?rfc tocdepth="3"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc ipr="trust200902"
docName="draft-castellani-core-http-mapping-04" category='info'>
<front>
<title abbrev="HTTP-CoAP mapping">
Best practices for HTTP-CoAP mapping implementation
</title>
<author initials="A.P." surname="Castellani" fullname="Angelo P. Castellani">
<organization>University of Padova</organization>
<address>
<postal>
<street>Via Gradenigo 6/B</street>
<code>35131</code>
<city>Padova</city>
<country>Italy</country>
</postal>
<email>angelo@castellani.net</email>
</address>
</author>
<author initials="S." surname="Loreto" fullname="Salvatore Loreto">
<organization>Ericsson</organization>
<address>
<postal>
<street>Hirsalantie 11</street>
<code>02420</code>
<city>Jorvas</city>
<country>Finland</country>
</postal>
<email>salvatore.loreto@ericsson.com</email>
</address>
</author>
<author initials="A." surname="Rahman" fullname="Akbar Rahman">
<organization>InterDigital Communications, LLC</organization>
<address>
<email>Akbar.Rahman@InterDigital.com</email>
</address>
</author>
<author initials="T." surname="Fossati" fullname="Thomas Fossati">
<organization>KoanLogic</organization>
<address>
<postal>
<street>Via di Sabbiuno 11/5</street>
<city>Bologna</city>
<code>40136</code>
<country>Italy</country>
</postal>
<phone>+39 051 644 82 68</phone>
<email>tho@koanlogic.com</email>
</address>
</author>
<author initials="E." surname="Dijk" fullname="Esko Dijk">
<organization>Philips Research</organization>
<address>
<email>esko.dijk@philips.com</email>
</address>
</author>
<date year="2012" />
<area>APP</area>
<workgroup>CoRE Working Group</workgroup>
<keyword>CoAP</keyword>
<keyword>HTTP-CoAP mapping</keyword>
<abstract>
<t>This draft aims at being a base reference documentation for HTTP-CoAP proxy implementors.
It details deployment options, discusses possible approaches for URI mapping,
and provides useful considerations related to protocol translation.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>RESTful protocols, such as HTTP <xref target="RFC2616"/> and CoAP <xref target="I-D.ietf-core-coap"/>,
can interoperate through an intermediary proxy which performs cross-protocol mapping.</t>
<t>A reference about the mapping process is provided in Section 8 of <xref target="I-D.ietf-core-coap"/>.
However, depending on the involved application, deployment scenario, or network topology,
such mapping could be realized using a wide range of intermediaries.</t>
<t>Moreover, the process of implementing such a proxy could be complex,
and details regarding its internal procedures and design choices
deserve further discussion, which is provided in this document.</t>
<t>This draft is organized as follows:
<list style="symbols">
<t><xref target="terminology"/> describes terminology to identify different mapping approaches
and the related proxy deployments;</t>
<t><xref target="URI"/> discusses impact of the mapping on URI and describes notable options;</t>
<t><xref target="hc"/> and <xref target="ch"/> respectively analyze the mapping from HTTP to CoAP and viceversa;</t>
<t><xref target="sec"/> discusses possible security impact related to the mapping.</t>
</list></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 title="Terminology" anchor="terminology">
<t>A device providing cross-protocol HTTP-CoAP mapping is called an HTTP-CoAP cross-protocol proxy (HC proxy).</t>
<!--
<t>Regular HTTP proxies are usually same-protocol proxies, because they can map from HTTP to HTTP.
CoAP same-protocol proxies are intermediaries for CoAP to CoAP exchanges.
However the discussion about these entities is out-of-scope of this document.</t>
-->
<t>At least two different kinds of HC proxies exist:
<list style="symbols">
<t>One-way cross-protocol proxy (1-way proxy):
This proxy translates from a client of a protocol to a server of another protocol but not vice-versa.</t>
<t>Two-way (or bidirectional) cross-protocol proxy (2-way proxy):
This proxy translates from a client of both protocols to a server supporting one protocol.</t>
</list>
</t>
<t>1-way and 2-way HC proxies are realized using the following general types of proxies:
<list style="hanging">
<t hangText="Forward proxy (F):">
Is a proxy known by the client (either CoAP or HTTP) used to access a specific cross-protocol server (respectively HTTP or CoAP).
Main feature: server(s) do not require to be known in advance by the proxy (ZSC: Zero Server Configuration).</t>
<t hangText="Reverse proxy (R):">
Is a proxy known by the client to be the server, however for a subset of resources it works as a proxy, by knowing the real server(s) serving each resource.
When a cross-protocol resource is accessed by a client, the request will be silently forwarded by the reverse proxy to the real server (running a different protocol).
If a response is received by the reverse proxy, it will be mapped, if possible, to the original protocol and sent back to the client.
Main feature: client(s) do not require to know in advance the proxy (ZCC: Zero Client Configuration).</t>
<t hangText="Interception proxy (I):">
This proxy <xref target="RFC3040" /> can intercept any origin protocol request (HTTP or CoAP) and map it to the destination protocol,
without any kind of knowledge about the client or server involved in the exchange.
Main feature: client(s) and server(s) do not require to know or be known in advance by the proxy (ZCC and ZSC).</t>
</list>
</t>
<t>A server-side (SS) proxy is placed in the same network domain of the server;
Conversely a client-side (CS) is in the same network domain of the client.
Differently from these two cases, the proxy is said to be External (E).</t>
</section>
<section anchor="URI" title="Cross-protocol resource identification using URIs">
<t>A Uniform Resource Identifier (URI) provides a simple and extensible means for identifying a resource.
It enables uniform identification of resources via a separately defined extensible set of naming schemes <xref target="RFC3986"/>.</t>
<t>URIs are formed of at least three components: scheme, authority and path.
The scheme is the first part of the URI,
and it often corresponds to the protocol used to access the resource.
However, as noted in Section 1.2.2 of <xref target="RFC3986"/>
the scheme does not imply that a particular protocol is used to access the resource.</t>
<t>Clients using URIs to identify target resources (e.g. HTTP web browsers)
may support only a limited set of schemes (i.e. 'http', 'https').
If such clients need to interoperate with resources identified by an unsupported scheme
(e.g. 'coap'), the existence of a URI using a scheme supported by the client
is required for interoperability.</t>
<t>Both CoAP and HTTP implement the REST paradigm,
so, in principle, the same resource can be made available in each protocol if protocol translation is applied.</t>
<t>In general two different procedures can be used by a client to access cross-protocol resources:
<list style="hanging">
<t hangText='Protocol-aware access:'>
Happens when a client knows the other protocol domain
and accesses the cross-protocol resource using its URI by using an HC proxy.
Example: An HTTP client accesses a CoAP resource by addressing it
using the 'coap' scheme inside the HTTP request
(actual protocol translation is provided by the proxy).
Both HTTP and CoAP allow using different schemes in requests to proxies:
(i) see Section 4.1.2 of <xref target="I-D.ietf-httpbis-p1-messaging"/>,
and (ii) Section 5.10.3 of <xref target="I-D.ietf-core-coap"/>.</t>
<t hangText='Protocol-agnostic access:'>
The client accesses the cross-protocol resource
using an URI with a scheme supported by the client
(e.g. uses 'http' scheme to access a CoAP resource),
URI and protocol translation is provided by a cross-protocol proxy.
In order to use this method a URI identifying an equivalent resource MUST exist,
and SHOULD be provided by the cross-protocol proxy.</t>
</list>
</t>
<t>URI mapping is NOT required when using protocol-aware access,
the following section is focused on URI mapping techniques for protocol-agnostic access.</t>
<section anchor="URI-mapping" title="URI mapping">
<t>When accessing cross-protocol resources in a protocol-agnostic way,
clients MUST use an URI with a scheme supported by the client.</t>
<t>Since determination of equivalence of URIs
(e.g. whether or not they identify the same resource) is based on lexicographic comparison,
URI domains using different schemes are fully distinct:
resources identified by the same authority and path tuple change when switching the scheme.</t>
<t>Example: Assume that the following resource exists - "coap://node.coap.something.net/foo".
The resource identified by "http://node.coap.something.net/foo" may not exist
or be non-equivalent to the one identified by the 'coap' scheme.</t>
<t>If a cross-protocol URI exists providing an equivalent representation of the native protocol resource,
it can be provided by a different URI (in terms of authority and path).
The mapping of an URI between HTTP and CoAP is said HC URI mapping.</t>
<t>Example: The HC URI mapping to HTTP of the CoAP resource identified
by "coap://node.coap.something.net/foo" is "http://node.something.net/foobar".</t>
<t>The process of providing the HC URI mapping could be complex,
since a proper mechanism to statically or dynamically (discover) map the resource HC URI mapping is required.</t>
<t>Two static HC URI mappings are discussed in the following subsections.</t>
<section title="Homogeneous mapping" anchor="URI-homogeneous-mapping">
<t>The URI mapping between CoAP and HTTP is called homogeneous,
if the same resource is identified by URIs with different schemes.</t>
<t>Example: The CoAP resource "//node.coap.something.net/foo"
identified either by the URI "coap://node.coap.something.net/foo",
and or by the URI "http://node.coap.something.net/foo" is the same.
When the resource is accessed using HTTP, the mapping from HTTP to CoAP is performed by an HC proxy</t>
<t>When homogeneous HC URI mapping is available, HC-I proxies are easily implementable.</t>
</section>
<section title="Embedded mapping" anchor="URI-embedded-mapping">
<t> When the HC URI mapping of the resource embeds inside it the authority and path part of the native URI,
then the mapping is said to be embedded.</t>
<t>Example: The CoAP resource "coap://node.coap.something.net/foo"
can be accessed at "http://hc-proxy.something.net/coap/node.coap.something.net/foo".</t>
<t>This mapping technique can be used to reduce the mapping complexity in an HC reverse proxy.</t>
<section title="HTML5 scheme handler registration" anchor="HTML5-mapping">
<t>The draft HTML5 standard offers a mechanism that allows an HTTP user agent
to register a custom scheme handler through an HTML5 web page.
This feature permits to an HC proxy to be registered as "handler" for URIs with the 'web+coap' or 'web+coaps' schemes
using an HTML5 web page which embeds the custom scheme handler registration call registerProtocolHandler()
described in Section 6.5.1.2 of <xref target="W3C.HTML5" />.</t>
<t>Example: the HTML5 homepage of a HC proxy at h2c.example.org could include the method call:</t>
<figure><artwork align="center"><![CDATA[
registerProtocolHandler('web+coap', 'proxy?url=%s', 'example HC proxy')
]]></artwork></figure>
<t>This registration call will prompt the HTTP user agent to ask for the user's permission
to register the HC proxy as a handler for all 'web+coap' URIs.
If the user accepts, whenever a 'web+coap' link is requested,
the request will be fulfilled through the HC proxy:
URI "web+coap://foo.org/a" will be transformed into
URI "http://h2c.example.org/proxy?url=web+coap://foo.org/a".
</t>
</section>
</section>
</section>
</section>
<section title="HTTP-CoAP implementation" anchor="hc">
<section anchor="hc-placement" title="Placement and deployment">
<t>In typical scenarios the HC proxy is expected to be server-side (SS), in particular
deployed at the edge of the constrained network.</t>
<t>The arguments supporting SS placement are the following:
<list style="hanging">
<t hangText="TCP/UDP:">Translation between HTTP and CoAP requires also a TCP to UDP mapping;
UDP performance over the unconstrained Internet may not be adequate.
In order to minimize the number of required retransmissions and overall reliability,
TCP/UDP conversion SHOULD be performed at a SS placed proxy.</t>
<t hangText="Caching:">Efficient caching requires that all the CoAP traffic is intercepted by the same proxy,
thus an SS placement, collecting all the traffic, is strategical for this need.</t>
<t hangText="Multicast:">To support using local-multicast functionalities available in the constrained network,
the HC proxy MAY require a network interface directly attached to the constrained network.</t>
</list></t>
<figure title="Server-side HC proxy deployment scenario" anchor="fig-http-coap-deployment"><artwork>
<![CDATA[
+------+
| |
| DNS |
| |
+------+
--------------------
/ \
/ /-----\ /-----\ \
/ CoAP CoAP \
/ server server \
|| \-----/ \-----/ ||
+----------+ ||
| HTTP/CoAP| /-----\ ||
| Proxy | CoAP ||
|(HC Proxy)| server ||
+------+ +----------+ \-----/ ||
|HTTP | || /-----\ ||
|Client| || CoAP ||
+------+ \ server /
\ \-----/ /
\ /-----\ /
\ CoAP /
\ server /
\ \-----/ /
----------------
]]>
</artwork></figure>
<t>Other important aspects involved in the selection of which type of proxy deployment,
whose choice impacts its placement too, are the following:
<list style="hanging">
<t hangText="Client/Proxy/Network configuration overhead:">
Forward proxies require either static configuration or discovery support in the client.
Reverse proxies require either static configuration, server discovery or embedded URI mapping in the proxy.
Interception proxies require minimal deployment effor (i.e. web traffic routing towards the proxy).</t>
<t hangText="Scalability/Availability:">
Both aspects are typically addressed using redundancy.
CS deployments, due to the limited catchment area and administrative-wide domain of operation,
have looser requirements on this.
SS deployments, in dense/popular/critical environments, have stricter requirements and MAY need to be replicated.
Stateful proxies (e.g. reverse) may be complex to replicate.</t>
</list></t>
<t>Discussion about security impacts of different deployments is covered in <xref target="sec"/>.</t>
<t><xref target="tab-hc-deployments"/> shows some interesting HC proxy deployment scenarios,
and notes the advantages related to each scenario.</t>
<texttable title="Interesting HC proxy deployments" anchor="tab-hc-deployments">
<ttcol align='left'> Feature </ttcol>
<ttcol align='right'> F CS </ttcol>
<ttcol align='right'> R SS </ttcol>
<ttcol align='right'> I SS </ttcol>
<c> TCP/UDP </c>
<c> - </c>
<c> + </c>
<c> + </c>
<c> Multicast </c>
<c> - </c>
<c> + </c>
<c> + </c>
<c> Caching </c>
<c> - </c>
<c> + </c>
<c> + </c>
<c> Scalability/Availability </c>
<c> + </c>
<c> +/- </c>
<c> + </c>
<c> Configuration </c>
<c> - </c>
<c> - </c>
<c> + </c>
</texttable>
<t>Guidelines proposed in the previous paragraphs have been used to fill out the above table.
In the first three rows, it can be seen that SS deployment is preferred versus CS.
Scalability/Availability issues can be generally handled, but some complexity may be involved in reverse
proxies scenarios. Configuration overhead could be simplified when interception proxies deployments
are feasible.</t>
<t>When support for legacy HTTP clients is required,
it may be preferable using configuration/discovery free deployments.
Discovery procedures for client or proxy auto-configuration are still under active-discussion:
see <xref target="I-D.vanderstok-core-bc"/>, <xref target="I-D.bormann-core-simple-server-discovery"/>
or <xref target="I-D.shelby-core-resource-directory"/>.
Static configuration of multiple forward proxies is typically not feasible in existing HTTP clients.</t>
</section>
<section title="Basic mapping">
<t>The mapping of HTTP requests to CoAP and of the response back to HTTP
is defined in Section 8.2 of <xref target="I-D.ietf-core-coap"/>.</t>
<t>The mapping of a CoAP response code to HTTP is not straightforward,
this mapping MUST be operated accordingly to Table 4 of <xref target="I-D.ietf-core-coap"/>.</t>
<t>No temporal upper bound is defined for a CoAP server to provide the response,
thus for long delays the HTTP client or any other proxy in between MAY timeout.
Further discussion is available in Section 7.1.4 of <xref target="I-D.ietf-httpbis-p1-messaging"/>.</t>
<t>The HC proxy MUST define an internal timeout for each pending CoAP request,
because the CoAP server may silently die before completing the request.</t>
<t>Even if the DNS protocol may not be used inside the constrained network,
having valid DNS entries for constrained hosts, where possible, MAY help HTTP clients
to access the resources offered by them.</t>
<t>An example of the usefulness of such entries is described in <xref target="hc-v4v6"/>.</t>
<t>HTTP connection pipelining (section 7.1.2.2 of <xref target="I-D.ietf-httpbis-p1-messaging"/>) is transparent to the CoAP network:
the HC proxy will sequentially serve the pipelined requests by issuing different CoAP requests.</t>
<section title="Caching and congestion control" anchor="hc-caching"> <!-- discuss cache-control -->
<t>The HC proxy SHOULD limit the number of requests to CoAP servers
by responding, where applicable, with a cached representation of the resource.</t>
<t>Duplicate idempotent pending requests to the same resource SHOULD in general be avoided,
by duplexing the response to the relevant hosts without duplicating the request.
<!--
The same consideration apply if multiple active HTTP subscriptions involve the same observe relationship.
-->
</t>
<t>If the HTTP client times out and drops the HTTP session to the proxy (closing the TCP connection),
the HC proxy SHOULD wait for the response and cache it if possible.
Further idempotent requests to the same resource can use the result present in cache,
or, if a response has still to come, requests will wait on the open CoAP session.</t>
<t>Resources experiencing a high access rate coupled with high volatility MAY be observed <xref target="I-D.ietf-core-observe"/> by the HC proxy
to keep their cached representation fresh while minimizing the number of needed messages.
See <xref target="refresh_via_observe"/> for a heuristics that enables the HC proxy
to decide whether observing is a more convenient strategy than ordinary refreshing via Max-Age/ETag-based mechanisms. </t>
<t>Specific deployments may show highly congested servers/resources -- e.g. multicast resources (see <xref target="hc-multicast"/>), popular servers, etc. A careful analysis is required to pick the correct caching policy involving these resources, also taking into consideration the security implications that may impact these targets specifically, and the constrained network in general.</t>
<t>To this end when traffic reduction obtained by the caching mechanism is not adequate,
the HC proxy could apply stricter policing by limiting the amount of aggregate traffic to the constrained network.
In particular, the HC proxy SHOULD pose a rigid upper limit to the number of concurrent CoAP request pending
on the same constrained network; further request MAY either be queued or dropped.
In order to efficiently apply this congestion control, the HC proxy SHOULD be SS placed.</t>
<t>Further discussion on congestion control can be found in <xref target="I-D.eggert-core-congestion-control"/>.</t>
</section>
<section title="Cache Refresh via Observe" anchor="refresh_via_observe">
<t>There are cases where using CoAP observe protocol to handle proxy cache refresh
may be preferable to the validation mechanism based on ETag's defined in section 5.6.2 of <xref target="I-D.ietf-core-coap"/>.
Such scenarios include, but are not limited to, sleeping nodes
-- with possibly high variance in requests' distribution --
which would greatly benefit from a server driven cache update mechanism.
Ideal candidates would also be the crowded or very low throughput networks,
where reduction of the total number of exchanged messages is an important requirement.</t>
<t>This subsection aims at providing a practical evaluation method to decide
whether the refresh of a cached resource R is more efficiently handled
via ETag validation or by establishing an observation on R.</t>
<t>Let T_R be the mean time between two client requests to resource R,
let F_R be the freshness lifetime of R representation,
and let M_R be the total number of messages exchanged towards resource R.
If we assume that the initial cost for establishing the observation is negligible,
an observation on R reduces M_R iff T_R < 2*F_R with respect to using ETag validation,
that is iff the mean arrival time of requests for resource R is greater than half the refresh rate of R.</t>
<t>When using observations M_R is always upper bounded by 2*F_R:
in the constrained network no more than 2*F_R messages will be generated towards resource R.</t>
<t>Proof: Let T be the evaluated interval of time,
let M_Ro be the total number of messages exchanged towards resource R using observation,
and let M_Re be the total number of messages exchanged towards resource R using ETag validation.
The following equations hold M_Re = T*2/T_R, M_Ro = T/F_R.
M_Ro < M_Re iff 1/F_R < 2/T_R, that is T_R < 2*F_R.
The amount of messages saved using observation is T*(2*F_R-T_R)/(T_R*F_R).</t>
<t>Example: assume that F_R is one second and T_R is 1.5 seconds.
Since 1.5 is lower than 2*1, an observation on R reduces M_R.
In a single day of usage, 28800 messages will be saved if the HC proxy establishes an observation on R.
The single message cost required to establish this observation is negligible.</t>
</section>
<section title="Use of CoAP blockwise transfer" anchor="hc-block">
<t>An HC proxy SHOULD support CoAP blockwise transfers <xref target="I-D.ietf-core-block"/> to allow transport of large CoAP payloads while avoiding link-layer fragmentation in LLNs, and to cope with small datagram buffers in CoAP end-points as described in <xref target="I-D.ietf-core-coap"/>.
An HC proxy SHOULD attempt to retry a CoAP PUT or POST request with a payload using blockwise transfer if the destination CoAP server responded with 4.13 (Request Entity Too Large) to the original request.
An HC proxy SHOULD attempt to use blockwise transfer when sending a CoAP PUT or POST request message that is larger than BLOCKWISE_THRESHOLD. The value of BLOCKWISE_THRESHOLD is implementation-specific, for example it may set by an administrator, preset to a known or typical UDP datagram buffer size for CoAP end-points, to N times the size of a link-layer frame where e.g. N=5, preset to a known IP MTU value, or set to a known Path MTU value.
</t><t>
For improved latency an HC proxy MAY initiate a blockwise CoAP request triggered by an incoming HTTP request even when the HTTP request message has not yet been fully received, but enough data has been received to send one or more data blocks to a CoAP server already.
</t>
</section>
<section title="Use case: HTTP/IPv4-CoAP/IPv6 proxy" anchor="hc-v4v6">
<t>This section covers the expected common use case regarding an HTTP/IPv4 client accessing a CoAP/IPv6 resource.</t>
<t>While HTTP and IPv4 are today widely adopted communication protocols in the Internet,
a pervasive deployment of constrained nodes exploiting the IPv6 address space is expected:
enabling direct interoperability of such technologies is a valuable goal.</t>
<t>An HC proxy supporting IPv4/IPv6 mapping is said to be a v4/v6 proxy.</t>
<t>An HC v4/v6 proxy SHOULD always try to resolve the URI authority,
and SHOULD prefer using the IPv6 resolution if available.
The authority part of the URI is used internally by the HC proxy
and SHOULD not be mapped to CoAP.</t>
<t><xref target="fig-simple-http-coap"/> shows an HTTP client on IPv4 (C) accessing a CoAP server on IPv6 (S) through an HC proxy on IPv4/IPv6 (P). The DNS has an A record for "node.coap.something.net" resolving to the IPv4 address of the HC proxy, and an AAAA record with the IPv6 address of the CoAP server.</t>
<figure title="HTTP/IPv4 to CoAP/IPv6 mapping" anchor="fig-simple-http-coap"><artwork>
<![CDATA[
C P S
| | |
| | | Source: IPv4 of C
| | | Destination: IPv4 of P
+---->| | GET /foo HTTP/1.1
| | | Host: node.coap.something.net
| | | ..other HTTP headers ..
| | |
| | | Source: IPv6 of P
| | | Destination: IPv6 of S
| +---->| CON GET
| | | URI-Path: foo
| | |
| | | Source: IPv6 of S
| | | Destination: IPv6 of P
| |<----+ ACK
| | |
| | | ... Time passes ...
| | |
| | | Source: IPv6 of S
| | | Destination: IPv6 of P
| |<----+ CON 2.00
| | | "bar"
| | |
| | | Source: IPv6 of P
| | | Destination: IPv6 of S
| +---->| ACK
| | |
| | | Source: IPv4 of P
| | | Destination: IPv4 of C
|<----+ | HTTP/1.1 200 OK
| | | .. other HTTP headers ..
| | |
| | | bar
| | |
]]>
</artwork></figure>
<t>The proposed example shows the HC proxy operating also the mapping between IPv4
to IPv6 using the authority information available in any HTTP 1.1 request.
This way, IPv6 connectivity is not required at the HTTP client
when accessing a CoAP server over IPv6 only, which is a typical expected use case.</t>
<t>When P is an interception HC proxy, the CoAP request SHOULD have the IPv6 address of C as source
(IPv4 can always be mapped into IPv6).</t>
<t>The described solution takes into account only the HTTP/IPv4 clients accessing CoAP/IPv6 servers;
this solution does not provide a full fledged mapping from HTTP to CoAP.</t>
<t>In order to obtain a working deployment for HTTP/IPv6 clients,
a different HC proxy access method may be required,
or Internet AAAA records should not point to the node anymore
(the HC proxy should use a different DNS database pointing to the node).</t>
<t>When an HC interception proxy deployment is used
this solution is fully working even with HTTP/IPv6 clients.</t>
</section>
</section>
<section title="Multiple message exchanges mapping">
<t>This section discusses the mapping of the multicast and observe features of CoAP,
which have no corresponding primitive in HTTP, and as such are not immediately translatable.</t>
<t>The mapping, which must be considered in both the arrow directions (H->C, C->H)
may involve multi-part responses, as in the multicast use case, asynchronous delivery through HTTP bidirectional techniques,
and HTTP Web Linking in order to reduce the semantics lost in the translation.</t>
<section title="Relevant features of existing standards">
<t>Various features provided by existing standards are useful to efficiently represent sessions involving multiple messages.</t>
<section title="Multipart messages" anchor="hc-multipart">
<t>In particular, the "multipart/*" media type, defined in Section 5.1 of <xref target="RFC2046"/>,
is a suitable solution to deliver multiple CoAP responses within a single HTTP payload.
Each part of a multipart entity SHOULD be represented using "message/http" media type
containing the full mapping of a single CoAP response as previously described.</t>
</section>
<section title="Immediate message delivery">
<t>An HC proxy may prefer to transfer each CoAP response immediately after its reception.
This is possible thanks to the HTTP Transfer-Encoding "chunked",
that enables transferring single responses without any further delay.</t>
<t>A detailed discussion on the use of chunked Transfer-Encoding to stream data
over HTTP can be found in <xref target="RFC6202"/>.
Large delays between chunks can lead the HTTP session to timeout,
more details on this issue can be found in <xref target="I-D.thomson-hybi-http-timeout"/>.</t>
<t>An HC proxy MAY prefer (e.g. to avoid buffering) to transfer each response related to a multicast request as soon as it comes in from the server.
One possible way to achieve this result is using the "chunked" Transfer-Encoding in the HTTP response,
to push individual responses until some trigger is fired (timeout, max number of messages, etc.).</t>
<t>An example showing immediate delivery of CoAP responses using HTTP chunks will be provided in <xref target="hc-subscription"/>,
while describing its application to an observe session.</t>
</section>
<section title="Detailing source information">
<t>Under some circumstances, responses may come from different sources (i.e. responses to a multicast request);
in this case details about the actual source of each CoAP response MAY be provided to the client.
Source information can be represented using HTTP Web Linking as defined in <xref target="RFC5988"/>,
by adding the actual source URI into each response using Link option with "via" relation type.</t>
</section>
</section> <!-- standard features section -->
<section title="Multicast mapping" anchor="hc-multicast">
<t>In order to establish a multicast communication such a feature should be offered either
by the network (i.e. IP multicast, link-layer multicast, etc.) or by a gateway (i.e. the HC proxy).
Rationale on the methods available to obtain such a feature is out-of-scope of this document, and
extensive discussion of group communication techniques is available in
<xref target="I-D.ietf-core-groupcomm"/>.</t>
<t>Additional considerations related to handling multicast requests mapping are detailed in the
following sections.</t>
<section title="URI identification and mapping">
<t>In order to successfully handle a multicast request, the HC proxy MUST successfully perform the
following tasks on the URI:
<list style="hanging">
<t hangText="Identification:">The HC proxy MUST understand whether the requested URI identifies a group of nodes.</t>
<t hangText="Mapping:">The HC proxy MUST know how to distribute the multicast request to involved servers;
this process is specific of the group communication technology used.</t>
</list></t>
<t>When using IPv6 multicast paired with DNS,
the mapping to IPv6 multicast is simply done using DNS resolution.
If the group management is performed at the proxy,
the URI or part of it (i.e. the authority) can be mapped using some static or
dynamic table available at the HC proxy.
In Section 3.5 of <xref target="I-D.ietf-core-groupcomm"/> discusses a method to build
and maintain a local table of multicast authorities.</t>
</section>
<section title="Request handling">
<t>When the HC proxy receives a request to a URI
that has been successfully identified and mapped to a group of nodes,
it SHOULD start a multicast proxying operation, if supported by the proxy.</t>
<t>Multicast request handling consists of the following steps:
<list style="hanging">
<t hangText="Multicast TX:">The HC proxy sends out the request on the CoAP side
by using the methods offered by the specific group communication technology used in the constrained network;</t>
<t hangText="Collecting RXs:">The HC proxy collects every response related to the request;</t>
<t hangText="Timeout:">The HC proxy has to pay special attention in multicast timing,
detailed discussion about timing depends upon the particular group communication technology used;</t>
<t hangText="Distributing RXs to the client:">The HC proxy can distribute the responses in two different ways:
batch delivering them at the end of the process or on timeout,
or immediately delivering them as they are available.
Batch requires more caching and introduces delays but may lead to lower TCP overhead and simpler processing.
Immediate delivery is the converse.
A trade-off solution of partial batch delivery may also be feasible and efficient in some circumstances.</t>
</list></t>
</section>
<section title="Examples">
<t><xref target="fig-multicast-http-coap"/> shows an HTTP client (C) requesting the resource "/foo"
to a group of CoAP servers (S1/S2/S3) through an HC proxy (P) which uses IP multicast to send the
corresponding CoAP request.</t>
<figure title="Unicast HTTP to multicast CoAP mapping" anchor="fig-multicast-http-coap"><artwork>
<![CDATA[
C P S1 S2 S3
| | | | |
+---->| | | | GET /foo HTTP/1.1
| | | | | Host: group-of-nodes.coap.something.net
| | | | | .. other HTTP headers ..
| | | | |
| +---->|---->|---->| NON GET
| | | | | URI-Path: foo
| | | | |
| |<----------+ | NON 2.00
| | | | | "S2"
| | | | |
| | X---------------+ NON 2.00
| | | | | "S3"
| | | | |
| |<----+ | | NON 2.00
| | | | | "S1"
| | | | |
| | | | | ... Timeout ...
| | | | |
|<----+ | | | HTTP/1.1 200 OK
| | | | | Content-Type: multipart/mixed; boundary="response"
| | | | | .. other HTTP headers ..
| | | | |
| | | | | --response
| | | | | Content-Type: message/http
| | | | |
| | | | | HTTP/1.1 200 OK
| | | | | Link: <http://node2.coap.something.net/foo>; rel=via
| | | | |
| | | | | S2
| | | | |
| | | | | --response
| | | | | Content-Type: message/http
| | | | |
| | | | | HTTP/1.1 200 OK
| | | | | Link: <http://node1.coap.something.net/foo>; rel=via
| | | | |
| | | | | S1
| | | | |
| | | | | --response--
| | | | |
]]>
</artwork></figure>
<t>The example proposed in the above diagram does not make any assumption
on which underlying group communication technology is available in the constrained network.
Some detailed discussion is provided about it along the following lines.</t>
<t>C makes a GET request to group-of-nodes.coap.something.net.
This domain name MAY either resolve to the address of P,
or to the IPv6 multicast address of the nodes (if IP multicast is supported and P is an interception proxy),
or the proxy P is specifically known by the client that sends this request to it.</t>
<t>To successfully start multicast proxying operation,
the HC proxy MUST know that the destination URI involves a group of CoAP servers,
e.g. the authority group-of-nodes.coap.something.net is known to identify a group of nodes
either by using an internal lookup table, using DNS paired with IPv6 multicast, or by using some
other special technique.</t>
<t>A specific implementation option is proposed to further explain the proposed example.
Assume that DNS is configured such that all subdomain queries to coap.something.net,
such as group-of-nodes.coap.something.net, resolve to the address of P.
P performs the HC URI mapping by removing the 'coap' subdomain from the authority and by switching
the scheme from 'http' to 'coap'
(result: "coap://group-of-node.something.net/foo");
"group-of-nodes.something.net" is resolved to an IPv6 multicast address to which S1, S2 and S3 belong.
The proxy handles this request as multicast and sends the request "GET /foo" to the multicast group .</t>
</section>
</section> <!-- multicast section -->
<section title="Multicast responses caching" anchor="mcast-caching">
<t>We call perfect caching when the proxy uses only the cached representations to provide a response to the HTTP client.
In the case of a multicast CoAP request, perfect caching is not adequate. This section
updates the general caching guidelines of <xref target="hc-caching" /> with specific
guidelines for the multicast use case.</t>
<t>Due to the inherent unreliable nature of the NON messages involved
and since nodes may have dynamic membership in multicast groups,
responding only with previously cached responses
without issuing a new multicast request is not recommended.
This perfect caching behaviour leads to miss responses of nodes that later joined the multicast group,
and/or to repeately serve partial representations due to message losses.
Therefore a multicast CoAP request SHOULD be sent by a HC proxy for each incoming request
addressed to a multicast group.</t>
<t>Caching of multicast responses is still a valuable goal to pursue reduce network congestion, battery consumption and response latency.
Some considerations to be performed when adopting a multicast caching behaviour are outlined in the following paragraph.</t>
<t>Caching of multicast GET responses MAY be implemented by adopting some technique that takes into account
either knowledge about dynamic characteristics of group membership (occurrence or frequency of group changes)
or even better its full knowledge (list of nodes currently part of the group).</t>
<t>When using a technique exploiting this knowledge, valid cached responses SHOULD be served from cache.</t>
<!--
<t>As a caching strategy, CoAP-observe MAY be used for multicast request caching
[TBD: multicast operation is not defined explicitly in CoAP-observe but it should work?].
ETag MUST NOT be used by a HC proxy in a CoAP multicast request because an ETag value is only valid
in context of a single CoAP server, not for a group of servers.
</t>
<t>[TBD] What about serving a cached valid response from server A,
while later in time an updated response comes in from server A with other payload?
Should HC proxy always wait for new responses first? Or cache the new response and
not serve this to the client? Or serve updated responses asynchronously over HTTP?
</t>
-->
</section> <!-- multicast caching section -->
<section title="Observe mapping" anchor="hc-subscription">
<t>By design, and certainly not without a good rationale, HTTP lacks a publish-subscriber facility. This implies that the mapping of the CoAP observe semantics has to be created ad hoc, perhaps by making use of one of the well-known HTTP techniques currently employed to establish an HTTP bidirectional connection with the target resource - as documented in <xref target="RFC6202"/>.</t>
<t>In the following sections we will describe some of the approaches that can be used to identify an observable resource and to create the communication bridging needed to set up an end to end HTTP-CoAP observation.</t>
<section title="Identification" anchor="hc-sub-identification">
<t>In order to appropriately process an observe request, the HC proxy needs to know whether a given request is intended to establish an observation on the target resource, instead of triggering a regular request-response exchange.</t>
<t>At least two different approaches to identify such special requests exist, as discussed below.</t>
<section title="Observable URI mapping">
<t>An URI is said to be observable whenever every request to it implicitly requires the establishment of an HTTP bidirectional connection to the resource.</t>
<t>Such subscription to the resource is always paired, if possible, to a CoAP observe session to the actual resource being observed. In general, multiple connections that are active with a single observable resource at the same time, are multiplexed to the single observe session opened by the intermediary. Its notifications are then de-multiplexed by the HC proxy to every HTTP subscriber.</t>
<t>An intermediary MAY pair a couple of distinct HTTP URIs to a single CoAP observable resource: one providing the usual request-response mediated access to the resource, and the other that always triggers a CoAP observe session.</t>
<section title="Discovery" anchor="hc-obs-resources">
<t>As shown in <xref target="OPTIONS+Link" />, in order to know whether an URI is observable, an HTTP UA MAY do a preflight request to the target resource using the HTTP OPTIONS method (see section 6.2 of <xref target="I-D.ietf-httpbis-p2-semantics" />) to discover the communication options available for that resource.</t>
<t>If the resource supports observation, the proxy adds a Link Header <xref target="RFC5988" /> with the "obs" attribute as link-param (see Section 7 of <xref target="I-D.ietf-core-observe" />).</t>
<figure title="Discover observability with HTTP OPTIONS" anchor="OPTIONS+Link">
<artwork>
<![CDATA[
C P S
| | | OPTIONS /kitchen/temp HTTP/1.1
+------>| | Host: node.coap.something.net
| | |
| +------>| CON GET
| | | Uri-Path: /.well-known/core?anchor=/kitchen/temp
| | |
| |<------+ ACK 2.05
| | | Payload: </kitchen/temp>;obs
| | |
|<------+ | HTTP/1.1 200 OK
| | | Link: </kitchen/temp>; obs; type="application/atom+xml"
| | | Allow: GET, OPTIONS
]]>
</artwork>
</figure>
<!-- <t>TODO: how do we fill the Allow field?</t> -->
</section>
</section>
<section title="Differentiation using HTTP Header">
<t>Discerning an observation request through in-protocol means, e.g. via the presence and values of some HTTP metadata, avoids introducing static "observable" URIs in the HC proxy namespace. Though ideally the former should be preferred, there seems to be no standard way to use one of the established HTTP headers to convey the observe semantics.</t>
<t>Standardizing such methods is out-of-scope of this document, so we just point out some possible approaches that in the future may be used to differentiate observation requests from regular requests.</t>
<section title="Expect Header">
<t>The first method involves the use of the Expect header as defined in Section 9.3 of <xref target="I-D.ietf-httpbis-p2-semantics" />. Whenever an HC proxy receives a request with a "206-partial-content" expectation, the proxy MUST fulfill this expectation by pairing this request to either a new or existing observe session to the resource.</t>
<t>If the proxy is unable to observe the resource, or if the observation establishment fails, the proxy MUST reply to the client with "417 Expectation Failed" status code.</t>
<t>Given that the Expect header is processed hop-by-hop, this method will fail immediately in case a proxy not supporting this expectation is traversed. For this reason, at present, the said approach can't be used in the public Internet.</t>
</section>
<section title="Prefer Header">
<t>A second, very similar, approach involves the use of the Prefer header, defined in <xref target="I-D.snell-http-prefer"/>. The HTTP user agent expresses the preference to establish an observation with the target resource by including a "streaming" preference to request an HTTP Streaming session, or a "long-polling" preference to signal to the proxy its intended polling behaviour (see <xref target="RFC6202"/>).</t>
<!-- XXX Is it necessary to signal the "long-polling" option: isn't it transparent to the server/proxy ? -->
<t>A compliant HC proxy will try to fulfill the preference, and manifest observation establishment success by responding with a status code of "206 Partial Content". The observation request fails, falling back to a single response, whenever the status code is different from 206.</t>
<t>This approach will never fail immediately, differently from the previous one, even across a chain of unaware proxies; however, as documented in <xref target="RFC6202"/>, caching intermediaries may interfere, delay or block the HTTP bidirectional connection, making this approach unacceptable when no weak consistency of the resource can be tolerated by the requesting UA.</t>
</section>
</section>
</section>
<section title="Notification(s) mapping" anchor="hc-sub-mapping">
<t>Multiplexing notifications using a single HTTP bidirectional session needs some further considerations about the selection of the media type that best fits this specific use case.</t>
<t>The usage of two different content-types that are suitable for carrying multiple notifications in a single session, is discussed in the following sections.</t>
<section title="Multipart messaging" anchor="hc-multipart-obs">
<t>As already discussed in <xref target="hc-multipart"/> for multicasting, the "multipart/*" media type is a suitable solution to deliver multiple CoAP notifications within a single HTTP payload.</t>
<t>As in the multicast case, each part of the multipart entity MAY be represented using a "message/http" media type, containing the full mapping of the single CoAP notification mapped, so that CoAP envelope informations are preserved (e.g. the response code).</t>
<t>A more sophisticated mapping could use multipart/mixed with native or translated media type.</t>
</section>
<section title="Using ATOM Feeds">
<t>Popular observable resources with refresh rates higher than a couple of seconds may be treated as Atom feeds <xref target="RFC4287" />, especially with delay tolerant user agents and where persistence is required.</t>
<t><xref target="OPTIONS+Link" /> shows a resource supporting 'application/atom+xml' media-type. In such case clients can listen to update notification by regularly polling the resource via opportunely spaced GETs, i.e. driven by the advertised max-age value.</t>
</section>
</section>
<section title="Examples" anchor="hc-sub-example">
<t><xref target="fig-streaming2observe"/> shows the interaction between an HTTP client (C),
an HC proxy (P), and a CoAP server (S) for the observation of the resource "temperature" (T)
available on S.</t>
<t>C manifests its intention to observe T by including the Expect Header in the request;
if P or S do not support this interaction, the request MUST fail with "417 Expectation Failed" return code.
In the presented example, both P and C support this interaction, and the subscription is successful,
as stated by the "206 Partial Content" return code.</t>
<t>At every notification corresponds the emission of a HTTP chunk containing a single part,
which contains a "message/http" payload containing the full mapping of the notification.
When the observation is dropped by the CoAP server, the HTTP streaming session is closed.</t>
<figure title="HTTP Streaming to CoAP Observe" anchor="fig-streaming2observe"><artwork>
<![CDATA[
C P S
| | |
+---->| | GET /temperature HTTP/1.1
| | | Host: node.coap.something.net
| | | Expect: 206-partial-content
| | | Accept: multipart/mixed
| | |
| +---->| CON GET
| | | Uri-Path: temperature
| | | Observe: 0
| | |
| |<----+ ACK 2.05
| | | Observe: 3482
| | | "22.1 C"
| | |
|<----+ | HTTP/1.1 206 Partial Content
| | | Content-Type: multipart/mixed; boundary=notification
| | |
| | | XX
| | | --notification
| | | Content-Type: message/http
| | |
| | | HTTP/1.1 200 OK
| | |
| | | 22.1 C
| | |
| | | ... about 60 seconds have passed ...
| | |
| |<----+ NON 2.05
| | | Observe: 3542
| | | "21.6 C"
| | |
|<----+ | YY
| | | --notification
| | | Content-Type: message/http
| | |
| | | HTTP/1.1 200 OK
| | |
| | | 21.6 C
| | |
| | | ... if the server drops the relationship ...
| | |
| |<----+ NON 2.05
| | | "21.8 C"
| | |
|<----+ | ZZ
| | | --notification
| | | Content-Type: message/http
| | |
| | | HTTP/1.1 200 OK
| | |
| | | 21.8 C
| | |
| | | --notification--
| | |
| | | 0
]]>
</artwork></figure>
<t><xref target="fig-longpolling2observe"/> shows the interaction between an HTTP client (C),
an HC proxy (P), and a CoAP server (S) for the observation of the resource "temperature" (T)
available on S.</t>
<t>C manifests its intention to observe T by including the Prefer Header in the request;
if P or S do not support this interaction, the request silently fails if a status code "200 OK" is returned,
which means that no further notification is expected on that session.</t>
<t>In the presented example, both P and C support this interaction, and the subscription is successful,
as stated by the "206 Partial Content" status code.
At every notification a new response is sent to the pending client,
always containing the "206 Partial Content" status code,
to indicate that the observe session is still active,
so that C can issue a new long-polling request immediately after this notification.</t>
<t>If the observation relationship is dropped by S,
P notifies the last received content using the "200 OK" status code,
indicating that no further notification is expected on this observe session.</t>
<figure title="HTTP Long Polling to CoAP Observe" anchor="fig-longpolling2observe"><artwork>
<![CDATA[
C P S
| | |
+---->| | GET /temperature HTTP/1.1
| | | Host: node.coap.something.net
| | | Prefer: long-polling
| | |
| +---->| CON GET
| | | Uri-Path: temperature
| | | Observe: 0
| | |
| |<----+ ACK 2.05
| | | Observe: 3482
| | | "22.1 C"
| | |
|<----+ | HTTP/1.1 206 Partial Content
| | |
| | | 22.1 C
| | |
+---->| | GET /temperature HTTP/1.1
| | | Host: node.coap.something.net
| | | Prefer: long-polling
| | |
| | | ... about 60 seconds have passed ...
| | |
| |<----+ NON 2.05
| | | Observe: 3542
| | | "21.6 C"
| | |
|<----+ | HTTP/1.1 206 Partial Content
| | |
| | | 21.6 C
| | |
+---->| | GET /temperature HTTP/1.1
| | | Host: node.coap.something.net
| | | Prefer: long-polling
| | |
| | | ... if the server drops the relationship ...
| | |
| |<----+ NON 2.05
| | | "21.8 C"
| | |
|<----+ | HTTP/1.1 200 OK
| | |
| | | 21.8 C
]]>
</artwork></figure>
<t><xref target="fig-atom2observe"/> shows the interaction between an HTTP client (C), an HC proxy (P), and a CoAP server (S) for the observation of the resource "kitchen/temp" (T) available on S.</t>
<t>It is assumed that the HC proxy knows that the requested resource is observable (since perhaps being asked beforehand to discover its properties as described in <xref target="OPTIONS+Link" />.) When asked by the HTTP client to retrieve the resource, it requests an observation - in case it weren't already in place - and then sends the collected data to the client as an Atom feed. The data coming through in the constrained network is stored locally on the proxy, and forwarded when further requests are received on the HTTP side. As already said, using the Atom format has two main advantages: first, there is always a "current" feed, but there may also be a complete log made available to HTTP clients; secondly, the HTTP intermediaries can play a substantial role in absorbing a fair amount of the load on the HC proxy. The latter is a very important property when the requested resource is or becomes very popular.</t>
<figure title="Observation via Atom feeds" anchor="fig-atom2observe">
<artwork>
<![CDATA[
C P S
| | | GET /kitchen/temp HTTP/1.1
+------>| | Host: node.coap.something.net
| | |
| +------>| CON GET
| | | Uri-Path: kitchen/temp
| | | Observe: 0
| | |
| |<------+ ACK 2.05
| | | Observe: 1000
| | | Max-Age: 10
| | | "22.3 C"
| | |
|<------+ | HTTP/1.1 200 OK
| | | Cache-Control: max-age=10
| | | ETag: "0x5555"
| | | Content-Type: application/atom+xml
| | |
| | | <feed xmlns="http://www.w3.org/2005/Atom">
| | | <entry>
| | | <id>urn:uuid:bf08203a-fbbf-49e8-bf11-3c4cff708525</id>
| | | <updated>2012-03-07T11:14:30</updated>
| | | <content type="text/plain">
| | | 22.3 C
| | | </content>
| | | <entry>
| | | </feed>
| | |
| | |
| |<------+ NON 2.05
| | | Observe: 1010
| | | Max-Age: 10
| | | "22.4 C"
| | |
+------>| | GET /kitchen/temp HTTP/1.1
| | | Host: node.coap.something.net
| | |
| | | [...]
| | |
]]>
</artwork>
</figure>
</section>
</section> <!-- subscription section -->
</section>
</section>
<section title="CoAP-HTTP implementation" anchor="ch">
<t>The CoAP protocol <xref target="I-D.ietf-core-coap"/> allows CoAP clients to
request CoAP proxies to perform an HTTP request on their behalf. This is
accomplished by the CoAP client populating an HTTP absolute URI in the
'Proxy-URI' option of the CoAP request to the CoAP proxy. An absolute URI
is an HTTP URI that does not contain a fragment component <xref target="RFC3986"/>.
The proxy then composes an HTTP request with the given URI and sends it
to the appropriate HTTP origin server. The server then returns the HTTP
response to the proxy, which the proxy returns to the CoAP client
via a CoAP response</t>
<section anchor="CoAP_Placement_Deployment" title="Placement and Deployment">
<t>In typical scenarios, for communication from a CoAP client to an HTTP origin server,
the HC proxy is expected to be located on the client-side (CS). Specifically, the
HC proxy is expected to be deployed at the edge of the constrained network as shown
in <xref target="fig-coap-http-deployment"/>.</t>
<t>The arguments supporting CS placement are as follows:
<list style="hanging">
<t hangText="Client/Proxy/Network configuration overhead:">CoAP clients require
either static proxy configuration or proxy discovery support. This overhead is
simplified if the proxy is placed on the same network domain of the client.</t>
<t hangText="TCP/UDP:">Translation between CoAP and HTTP requires also UDP to TCP mapping;
UDP performance over the unconstrained Internet may not be adequate.
In order to minimize the number of required retransmissions on the constrained part of the network and the overall reliability,
TCP/UDP conversion SHOULD be performed as soon as possible in the network path.</t>
<t hangText="Caching:">Efficient caching requires that all the CoAP traffic is intercepted by the same proxy,
thus a CS placement, collecting all the traffic, is strategic for this need.</t>
</list></t>
<figure title="Client-side HC proxy deployment scenario" anchor="fig-coap-http-deployment"><artwork>
<![CDATA[
+------+
| |
| DNS |
| |
+------+
--------------------
// \\
/ /-----\ /---\ \
/ CoAP CoAP \
|| client client ||
+----------+ \-----/ \-----/ ||
| HTTP/CoAP| /-----\ ||
| Proxy | CoAP ||
|(HC Proxy)| client ||
+------+ +----------+ \-----/ ||
|HTTP | || /-----\ ||
|Origin| || CoAP ||
|Server| \ client /-----\ /
+------+ \ \-----/ CoAP /
\ client /
\\ \-----/ //
------------------
]]>
</artwork></figure>
</section>
<section anchor="CoAP_HTTP_Mapping" title="Basic mapping">
<t>The basic mapping of CoAP methods to HTTP is defined in
<xref target="I-D.ietf-core-coap"/>. Specifically the
{GET, PUT, POST, DELETE} set of CoAP methods are mapped to
the equivalent HTTP methods.</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 section
gives some hints for implementing the translation. In addition,
some examples are given to illustrate the mappings.</t>
<section 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 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 title="Use of CoAP blockwise transfer" anchor="ch-block">
<t>A CH proxy SHOULD support CoAP blockwise transfers <xref target="I-D.ietf-core-block"/>
to allow transport of large CoAP payloads while avoiding link-layer fragmentation
in LLNs, and to cope with small datagram buffers in CoAP end-points as described
in <xref target="I-D.ietf-core-block"/>.</t>
<t>For improved latency a CH proxy MAY initiate a HTTP request triggered by an
incoming blockwise CoAP request even when blocks of the CoAP request
have only been partially received by the proxy, in cases where the
Content-Length field is not going to be used in the HTTP request.
This is useful especially if the network between proxy and HTTP server
involves low-bandwidth links.</t>
</section>
<section 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 title="Examples">
<t><xref target="fig-basic-coap-http"/> shows an example 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 a 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 title="A basic CoAP-HTTP GET request" anchor="fig-basic-coap-http"><artwork>
<![CDATA[
C P S
| | |
+---------->| | CoAP Header: GET (T=CON, Code=1, MID=0x1633)
| CoAP | | Token: 0x5a
| Get | | Proxy-URI: http://www.example.com/foo/bar
| | |
| | |
| +---------->| HTTP/1.1 GET /foo/bar
| | HTTP | Host: www.example.com
| | GET |
| | |
| | |
|<----------+ | CoAP Header: (T=ACK, Code=0, MID=0x1633)
| | |
| | |
| |<----------+ HTTP/1.1 200 OK
| | HTTP | Date: Friday, 14 Oct 2011 15:00:00 GMT
| | 200 OK | Content-Type: text/plain; charset=iso-8859-1
| | | Content-Length: 11
| | | Expires: Friday, 14 Oct 2011 16:00:00 GMT
| | | ETag: "xyzzy"
| | | Connection: close
| | |
| | | Hello World
| | |
| | |
|<----------+ | CoAP Header: 2.00 OK (T=CON, Code=64, MID=0xAAFO)
| CoAP | | Token: 0x5a
| 2.00 OK | | C-Type: text/plain; charset=utf-8
| | | Max-Age: 3600
| | | ETag: 0x78797A7A79
| | | Payload: "Hello World"
| | |
+---------->| | CoAP Header: (T=ACK, Code=0, MID=0xAAF0)
]]>
</artwork></figure>
<t>The example in <xref target="fig-complex-coap-http"/> builds on the previous
example and shows an 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 title="A CoAP-HTTP GET request with an ETag Option" anchor="fig-complex-coap-http"><artwork>
<![CDATA[
C P S
| | |
+---------->| | CoAP Header: GET (T=CON, Code=1, MID=0x1CBO)
| CoAP | | Token: 0x7b
| Get | | Proxy-URI: http://www.example.com/foo/bar
| | | ETag: 0x78797A7A79
| | |
| | |
| +---------->| HTTP/1.1 GET /foo/bar
| | HTTP | Host: www.example.com
| | GET | If-None-Match: "xyzzy"
| | |
| | |
|<----------+ | CoAP Header: (T=ACK, Code=0, MID=0x1CBO)
| | |
| | |
| |<----------+ HTTP/1.1 304 Not Modified
| | HTTP | Date: Friday, 14 Oct 2011 17:00:00 GMT
| | 304 | Expires: Friday, 14 Oct 2011 18:00:00 GMT
| | | ETag: "xyzzy"
| | | Connection: close
| | |
| | |
|<----------+ | CoAP Header: 2.03 Valid (T=CON, Code=67, MID=0xAAFF)
| CoAP | | Token: 0x7b
| 2.03 | | Max-Age: 3600
| | | ETag: 0x78797A7A79
| | |
| | |
+---------->| | CoAP Header: (T=ACK, Code=0, MID=0xAAFF)
]]>
</artwork></figure>
</section>
</section>
</section>
<section title="Security Considerations" anchor="sec">
<t>The security concerns raised in Section 15.7 of <xref target="RFC2616" /> also apply to the HC proxy scenario.
In fact, the HC proxy is a trusted (not rarely a transparently trusted) component in the network path.</t>
<t>The trustworthiness assumption on the HC proxy cannot be dropped.
Even if we had a blind, bi-directional, end-to-end, tunneling facility like the one provided by the CONNECT method in HTTP, and also assuming the existence of a DTLS-TLS transparent mapping, the two tunneled ends should be speaking the same application protocol, which is not the case. Basically, the protocol translation function is a core duty of the HC proxy that can't be removed, and makes it a necessarily trusted, impossible to bypass, component in the communication path.</t>
<t>A reverse proxy deployed at the boundary of a constrained network is an easy single point of failure for reducing availability. As such, a special care should be taken in designing, developing and operating it, keeping in mind that, in most cases, it could have fewer limitations than the constrained devices it is serving.</t>
<t>The following sub paragraphs categorize and argue about a set of specific security issues related to the translation,
caching and forwarding functionality exposed by an HC proxy module.</t>
<section title="Traffic overflow">
<t>Due to the typically constrained nature of CoAP nodes,
particular attention SHOULD be posed in the implementation of traffic reduction
mechanisms (see <xref target="hc-caching"/>),
because inefficient implementations can be targeted by unconstrained Internet attackers.
Bandwidth or complexity involved in such attacks is very low.</t>
<t>An amplification attack to the constrained network may be triggered by a multicast request
generated by a single HTTP request mapped to a CoAP multicast resource,
as considered in Section XX of <xref target="I-D.ietf-core-coap"/>.</t>
<t>The impact of this amplification technique is higher than an amplification attack
carried out by a malicious constrained device
(i.e. ICMPv6 flooding, like Packet Too Big, or Parameter Problem on a multicast
destination <xref target="RFC4732" />),
since it does not require direct access to the constrained network.</t>
<t>The feasibility of this attack, disruptive in terms of CoAP server availability, can be limited by
access controlling the exposed HTTP multicast resource, so that only known/authorized users access such URIs.</t>
</section>
<section anchor="sec_mapping" title="Cross-protocol security policy mapping">
<t>At the moment of this writing, CoAP and HTTP are missing any cross-protocol security policy mapping.</t>
<t>The HC proxy SHOULD flexibly support security policies between the two protocols,
possibly as part of the HC URI mapping function,
in order to statically map HTTP and CoAP security policies at the proxy
(see <xref target="appendix_secpol_map" /> for an example.)</t>
</section>
<section title="Handling secured exchanges">
<t>It is possible that the request from the client to the HC proxy is sent over a secured connection.
However, there may or may not exist a secure connection mapping to the other protocol.
For example, a secure distribution method for multicast traffic is complex and MAY not be
implemented (see <xref target="I-D.ietf-core-groupcomm"/>).</t>
<t>By default, an HC proxy SHOULD reject any secured client request if there is no configured security policy mapping. This recommendation MAY be relaxed in case the destination network is believed to be secured by other, complementary, means. E.g.: assumed that CoAP nodes are isolated behind a firewall (e.g. as the SS HC proxy deployment shown in <xref target="fig-http-coap-deployment"/>), the HC proxy may be configured to translate the incoming HTTPS request using plain CoAP (i.e. NoSec mode.)</t>
<t>The HC URI mapping MUST NOT map to HTTP (see <xref target="URI-mapping"/>)
a CoAP resource intended to be accessed only using HTTPS.</t>
<t>A secured connection that is terminated at the HC proxy, i.e. the proxy decrypts secured data locally,
raises an ambiguity about the cacheability of the requested resource.
The HC proxy SHOULD NOT cache any secured content to avoid any leak of secured information.
However in some specific scenario, a security/efficiency trade-off could motivate caching secured information;
in that case the caching behavior MAY be tuned to some extent on a per-resource basis (see <xref target="sec_mapping" />).</t>
</section>
<section title="Spoofing and Cache Poisoning">
<!-- TODO add references -->
<t>In web security jargon, the "cache poisoning" verb accounts for attacks
where an evil user causes the proxy server to associate incorrect content to a cached resource,
which work through especially crafted HTTP requests or request/response combos.</t>
<t>When working in CoAP NoSec mode, the use of UDP makes cache poisoning on the constrained network easy and effective,
simple address spoofing by a malicious host is sufficient to perform the attack.
The implicit broadcast nature of typical link-layer communication technologies used in constrained networks
lead this attack to be easily performed by any host, even without the requirement of being a router in the network.
The ultimate outcome depends on both the order of arrival of packets (legitimate and rogue) and the processing/discarding policy at the CoAP node;
attackers targeting this weakness may have less requirements on timing,
thus leading the attack to succeed with high probability.</t>
<t>In case the threat of a rogue mote acting in the constrained network can't be winded up by
appropriate procedural means,
the only way to avoid such attacks is for any CoAP server to work
at least in MultiKey mode with a 1:1 key with the HC proxy.
SharedKey mode would just mitigate the attack,
since a guessable MIDs and Tokens generation function at the HC proxy side
would make it feasible for the evil mote to implement a "try until succeed" strategy.
Also, (authenticated) encryption at a lower layer (MAC/PHY) could be defeated
by a slightly more powerful attacker, a compromised router mote.</t>.
</section>
<section title="Subscription">
<!-- TODO ask Klaus about observe + intermediaries and loops (Sec 7. of draft-ietf-core-observe-02). -->
<t>As noted in Section 7 of <xref target="I-D.ietf-core-observe" />,
when using the observe pattern, an attacker could easily impose resource exhaustion on a naive server
who's indiscriminately accepting observer relationships establishment from clients.
The converse of this problem is also present, a malicious client may also target the HC proxy itself,
by trying to exhaust the HTTP connection limit of the proxy by opening multiple subscriptions to some CoAP resource.</t>
<t>Effective strategies to reduce success of such a DoS on the HTTP side
(by forcing prior identification of the HTTP client via usual web authentication mechanisms),
must always be weighted against an acceptable level of usability of the exposed CoAP resources.</t>
</section>
</section>
<section title="Acknowledgements">
<t>Special credit is given to Klaus Hartke who provided the text for <xref target="ch"/> and a lot of direct input to this document.
Special credit about the text in <xref target="ch"/> is given to Carsten Bormann who provied parts of it.</t>
<t>Thanks to
Zach Shelby,
Michele Rossi,
Nicola Bui,
Michele Zorzi,
Peter Saint-Andre,
Cullen Jennings,
Kepeng Li,
Brian Frank,
Peter Van Der Stok,
Kerry Lynn,
Linyi Tian,
Dorothy Gellert
for helpful comments and discussions that have shaped the document.</t>
<t>The research leading to these results has received funding from the European Community's
Seventh Framework Programme [FP7/2007-2013] under grant agreement n. [251557].</t>
</section>
</middle>
<back>
<references title="Normative References">
&RFC2046;
&RFC2119;
&RFC2616;
&RFC3986;
&RFC5988;
&RFC4287;
&I-D.ietf-core-coap;
&I-D.ietf-core-observe;
&I-D.ietf-core-block;
&I-D.ietf-core-groupcomm;
&I-D.ietf-httpbis-p1-messaging;
&I-D.ietf-httpbis-p2-semantics;
&I-D.thomson-hybi-http-timeout;
</references>
<references title="Informative References">
&RFC3040;
&RFC4732;
&RFC6202;
&I-D.snell-http-prefer;
&I-D.vanderstok-core-bc;
&I-D.bormann-core-simple-server-discovery;
&I-D.eggert-core-congestion-control;
&I-D.shelby-core-resource-directory;
<reference anchor="W3C.HTML5" target="http://dev.w3.org/html5/spec/">
<front><title>HTML5</title><author initials="I." surname="Hickson" fullname="Ian Hickson"><organization/></author><date month="October" day="18" year="2011"/></front><seriesInfo name="World Wide Web Consortium WD (work in progress)" value="WD-html5-20111018"/><format type="HTML" target="http://dev.w3.org/html5/spec/Overview.html"/>
</reference>
</references>
<section title="Internal Mapping Functions (from an implementer's perspective)">
<t>At least three mapping functions have been identified,
which take place at different stages of the HC proxy processing chain,
involving the URL, Content-Type and Security Policy translation.</t>
<t>All these maps are required to have at least URL granularity so that, in principle,
each and every requested URL may be treated as an independent mapping source.</t>
<t>In the following, the said map functions are characterized via their expected input and output,
and a simple, yet sufficiently rich, configuration syntax is suggested.</t>
<t>In the spirit of a document providing implementation guidance,
the specification of a map grammar aims at putting the basis for a reusable software component (e.g. a stand-alone C library)
that many different proxy implementations can link to, and benefit from.</t>
<section title="URL Map Algorithm">
<t>In case the HC proxy is a reverse proxy, i.e. it acts as the origin server in face of the served network,
the URL of the resource requested by its clients (perhaps having an 'http' scheme) shall be mapped to the real resource origin (perhaps in the 'coap' scheme).</t>
<t>In case HC is a forward proxy, no URL translation is needed since the client already knows the "real name" of the resource.</t>
<t>An interception HC proxy, instead, MAY use the homogeneous mapping strategy (see <xref target="URI-homogeneous-mapping" /> for details) to operate without any pre-configuration need.</t>
<t>As noted in Appendix B of <xref target="RFC3986" /> any correctly formatted URL can be matched by a POSIX regular expression.
By leveraging on this property, we suggest a syntax that describes the URL mapping
in terms of substituting the regex-matching portions of the requested URL into the mapped URL template.</t>
<t>E.g.: given the source regular expression '^http://example.com/coap/.*$' and destination template 'coap://$1' (where $1 stands for the first - and only in this specific case - substring matched by the regex pattern in the source), the input URL "http://example.com/coap/node1/resource2" translates to "coap://node1/resource2".</t>
<t>This is a well established technique used in many todays web components (e.g. Django URL dispatcher, Apache mod_rewrite, etc.), which provides a compact and powerful engine to implement what essentially is an URL rewrite function.</t>
<figure><artwork><![CDATA[
INPUT
* requested URL
OUTPUT
* target URL
SYNTAX
url_map [rule name] {
requested_url <regex>
mapped_url <regex match subst template>
}
EXAMPLE 1
url_map homogeneous {
requested_url '^http://.*$'
mapped_url 'coap//$1'
}
EXAMPLE 2
url_map embedded {
requested_url '^http://example.com/coap/.*$'
mapped_url 'coap//$1'
}
]]></artwork></figure>
<t>Note that many different url_map records may be given in order to build the whole mapping function. Each of these records can be queried (in some predefined order) by the HC proxy until a match is found, or the list is exhausted. In the latter case, depending on the mapping policy (only internal, internal then external, etc.) the original request can be refused, or the same mapping query is forwarded to one or more external URL mapping components.</t>
</section> <!-- End of "URL Map Algorithm" -->
<section title="Security Policy Map Algorithm" anchor="appendix_secpol_map">
<t>In case the "incoming" URL has been successfully translated, the HC proxy must lookup the security policy, if any, that needs to be applied to the request/response transaction carried on the "outgoing" leg.</t>
<figure><artwork align="center"><![CDATA[
INPUT
* target URL (after URL map has been applied)
* original requester identity (given by cookie, or IP address, or
crypto credentials/security context, etc.)
OUTPUT
* security context that will be applied to access the target URL
SYNTAX
sec_map [rule name] {
target_url <regex> -- one or more
requester_id [TBD]
sec_context [TBD]
}
EXAMPLE
[TBD]
]]></artwork></figure>
</section> <!-- End of "Security Policy Map Algorithm" -->
<section title="Content-Type Map Algorithm">
<t>In case a set of destination URLs is known as being limited in handling a narrow subset of mime types, a content-type map can be configured in order to let the HC proxy transparently handle the compatible/lossless format translation.</t>
<figure><artwork align="center"><![CDATA[
INPUT
* destination URL (after URL map has been applied)
* original content-type
OUTPUT
* mapped content-type
SYNTAX
ct_map {
target_url <regex> -- one or more targetURLs
ct_switch <source_ct, dest_ct> -- one or more CTs
}
EXAMPLE
ct_map {
target_url '^coap://class-1-device/.*$'
ct_switch */xml application/exi
}
]]></artwork></figure>
</section> <!-- End of "Content-Type Map Algorithm" -->
</section> <!-- End of "Internal Mapping Functions" -->
</back>
</rfc>
<!-- Change log
-->
<!-- LocalWords: xref CDATA exploders BUA -->
| PAFTECH AB 2003-2026 | 2026-04-23 18:30:28 |