idnits 2.17.1 draft-hartke-t2trg-data-hub-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 4, 2019) is 1635 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-06) exists of draft-ietf-core-coral-01 == Outdated reference: A later version (-14) exists of draft-ietf-core-coap-pubsub-09 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-23 == Outdated reference: A later version (-16) exists of draft-ietf-suit-architecture-07 == Outdated reference: A later version (-13) exists of draft-ietf-suit-information-model-04 Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group K. Hartke 3 Internet-Draft Ericsson 4 Intended status: Experimental November 4, 2019 5 Expires: May 7, 2020 7 Thing-to-Thing Data Hub 8 draft-hartke-t2trg-data-hub-05 10 Abstract 12 A "Thing-to-Thing Data Hub" is a RESTful, hypermedia-driven Web 13 application that can be used in Thing-to-Thing communications to 14 share data items such as thing descriptions, configurations, resource 15 descriptions, or firmware updates at a central location. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on May 7, 2020. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 53 2. Data Hubs . . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2.1. Data Items . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.1.1. Data Item Representation . . . . . . . . . . . . . . 4 56 2.2. Data Collections . . . . . . . . . . . . . . . . . . . . 4 57 2.2.1. Data Collection Representation . . . . . . . . . . . 5 58 2.2.2. Filter Query Representation . . . . . . . . . . . . . 5 59 2.3. Data Hub Discovery . . . . . . . . . . . . . . . . . . . 5 60 2.4. Interactions . . . . . . . . . . . . . . . . . . . . . . 6 61 2.4.1. Getting All Data Items . . . . . . . . . . . . . . . 6 62 2.4.2. Getting Data Items by Metadata . . . . . . . . . . . 6 63 2.4.3. Creating a Data Item . . . . . . . . . . . . . . . . 6 64 2.4.4. Reading a Data Item . . . . . . . . . . . . . . . . . 7 65 2.4.5. Observing a Data Item . . . . . . . . . . . . . . . . 7 66 2.4.6. Updating a Data Item . . . . . . . . . . . . . . . . 7 67 2.4.7. Deleting a Data Item . . . . . . . . . . . . . . . . 7 68 3. Security Considerations . . . . . . . . . . . . . . . . . . . 7 69 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 70 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 5.1. Normative References . . . . . . . . . . . . . . . . . . 8 72 5.2. Informative References . . . . . . . . . . . . . . . . . 9 73 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 10 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 76 1. Introduction 78 In Thing-to-Thing communication, there is often a need to share data 79 items of common interest through a central location. For example, 80 the Resource Directory [I-D.ietf-core-resource-directory] aggregates 81 descriptions of Web resources held on constrained nodes, which 82 enables other nodes to easily discover these resources; a Thing 83 Directory [W3C.CR-wot-architecture-20190516] stores metadata of IoT 84 devices, allowing clients to discover interaction affordances and 85 supported protocol bindings of Things; a Firmware Server 86 [I-D.ietf-suit-architecture] stores firmware images and manifests, 87 making this data available to deployed devices, commissioning tools, 88 and other services. 90 As more and more Thing-to-Thing applications are implemented, it 91 becomes increasingly important being able to not only share resource 92 descriptions and firmware updates but also many other kinds of data, 93 such as default configurations for new devices, service locations, or 94 certificate revocation lists. Resource directories and firmware 95 servers are not a good fit for these kinds of data, as they're 96 specialized to their use cases and generally not accepting any other 97 kinds of data. The creation of new, specialized applications for 98 every type of data is not practical in the long term. 100 This document defines a simple "data hub" application, a RESTful Web 101 application with a machine-understandable hypermedia API. A "data 102 hub" generalizes the concept of a central repository for different 103 applications and is suitable for constrained environments [RFC7228]. 104 Specifically, it enables clients to share data items in any format 105 and provides means for creating, reading, observing, updating, 106 deleting, and finding data items at a data hub server. 108 Data hubs are primarily intended to be accessible over the 109 Constrained Application Protocol (CoAP) [RFC7252]. 111 Features: 113 o General 115 The data hub generalizes the concept of a directory or repository 116 to data items of any Internet media type. This means that 117 applications using the data hub aren't stuck forever with the same 118 media types or limited to just resource descriptions or firmware 119 updates. 121 o Searchable 123 Clients can retrieve a subset of data items from a data hub based 124 on item metadata. 126 o Observable 128 Data items published to a data hub are exposed as resources. As 129 such, they can be observed for changes [RFC7641] over CoAP. This 130 allows clients to stay informed of information that other clients 131 update over time. As a result, the data hub functions similar to 132 a Publish-Subscribe Broker [I-D.ietf-core-coap-pubsub]. 134 o Evolvable 136 The key differentiator of the data hub compared to Resource 137 Directory [I-D.ietf-core-resource-directory] and CoAP Publish- 138 Subscribe Broker [I-D.ietf-core-coap-pubsub] lies in the 139 evolvability of the application -- the ability to respond 140 effectively to the need for changes without negatively impacting 141 existing and new clients. 143 Data hubs enable fine-grained evolvability by driving all 144 interactions by machine-understandable hypermedia elements. 146 Features can be added, changed or removed in a safe, backwards- 147 compatible way simply by updating the data hub representation to 148 expose appropriate links and forms. 150 1.1. Notational Conventions 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 154 "OPTIONAL" in this document are to be interpreted as described in 155 [RFC2119]. 157 2. Data Hubs 159 The "Thing-to-Thing Data Hub" application consists of two types of 160 resources: a "data collection" and a number of "data items" that have 161 been shared (Figure 1). 163 ___ 164 Data / \ 165 Collection \___/ 166 \ 167 \____________________ 168 \___ \___ \___ 169 / \ / \ ... / \ Data Items 170 \___/ \___/ \___/ 172 Figure 1: Resources of a Data Hub 174 2.1. Data Items 176 A data item is a resource that is a member of the data collection 177 resource. 179 2.1.1. Data Item Representation 181 The representation of a data item can be of any media type. However, 182 a data hub can restrict the media types it accepts for publication 183 (see Section 2.2.1). 185 2.2. Data Collections 187 A data collection is a collection resource that contains data item 188 resources. 190 Design Note: In this version of this document, a data hub has only a 191 depth of one level; i.e., all data item resources are organized 192 directly under the top-level data collection resource. This could 193 be extended to multiple levels in a future version. 195 2.2.1. Data Collection Representation 197 The representation of a data collection is a CoRAL document 198 [I-D.ietf-core-coral] containing the following elements: 200 A form of type containing 201 the following fields: 203 For each content format accepted for publication, a form field 204 of type indicating that 205 content format. The absence of any form fields of this type 206 indicates that any content format is accepted. 208 A form of type . 210 For each data item in the data collection, a link of type 211 [RFC6573] 212 targeting the data item and containing the following elements: 214 A form of type . 216 A form of type . 218 Optionally, a (complete or partial) embedded representation of 219 the data item. 221 The document MAY additionally contain other links and forms not 222 described in this document. For example, a document could contain a 223 link with the 224 link relation type [W3C.REC-html52-20171214] that references an 225 alternate representation of a data item. 227 Any of the links and forms MUST be omitted if following or submitting 228 it can never lead to a successful outcome, for example, because the 229 client is not authorized or the server does not support the feature. 231 2.2.2. Filter Query Representation 233 TODO. 235 2.3. Data Hub Discovery 237 In this version of this document, clients are assumed to be pre- 238 configured with the URI of a data collection at a data hub. 240 2.4. Interactions 242 2.4.1. Getting All Data Items 244 A client can list all data items in a data collection by making a GET 245 request to the data collection URI (e.g., after discovering the data 246 hub as described in Section 2.3). 248 On success, the server returns a 2.05 (Content) response with a 249 representation of the collection. As specified in Section 2.2.1 250 above, this representation includes links to (and, optionally, 251 representations of) the data items in the data collection as well as 252 forms for creating, updating, deleting, and finding data items. 254 2.4.2. Getting Data Items by Metadata 256 If the representation of a data collection contains a form of type 257 , the client can filter the data 258 collection by submitting this form with a search query (see 259 Section 2.2.2). 261 Implementations of this version of this document MUST use the method 262 implied by the operation type, 263 i.e., the FETCH method [RFC8132]. Any form indicating a different 264 method MUST be ignored. 266 On success, the server returns a 2.05 (Content) response with a 267 representation of a list of data items in the collection (see 268 Section 2.2.1) that match the query. 270 2.4.3. Creating a Data Item 272 If the representation of a data collection contains a form of type 273 , the client can create a new 274 data item in the data collection by submitting this form with a 275 representation in one of the acceptable media types. The acceptable 276 media types are indicated by form fields of type 277 . 279 Implementations of this version of this document MUST use the method 280 implied by the operation 281 type, i.e., the POST method [RFC7252]. Any form indicating a 282 different method MUST be ignored. 284 On success, the server returns a 2.01 (Created) response. The 285 location of the created data item is conveyed using the Location-Path 286 and Location-Query options [RFC7252]. 288 2.4.4. Reading a Data Item 290 A client can read a data item by following a link with the 291 link relation type in 292 the representation of the data collection. 294 2.4.5. Observing a Data Item 296 A client can observe a data item by following a link with the 297 link relation type in 298 the representation of the data collection and observing the target 299 resource as specified in RFC 7641 [RFC7641]. 301 2.4.6. Updating a Data Item 303 If the representation of a data collection includes a form of type 304 nested within the link to a data 305 item, a client can update the data item by submitting this form with 306 a representation of the updated data item. 308 Implementations of this version of this document MUST use the method 309 implied by the operation type, 310 i.e., the PUT method [RFC7252]. Any form indicating a different 311 method MUST be ignored. 313 On success, the server returns a 2.04 (Changed) response. 315 2.4.7. Deleting a Data Item 317 If the representation of a data collection includes a form of type 318 nested within the link to a 319 data item, the client can delete the data item by submitting this 320 form. 322 Implementations of this version of this document MUST use the method 323 implied by the operation 324 type, i.e., the DELETE method [RFC7252]. Any form indicating a 325 different method MUST be ignored. 327 On success, the server returns a 2.02 (Deleted) response. 329 3. Security Considerations 331 The data hub application relies on a Web transfer protocol like CoAP 332 to exchange representations in a CoRAL serialization format. See 333 Section 11 of RFC 7252 [RFC7252] and Section 7 of RFC 7641 [RFC7641] 334 for security considerations relating to CoAP. See Section XX of RFC 335 XXXX [I-D.ietf-core-coral] for security considerations relating to 336 CoRAL. 338 The data hub application does not define any specific mechanisms for 339 protecting the confidentiality and integrity of messages exchanged 340 between a data hub and a client. It is recommended that 341 implementations employ application layer or transport layer 342 mechanisms for interactions with a data hub. 344 The data hub application does not define any specific mechanisms for 345 protecting the confidentiality and integrity of representations of 346 data items shared through a data hub. For scenarios where end-to-end 347 security matters, such as for firmware updates 348 [I-D.ietf-suit-information-model], implementations should employ an 349 object security mechanism. 351 4. IANA Considerations 353 This document has no IANA actions. 355 5. References 357 5.1. Normative References 359 [I-D.ietf-core-coral] 360 Hartke, K., "The Constrained RESTful Application Language 361 (CoRAL)", draft-ietf-core-coral-01 (work in progress), 362 November 2019. 364 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 365 Requirement Levels", BCP 14, RFC 2119, 366 DOI 10.17487/RFC2119, March 1997, 367 . 369 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 370 RFC 6573, DOI 10.17487/RFC6573, April 2012, 371 . 373 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 374 Application Protocol (CoAP)", RFC 7252, 375 DOI 10.17487/RFC7252, June 2014, 376 . 378 [RFC7641] Hartke, K., "Observing Resources in the Constrained 379 Application Protocol (CoAP)", RFC 7641, 380 DOI 10.17487/RFC7641, September 2015, 381 . 383 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 384 FETCH Methods for the Constrained Application Protocol 385 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 386 . 388 5.2. Informative References 390 [I-D.ietf-core-coap-pubsub] 391 Koster, M., Keranen, A., and J. Jimenez, "Publish- 392 Subscribe Broker for the Constrained Application Protocol 393 (CoAP)", draft-ietf-core-coap-pubsub-09 (work in 394 progress), September 2019. 396 [I-D.ietf-core-resource-directory] 397 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 398 Amsuess, "CoRE Resource Directory", draft-ietf-core- 399 resource-directory-23 (work in progress), July 2019. 401 [I-D.ietf-suit-architecture] 402 Moran, B., Meriac, M., Tschofenig, H., and D. Brown, "A 403 Firmware Update Architecture for Internet of Things 404 Devices", draft-ietf-suit-architecture-07 (work in 405 progress), October 2019. 407 [I-D.ietf-suit-information-model] 408 Moran, B., Tschofenig, H., and H. Birkholz, "An 409 Information Model for Firmware Updates in IoT Devices", 410 draft-ietf-suit-information-model-04 (work in progress), 411 October 2019. 413 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 414 Constrained-Node Networks", RFC 7228, 415 DOI 10.17487/RFC7228, May 2014, 416 . 418 [W3C.CR-wot-architecture-20190516] 419 Kovatsch, M., Matsukura, R., Lagally, M., Kawaguchi, T., 420 Toumura, K., and K. Kajimoto, "Web of Things (WoT) 421 Architecture", World Wide Web Consortium Candidate 422 Recommendation CR-wot-architecture-20190516, May 2019, 423 . 425 [W3C.REC-html52-20171214] 426 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 427 S. Moon, "HTML 5.2", World Wide Web Consortium 428 Recommendation REC-html52-20171214, December 2017, 429 . 431 Acknowledgements 433 Thanks to Christian Amsuess and Jaime Jimenez for helpful comments 434 and discussions that have shaped the document. 436 Author's Address 438 Klaus Hartke 439 Ericsson 440 Torshamnsgatan 23 441 Stockholm SE-16483 442 Sweden 444 Email: klaus.hartke@ericsson.com