Guidelines for Mapping Implementations: HTTP to the Constrained Application Protocol (CoAP)
Extracted elements (30)
CoAP 4.01 (Unauthorized) maps to HTTP 403 (Forbidden) rather than HTTP 401 (Unauthorized) because HTTP 401 mandates a WWW-Authenticate header field, which has no equivalent in CoAP, making a semantically correct 401 response impossible to construct.
CoAP 4.05 (Method Not Allowed) SHOULD normally map to HTTP 400 rather than HTTP 405 because HTTP 405 requires listing allowed methods in an 'Allow' header, and CoAP servers generally do not convey that information. HTTP 405 MAY be used only when the HC Proxy has explicit knowledge of the allowed methods (e.g., from a Resource Directory).
CoRE Link Format payloads in CoAP responses may contain CoAP URIs that could be rewritten to HTTP URIs by the HC Proxy. However, such transcoding risks corrupting payloads, breaking integrity-protected resources, and exposing clients to modified content; it should only be done at the proxy implementer's discretion.
The 'application/coap-payload' media type can never be used directly in CoAP messages because there is no mechanism to encode the mandatory 'cf' parameter in CoAP. It is exclusively an HTTP-side representation for passing through CoAP payloads with unmapped content-formats.
An HC Proxy MUST define an internal timeout for each pending CoAP request. For confirmable requests, the timeout T SHOULD be T = MAX_RTT + MAX_SERVER_RESPONSE_DELAY; if MAX_SERVER_RESPONSE_DELAY is unknown, a default of 250 seconds MAY be used.
An HC Proxy MUST implement TLS with Pre-Shared Key (PSK) (RFC 4279) and SHOULD implement TLS (RFC 5246) with client authentication using X.509 certificates to secure HTTP communication with clients.
An HC Proxy SHOULD support CoAP block-wise transfers (RFC 7959) to handle large payloads and constrained datagram buffers. It SHOULD retry a PUT or POST with block-wise transfer if the CoAP server responds with 4.13 (Request Entity Too Large), and SHOULD proactively use block-wise when request size exceeds BLOCKWISE_THRESHOLD.
An HTTP Accept */* header MUST be mapped to a CoAP request with no Accept option. Failure to map Accept and Accept-* headers SHOULD be silently ignored by forwarding the CoAP request without an Accept option.
An HTTP request with a Content-Type and Content-Encoding combination that the HC Proxy cannot map to a CoAP Content-Format SHALL elicit a 415 (Unsupported Media Type) response from the HC Proxy.
By default, the HC Proxy MUST authenticate all incoming HTTP requests prior to forwarding them to the CoAP server. This default behavior MAY be explicitly disabled by an administrator.
CoAP diagnostic payloads SHOULD be copied into the HTTP response body with Content-Type 'text/plain;charset=utf-8'. They MUST NOT be copied into the HTTP reason-phrase, as they may contain CR-LF characters incompatible with HTTP reason-phrase syntax.
If an 'hct' attribute is present in a returned 'core.hc' discovery link, the client MUST use it to create the Hosting HTTP URI. If absent, the default template '{+tu}' MUST be assumed.
The default URI mapping function SHOULD be implemented and SHOULD be activated by default in an HC Proxy, unless valid (e.g., application-specific) reasons exist to use a different mapping function.
Unless explicitly configured to allow pass-through of unknown content-formats, the HC Proxy SHOULD NOT forward requests carrying a Content-Type or Accept header with 'application/coap-payload', and SHOULD return an appropriate client error instead.
When no prior mutual agreement exists, a Target CoAP URI embedded in the Hosting HTTP URI without its scheme component MUST NOT be emitted by clients, and MUST elicit a suitable 4xx client error response from the HC Proxy.
When the Target CoAP URI authority contains an IPv6address, the surrounding square brackets MUST be percent-encoded in the Hosting HTTP URI path segment (e.g., coap://[2001:db8::1]/light becomes coap://%5B2001:db8::1%5D/light), and MUST be reverted when the HC Proxy unpacks the Target CoAP URI.
An HC (HTTP-to-CoAP) Proxy acts as both an HTTP server and a CoAP client, receiving HTTP requests, translating them to CoAP requests, forwarding them to CoAP servers, and mapping CoAP responses back to HTTP responses for the originating HTTP client.
If the HC Proxy receives a CoAP response with an unrecognized Content-Format, it SHALL return the payload with the generic 'application/coap-payload;cf=<N>' media type, where N is the numeric CoAP Content-Format value.
Table 2 defines the normative mapping from CoAP response codes to HTTP status codes: 2.01→201, 2.02→200/204, 2.03→304/200, 2.04→200/204, 2.05→200, 4.00→400, 4.01→403, 4.03→403, 4.04→404, 4.05→400/405, 4.06→406, 4.12→412, 4.13→413, 4.15→415, 5.00→500, 5.01→501, 5.02→502, 5.03→503, 5.04→504, 5.05→502. Block-wise codes 2.31 and 4.08 are not translated to HTTP.
The enhanced URI mapping template form uses up to five template variables—s (scheme), hp (host:port), p (path), q (query), qq (optional query)—where q and qq MUST be used in mutual exclusion. At most one instance of each variable is allowed in a template definition.
The HC Proxy SHOULD publish its location and URI mapping template using the CoRE Link Format (RFC 6690) resource type 'core.hc', discoverable via '/.well-known/core?rt=core.hc'. On the CoAP side, links must include an explicit anchor parameter with the HTTP origin; on the HTTP side, the anchor may be omitted if it equals the HTTP origin.
The loose media type mapping table generalizes specific HTTP media types to CoAP-mappable super-types: application/*+xml→application/xml, application/*+json→application/json, application/*+cbor→application/cbor, text/xml→application/xml, text/*→text/plain, */*→application/octet-stream. Entries are matched top-to-bottom using the most specific match.
The mt2cf algorithm maps an HTTP Internet media type (and optional content encoding) to a CoAP Content-Format by first looking up the IANA 'CoAP Content-Formats' registry, then optionally applying the loose media type mapper if no exact match is found.
Three URI mapping modes are defined: null mapping (reverse-proxy with private CoAP URI derivation), default mapping (Target CoAP URI appended verbatim to HC Proxy URI), and URI mapping templates (Level 2 RFC 6570 templates for custom mappings). The 'tu' template variable represents a full Target CoAP URI in the simple form.
This document registers the 'application/coap-payload' Internet media type with a mandatory 'cf' parameter (integer 0–65535 identifying the CoAP Content-Format). It is used by HTTP-to-CoAP proxies to carry CoAP payloads with unrecognized or unmapped content-formats.
This document registers the 'core.hc' Resource Type Link Target Attribute in the 'Resource Type (rt=) Link Target Attribute Values' subregistry under the 'Constrained RESTful Environments (CoRE) Parameters' registry, identifying the HTTP-to-CoAP mapping base resource.
A single HTTP request mapping to a CoAP multicast resource can trigger an amplification attack against the constrained network, since no direct access to the constrained network is required. The feasibility is mitigated by access-controlling exposed multicast resources to known/authorized users.
CoAP multicast requests are a DoS and reconnaissance attack vector: they impose cost on constrained networks and can expose a full inventory of home appliances via '/.well-known/core'. It is RECOMMENDED that multicast resources be access-controlled with a default-deny policy and that requestors be strongly authenticated; transport SHOULD use mutually authenticated TLS when traversing the public Internet.
It is RECOMMENDED that accessing a 'coaps' URI be allowed only from a corresponding 'https' URI by default. An HC Proxy SHOULD reject any secured CoAP client request lacking a configured security policy mapping; however, this MAY be relaxed when the destination network is secured by other means (e.g., isolated behind a firewall).
URI mapping introduces three risks: DoS via multicast URIs (mitigate with default-deny multicast whitelist), topology leakage via '/.well-known/core' (mitigate with default-deny resource whitelist), and CoAP target transparency (mitigate with HTTPS-only interface to make Target CoAP URIs opaque to passive attackers).