| CoRE | C. Amsüss |
| Internet-Draft | September 27, 2018 |
| Expires: March 31, 2019 |
Expressing indirection in a dereferencing content type
draft-amsuess-core-dereference-type-latest
[ See introduction ]
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 https://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 March 31, 2019.
Copyright (c) 2018 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 (https://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.
The topic of providing a content format that indicates that a particular URI should be dereferenced instead of using the payload itself has come up time and again in CoRE [citation needed].
Nobody has done anything about it. [TDB: Check whether that’s actually the case.]
Until now.
The Dereference Link type is a media type for use with RESTful systems that carries a very particular piece of information: That a representation of the requested resource is available at a given location.
The location of that representation is expressed in an [RFC6690] link format document that contains only a single link whose target is expressed as a URI (ie. not a relative reference). The link MAY contain target attributes, which the client MAY ignore.
[ TBD: Detailed deliberations on whether to use link-format, just a plain URI, links-json or what so not – and whether a relative refrence can make sense. ]
A Dereference Link always indicates semantic equivalence: It indicates that any information derived from its link target could also have been obtained from the requested resource. It does not mean that any resource representation obtained of the target resource could be literally substituted for it.
This specification does not prescribe any behavior to recipients of a Dereference Link, it is up to application descriptions to explore its security implications and to describe what a recipient may or may not do about it.
Various media types contain built-in facilities to express the same intent as a Derefere Link:
A HTML document can contain an <iframe> tag that is displayed full-screen.
An SVG document can use the <image> tag to include another SVG file at the current location.
The C preprocessor directive #include allows sourcing in code from a different file. This is limited to local file systems, but preserves the semantics of the included file: If the included file contains an #include itself, its argument is interpreted relative to the included file’s location.
LaTeX’s \input command does something differetn than the Dereference Link type: it includes a literal copy of the target file in the outer file’s source code, and any relative references in there are interpreted relative to the outer document.
People requested that CoAP have redirection – be served:
GET coap://example.com/weather
2.05 Content
Content-Format: application/dereference+link-format
Payload:
<coap://example.net/weather-in-vienna>
GET coap://example.net/weather-in-vienna
2.05 Content
Content-Format: application/senml+json
Payload:
[{"n": "urn:example:weather:VIE:temperature", "v": 16.5, "u": "Cel"}]
Also works for POST operations:
POST coap://node.example.com/create-long-report 2.05 Content (sent immediately) Content-Format: application/dereference+link-format Payload: <coap://node.example.com/report-spool/123> GET coap://node.example.com/report-spool/123 5.03 I'm Still Busy With That ... GET coap://node.example.com/report-spool/123 2.05 Here You Go ...
Pushing a firmware upload using a close data source:
PUT coap://node1.example.com/firmware Content-Format: application/dereference+link-format Payload: <coap://gateway.example.com/files/fw01234.bin> (Server goes there and fetches its firmware update) 2.04 Changed
Note that different application specifications might disagree on whether the server returns success immediately or whether it needs to obtain a full copy before doing so.
A batch of SenML values can be accessed with a FETCH operation according to [I-D.keranen-core-senml-fetch] by sending a list of names to the batch and receiving a subset of its data.
If one agrees that a list of names and a list of resource links are interchangable, a server might support more elaborate queries using a filter language it has already built in:
FETCH coap://node1.example.com/bigbatch/
Content-Format: application/dereference+link-format
Payload:
<coap://node1.example.com/.well-known/core?if=core.s&rt=temperature>;ct="40"
2.05 Content
Content-Format: application/senml+json
Payload:
[{"bn": "coap://node1.example.com/s/", "bu": "degC",
"n": "1/temp", "v": 16.4},
{"n": "3/temp", "v": 20.3},
{"n": "6/t-core", "v": 42.5}]
The hint that .well-known/core has a representation in application/link-format (ct="40") is probably needless here, given that the device will hopefully know by itself and might not even trigger a CoAP request to the resource it hosts itself if it can utilize its intrinsic knowledge in a more optimized way.
All kinds of things can go wrong with this.
Therefore, a recipient of a Derefere Link MUST NOT act on it unless it is following a concrete specification that has its own security considerations and policies on when a link should be followed.
| [RFC6690] | Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, August 2012. |
| [RFC6838] | Freed, N., Klensin, J. and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013. |
| [I-D.keranen-core-senml-fetch] | Keranen, A. and M. Mohajer, "FETCH & PATCH with Sensor Measurement Lists (SenML)", Internet-Draft draft-keranen-core-senml-fetch-02, July 2018. |
data:application/dereference;http://www.example.com treated like http://www.example.com (if dereferencing allowed!)